Skip to content

Elina Traffic Controller (Elina-TC)

Introduction

Elina-TC is a powerful, command-line network impairment and emulation tool for Linux. It provides a user-friendly interface to the Linux kernel's built-in Traffic Control (tc) and NetEm (netem) subsystems, enabling you to simulate a wide variety of realistic network conditions on a given network interface.

Elina-TC excels as a standalone tool for network testing, application resilience analysis, and performance validation. It’s also designed to be integrated with a traffic generator, such as Elina-TG, allowing you to generate application traffic while simultaneously degrading the network path. This enables you to measure and understand the direct impact of network impairments on application performance.

How it works

Elina-TC applies network impairment rules to the ingress (download) and egress (upload) traffic of a specified network interface, allowing you to test the impact of network conditions on your application. It leverages an Intermediate Functional Block (ifb) virtual device to make these changes.

Important — symmetric shaping: Impairments are applied in both directions. A profile with delay: "50ms" adds about 50ms on upload and 50ms on download (~100ms to RTT). A rate: "10mbit" limit applies to both directions. This matters especially when using /asymmetric profiles: to test a specific direction (e.g. 400 Mbps download), apply a profile whose symmetric rate matches that bottleneck, then switch profiles to test the other direction.

The tool can be run in several modes:

  • On-the-Fly: For quickly applying temporary impairments directly from the command line.
  • Batch: For running automated test sequences by cycling through predefined impairment profiles.
  • Interactive: For real-time control of network conditions, ideal for debugging and exploratory testing.
  • Validate: For checking the syntax and logical correctness of profile files before use.

Capabilities

  • Rate limiting (TBF), delay, jitter, packet loss, duplication, corruption, reordering, and queue limits (netem)
  • Symmetric ingress/egress shaping via an IFB device
  • Dry-run mode to preview tc commands without applying them
  • Optional tc -s statistics in Batch Mode (--show-stats) and Interactive Mode (stats, watch stats)
  • Profile validation with filename, profile index, and description in error reports

Setup

Elina-TC is a Python application and requires Python 3.7+ on a Linux operating system.

1. Prerequisites: Ensure you have the necessary system packages installed. On Debian/Ubuntu, this can be done with:

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

2. Download and Unpack the tool:

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

3. Set up a Virtual Environment (Recommended): This is highly recommended to isolate the Elina-TC dependencies.

python3 -m venv venv
source venv/bin/activate

4. Install Elina-TC: * For the core command-line tool and the Web UI (beta):

pip install .[ui]

This will make the elina-tc command available and install the libraries needed for the web server.

5. Sudoers Configuration (CRITICAL):

The UI and some CLI features execute elina-tc using sudo. For passwordless operation, you must configure your sudoers file to allow your user to run the elina-tc command without a password.

First, find the command's full path:

# Make sure your virtual environment is active
which elina-tc
# Example output: /home/user/elina-tc-release/venv/bin/elina-tc

Then, add the corresponding line to the sudoers file. Replace your_username and the example path with your actual details. Use sudo visudo to safely edit /etc/sudoers:

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

Usage Modes (Command Line Interface)

Once installed, Elina-TC is run using the elina-tc command. Note: All commands that modify network rules require sudo privileges.

1. Validate Mode

  • Checks profile files for errors:
elina-tc --validate -f profiles/satellite/profiles_LEO_Starlink.json

2. On-the-Fly Mode

  • Applies impairments directly:
elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
  • This will apply 100ms of delay and 1% packet loss to all traffic through eth0.
  • On-the-fly parameters use the same keys as profile fields (see Profile parameters below), for example: delay, jitter, loss, corrupt, rate, duplicate, reorder.

3. Batch Mode

  • Runs test sequences from profiles:
elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats
  • Useful options: -n COUNT (number of cycles), --loop (run forever), --start_at "YYYY-MM-DD HH:MM:SS" (scheduled start), --dry-run (print tc commands without applying), -d SEC (default duration per phase). You can pass multiple -f files to chain profile sequences.

4. Interactive Mode

  • For live control and debugging:
elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive

Interactive commands (continuous session):

  • help — list available commands
  • list — display all loaded profiles
  • apply <index_or_name> [for Xs] [with stats] — apply a profile by index or description substring; optional for 30s auto-clears after X seconds; optional with stats shows tc -s after apply
  • status — show tc rules on egress and ingress (ifb0)
  • stats [interface] — show detailed tc -s statistics
  • watch stats [interval] — live stats refreshing every interval seconds (default: 2); Ctrl+C to stop
  • clear — clear all tc rules from the interface and ifb0
  • exit / quit — leave the session and clean up

