Zum Inhalt

Elina Traffic Controller (Elina-TC)

Einführung

Elina-TC ist ein leistungsstarkes Befehlszeilenwerkzeug zur Netzwerkbeeinträchtigung und -emulation unter Linux. Es bietet eine benutzerfreundliche Oberfläche für die im Linux-Kernel integrierten Subsysteme Traffic Control (tc) und NetEm (netem) und ermöglicht es Ihnen, auf einer bestimmten Netzwerkschnittstelle eine Vielzahl realistischer Netzwerkbedingungen zu simulieren.

Elina-TC eignet sich hervorragend als eigenständiges Werkzeug für Netzwerktests, die Analyse der Anwendungsresilienz und die Leistungsvalidierung. Es ist außerdem für die Integration mit einem Verkehrsgenerator wie Elina-TG ausgelegt, sodass Sie Anwendungsverkehr erzeugen und gleichzeitig den Netzwerkpfad verschlechtern können. So können Sie die direkte Auswirkung von Netzwerkbeeinträchtigungen auf die Anwendungsleistung messen und verstehen.

Funktionsweise

Elina-TC wendet Regeln zur Netzwerkbeeinträchtigung auf den Ingress-Verkehr (Download) und den Egress-Verkehr (Upload) einer angegebenen Netzwerkschnittstelle an, sodass Sie die Auswirkung der Netzwerkbedingungen auf Ihre Anwendung testen können. Dazu verwendet es ein virtuelles Gerät vom Typ Intermediate Functional Block (ifb).

Wichtig — symmetrische Formung: Die Beeinträchtigungen werden in beide Richtungen angewendet. Ein Profil mit delay: "50ms" fügt etwa 50 ms im Upload und 50 ms im Download hinzu (~100 ms RTT). Eine Begrenzung rate: "10mbit" gilt für beide Richtungen. Das ist besonders bei den Profilen /asymmetric wichtig: Um eine bestimmte Richtung zu testen (z. B. 400 Mbps im Download), wenden Sie ein Profil an, dessen symmetrischer Durchsatz diesem Engpass entspricht, und wechseln Sie dann das Profil, um die andere Richtung zu testen.

Das Werkzeug kann in mehreren Modi ausgeführt werden:

  • On-the-Fly: Zum schnellen Anwenden vorübergehender Beeinträchtigungen direkt über die Befehlszeile.
  • Batch: Zum Ausführen automatisierter Testsequenzen durch Abarbeiten vordefinierter Beeinträchtigungsprofile.
  • Interactive: Zur Echtzeitsteuerung der Netzwerkbedingungen, ideal für Debugging und explorative Tests.
  • Validate: Zur Prüfung von Syntax und logischer Korrektheit der Profildateien vor der Verwendung.

Fähigkeiten

  • Ratenbegrenzung (TBF), Verzögerung, Jitter, Paketverlust, Duplizierung, Beschädigung, Umordnung und Warteschlangengrenzen (netem)
  • Symmetrische Ingress-/Egress-Formung über ein IFB-Gerät
  • Dry-Run-Modus zur Vorschau der tc-Befehle, ohne sie anzuwenden
  • Optionale tc -s-Statistiken im Modus Batch (--show-stats) und Interactive (stats, watch stats)
  • Validierung der Profile mit Dateiname, Profilindex und Beschreibung in den Fehlermeldungen

Konfiguration

Elina-TC ist eine Python-Anwendung und erfordert Python 3.7+ unter einem Linux-Betriebssystem.

1. Voraussetzungen: Stellen Sie sicher, dass die erforderlichen Systempakete installiert sind. Unter Debian/Ubuntu geht das mit:

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

2. Werkzeug herunterladen und entpacken:

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

3. Virtuelle Umgebung einrichten (empfohlen): Dies wird dringend empfohlen, um die Abhängigkeiten von Elina-TC zu isolieren.

python3 -m venv venv
source venv/bin/activate

4. Elina-TC installieren: * Für das Hauptbefehlszeilenwerkzeug und die Weboberfläche (Beta):

pip install .[ui]

Dadurch wird der Befehl elina-tc verfügbar, und die für den Webserver benötigten Bibliotheken werden installiert.

