Table of Contents

1. Console

1.1. Overview

The console uses TRex Client API for controlling TRex. It gives the ability to control the TRex server and get statistic in real-time.

  • It does not save it is own state, it only caches server state. It syncs the cache state in connection phase.

  • Only one connection can have the R/W capability (change the state of the server for example, start traffic, or change port state).

  • There could be many read-only connections for same user same ports, so user can acquire some port and start traffic in one Console/script and get statistic from another Console in read only mode

  • There is an ability to acquire specific ports (or all of them)

  • The commands are in python argparse format, --help will show the command detail and -h the short version of it

  • Ability to show stats in real time.

The following pages show simple tutorial of TRex console:STL, ASTF and EMU

1.2. Tutorial

Some examples on how to use the Console and TRex

1.2.1. Prepare TRex configuration file

If you haven’t configure TRex yet follow this tutorial

Goal

Define the TRex physical or virtual ports and create configuration file.

Follow this chapter first time configuration

1.2.2. Load TRex server, Simple Port commands

Run trex in interactive mode

[bash]>sudo ./t-rex-64 -i

on the same machine from a different window connect to trex using the command

[bash]>./trex-console

Before we start transmitting traffic lets see that the port’s configuration is as we desire. We can use the command portattr in the console to see our port’s configuration.

trex>portattr
usage: portattr [-h] [-p PORTS [PORTS ...] | -a] [--prom {on,off}]
                [--link {up,down}] [--led {on,off}] [--fc {none,tx,rx,full}]
                [--vxlan-fs [VXLAN_FS [VXLAN_FS ...]]] [--supp]
                [--mult {on,off}]

Sets port attributes

optional arguments:
  -h, --help            show this help message and exit
  -p PORTS [PORTS ...], --port PORTS [PORTS ...]
                        A list of ports on which to apply the command
  -a                    Set this flag to apply the command on all available
                        ports
  --prom {on,off}       Set port promiscuous on/off
  --link {up,down}      Set link status up/down
  --led {on,off}        Set LED status on/off
  --fc {none,tx,rx,full}
                        Set Flow Control type
  --vxlan-fs [VXLAN_FS [VXLAN_FS ...]]
                        UDP ports for which HW flow stats will be read from
                        layers after VXLAN
  --supp                Show which attributes are supported by current NICs
  --mult {on,off}       Set port multicast on/off

Port Status:


     port       |          0           |          1
