Aller au contenu

Elina Traffic Controller (Elina-TC)

Introduction

Elina-TC est un outil puissant en ligne de commande pour la dégradation et l'émulation de réseau sur Linux. Il fournit une interface conviviale aux sous-systèmes Traffic Control (tc) et NetEm (netem) intégrés au noyau Linux, vous permettant de simuler une grande variété de conditions réseau réalistes sur une interface réseau donnée.

Elina-TC excelle en tant qu'outil autonome pour les tests réseau, l'analyse de résilience des applications et la validation des performances. Il est également conçu pour être intégré avec un générateur de trafic, tel qu'Elina-TG, vous permettant de générer du trafic d'application tout en dégradant simultanément le chemin réseau. Cela vous permet de mesurer et de comprendre l'impact direct des dégradations réseau sur les performances de l'application.

Comment ça fonctionne

Elina-TC applique des règles de dégradation réseau au trafic ingress (téléchargement) et egress (upload) d'une interface réseau spécifiée, vous permettant de tester l'impact des conditions réseau sur votre application. Il utilise un périphérique virtuel Intermediate Functional Block (ifb) pour effectuer ces modifications.

Important — mise en forme symétrique : Les dégradations sont appliquées dans les deux directions. Un profil avec delay: "50ms" ajoute environ 50 ms en upload et 50 ms en download (~100 ms de RTT). Une limite rate: "10mbit" s'applique aux deux directions. Cela compte particulièrement avec les profils /asymmetric : pour tester une direction précise (par ex. 400 Mbps en download), appliquez un profil dont le débit symétrique correspond à ce goulot, puis changez de profil pour tester l'autre direction.

L'outil peut être exécuté dans plusieurs modes :

  • On-the-Fly : Pour appliquer rapidement des dégradations temporaires directement depuis la ligne de commande.
  • Batch : Pour exécuter des séquences de test automatisées en parcourant des profils de dégradation prédéfinis.
  • Interactive : Pour le contrôle en temps réel des conditions réseau, idéal pour le débogage et les tests exploratoires.
  • Validate : Pour vérifier la syntaxe et l'exactitude logique des fichiers de profil avant utilisation.

Capacités

  • Limitation de débit (TBF), délai, gigue, perte de paquets, duplication, corruption, réordonnancement et limites de file d'attente (netem)
  • Mise en forme symétrique ingress/egress via un périphérique IFB
  • Mode dry-run pour prévisualiser les commandes tc sans les appliquer
  • Statistiques tc -s optionnelles en mode Batch (--show-stats) et Interactive (stats, watch stats)
  • Validation des profils avec nom de fichier, index de profil et description dans les rapports d'erreur

Configuration

Elina-TC est une application Python et nécessite Python 3.7+ sur un système d'exploitation Linux.

1. Prérequis : Assurez-vous d'avoir les packages système nécessaires installés. Sur Debian/Ubuntu, cela peut être fait avec :

sudo apt-get update && sudo apt-get install -y python3-pip python3-venv iproute2

2. Télécharger et décompresser l'outil :

wget https://api.latence.ca/software/elina-tc.zip
unzip elina-tc.zip
cd elina-tc-release

3. Configurer un environnement virtuel (Recommandé) : Ceci est fortement recommandé pour isoler les dépendances d'Elina-TC.

python3 -m venv venv
source venv/bin/activate

4. Installer Elina-TC : * Pour l'outil en ligne de commande principal et l'interface Web (beta) :

pip install .[ui]

Cela rendra la commande elina-tc disponible et installera les bibliothèques nécessaires pour le serveur web.

5. Configuration des Sudoers (CRITIQUE) :

L'interface utilisateur et certaines fonctionnalités CLI exécutent elina-tc en utilisant sudo. Pour un fonctionnement sans mot de passe, vous devez configurer votre fichier sudoers pour permettre à votre utilisateur d'exécuter la commande elina-tc sans mot de passe.

Tout d'abord, trouvez le chemin complet de la commande :

# Assurez-vous que votre environnement virtuel est actif
which elina-tc
# Exemple de sortie : /home/user/elina-tc-release/venv/bin/elina-tc

Ensuite, ajoutez la ligne correspondante au fichier sudoers. Remplacez votre_nom_utilisateur et le chemin d'exemple par vos détails réels. Utilisez sudo visudo pour éditer /etc/sudoers en toute sécurité :

votre_nom_utilisateur ALL=(ALL) NOPASSWD: /home/votre_nom_utilisateur/elina-tc-release/venv/bin/elina-tc