The Web UI (Beta)

Elina-TC includes a complementary Web UI (Beta) that simplifies frequent operations without using the CLI directly. After pip install .[ui] and the sudoers setup above:

cd web_ui
python3 elina-tc-ui.py
# Open http://127.0.0.1:5000/ in a browser

Typical workflow:

  1. Discover Interfaces — list adapters and select the one to impair.
  2. Browse Profiles — the profile tree loads automatically; click a JSON file to open it in the editor.
  3. Edit & Save — modify the JSON in the editor and click Save to write it back to disk.
  4. Validate — run the same checks as elina-tc --validate on the selected file.
  5. Apply — run all phases in the file sequentially (like Batch Mode), or use On-the-Fly for a one-shot impairment string.
  6. Stats / Clear — show tc -s statistics or remove rules from the interface and ifb0.

Security: Do not expose the UI to untrusted networks; it performs privileged network operations via sudo. More detail is in web_ui/README_web_ui.md in the package.

Working with Profiles

Profiles are JSON or CSV files that define one or more impairment phases. Prebuilt scenarios live under profiles/; your own scenarios should go under profiles/custom/ so library files stay intact.

Create a new profile

  1. Copy a template from profiles/custom/ (or any existing library file) to a new name, e.g. profiles/custom/my_scenario.json.
  2. Edit the fields (see Profile parameters). A file can be a single object or an array of phases for Batch Mode sequences.
  3. Validate before use:
elina-tc --validate -f profiles/custom/my_scenario.json
  1. Apply it (Batch or Interactive):
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json -n 1
# or
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json --interactive

Minimal example (single phase):

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

Tip: The package includes an AI prompt template under profiles/_prompt-profile-generator/ and a JSON schema under profiles/schema/elina-tc-profile-schema.json if you want an assistant to draft a valid profile for you. Always run --validate on generated files.

Edit an existing profile

  • CLI / files: Open the .json or .csv in any editor, save, then --validate and re-apply. Prefer copying library files into profiles/custom/ before changing them.
  • Web UI: Select the file in the tree, edit in the panel, click Save, then Validate / Apply. The UI edits existing files; it does not create new profile filenames — create those on disk (or copy a template) first.

Profile parameters

Omit any parameter you do not need. Empty strings are ignored.

Parameter Example Notes
description "Congested Wi-Fi" Shown in Interactive list / apply matching
duration_sec "30" Seconds this phase stays active in Batch Mode
rate "100mbit" Bandwidth limit (TBF). Units: kbit/mbit/gbit or kbps/mbps/gbps
tbf_burst "128kb" Token-bucket burst; defaults apply if omitted (--default-tbf-burst)
tbf_latency "50ms" Max TBF queue wait; defaults apply if omitted
delay "100ms" Base latency (ms/us/s)
jitter "10ms" Delay variation — requires delay
delay_dist "normal" uniform, normal, pareto, paretonormal — requires jitter
loss "1%" Packet loss percentage
loss_correlation "25%" Makes loss burstier — requires loss
duplicate "0.5%" Packet duplication
corrupt "0.1%" Bit corruption
reorder "5%" Out-of-order delivery
reorder_correlation "20%" — requires reorder
reorder_gap "5" Gap in packets — requires reorder
netem_limit "1000" Max packets in the netem queue

CSV files use the same column names (see profiles/custom/custom_profiles.csv). Comment lines starting with # are skipped.

The Predefined Profile Library

