TRex is a powerful, open-source traffic generator that is widely used for network performance testing. Its flexibility and robust feature set are largely accessible through its command-line interface (CLI). Understanding TRex command-line arguments is crucial for effectively utilizing this tool, whether you are setting up basic traffic simulations or conducting advanced network stress tests. This guide provides a detailed overview of the essential TRex command-line options, enabling you to control and customize your network testing scenarios.
Essential TRex Command Line Options Explained
TRex offers a wide array of command-line arguments to tailor its behavior to your specific testing needs. Below, we break down each option, explaining its function and usage.
Controlling Active Flows
--active-flows <number>
This experimental switch allows you to adjust the approximate number of active flows. It’s important to note that due to the nature of the flow scheduler’s quantization, this setting is not perfectly precise and may not function in all scenarios.
Example: --active-flows 500000 aims to set the active flows to around 0.5 million.
Core Dump Management
--allow-coredump
This flag enables the creation of core dump files in case of crashes or unexpected termination. Core dumps are valuable for debugging and diagnosing issues within TRex.
ARP Refresh Period
--arp-refresh-period <seconds>
Controls the frequency at which TRex sends gratuitous ARP (Address Resolution Protocol) requests for its own addresses. Gratuitous ARPs announce IP address to MAC address mappings to the network.
- A value of
0disables the sending of gratuitous ARP requests. - A positive integer specifies the period in seconds between ARP broadcasts.
Advanced Stateful Mode
--astf
Introduced in version 2.29, this flag activates the Advanced Stateful Traffic (ASTF) mode. When using this mode, the -f argument should point to a Python ASTF profile file. ASTF mode offers more sophisticated stateful traffic generation capabilities. Currently, it primarily operates in batch mode, with interactive support under development.
Hardware Threads per Interface Pair
-c <number>
Specifies the number of hardware threads to be used for each interface pair. For high-performance setups like TRex 40Gbs, it’s recommended to use at least 4 threads. TRex reserves 2 threads for internal operations, leaving the remaining threads available for user-defined tasks. The maximum usable threads are determined by the number of free threads divided by the number of interface pairs. For virtual NICs in virtual machine environments, TRex defaults to using one thread per interface pair.
Configuration File
--cfg <filename>
Specifies the path to the TRex configuration file. The configuration file allows you to set various TRex parameters, including interface settings, ports, and other system-level configurations. Refer to the TRex manual for a comprehensive list of configuration options.
Checksum Offload Control
--checksum-offload-disable
Disables IP, TCP, and UDP transmit (tx) checksum offloading. Checksum offloading is a hardware feature that calculates checksums in hardware, reducing CPU load. Disabling it forces checksum calculation in software. This option requires that all network interfaces used support checksum offloading.
Client Configuration File
--client_cfg <filename>
Specifies the YAML file that describes client clustering configurations. Client clustering is a feature that allows you to distribute TRex clients across multiple systems for large-scale simulations. Detailed information about client clustering can be found in the TRex manual under the “Client Clustering Configuration” section.
Test Duration
-d <seconds>
Sets the duration of the traffic test in seconds. TRex will run the traffic simulation for the specified amount of time.
Port-Based IP Address Assignment
-e
Similar to the -p option, but modifies the source and destination IP addresses based on the port. This ensures that all packets within the same flow originate from the same port and share the same source/destination IP addresses. This option might not be compatible with Network Behavior Analysis and Reporting (NBAR) systems, as they typically expect client IPs to originate from the same direction.
Traffic Configuration File
-f <filename>
Specifies the traffic YAML configuration file to be used. This is a mandatory option for stateful mode. The YAML file defines the traffic profiles, flows, and other parameters for the test.
Hop Count in Setup
--hops <number>
Defines the number of hops in the network setup. This is relevant only when the Rx (receive) check module is enabled. The hop count is used in latency and flow order verification. More details can be found in the TRex manual section on “Flow Order & Latency Verification.”
Interactive Mode
-i
Enables interactive mode. Currently, this mode is primarily used for stateless traffic generation. Interactive mode allows for real-time control and monitoring of the traffic generation process. Work is in progress to extend interactive mode to Advanced Stateful Traffic (ASTF).
I/O Mode
--iom <mode>
Sets the Input/Output (I/O) mode, controlling the level of output and verbosity.
0(silent): Minimal output.1(normal): Standard level of output.2(short): Reduced, concise output.
IPv6 Mode
--ipv6
Converts traffic templates to IPv6 (Internet Protocol version 6) mode. This option allows you to generate and test IPv6 traffic.
Warm-up Time
-k <seconds>
Specifies a “warm-up” period in seconds before the actual test begins. During the warm-up, TRex sends traffic but does not record statistics. This is useful when TRex is connected to a switch running Spanning Tree Protocol (STP). The warm-up traffic allows the switch to learn MAC addresses before the real test data is sent, preventing packet loss due to STP convergence. This option is primarily used with latency tests (-l option). Note: Prior to TRex version 1.82, this feature may not function correctly in virtual machine environments.
Latency Check
-l <rate/sec>
Enables a parallel latency check during the main traffic test. TRex sends latency measurement packets at the specified rate per second from each interface. This allows for concurrent latency measurements alongside the primary traffic load.
NAT Learning Mode
--learn-mode
Activates the dynamic Network Address Translation (NAT) learning mode. This feature allows TRex to learn and adapt to NAT translations performed by a device under test (DUT). Detailed information about NAT support in TRex can be found in the manual section on “NAT Support.”
NAT Learning Verification
--learn-verify
Used for testing the NAT learning mechanism itself. In this mode, TRex performs the NAT learning process as if a DUT were performing NAT, but it verifies that packets are not actually modified. This helps in validating the NAT learning functionality.
Port Limit
--limit-ports <number>
Limits the number of ports used by TRex. This option overrides the port_limit setting in the configuration file. It allows you to restrict TRex to using only a specific number of ports, even if more are available.
Port Mask for Traffic Sending
--lm <mask>
Specifies a port mask to control which ports will transmit traffic. The mask is a hexadecimal value where each bit corresponds to a port.
0x1: Only port 0 will send traffic.0x4: Only port 2 will send traffic.
This option is useful for verifying port connectivity and isolating traffic to specific ports for debugging or focused testing. You can send packets from a single port and monitor counters on the device under test (DUT).
Latency-Only Mode
--lo
Latency-only mode. TRex will only send latency packets and will not transmit traffic from configured templates or PCAP files. This mode is specifically for focusing on latency measurements without the influence of other traffic streams.
Rate Multiplier
-m <multiplier>
Applies a rate multiplier to the CPS (Connections Per Second) rate of each traffic template. TRex multiplies the base CPS rate defined in the traffic profile by the specified number. This allows you to easily scale the traffic load generated by TRex.
Precise Termination
--nc
When set, TRex terminates the test precisely at the end of the specified duration. This provides faster and more accurate test termination. By default, without this option, TRex waits for all flows to terminate gracefully, which can prolong the termination time if long-lasting flows are involved.
Disable Flow Control Change
--no-flow-control-change
Introduced in version 2.21, this option prevents TRex from automatically changing flow control settings. By default, TRex disables flow control at startup for all network interface cards (NICs) except for the Intel XL710 40G card. This option preserves the existing flow control configuration.
Disable Hardware Flow Statistics
--no-hw-flow-stat
Relevant only for Intel x710 NICs in stateless mode. Disables the use of hardware counters for flow statistics. Enabling this option may reduce the maximum achievable traffic rate but will enable reporting of RX byte count statistics, which are not available when hardware counters are used.
Daemon Mode (No Keyboard Input)
--no-key
Runs TRex in daemon mode, preventing it from taking input from the keyboard. This is useful for automated testing or when running TRex in the background.
Disable Watchdog Timer
--no-watchdog
Disables the watchdog timer. The watchdog timer is a safety mechanism that restarts TRex if it becomes unresponsive. Disabling it should be done with caution and primarily for debugging purposes.
Single Port Flow Direction
-p
Directs all packets of the same flow to originate from the same direction (either client port or server port). For each flow, TRex randomly selects either the client or server port and sends all packets for that flow from the chosen port. Source and destination IPs retain their original values as if packets were sent from both ports. This configuration means that packets from client to server and server to client in the same flow will be seen on the same port. If used with a router, policy-based routing may be required to correctly direct traffic to TRex, as standard routing rules might not suffice.
Platform Factor
-pm <factor>
Platform multiplier factor. If the test setup includes a splitter, you can use this option to multiply all statistic numbers displayed by TRex by the given factor. This allows TRex’s reported statistics to align with the counters on the device under test (DUT).
Disable ZMQ Monitor Publishers
--pubd
Disables the ZMQ (Zero Message Queue) monitor’s publishers. ZMQ is used for real-time monitoring and data streaming from TRex. Disabling publishers can reduce overhead if monitoring is not required.
Queue Drop Behavior
--queue-drop
Introduced in version 2.37. Configures TRex to not retry sending packets if sending fails due to queue full or other reasons. By default, TRex attempts to resend packets on failure. This option changes the behavior to drop packets immediately upon sending failure.
Rx Check Module
--rx-check
Enables the Rx check module. This module, running on the RX (receive) thread, randomly samples 1/sample_rate of the flows and performs checks on packet order, latency, and collects additional statistics for the sampled flows. This feature provides insights into packet delivery and performance from the receiver’s perspective.
Sleep-Based Scheduler
--sleeps
Introduced in version 2.37. Configures the scheduler to use sleep operations instead of busy-waiting. Using sleeps reduces CPU utilization and power consumption but may result in less accurate timing and scheduling compared to busy-waiting.
Software Mode (No Hardware Offload)
--software
Introduced in version 2.21. Disables all hardware rule configurations. In software mode, all received packets are processed by the software. Hardware-assisted packet dropping (during counting) is disabled. This mode is beneficial for enabling features such as:
- Per-stream statistics
- Latency measurements
- Support for packet types not natively supported by hardware flow director rules (e.g., QinQ VLAN tagging).
Software mode can also be used to run TRex on NICs that are supported by DPDK drivers (like e1000_igb) but have different hardware capabilities than expected (e.g., i350 NICs). A drawback of software mode is that the total rate of RX streams is significantly lower due to software processing overhead. Up to version 2.49 (exclusive), software mode was limited to a single TX core (and one RX core). Later versions utilize multi-queue for RX and TX, primarily for scaling virtual interfaces.
Debug Information
-v <level>
Controls the verbosity of debug information output.
1: Shows debug information during startup.3: Shows debug information during runtime in certain scenarios.
Higher debug levels may impact performance due to increased logging and output.
VLAN Mode for Flow Statistics and Latency
--vlan
Relevant only for stateless mode with Intel 82599 10G NICs. When configuring flow statistics and latency per stream rules, this option assumes that all streams use VLAN tagging.
Wait Time After NIC Initialization
-w <seconds>
Specifies additional wait time in seconds between NIC initialization and the start of traffic transmission. This can be useful if the device under test (DUT) requires extra setup time after the network interfaces are initialized. The default wait time is 1 second.
Conclusion
Mastering TRex command-line arguments is essential for harnessing the full potential of this versatile traffic generator. By understanding and utilizing these options, you can precisely control and customize your network testing scenarios, from basic performance benchmarks to complex, stateful simulations. This guide provides a comprehensive starting point for exploring the vast capabilities of TRex and effectively employing it for your network testing needs.