Modes d'utilisation (Interface en ligne de commande)

Une fois installé, Elina-TC est exécuté à l'aide de la commande elina-tc. Note : Toutes les commandes qui modifient les règles réseau nécessitent des privilèges sudo.

1. Mode Validate

  • Vérifie les fichiers de profil pour les erreurs :
elina-tc --validate -f profiles/satellite/profiles_LEO_Starlink.json

2. Mode On-the-Fly

  • Applique des dégradations directement :
elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
  • Cela appliquera 100 ms de délai et 1 % de perte de paquets à tout le trafic passant par eth0.
  • Les paramètres on-the-fly utilisent les mêmes clés que les champs de profil (voir Paramètres de profil ci-dessous), par exemple : delay, jitter, loss, corrupt, rate, duplicate, reorder.

3. Mode Batch

  • Exécute des séquences de test à partir de profils :
elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats
  • Options utiles : -n COUNT (nombre de cycles), --loop (exécution continue), --start_at "YYYY-MM-DD HH:MM:SS" (démarrage planifié), --dry-run (affiche les commandes tc sans les appliquer), -d SEC (durée par défaut par phase). Vous pouvez passer plusieurs fichiers -f pour enchaîner des séquences de profils.

4. Mode Interactive

  • Pour le contrôle en direct et le débogage :
elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive

Commandes interactives (session continue) :

  • help — liste les commandes disponibles
  • list — affiche tous les profils chargés
  • apply <index_or_name> [for Xs] [with stats] — applique un profil par index ou sous-chaîne de description ; for 30s optionnel efface automatiquement après X secondes ; with stats optionnel affiche tc -s après l'application
  • status — affiche les règles tc en egress et ingress (ifb0)
  • stats [interface] — affiche les statistiques tc -s détaillées
  • watch stats [interval] — statistiques en direct, rafraîchies toutes les interval secondes (par défaut : 2) ; Ctrl+C pour arrêter
  • clear — efface toutes les règles tc de l'interface et de ifb0
  • exit / quit — quitte la session et nettoie

L'interface Web (Beta)

Elina-TC inclut une interface Web complémentaire (Beta) qui simplifie les opérations fréquentes sans passer par le CLI. Après pip install .[ui] et la configuration sudoers ci-dessus :

cd web_ui
python3 elina-tc-ui.py
# Ouvrir http://127.0.0.1:5000/ dans un navigateur

Déroulement typique :

  1. Discover Interfaces — liste les adaptateurs et sélectionnez celui à dégrader.
  2. Browse Profiles — l'arbre des profils se charge automatiquement ; cliquez un fichier JSON pour l'ouvrir dans l'éditeur.
  3. Edit & Save — modifiez le JSON dans l'éditeur et cliquez Save pour l'écrire sur le disque.
  4. Validate — exécute les mêmes contrôles que elina-tc --validate sur le fichier sélectionné.
  5. Apply — exécute toutes les phases du fichier séquentiellement (comme le mode Batch), ou utilisez On-the-Fly pour une chaîne de dégradation ponctuelle.
  6. Stats / Clear — affiche les statistiques tc -s ou retire les règles de l'interface et de ifb0.

Sécurité : N'exposez pas l'UI à des réseaux non fiables ; elle effectue des opérations réseau privilégiées via sudo. Plus de détails dans web_ui/README_web_ui.md du package.

Travailler avec les profils

Les profils sont des fichiers JSON ou CSV qui définissent une ou plusieurs phases de dégradation. Les scénarios préconstruits sont sous profiles/ ; vos propres scénarios doivent aller sous profiles/custom/ afin de ne pas modifier la bibliothèque.

Créer un nouveau profil

  1. Copiez un modèle depuis profiles/custom/ (ou tout fichier de la bibliothèque) vers un nouveau nom, par ex. profiles/custom/my_scenario.json.
  2. Modifiez les champs (voir Paramètres de profil). Un fichier peut être un objet unique ou un tableau de phases pour les séquences en mode Batch.
  3. Validez avant utilisation :
elina-tc --validate -f profiles/custom/my_scenario.json
  1. Appliquez-le (Batch ou Interactive) :
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json -n 1
# ou
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json --interactive

Exemple minimal (une seule phase) :

{
  "description": "Flaky 4G Mobile in a Vehicle",
  "duration_sec": "120",
  "rate": "25mbit",
  "delay": "70ms",
  "jitter": "30ms",
  "delay_dist": "normal",
  "loss": "0.8%"
}

