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.

For a quick start, please refer to the "1st-test-guide.md" document, which provides a complete walk-through.

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.

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.

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
  1. Download and Unpack the tool:
wget https://api.latence.ca/software/elina-tc.zip
unzip elina-tc.zip
cd elina-tc-release
cp -r src/elina_tc/pyarmor_runtime_000000/ venv/lib/python3.12/site-packages/
  1. Set up a Virtual Environment (Recommended): This is highly recommended to isolate the Elina-TC dependencies.
python3 -m venv venv
source venv/bin/activate
  1. Install Elina-TC:
    • For the core command-line tool and the Web UI (beta):
# This installs elina-tc and its runtime dependencies (like tqdm)
pip install .[ui]

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

  1. 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-project/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/user/elina-tc-project/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:
sudo elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
  • This will apply 100ms of delay and 1% packet loss to all traffic through eth0.

3. Batch Mode

  • Runs test sequences from profiles:
sudo elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats

4. Interactive Mode

  • For live control and debugging:
sudo elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive
  • Once inside, use commands like list, apply "5G - 5QI-82 (V2X)", watch stats, and clear.

The Web UI (Beta)

Elina-TC also includes a complementary Interactive User Interface (Beta). It’s designed to simplify the use of the CLI and make frequent operations easier. You can find detailed information, including setup and usage instructions, in the web_ui/README_web_ui.md file.

The Predefined Profile Library

Elina-TC comes with an extensive library of expertly crafted impairment profiles located in the profiles/ directory. These are organized by network technology to help you quickly simulate real-world conditions:

  • /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. Includes profiles for broadband technologies like DOCSIS cable and Fiber-to-the-Home (FTTH), where download speeds are typically much higher than upload speeds.

  • /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.
  • 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).
  • Detailed Documentation: For a complete overview of all features and command-line arguments, please refer to the main README.md file included in the package.