5. Sudoers-Konfiguration (KRITISCH):

Die Benutzeroberfläche und einige CLI-Funktionen führen elina-tc mit sudo aus. Für einen passwortlosen Betrieb müssen Sie Ihre sudoers-Datei so konfigurieren, dass Ihr Benutzer den Befehl elina-tc ohne Passwort ausführen darf.

Ermitteln Sie zunächst den vollständigen Pfad des Befehls:

# Stellen Sie sicher, dass Ihre virtuelle Umgebung aktiv ist
which elina-tc
# Beispielausgabe: /home/user/elina-tc-release/venv/bin/elina-tc

Fügen Sie dann die entsprechende Zeile zur sudoers-Datei hinzu. Ersetzen Sie ihr_benutzername und den Beispielpfad durch Ihre tatsächlichen Angaben. Verwenden Sie sudo visudo, um /etc/sudoers sicher zu bearbeiten:

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

Verwendungsmodi (Befehlszeilenschnittstelle)

Nach der Installation wird Elina-TC mit dem Befehl elina-tc ausgeführt. Hinweis: Alle Befehle, die Netzwerkregeln ändern, erfordern sudo-Rechte.

1. Modus Validate

  • Prüft Profildateien auf Fehler:
elina-tc --validate -f profiles/satellite/profiles_LEO_Starlink.json

2. Modus On-the-Fly

  • Wendet Beeinträchtigungen direkt an:
elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
  • Dadurch werden 100 ms Verzögerung und 1 % Paketverlust auf den gesamten Verkehr über eth0 angewendet.
  • On-the-Fly-Parameter verwenden dieselben Schlüssel wie die Profilfelder (siehe Profilparameter unten), zum Beispiel: delay, jitter, loss, corrupt, rate, duplicate, reorder.

3. Modus Batch

  • Führt Testsequenzen aus Profilen aus:
elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats
  • Nützliche Optionen: -n COUNT (Anzahl der Durchläufe), --loop (Endlosbetrieb), --start_at "YYYY-MM-DD HH:MM:SS" (geplanter Start), --dry-run (zeigt die tc-Befehle, ohne sie anzuwenden), -d SEC (Standarddauer pro Phase). Sie können mehrere -f-Dateien angeben, um Profilsequenzen zu verketten.

4. Modus Interactive

  • Für Live-Steuerung und Debugging:
elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive

Interaktive Befehle (fortlaufende Sitzung):

  • help — listet die verfügbaren Befehle auf
  • list — zeigt alle geladenen Profile an
  • apply <index_or_name> [for Xs] [with stats] — wendet ein Profil nach Index oder Teilzeichenfolge der Beschreibung an; optional for 30s entfernt es nach X Sekunden automatisch; optional with stats zeigt nach dem Anwenden tc -s an
  • status — zeigt die tc-Regeln für Egress und Ingress (ifb0) an
  • stats [interface] — zeigt detaillierte tc -s-Statistiken an
  • watch stats [interval] — Live-Statistiken, alle interval Sekunden aktualisiert (Standard: 2); Ctrl+C zum Beenden
  • clear — entfernt alle tc-Regeln von der Schnittstelle und von ifb0
  • exit / quit — beendet die Sitzung und räumt auf

Die Weboberfläche (Beta)

Elina-TC enthält eine ergänzende Weboberfläche (Beta), die häufige Vorgänge ohne CLI vereinfacht. Nach pip install .[ui] und der sudoers-Konfiguration oben:

cd web_ui
python3 elina-tc-ui.py
# http://127.0.0.1:5000/ in einem Browser öffnen

Typischer Ablauf:

  1. Discover Interfaces — listet die Adapter auf; wählen Sie den zu beeinträchtigenden aus.
  2. Browse Profiles — der Profilbaum wird automatisch geladen; klicken Sie auf eine JSON-Datei, um sie im Editor zu öffnen.
  3. Edit & Save — bearbeiten Sie das JSON im Editor und klicken Sie auf Save, um es auf die Festplatte zu schreiben.
  4. Validate — führt für die ausgewählte Datei dieselben Prüfungen wie elina-tc --validate aus.
  5. Apply — führt alle Phasen der Datei nacheinander aus (wie der Modus Batch), oder verwenden Sie On-the-Fly für eine einmalige Beeinträchtigungszeichenkette.
  6. Stats / Clear — zeigt tc -s-Statistiken an oder entfernt die Regeln von der Schnittstelle und von ifb0.