Elina-TC comes with an extensive library of impairment profiles in the profiles/ directory, organized by network technology:

  • /basic: Introductory, general-purpose example profiles — a good starting point.
  • /custom: Place for your own profiles, including JSON/CSV templates to copy.
  • /cellular: Emulates mobile network conditions. Includes profiles for 4G LTE based on QoS Class Identifiers (QCI) and 5G based on 5G QoS Identifiers (5QI) and network slicing (eMBB, URLLC). Perfect for testing mobile apps, IoT devices, and connected vehicle (V2X) use cases.
  • /satellite: Simulates the unique characteristics of satellite networks. Includes profiles for Low Earth Orbit (LEO) constellations like Starlink (low latency, variable performance), Medium Earth Orbit (MEO), and traditional Geostationary (GEO) satellites (high, stable latency). Ideal for maritime, aerospace, and remote IoT applications.
  • /wireless: Models common wireless local area networks. Contains profiles for various Wi-Fi conditions (ideal, congested), Bluetooth, and low-power IoT networks, helping you test applications in home, office, or short-range device environments.
  • /asymmetric: Simulates networks with different upload and download characteristics (DOCSIS, FTTH, 4G/5G). Because Elina-TC shapes symmetrically, these profiles are meant to be applied one direction at a time — see the symmetric-shaping note under How it works.
  • /industrial: Models networks found in Operational Technology (OT) environments. Includes profiles for industrial protocols such as Profinet, EtherNet/IP, and Modbus. Essential for testing the resilience of industrial automation and SCADA systems.
  • /impairments: Contains generic, building-block profiles designed to test application resilience against specific problems. Includes sequences for progressively worsening packet loss, increasing latency, or simulating a congested internet path. Perfect for identifying application breaking points.

Using Elina-TC with a Traffic Generator

The true power of Elina-TC is unlocked when it is used to control the network conditions for traffic generated by another tool, such as Elina-TG.

  • On the Server Machine (running Elina-TC): Use Elina-TC to apply a specific network condition (e.g., a flaky 5G mobile edge network) to the server's network interface.
  • On the Client Machine (running Elina-TG): Use Elina-TG to generate a realistic application workload (e.g., a Zoom call simulation) directed at the server.

This combination allows you to precisely measure how your application performs under specific, repeatable, and realistic network impairment scenarios.

Important Notes

  • Permissions: Nearly all elina-tc commands that modify the network require sudo privileges. Note: If you configured passwordless sudo for elina-tc in step 5 of Setup above, this does not apply — you will not be prompted for a password.
  • State Snapshots: Before modifying an interface, Elina-TC automatically saves the existing tc configuration to a timestamped log file (elina-tc_state_*.log) in your current directory, providing an audit trail.
  • Cleanup: Elina-TC is designed to robustly clean up all its rules and virtual devices when it exits or is interrupted (Ctrl+C).
  • Concurrent use: Only one Elina-TC run may control a given interface at a time (and the shared ifb0 device). A second run is refused with a clear error until the first exits. Lock files live under $TMPDIR/elina-tc-locks/ by default (ELINA_TC_LOCK_DIR to override).
  • Detailed Documentation: For the full command-line reference (elina-tc -h), error-code table, and package READMEs, see the files included in the distribution.

Troubleshooting

Symptom What to check
elina-tc: command not found Activate the virtual environment (source venv/bin/activate) and confirm install with which elina-tc. Re-run pip install .[ui] from the package root if needed.
Permission denied / asked for a password every time Apply modes need sudo. For the Web UI (and passwordless CLI), configure the sudoers entry to the full path returned by which elina-tc.
Profile validation errors (EC1004–EC1010) Run elina-tc --validate -f <file>. Common causes: bad units (100ms not 100), jitter without delay, loss_correlation without loss, percentage outside 0–100. Fix the reported profile index/description and re-validate.
Unknown on-the-fly parameter (EC1003) Use the same keys as profile parameters (e.g. delay 50ms loss 1%). Values must follow each key.
Interface already in use (EC3001) / shared ifb0 conflict Another Elina-TC process (CLI session or Web UI apply) still holds the lock. Exit or clear that session first. Stale locks from a killed process are usually reclaimed automatically; lock files live under $TMPDIR/elina-tc-locks/.
tc / ip / modprobe failed (EC2001) Confirm you are on Linux with iproute2 installed, the interface name is correct (ip link), and the ifb module can load (sudo modprobe ifb).
Measured RTT is ~2× the profile delay Expected: shaping is symmetric. delay: "50ms" adds ~50ms each way (~100ms RTT).
Web UI cannot apply / save fails Confirm pip install .[ui], sudoers is set, and the UI is opened on the host (http://127.0.0.1:5000/). Do not expose the UI to untrusted networks.
Rules left behind after a crash Run sudo elina-tc -i <iface> --interactive clear. Elina-TC normally cleans up on exit or Ctrl+C.

Errors are tagged with stable codes like [EC2001]. The full table is in documentation/ERROR_CODES.md inside the package; when contacting support, include the ECnnnn code and the command you ran.