Astuce : Le package inclut un modèle de prompt IA sous profiles/_prompt-profile-generator/ et un schéma JSON sous profiles/schema/elina-tc-profile-schema.json si vous souhaitez qu'un assistant rédige un profil valide. Exécutez toujours --validate sur les fichiers générés.

Modifier un profil existant

  • CLI / fichiers : Ouvrez le .json ou .csv dans un éditeur, enregistrez, puis --validate et réappliquez. Préférez copier les fichiers de la bibliothèque dans profiles/custom/ avant de les modifier.
  • Interface Web : Sélectionnez le fichier dans l'arbre, éditez dans le panneau, cliquez Save, puis Validate / Apply. L'UI modifie des fichiers existants ; elle ne crée pas de nouveaux noms de profil — créez-les d'abord sur le disque (ou copiez un modèle).

Paramètres de profil

Omettez tout paramètre dont vous n'avez pas besoin. Les chaînes vides sont ignorées.

Paramètre Exemple Notes
description "Congested Wi-Fi" Affiché pour le matching Interactive list / apply
duration_sec "30" Secondes pendant lesquelles cette phase reste active en mode Batch
rate "100mbit" Limite de débit (TBF). Unités : kbit/mbit/gbit ou kbps/mbps/gbps
tbf_burst "128kb" Rafale du token bucket ; des valeurs par défaut s'appliquent si omis (--default-tbf-burst)
tbf_latency "50ms" Attente max dans la file TBF ; des valeurs par défaut s'appliquent si omis
delay "100ms" Latence de base (ms/us/s)
jitter "10ms" Variation du délai — nécessite delay
delay_dist "normal" uniform, normal, pareto, paretonormal — nécessite jitter
loss "1%" Pourcentage de perte de paquets
loss_correlation "25%" Rend la perte plus en rafales — nécessite loss
duplicate "0.5%" Duplication de paquets
corrupt "0.1%" Corruption de bits
reorder "5%" Livraison hors ordre
reorder_correlation "20%" — nécessite reorder
reorder_gap "5" Écart en paquets — nécessite reorder
netem_limit "1000" Nombre max de paquets dans la file netem

Les fichiers CSV utilisent les mêmes noms de colonnes (voir profiles/custom/custom_profiles.csv). Les lignes de commentaire commençant par # sont ignorées.

La bibliothèque de profils prédéfinis

Elina-TC est livré avec une bibliothèque étendue de profils de dégradation dans le répertoire profiles/, organisés par technologie réseau :

  • /basic : Profils d'exemple introductifs et polyvalents — un bon point de départ.
  • /custom : Emplacement pour vos propres profils, avec des modèles JSON/CSV à copier.
  • /cellular : Émule les conditions de réseau mobile. Comprend des profils pour la 4G LTE basés sur les identifiants de classe QoS (QCI) et la 5G basés sur les identifiants QoS 5G (5QI) et le découpage réseau (eMBB, URLLC). Parfait pour tester les applications mobiles, les appareils IoT et les cas d'utilisation de véhicules connectés (V2X).
  • /satellite : Simule les caractéristiques uniques des réseaux satellites. Comprend des profils pour les constellations en orbite terrestre basse (LEO) comme Starlink (faible latence, performances variables), l'orbite terrestre moyenne (MEO) et les satellites géostationnaires (GEO) traditionnels (latence élevée et stable). Idéal pour les applications maritimes, aérospatiales et IoT distantes.
  • /wireless : Modélise les réseaux locaux sans fil courants. Contient des profils pour diverses conditions WiFi (idéales, congestionnées), Bluetooth et réseaux IoT basse consommation, vous aidant à tester les applications dans des environnements domestiques, de bureau ou d'appareils courte portée.
  • /asymmetric : Simule des réseaux avec différentes caractéristiques upload/download (DOCSIS, FTTH, 4G/5G). Comme Elina-TC met en forme de façon symétrique, ces profils sont destinés à être appliqués une direction à la fois — voir la note sur la mise en forme symétrique sous Comment ça fonctionne.
  • /industrial : Modélise les réseaux trouvés dans les environnements de technologie opérationnelle (OT). Comprend des profils pour les protocoles industriels tels que Profinet, EtherNet/IP et Modbus. Essentiel pour tester la résilience des systèmes d'automatisation industrielle et SCADA.
  • /impairments : Contient des profils génériques de base conçus pour tester la résilience des applications contre des problèmes spécifiques. Comprend des séquences pour une perte de paquets progressivement croissante, une latence croissante ou la simulation d'un chemin Internet congestionné. Parfait pour identifier les points de rupture des applications.

