Skip to content

Elina Traffic Generator (Elina-TG)

Introduction

Elina Traffic Generator (elina-tg) is a powerful, command-line traffic generation tool used to simulate a wide variety of application and network behaviors. It can generate multiple, concurrent streams of TCP, UDP, and RTP traffic with highly configurable parameters, including packet size, variable rates, IPv4/IPv6, QoS markings (DSCP), and sophisticated, customizable payloads.

Dashboard

Elina-TG can be used as a standalone tool for network testing and QoS validation. It can also run alongside LatenceTech's QoS-Agent on the same network path: Elina-TG generates application-like load while the Agent measures latency, jitter, and loss on the Analyzer dashboards.

Dashboard

How it works

Elina-TG operates in a client/server model. A "client" instance reads a flow configuration file and sends traffic, while a "server" instance listens for that traffic, measures key metrics like packet loss and jitter, and logs the results. The tool can run in client, server, or both modes (for simple loopback tests on a single machine). It also includes a powerful schedule mode to orchestrate complex, time-based test sequences, and an aggregate mode to merge stats from multiple runs.

Setup

The release package is a self-contained Linux binary (plus configs and documentation). No Python install step is required.

System requirements:

  • Linux x86_64
  • GLIBC 2.35 or newer (e.g. Ubuntu 22.04+ / Debian 12+). Older hosts such as Ubuntu 20.04 (GLIBC 2.31) cannot run the binary.

1. Download and Unpack the tool:

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

2. Verify the binary:

./elina-tg --help

Always invoke it as ./elina-tg from the elina-tg-release directory (it is not added to your PATH).

Modes of Operation

1. A Simple Loopback Test (First Steps) This is the best way to verify your installation. It runs both a client and a server on your local machine for 15 seconds.

# Run the test in verbose mode and save results
./elina-tg both --duration 15 -v --stats_file my_first_test_results.json

After the run, a human-readable summary is printed to the console, and detailed JSON statistics are saved to the specified file.

2. A Client/Server Test (Two Machines) This simulates traffic over a real network link.

  • On the Server Machine (e.g., IP 192.168.1.101): Start the server to listen for traffic defined in the basic config file.
./elina-tg server --config configs/basic/flows_config_basic.json --listen_ip 0.0.0.0 -v
  • On the Client Machine: Send traffic to the server for 60 seconds.
./elina-tg client --config configs/basic/flows_config_basic.json --dest_ip 192.168.1.101 --duration 60 -v

3. Scheduler Mode (Automated Test Sequences) This mode executes a series of client/server actions defined in a schedule file. It's ideal for emulating complex, time-varying traffic patterns.

# Run the pre-defined ITU-T G.1051 e-Gaming simulation
./elina-tg schedule --schedule_config configs/itu_g1051_egaming/schedule_config_egaming_g1051.json -v

Command-Line Reference

./elina-tg <mode> [options]

Modes

  • client — Generate traffic from a flow config.
  • server — Listen for traffic and collect statistics.
  • both — Run client and server together (loopback / single-host tests).
  • schedule — Run a timed sequence from a schedule config (JSON or CSV).
  • aggregate — Merge multiple JSON stats files into one report.

Common options

  • --config FILE — Flow configuration JSON (default: configs/basic/flows_config_basic.json).
  • --dest_ip IP — Client destination IP (default: 127.0.0.1).
  • --listen_ip IP — Server listen IP (default: 0.0.0.0).
  • --base_port PORT — Base port for flows; each flow uses base_port + index unless overridden (default: 5000).
  • --duration SECONDS — How long the client sends traffic (default: 10).
  • --stats_file PATH — Write JSON stats. If you pass a bare filename, a UTC timestamp is appended.
  • --stats_interval SECONDS — Print a live stats snapshot every N seconds (0 = disabled).
  • --ipv6 — Force IPv6 (also auto-enabled if an IPv6 address is detected in --dest_ip / --listen_ip).
  • -v / -vv — Verbose / debug logging. -q — Quiet.
  • --version — Show version and exit.