----------------+----------------------+---------------------
driver          |       net_mlx5       |       net_mlx5
description     |  MT28800 Family [Co  |  MT28800 Family [Co
link status     |          UP          |          UP
link speed      |       100 Gb/s       |       100 Gb/s
port status     |         IDLE         |         IDLE
promiscuous     |         off          |         off
multicast       |         off          |         off
flow ctrl       |         none         |         none
vxlan fs        |          -           |          -
                |                      |
layer mode      |         IPv4         |         IPv4
src IPv4        |       1.1.1.1        |       2.2.2.2
IPv6            |         off          |         off
src MAC         |  24:8a:07:a2:f3:80   |  24:8a:07:a2:f3:81
                |                      |
Destination     |       2.2.2.2        |       1.1.1.1
ARP Resolution  |  24:8a:07:a2:f3:81   |  24:8a:07:a2:f3:80
                |                      |
VLAN            |          -           |          -
                |                      |
PCI Address     |     0000:04:00.0     |     0000:04:00.1
NUMA Node       |          0           |          0
RX Filter Mode  |    hardware match    |    hardware match
RX Queueing     |         off          |         off
Grat ARP        |         off          |         off
                |                      |

We can see that the IPv6 and also the VLAN are off.

If we want to change that we can use VLAN and IPv6 commands. But first we will need to configure the specifics ports to service mode( In service mode ports will reply to ARP, PING and etc.)

let’s say that we want to add vlan with tag 100 to port 0.

1.First we need to configure port 0 to service mode

trex>service -p 0

2.Adding VLAN with the tag 100 to port 0

trex>vlan -p 0 --vlan 100

We can use the portattr command again to verify that we indeed added vlan.

trex>portattr

Port Status

     port       |          0           |          1
----------------+----------------------+---------------------
driver          |       net_mlx5       |       net_mlx5
description     |  MT28800 Family [Co  |  MT28800 Family [Co
link status     |          UP          |          UP
link speed      |       100 Gb/s       |       100 Gb/s
port status     |         IDLE         |         IDLE
promiscuous     |         off          |         off
multicast       |         off          |         off
flow ctrl       |         none         |         none
vxlan fs        |          -           |          -
                |                      |
layer mode      |         IPv4         |         IPv4
src IPv4        |       1.1.1.1        |       2.2.2.2
IPv6            |         off          |         off
src MAC         |  24:8a:07:a2:f3:80   |  24:8a:07:a2:f3:81
                |                      |
Destination     |       2.2.2.2        |       1.1.1.1
ARP Resolution  |  24:8a:07:a2:f3:81   |  24:8a:07:a2:f3:80
                |                      |
VLAN            |         100          |          -
                |                      |
PCI Address     |     0000:04:00.0     |     0000:04:00.1
NUMA Node       |          0           |          0
RX Filter Mode  |      fetch all       |      fetch all
RX Queueing     |         off          |         off
Grat ARP        |         off          |         off

Now the traffic will be sent with vlan tag 100.

1.2.3. Transmitting traffic

Let’s start to transmit traffic with the profile stl/imix.py

To do that we need to use the start command with the argument -f. The start command has several arguments but only -f argument (the file path) is required. You can read more about the arguments using the command

trex>start -h

For now let’s transmit the traffic in all port and with multiplier of 10. Run the command

trex>start -f stl/imix.py -m 10

1.2.4. Getting the stats

Showing stats:

In order to see the stats in a textual window we can use tui Tui shows severals textual windows with stats about the traffic. The tui windows are getting updated all the time.

Run the command:

trex>tui

Dashboard and utils examples while TRex transmits the traffic

Dashboard:

Global Statistics

connection   : localhost, Port 4501                       total_tx_L2  : 2.77 Mbps
version      : STL @ v2.89                                total_tx_L1  : 2.93 Mbps
cpu_util.    : 0.03% @ 1 cores (1 per dual port)          total_rx     : 2.77 Mbps
rx_cpu_util. : 0.0% / 0 pps                               total_pps    : 959.22 pps
async_util.  : 0% / 0.93 bps                              drop_rate    : 0 bps
total_cps.   : 0 cps                                      queue_full   : 0 pkts

Port Statistics

   port   |      0       |       1      |    total
----------+--------------+--------------+-------------
owner     |         root |         root |
link      |           UP |           UP |
state     | TRANSMITTING | TRANSMITTING |
speed     |     100 Gb/s |     100 Gb/s |
CPU util. |        0.03% |        0.03% |
--        |              |              |
Tx bps L2 |    1.39 Mbps |    1.39 Mbps |   2.77 Mbps
Tx bps L1 |    1.46 Mbps |    1.46 Mbps |   2.93 Mbps
Tx pps    |   479.68 pps |   479.55 pps |  959.22 pps
Line Util.|          0 % |          0 % |
---       |              |              |
Rx bps    |    1.39 Mbps |    1.39 Mbps |   2.77 Mbps
Rx pps    |   479.68 pps |   479.55 pps |  959.22 pps
----      |              |              |
opackets  |        49270 |        49272 |       98542
ipackets  |        49270 |        49272 |       98542
obytes    |     17827594 |     17828252 |    35655846
ibytes    |     17827594 |     17828252 |    35655846
tx-pkts   |  49.27 Kpkts |  49.27 Kpkts | 98.54 Kpkts
rx-pkts   |  49.27 Kpkts |  49.27 Kpkts | 98.54 Kpkts
tx-bytes  |     17.83 MB |     17.83 MB |    35.66 MB
rx-bytes  |     17.83 MB |     17.83 MB |    35.66 MB
-----     |              |              |
oerrors   |            0 |            0 |           0
ierrors   |            0 |            0 |           0

status:  \

browse:     'ESC' - console, 'q' - quit, 'd' - dashboard, 'u' - util, 's' - streams, 'l' - latency,
dashboard:  'n' - reset view, 'o' - owned ports, 'a' - all ports, 'c' - clear, 'p' - pause,

utils:


Global Statistics

connection   : localhost, Port 4501                       total_tx_L2  : 2.77 Mbps
version      : STL @ v2.89                                total_tx_L1  : 2.93 Mbps
cpu_util.    : 0.03% @ 1 cores (1 per dual port)          total_rx     : 2.77 Mbps
rx_cpu_util. : 0.0% / 0 pps                               total_pps    : 956.95 pps
async_util.  : 0% / 0.93 bps                              drop_rate    : 0 bps
total_cps.   : 0 cps                                      queue_full   : 0 pkts

Cpu Util(%)

  Thread  | Avg | Latest | -1  | -2  | -3  | -4  | -5  | -6  | -7  | -8  | -9  | -10 | -11 | -12 | -13 | -14
----------+-----+--------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+----
 0  (0,1) |   0 |      0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0 |   0

Mbuf Util

           |   64b   |  128b   |  256b   |  512b   |  1024b  |  2048b  |  4096b  |   9kb   | RAM(MB)
-----------+---------+---------+---------+---------+---------+---------+---------+---------+--------
Total:     |   81900 |   40950 |   16380 |   16380 |   16380 |   45175 |    1024 |    1024 |     145
Used:      |         |         |         |         |         |         |         |         |
Socket 0:  |      32 |       0 |       0 |       0 |       2 |    8194 |       0 |       0 |      16
Percent:   |      0% |      0% |      0% |      0% |      0% |     18% |      0% |      0% |

status:  |

browse:     'ESC' - console, 'q' - quit, 'd' - dashboard, 'u' - util, 's' - streams, 'l' - latency,
ustats:

To navigate between the different windows press ESC and then press the letter that represents the window you want.

We can also use the command stats to get stats. But in this command we are getting stats that are relevant to the moment we ran the command.

Streams:

trex>streams

Port 0:

 ID | name | profile |       packet type       | length |     mode   |  rate  | PG ID | next
-----------+-----------------+-----------------+-------------------------+----------+-----------
 1  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |     64 | Continuous | 28 pps |   -   |  -
 2  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |    594 | Continuous | 16 pps |   -   |  -
 3  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |   1518 | Continuous | 4 pps  |   -   |  -

Port 1:

 ID | name | profile |       packet type       | length |     mode   |  rate  | PG ID | next
-----------+-----------------+-----------------+-------------------------+----------+-----------
 1  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |     64 | Continuous | 28 pps |   -   |  -
 2  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |    594 | Continuous | 16 pps |   -   |  -
 3  |  -   |    -    | Ethernet:IP:UDP:DNS:Raw |   1518 | Continuous | 4 pps  |   -   |  -

Clearing stats

We can clear the ports stats counter with the command clear. Run the command clear to clear all the ports stats or some of the ports using the -p argument

trex>clear
trex>stats

Global Statistics

connection   : localhost, Port 4501                total_tx_L2  : 2.77 Mbps
version      : STL @ v2.89                         total_tx_L1  : 2.92 Mbps
cpu_util.    : 0.03% @ 1 cores (1 per dual port)   total_rx     : 2.77 Mbps
rx_cpu_util. : 0.0% / 0 pps                        total_pps    : 957.55 pps
async_util.  : 0% / 0.93 bps                       drop_rate    : 0 bps
total_cps.   : 0 cps                               queue_full   : 0 pkts

Port Statistics

   port    |       0      |       1      |  total
-----------+--------------+--------------+-------------
owner      |         root |         root |
link       |           UP |           UP |
state      | TRANSMITTING | TRANSMITTING |
speed      |     100 Gb/s |     100 Gb/s |
CPU util.  |        0.03% |        0.03% |
           |              |              |
Tx bps L2  |    1.39 Mbps |    1.38 Mbps |  2.77 Mbps
Tx bps L1  |    1.46 Mbps |    1.46 Mbps |  2.92 Mbps
Tx pps     |   479.56 pps |   477.99 pps | 957.55 pps
Line Util. |          0 % |          0 % |
           |              |              |
Rx bps     |    1.39 Mbps |    1.38 Mbps |  2.77 Mbps
Rx pps     |   479.56 pps |   477.99 pps | 957.55 pps
           |              |              |
opackets   |         1437 |         1437 |       2874
ipackets   |         1437 |         1437 |       2874
obytes     |       520318 |       520318 |    1040636
ibytes     |       520318 |       520318 |    1040636
tx-pkts    |   1.44 Kpkts |   1.44 Kpkts | 2.87 Kpkts
rx-pkts    |   1.44 Kpkts |   1.44 Kpkts | 2.87 Kpkts
tx-bytes   |    520.32 KB |    520.32 KB |    1.04 MB
rx-bytes   |    520.32 KB |    520.32 KB |    1.04 MB
           |              |              |
oerrors    |            0 |            0 |          0
ierrors    |            0 |            0 |          0






trex>stats
Global Statistics

connection   : csi-kiwi-02, Port 4501                     total_tx_L2  : 0 bps
version      : STL @ v2.89                                total_tx_L1  : 0 bps
cpu_util.    : 0.0% @ 2 cores (1 per dual port)           total_rx     : 611.69 bps
rx_cpu_util. : 0.0% / 0.44 pps                            total_pps    : 0 pps
async_util.  : 0% / 8.32 bps                              drop_rate    : 0 bps
total_cps.   : 0 cps                                      queue_full   : 0 pkts

Port Stat
   port    |       0     |      1      |     2      |      3
-----------+-------------+-------------+------------+-------------
owner      |       hhaim |       hhaim |      hhaim |      hhaim
link       |          UP |          UP |         UP |         UP
state      |        IDLE |        IDLE |       IDLE |       IDLE
speed      |     10 Gb/s |     10 Gb/s |    10 Gb/s |    10 Gb/s
CPU util.  |        0.0% |        0.0% |       0.0% |       0.0%
--         |             |             |            |
Tx bps L2  |       0 bps |       0 bps |      0 bps |      0 bps
Tx bps L1  |       0 bps |       0 bps |      0 bps |      0 bps
Tx pps     |       0 pps |       0 pps |      0 pps |      0 pps
Line Util. |         0 % |         0 % |        0 % |        0 %
----       |             |             |            |
Rx bps     |  471.58 bps |    0.04 bps |   0.07 bps |    140 bps
Rx pps     |    0.31 pps |       0 pps |      0 pps |   0.12 pps
----       |             |             |            |
opackets   |        6436 |        6360 |          0 |          0
ipackets   |       41368 |       10689 |       4223 |       4227
obytes     |      433348 |      407850 |          0 |          0
ibytes     |     4858520 |     1012312 |     576136 |     576624
tx-pkts    |  6.44 Kpkts |  6.36 Kpkts |     0 pkts |     0 pkts
rx-pkts    | 41.37 Kpkts | 10.69 Kpkts | 4.22 Kpkts | 4.23 Kpkts
tx-bytes   |   433.35 KB |   407.85 KB |        0 B |        0 B
rx-bytes   |     4.86 MB |     1.01 MB |  576.14 KB |  576.62 KB
-----      |             |             |            |
oerrors    |           0 |           0 |          0 |          0
ierrors    |           0 |           0 |          0 |          0


trex>stats -x

trex>stats -x
Xstats

            Name:           | Port 0: | Port 1: | Port 2: | Port 3:
----------------------------+------- -+ --------+---------+----------
rx_good_packets             |   42551 |   10902 |    4330 |    4334
rx_good_bytes               | 4823918 |  990306 |  573418 |  573890
rx_q0_packets               |   42551 |   10902 |    4330 |    4334
rx_q0_bytes                 | 4823918 |  990306 |  573418 |  573890
tx_q0_packets               |    7254 |    6909 |       0 |       0
tx_q0_bytes                 |  329990 |  291258 |       0 |       0
mac_local_errors            |       2 |       2 |       0 |       0
mac_remote_errors           |       0 |      16 |       0 |       0
rx_size_64_packets          |   12177 |    6522 |       0 |       0
rx_size_65_to_127_packets   |   17593 |    1086 |    1067 |    1071
rx_size_128_to_255_packets  |   12781 |    3264 |    3263 |    3263
rx_size_512_to_1023_packets |       0 |      24 |       0 |       0
rx_size_1024_to_max_packets |       0 |       6 |       0 |       0
rx_multicast_packets        |   35565 |    4335 |    4330 |    4334
rx_total_packets            |   42556 |   10903 |    4332 |    4334
rx_total_bytes              | 4824548 |  990442 |  573672 |  573890
tx_total_packets            |    7254 |    6909 |       0 |       0
tx_size_64_packets          |    7209 |    6894 |       0 |       0
tx_size_65_to_127_packets   |      15 |      15 |       0 |       0
tx_size_512_to_1023_packets |      24 |       0 |       0 |       0
tx_size_1024_to_max_packets |       6 |       0 |       0 |       0
tx_broadcast_packets        |    7073 |    6894 |       0 |       0
rx_l3_l4_xsum_error         |       0 |      68 |       0 |       0
out_pkts_untagged           |    7254 |    6909 |       0 |       0
# this shows the multiple profile active
trex>profiles
Port 0:

  Profile ID    |   state    | stream ID
----------------+------------+-----------
       _        |  STREAMS   | [1, 2, 3]

Port 1:

  Profile ID    |   state    | stream ID
----------------+------------+-----------

Port 2:

  Profile ID    |   state    | stream ID
----------------+------------+-----------

Port 3:

  Profile ID    |   state    | stream ID
----------------+------------+-----------

1.2.5. traffic manipulation

In order to pause the traffic’s transmitting we can use the command pause

trex>pause

The pause command work only on active ports

We can resume stopped traffic with the command resume.

trex>resume

The resume command work only on paused ports.

We can also stop the traffic with the command stop

trex>stop

The stop command work only on active ports

1.3. Common Arguments

This section includes arguments that are common to many commands In the command they will be marked like this (arg name)

1.3.1. Port mask

this gives the ability to choose batch of ports

$command   [--port/-p 1 2 3]

  port mask :
    [--port 1 2 3]  : port 1,2,3
    [--port 0.<profile_id>] allocate profiles with the specified id

  The default is all of the ports when the -p argument is not being used.

1.3.2. Packet capturing

Follow this tutorial

1.3.3. Duration

duration in second or in min or hours

$command [-d 100] [-d 10m] [-d 1h]

  duration:
   -d 100 : in sec
   -d 10m : in min
   -d 1h  : in hours

1.3.4. Multiplier

$command [-m 100] [-m 10bps] [-m 10kbps] [-m 10mbps] [-m 10gbps] [-m 10bpsl1] [-m 10kbpsl1] [-m 10mbpsl1] [-m 10gbpsl1] [-m 10pps] [-m 10kpps] [-m 10mpps] [-m 40%]

  multiplier :

  -m 100                     : multiply stream file by this factor
  -m 10bps,..,-m 10gbps      : from graph calculate the maximum rate as this bandwidth ( for each port L2 bandwidth)
  -m 10bpsl1,..,-m 10gbpsl1  : from graph calculate the maximum rate as this bandwidth ( for each port L1 bandwidth)
  -m 10pps,...,-m 10mpps     : from graph calculate the maximum rate as this pps       ( for each port )
  -m 40%                     : from graph calculate the maximum rate as this percent from total port  ( for each port L1 bandwidth)

1.4. List of the commands

>help
Console Commands:

capture -                      Manage PCAP captures
debug -                        Internal debugger for development.
events -                       Shows events log
help -                         Shows This Help Screen
history -                      Manage the command history
plugins -                      Show / load / use plugins
quit -                         Exit the console
tui -                          Shows a graphical console
verbose -                      Shows or set verbose mode

Common Commands:

acquire -                      Acquire ports
arp -                          Performs a port ARP resolution
clear -                        Clear cached local statistics
connect -                      Connects to the TRex server and acquire ports
disconnect -                   Disconnect from the TRex server
global_cfg -                   Set global configuration parameters
ipv6 -                         Configures IPv6 of a port
l2 -                           Configures a port in L2 mode
l3 -                           Configures a port in L3 mode
map -                          Maps ports topology
ns -                           Network namespace
ping -                         Pings the server / specific IP
pkt -                          Sends a Scapy format packet
portattr -                     Sets port attributes
release -                      Release ports
reset -                        Reset ports
scan6 -                        Search for IPv6 neighbors
shutdown -                     Shutdown the server
stats -                        Show various statistics
vlan -                         Configures VLAN tagging for a port.

Have a look in the stateless manual for how to use capture commands to capture traffic in rx or tx, using linux name-space for creating CP protocols simulation and more