Skip to content

Elina Traffic Controller (Elina-TC)

Introduction

Elina Traffic Controller (elina-tc) is a powerful command-line network emulator designed to disturb, impair, or "shape" the inbound and outbound IP traffic of a host. It introduces precise, repeatable impairments like latency, jitter, packet loss, and rate limits to simulate various network conditions. This version features a robust, refactored codebase, automatic stripping of percentage symbols from profile values, and correct handling of common size unit shorthands (e.g., "128k" for kilobyte burst). It also includes significantly enhanced pre-application validation for profile parameters, providing clear, detailed error feedback. Elina-TC can be used as a standalone tool or integrated with LatenceTech's QoS-Agent and Analyzer platform for real-time monitoring of the impact of these impairments on your application's performance.

How it works

Elina-TC shall be installed and configured on the host machine whose network is to be tested (often where the QoSAgent is also running). Elina-TC leverages the underlying Linux utilities tc (Traffic Control), netem (Network Emulator), and ifb (Intermediate Functional Block) to create a symmetric shaping environment. This means that any applied profile will affect both upload (egress) and download (ingress) traffic, providing a complete and realistic simulation of network bottlenecks.

Setup

Elina-TC is a Python script and requires Python 3.7+ and the iproute2 package (which provides the tc command) to be installed on your Linux agent.

1) Download the tool:

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

2) Unzip and move into the directory

Modes of Operation (Command Line Interface)

Elina-TC is a flexible command-line tool that can be run in several modes. All commands that apply rules must be run with sudo.

1) Validation Mode (Safe First Step)

Before applying any rules, you can validate your profile files for syntactic and logical errors. This mode does not require sudo.

# Validate a specific profile file:
python3 ./elina-tc.py --validate -f profiles/satellite/profiles_GEO_HTS.json

# Validate multiple profile files:
python3 ./elina-tc.py --validate -f profiles/basic/profiles_config.json profiles/impairments/profiles_FlakyWIFI_MobileEdge.json

# Validate all profile files found in the default profiles directory:
python3 ./elina-tc.py --validate

2) On-the-Fly Mode (Quick Tests)

For applying simple impairments without needing a pre-defined profile file. The impairment is applied for a default_duration_per_profile (defaulting to 30 seconds, which can be changed with the -d flag).

# Apply 100ms of delay, 1% loss, 0.05% corruption, and limit TBF burst to 128KB on interface eth0 for default duration
sudo python3 ./elina-tc.py -i eth0 --onthefly "delay 100ms loss 1% corrupt 0.05% tbf_burst 128k"

3) Batch Mode (Automation)

For running automated test scenarios from the profile library. This mode is ideal for CI/CD integration and long-running, repeatable tests.

# Run through the entire Flaky Wi-Fi simulation on eth0 for one cycle
sudo python3 ./elina-tc.py -i eth0 -n 1 -f profiles/impairments/profiles_FlakyWIFI_MobileEdge.json

# Continuously cycle through multiple impairment profiles
sudo python3 ./elina-tc.py -i eth0 -f profiles/impairments/profiles_FlakyWIFI_MobileEdge.json profiles/impairments/profiles_Congested_Internet_Path.json --loop

# Run a batch mode with a scheduled start time
sudo python3 ./elina-tc.py -i eth0 -f profiles/ThroughputRate_Degradation.json --num_cycles 1 --start_at "2025-08-20 18:30:00"

4) Interactive Mode (Live Control & Direct Commands)

This mode allows for live, manual control of network conditions, or to execute single interactive commands directly from the command line without entering a continuous interactive shell. This is perfect for demonstrations, hands-on debugging, or scripting specific actions.

Entering a Continuous Interactive Session:

# Start an interactive session, loading profiles from the specified file for 'list' and 'apply' commands
sudo python3 ./elina-tc.py -i eth0 -f profiles/satellite/profiles_LEO_Starlink.json --interactive

Once launched into the continuous session, you can use commands like list, apply <name/index> [for Xs], status, and clear.

Executing a Single Interactive Command Directly: This is how the Elina-TC Web UI interacts with the CLI for specific actions.

# Apply a profile by its exact description (case-sensitive) and automatically clear it after 30 seconds
sudo python3 ./elina-tc.py -i eth0 -f profiles/satellite/profiles_LEO_Starlink.json --interactive apply "LEO Starlink - Baseline Conditions (Uncongested)" for 30s

# Get the current TC status on the interface and then exit
sudo python3 ./elina-tc.py -i eth0 --interactive status

# Clear all TC rules on the interface and then exit
sudo python3 ./elina-tc.py -i eth0 --interactive clear

The Profile Library

Elina-TC comes with a rich library of expertly crafted profiles located in the profiles/ directory. These are organized by category:

  • /impairments: Simulates general network degradation patterns like rising latency or packet loss.
  • /satellite: Simulates specific satellite links (GEO, MEO, LEO).
  • /asymmetric: Simulates links with different upload/download speeds (Fiber, Cable, 5G/4G, DOCSIS).
  • /cellular: Simulates network impairment profiles for LTE QCI, 5G 5QI, 5G Slices, and cellular IoT
  • /industrial: Simulates capabilities of industrial (OT) networks such as EtherNetIP, Scada, Profinet, etc.
  • /wireless: Simulates wireless links with specific capabilities for WIFI, IoT, Bluetooth.
  • /basic: A basic profiles with multiple phases of impairments to test elina-tc.
  • /custom: Templates for you to create new profiles adaptated to your needs.

Visualisation of Results in LatenceTech Dashboards

Changing network conditions with Elina-tc will directly impact the measured quality and latency of the connectivity. The results, as measured by the QoS-Agent, will be displayed on the Analyzer's real-time dashboards within a few seconds, allowing you to observe the cause-and-effect relationship between network impairments and your application's performance.

Web User Interface Mode (Beta) We have included a beta version of a Web UI for your testing. The purpose of the UI is to facilitate interaction with Elina-TC for users less at ease with the CLI. The UI provides a visual way to browse profiles, view their content, edit them, apply profiles on selected network interface, and monitor status.

Setup for Web UI: With appropriate privileges and permissions, install the Python Flask and psutil packages: pip install Flask psutil. Configure sudoers to allow passwordless execution of elina-tc.py (refer to web_ui/README_web_ui.md for details). Then, check or adjust your firewall settings to open port 5000 (or another port if configured). Refer to the specific web ui README file for details on deployment and use.

Important Notes

  • Sudo Requirement: All modes that modify the network or interact directly with tc commands (e.g., apply, status, clear) require sudo privileges. The --dry-run and basic --validate modes do not.
  • Symmetric Shaping: Remember that all rules are applied to both upload and download traffic using the IFB device.
  • Enhanced Validation: Profiles are now pre-validated for correct formatting, value ranges, and logical dependencies. Malformed profiles will prevent tc commands from being attempted, providing clearer error feedback that includes the source filename, profile index, and description.
  • Usage Caution: This tool directly modifies the host's networking. It is highly recommended to use it on dedicated test interfaces or in isolated virtual machines to avoid disrupting critical network traffic. The script is designed to automatically clean up all rules on exit or interruption.

Additional Information

There are multiple README files in the elina-tc program providing additional technical details on the usage modes and options. A specific file explains our use of TBF parameters. There is also a test plan and several README files providing details on the predefine profiles.