Scheduling and time sync

  • --start_at DATETIME — Start the client at a specific time (ISO 8601 UTC recommended, e.g. 2025-08-27T14:30:00Z).
  • --schedule_config FILE — Schedule file for schedule mode (.json or .csv).
  • --check_time_sync — Check clock sync (NTP and/or custom sync) before starting.
  • --time_sync_port_offset OFFSET — Port offset relative to base_port for the custom sync service (default: -1).
  • --time_sync_threshold SECONDS — Max acceptable clock difference (default: 1.0).
  • --ntp_server_host HOST — NTP server to query (default: pool.ntp.org).

Aggregate mode

  • --inputs FILE [FILE ...] — Input JSON stats files to merge.
  • --output FILE — Aggregated report path (default: aggregate_report.json).
./elina-tg aggregate --inputs run1.json run2.json --output campaign_report.json

Flow Configuration Reference

Flow configs are JSON objects. Each top-level key is a unique Flow ID. Ports are assigned as base_port + flow_index unless dest_port_override is set. A JSON Schema is available at configs/schemas/flow-config.schema.json for editor validation.

Minimal annotated example (configs/basic/flows_config_basic.json):

{
  "F1_UDP_SIMPLE": {
    "protocol": "UDP",
    "size": 128,
    "rate": 10,
    "type": "BASIC_UDP_PAYLOAD",
    "dscp": 0
  },
  "F2_TCP_SIMPLE": {
    "protocol": "TCP",
    "size": 512,
    "rate": 5,
    "type": "BASIC_TCP_STREAM",
    "concurrent_connections": 5,
    "enable_keepalive": true,
    "start_delay_seconds": 1
  },
  "F3_RTP_AUDIO_SIM": {
    "protocol": "RTP",
    "size": 172,
    "rate": 50,
    "type": "SIMPLE_AUDIO_SIM",
    "dscp": 46,
    "rtp_config": {
      "payload_type": 96,
      "ssrc": "auto",
      "media_clock_rate": 8000,
      "simulated_media_rate": 50
    }
  }
}

Common parameters

  • protocol (required) — "UDP", "TCP", or "RTP".
  • size (required) — Target packet size in bytes.
  • rate — Static packets per second. Use 0 for maximum speed. Ignored if rate_profile or rate_control is set. One of rate, rate_profile, or rate_control is required.
  • type — User-defined string embedded in the payload for identification.
  • start_delay_seconds — Delay before this flow starts sending.
  • dest_port_override — Override the auto-assigned destination port.
  • dscp — DSCP value (0–63) for IP QoS marking.

Rate control

  • rate_profile — Array of { "rate", "duration_seconds" } phases. Overrides rate.
  • rate_control — Granular control; overrides rate and rate_profile:
    • Burst: "mode": "burst" with packets_per_burst, rate_in_burst_pps, pause_between_bursts_ms
    • Inter-packet gap: "mode": "ipg" with ipg_ms

Payload, TCP, and RTP

  • payload_config — mode: "random" (default), "pattern" (hex), or "file". Optional incremental_fields to embed counters at byte offsets.
  • tcp_config — concurrent_connections, enable_keepalive, behavior ("stream" or "request_response"), plus response size/timeout/server delay for request-response.
  • rtp_config (required for RTP) — payload_type, ssrc ("auto" or integer), media_clock_rate, simulated_media_rate, optional marker_bit_logic.

Advanced Features

Server echo (packet reflection)

Set "server_config": { "behavior": "echo" } on a UDP or TCP flow so the server reflects packets back to the sender. Useful for round-trip style tests.

./elina-tg both --config configs/features/flows_config_echo.json --duration 15 -v

UDP sequence tracking (loss / out-of-order)