Utilisation d'Elina-TC avec un générateur de trafic

La véritable puissance d'Elina-TC est libérée lorsqu'il est utilisé pour contrôler les conditions réseau pour le trafic généré par un autre outil, tel qu'Elina-TG.

  • Sur la machine serveur (exécutant Elina-TC) : Utilisez Elina-TC pour appliquer une condition réseau spécifique (par exemple, un réseau mobile 5G instable) à l'interface réseau du serveur.
  • Sur la machine cliente (exécutant Elina-TG) : Utilisez Elina-TG pour générer une charge de travail d'application réaliste (par exemple, une simulation d'appel Zoom) dirigée vers le serveur.

Cette combinaison vous permet de mesurer précisément comment votre application se comporte dans des scénarios de dégradation réseau spécifiques, reproductibles et réalistes.

Notes importantes

  • Permissions : Presque toutes les commandes elina-tc qui modifient le réseau nécessitent des privilèges sudo. Note : Si vous avez configuré sudo sans mot de passe pour elina-tc à l'étape 5 de la Configuration ci-dessus, ceci ne s'applique pas — aucun mot de passe ne vous sera demandé.
  • Instantanés d'état : Avant de modifier une interface, Elina-TC enregistre automatiquement la configuration tc existante dans un fichier journal horodaté (elina-tc_state_*.log) dans votre répertoire actuel, fournissant une piste d'audit.
  • Nettoyage : Elina-TC est conçu pour nettoyer de manière robuste toutes ses règles et périphériques virtuels lorsqu'il se termine ou est interrompu (Ctrl+C).
  • Utilisation concurrente : Une seule exécution d'Elina-TC peut contrôler une interface donnée à la fois (et le périphérique partagé ifb0). Une seconde exécution est refusée avec une erreur claire jusqu'à la fin de la première. Les fichiers de verrouillage se trouvent sous $TMPDIR/elina-tc-locks/ par défaut (ELINA_TC_LOCK_DIR pour remplacer).
  • Documentation détaillée : Pour la référence complète de la ligne de commande (elina-tc -h), le tableau des codes d'erreur et les README du package, consultez les fichiers inclus dans la distribution.

Dépannage

Symptôme À vérifier
elina-tc: command not found Activez l'environnement virtuel (source venv/bin/activate) et confirmez l'installation avec which elina-tc. Relancez pip install .[ui] depuis la racine du package si besoin.
Permission refusée / mot de passe demandé à chaque fois Les modes d'application nécessitent sudo. Pour l'interface Web (et le CLI sans mot de passe), configurez l'entrée sudoers avec le chemin complet renvoyé par which elina-tc.
Erreurs de validation de profil (EC1004–EC1010) Exécutez elina-tc --validate -f <fichier>. Causes fréquentes : mauvaises unités (100ms et non 100), jitter sans delay, loss_correlation sans loss, pourcentage hors 0–100. Corrigez l'index/description signalé et revalidez.
Paramètre on-the-fly inconnu (EC1003) Utilisez les mêmes clés que les paramètres de profil (ex. delay 50ms loss 1%). Les valeurs doivent suivre chaque clé.
Interface déjà utilisée (EC3001) / conflit ifb0 partagé Un autre processus Elina-TC (session CLI ou apply Web UI) détient encore le verrou. Quittez ou effacez cette session d'abord. Les verrous obsolètes d'un processus tué sont généralement récupérés automatiquement ; fichiers sous $TMPDIR/elina-tc-locks/.
Échec tc / ip / modprobe (EC2001) Vérifiez que vous êtes sous Linux avec iproute2 installé, que le nom d'interface est correct (ip link), et que le module ifb peut se charger (sudo modprobe ifb).
RTT mesuré ≈ 2× le delay du profil Attendu : la mise en forme est symétrique. delay: "50ms" ajoute ~50 ms dans chaque sens (~100 ms de RTT).
L'interface Web ne peut pas appliquer / l'enregistrement échoue Confirmez pip install .[ui], que sudoers est configuré, et que l'UI est ouverte sur l'hôte (http://127.0.0.1:5000/). N'exposez pas l'UI à des réseaux non fiables.
Règles restantes après un crash Exécutez sudo elina-tc -i <iface> --interactive clear. Elina-TC nettoie normalement à la sortie ou avec Ctrl+C.

Les erreurs sont marquées avec des codes stables comme [EC2001]. Le tableau complet est dans documentation/ERROR_CODES.md du package ; en contactant le support, incluez le code ECnnnn et la commande exécutée.