Sicherheit: Stellen Sie die UI nicht in nicht vertrauenswürdigen Netzen bereit; sie führt privilegierte Netzwerkvorgänge über sudo aus. Weitere Details finden Sie in web_ui/README_web_ui.md im Paket.

Mit Profilen arbeiten

Profile sind JSON- oder CSV-Dateien, die eine oder mehrere Beeinträchtigungsphasen definieren. Die vorgefertigten Szenarien befinden sich unter profiles/; Ihre eigenen Szenarien sollten unter profiles/custom/ abgelegt werden, damit die Bibliothek nicht verändert wird.

Neues Profil erstellen

  1. Kopieren Sie eine Vorlage aus profiles/custom/ (oder eine beliebige Datei der Bibliothek) unter einem neuen Namen, z. B. profiles/custom/my_scenario.json.
  2. Bearbeiten Sie die Felder (siehe Profilparameter). Eine Datei kann ein einzelnes Objekt oder ein Array von Phasen für Sequenzen im Modus Batch sein.
  3. Validieren Sie sie vor der Verwendung:
elina-tc --validate -f profiles/custom/my_scenario.json
  1. Wenden Sie sie an (Batch oder Interactive):
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json -n 1
# oder
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json --interactive

Minimales Beispiel (eine einzige Phase):

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

Tipp: Das Paket enthält eine KI-Prompt-Vorlage unter profiles/_prompt-profile-generator/ und ein JSON-Schema unter profiles/schema/elina-tc-profile-schema.json, falls ein Assistent ein gültiges Profil entwerfen soll. Führen Sie für erzeugte Dateien immer --validate aus.

Vorhandenes Profil bearbeiten

  • CLI / Dateien: Öffnen Sie die .json- oder .csv-Datei in einem Editor, speichern Sie, führen Sie dann --validate aus und wenden Sie sie erneut an. Kopieren Sie Bibliotheksdateien vorzugsweise nach profiles/custom/, bevor Sie sie bearbeiten.
  • Weboberfläche: Wählen Sie die Datei im Baum aus, bearbeiten Sie sie im Bereich, klicken Sie auf Save und dann auf Validate / Apply. Die UI bearbeitet vorhandene Dateien; sie erstellt keine neuen Profilnamen — legen Sie diese zuerst auf der Festplatte an (oder kopieren Sie eine Vorlage).

Profilparameter

Lassen Sie jeden Parameter weg, den Sie nicht benötigen. Leere Zeichenketten werden ignoriert.

Parameter Beispiel Hinweise
description "Congested Wi-Fi" Wird für die Suche mit Interactive list / apply angezeigt
duration_sec "30" Sekunden, die diese Phase im Modus Batch aktiv bleibt
rate "100mbit" Ratenbegrenzung (TBF). Einheiten: kbit/mbit/gbit oder kbps/mbps/gbps
tbf_burst "128kb" Burst des Token-Buckets; bei Weglassen gelten Standardwerte (--default-tbf-burst)
tbf_latency "50ms" Maximale Wartezeit in der TBF-Warteschlange; bei Weglassen gelten Standardwerte
delay "100ms" Basislatenz (ms/us/s)
jitter "10ms" Schwankung der Verzögerung — erfordert delay
delay_dist "normal" uniform, normal, pareto, paretonormal — erfordert jitter
loss "1%" Prozentsatz des Paketverlusts
loss_correlation "25%" Macht den Verlust burstartiger — erfordert loss
duplicate "0.5%" Duplizierung von Paketen
corrupt "0.1%" Bitfehler
reorder "5%" Auslieferung in falscher Reihenfolge
reorder_correlation "20%" — erfordert reorder
reorder_gap "5" Abstand in Paketen — erfordert reorder
netem_limit "1000" Maximale Anzahl Pakete in der netem-Warteschlange