Combine payload incremental_fields with "server_config": { "sequence_tracking": { "enabled": true, "offset": N, "size": 4 } }. The server reports estimated loss and out-of-order counts in the stats JSON.

./elina-tg both --config configs/features/flows_config_seq_tracking.json --duration 15 -v

Live stats

Use --stats_interval N to print a stats snapshot every N seconds during a run.

Aggregate mode

Merge stats from multi-run or multi-node campaigns:

./elina-tg aggregate --inputs node_a.json node_b.json --output combined.json

CSV schedules

--schedule_config accepts .csv as well as .json. See configs/features/schedule_example.csv for the column layout (event_id, action, start_UTC_datetime, start_offset_from_previous_end, params_json).

Reading Results

Console summary

At the end of a client, server, or both run (unless -q), Elina-TG prints a summary table:

  • Client — per-flow packets sent, bytes sent, and achieved bitrate.
  • Server — per-port packets/bytes received and average jitter (UDP inter-arrival or RTP RFC 3550, depending on the flow).

A progress bar is shown during client / both runs when not in quiet mode.

JSON stats file (--stats_file)

Top-level structure:

{
  "overall_simulation_summary": {},
  "client_flow_details": {},
  "server_port_activity": {}
}
  • overall_simulation_summary — Version, start/end times, IP family, and the CLI arguments used (useful for reproducibility).
  • client_flow_details — Per flow ID: config echo-back plus packets_sent, bytes_sent, achieved_rate_pps, achieved_bitrate_bps, and timing fields.
  • server_port_activity — Per port: packets/bytes received, TCP connection counts, optional echo counters, UDP jitter_stats, and per-SSRC RTP jitter under ssrc_data. With sequence tracking enabled, loss/OOO estimates appear here as well.

Verbosity levels: -q (errors only), default (info + summary), -v (detailed), -vv (debug).

For the full field list, see documentation/Statistics_Logs.md in the package.

The Predefined Profile Library

Elina-TG comes with a rich library of simulation profiles in the configs/ directory.
You will need to modify them to fit your use cases.
These are organized by category:

  • /basic — Simple getting-started configs (default flows + a minimal schedule).
  • /features — Advanced feature demos (payloads, burst/IPG, echo, sequence tracking, TCP/UDP/RTP variants, CSV schedule example).
  • /ipv6 — IPv6 (and dual-stack) flow examples.
  • /iot — IoT-style patterns (e.g. water-meter heartbeat and periodic stats over a schedule).
  • /teams & /zoom — Emulated Microsoft Teams and Zoom video-call traffic, including realistic QoS markings.
  • /itu_g1051_egaming — Scheduler-based ITU-T G.1051 e-Gaming simulation.
  • /itu_g1051_dronecontrol — Highly asymmetrical remote-drone control traffic (pilot uplink + video downlink).

For detailed instructions on using these advanced profiles, please refer to the simulating-*.md guides located within each respective directory. An overview of all configs is also in configs/README-configs.md.

Visualisation of Results in LatenceTech Dashboards

Elina-TG does not connect to the QoS-Agent or Analyzer. Run it alongside an Agent that is already measuring the same network path: generate a specific application load (for example a Zoom or gaming profile) and observe latency, jitter, and packet loss change on the Analyzer dashboards in real time.

Important Notes

  • Linux / GLIBC: The release binary requires GLIBC 2.35+ (Ubuntu 22.04 or newer). On older systems you will see an error such as version 'GLIBC_2.35' not found.
  • Permissions for DSCP/QoS: On some systems, setting DSCP values may require elevated privileges (e.g., sudo ./elina-tg ...).
  • Scheduler Paths: When using the scheduler, ensure the flow_config_file paths inside your schedule file are correct and relative to the project's root directory.
  • Detailed Documentation: For a complete overview of all features and the JSON statistics schema, see README.md and documentation/Statistics_Logs.md in the package.