CSV-Dateien verwenden dieselben Spaltennamen (siehe profiles/custom/custom_profiles.csv). Kommentarzeilen, die mit # beginnen, werden ignoriert.

Die Bibliothek vordefinierter Profile

Elina-TC enthält im Verzeichnis profiles/ eine umfangreiche Bibliothek von Beeinträchtigungsprofilen, geordnet nach Netzwerktechnologie:

  • /basic: Einführende, vielseitige Beispielprofile — ein guter Ausgangspunkt.
  • /custom: Ablageort für Ihre eigenen Profile, mit JSON-/CSV-Vorlagen zum Kopieren.
  • /cellular: Emuliert Mobilfunkbedingungen. Enthält Profile für 4G LTE auf Basis der QoS Class Identifiers (QCI) und für 5G auf Basis der 5G QoS Identifiers (5QI) und des Network Slicing (eMBB, URLLC). Ideal zum Testen mobiler Anwendungen, IoT-Geräte und Anwendungsfälle vernetzter Fahrzeuge (V2X).
  • /satellite: Simuliert die besonderen Eigenschaften von Satellitennetzen. Enthält Profile für Konstellationen im niedrigen Erdorbit (LEO) wie Starlink (niedrige Latenz, schwankende Leistung), im mittleren Erdorbit (MEO) und für klassische geostationäre Satelliten (GEO) (hohe, stabile Latenz). Ideal für maritime, Luft- und Raumfahrt- sowie abgelegene IoT-Anwendungen.
  • /wireless: Modelliert gängige drahtlose lokale Netze. Enthält Profile für verschiedene WLAN-Bedingungen (ideal, überlastet), Bluetooth und stromsparende IoT-Netze und hilft Ihnen, Anwendungen in Heim-, Büro- oder Kurzstreckenumgebungen zu testen.
  • /asymmetric: Simuliert Netze mit unterschiedlichen Upload-/Download-Eigenschaften (DOCSIS, FTTH, 4G/5G). Da Elina-TC symmetrisch formt, sind diese Profile dafür gedacht, jeweils eine Richtung anzuwenden — siehe den Hinweis zur symmetrischen Formung unter Funktionsweise.
  • /industrial: Modelliert Netze in Umgebungen der Betriebstechnik (OT). Enthält Profile für Industrieprotokolle wie Profinet, EtherNet/IP und Modbus. Unverzichtbar zum Testen der Resilienz von Industrieautomatisierungs- und SCADA-Systemen.
  • /impairments: Enthält allgemeine Basisprofile, um die Resilienz von Anwendungen gegenüber bestimmten Problemen zu testen. Enthält Sequenzen mit schrittweise steigendem Paketverlust, steigender Latenz oder der Simulation eines überlasteten Internetpfads. Ideal, um die Belastungsgrenzen von Anwendungen zu ermitteln.

Elina-TC mit einem Verkehrsgenerator verwenden

Ihr volles Potenzial entfaltet Elina-TC, wenn es die Netzwerkbedingungen für Verkehr steuert, der von einem anderen Werkzeug wie Elina-TG erzeugt wird.

  • Auf der Server-Maschine (mit Elina-TC): Wenden Sie mit Elina-TC eine bestimmte Netzwerkbedingung (zum Beispiel ein instabiles 5G-Mobilfunknetz) auf die Netzwerkschnittstelle des Servers an.
  • Auf der Client-Maschine (mit Elina-TG): Erzeugen Sie mit Elina-TG eine realistische Anwendungslast (zum Beispiel eine Zoom-Anrufsimulation), die an den Server gerichtet ist.

Mit dieser Kombination können Sie genau messen, wie sich Ihre Anwendung in spezifischen, reproduzierbaren und realistischen Szenarien der Netzwerkbeeinträchtigung verhält.

Wichtige Hinweise

  • Berechtigungen: Fast alle elina-tc-Befehle, die das Netzwerk verändern, erfordern sudo-Rechte. Hinweis: Wenn Sie in Schritt 5 der Konfiguration oben ein passwortloses sudo für elina-tc eingerichtet haben, gilt dies nicht — Sie werden nicht nach einem Passwort gefragt.
  • Statusmomentaufnahmen: Bevor Elina-TC eine Schnittstelle verändert, speichert es die vorhandene tc-Konfiguration automatisch in einer Protokolldatei mit Zeitstempel (elina-tc_state_*.log) in Ihrem aktuellen Verzeichnis und schafft so einen Prüfpfad.
  • Aufräumen: Elina-TC ist darauf ausgelegt, alle seine Regeln und virtuellen Geräte zuverlässig zu entfernen, wenn es beendet oder unterbrochen wird (Ctrl+C).
  • Gleichzeitige Nutzung: Nur ein Elina-TC-Lauf kann eine bestimmte Schnittstelle (und das gemeinsam genutzte Gerät ifb0) gleichzeitig steuern. Ein zweiter Lauf wird mit einer klaren Fehlermeldung abgelehnt, bis der erste beendet ist. Die Sperrdateien liegen standardmäßig unter $TMPDIR/elina-tc-locks/ (mit ELINA_TC_LOCK_DIR änderbar).
  • Ausführliche Dokumentation: Die vollständige Befehlszeilenreferenz (elina-tc -h), die Tabelle der Fehlercodes und die README-Dateien des Pakets finden Sie in den mitgelieferten Dateien.

Fehlerbehebung

Symptom Zu prüfen
elina-tc: command not found Aktivieren Sie die virtuelle Umgebung (source venv/bin/activate) und bestätigen Sie die Installation mit which elina-tc. Führen Sie bei Bedarf pip install .[ui] im Stammverzeichnis des Pakets erneut aus.
Zugriff verweigert / Passwort wird jedes Mal abgefragt Die Anwendungsmodi erfordern sudo. Für die Weboberfläche (und die passwortlose CLI) richten Sie den sudoers-Eintrag mit dem vollständigen Pfad ein, den which elina-tc zurückgibt.
Fehler bei der Profilvalidierung (EC1004–EC1010) Führen Sie elina-tc --validate -f <datei> aus. Häufige Ursachen: falsche Einheiten (100ms statt 100), Jitter ohne delay, loss_correlation ohne loss, Prozentsatz außerhalb von 0–100. Korrigieren Sie den gemeldeten Index bzw. die Beschreibung und validieren Sie erneut.
Unbekannter On-the-Fly-Parameter (EC1003) Verwenden Sie dieselben Schlüssel wie bei den Profilparametern (z. B. delay 50ms loss 1%). Auf jeden Schlüssel muss ein Wert folgen.
Schnittstelle bereits in Verwendung (EC3001) / Konflikt mit gemeinsamem ifb0 Ein anderer Elina-TC-Prozess (CLI-Sitzung oder Apply in der Web-UI) hält noch die Sperre. Beenden oder bereinigen Sie zuerst diese Sitzung. Veraltete Sperren eines beendeten Prozesses werden in der Regel automatisch freigegeben; Dateien unter $TMPDIR/elina-tc-locks/.
Fehler bei tc / ip / modprobe (EC2001) Prüfen Sie, ob Sie unter Linux mit installiertem iproute2 arbeiten, ob der Schnittstellenname korrekt ist (ip link) und ob das Modul ifb geladen werden kann (sudo modprobe ifb).
Gemessene RTT ≈ 2× das delay des Profils Erwartet: Die Formung ist symmetrisch. delay: "50ms" fügt in jede Richtung ~50 ms hinzu (~100 ms RTT).
Die Weboberfläche kann nicht anwenden / Speichern schlägt fehl Prüfen Sie pip install .[ui], die sudoers-Konfiguration und ob die UI auf dem Host geöffnet ist (http://127.0.0.1:5000/). Stellen Sie die UI nicht in nicht vertrauenswürdigen Netzen bereit.
Verbleibende Regeln nach einem Absturz Führen Sie sudo elina-tc -i <iface> --interactive clear aus. Elina-TC räumt normalerweise beim Beenden oder mit Ctrl+C auf.

Fehler sind mit stabilen Codes wie [EC2001] gekennzeichnet. Die vollständige Tabelle finden Sie in documentation/ERROR_CODES.md im Paket; geben Sie bei Kontakt mit dem Support den Code ECnnnn und den ausgeführten Befehl an.