Traffic profile modules

The TRex STLProfile traffic profile includes a number of streams. The profile is a program of related streams. Each stream can trigger another stream. Each stream can be named. For a full set of examples, see Manual.

Example:

def create_stream (self):

    # create a base packet and pad it to size
    size = self.fsize - 4; # no FCS
    base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    base_pkt1 =  Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    base_pkt2 =  Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    pad = max(0, size - len(base_pkt)) * 'x'


    return STLProfile( [ STLStream( isg = 1.0, # star in delay in usec
                                    packet = STLPktBuilder(pkt = base_pkt/pad),
                                    mode = STLTXCont( pps = 10),
                                    ),

                         STLStream( isg = 2.0,
                                    packet  = STLPktBuilder(pkt = base_pkt1/pad),
                                    mode    = STLTXCont( pps = 20),
                                    ),

                         STLStream(  isg = 3.0,
                                     packet = STLPktBuilder(pkt = base_pkt2/pad),
                                     mode    = STLTXCont( pps = 30)

                                    )
                        ]).get_streams()

STLProfile class

class trex.stl.trex_stl_streams.STLProfile(streams=None)[source]

Describe a list of streams

# STLProfile Example

profile =  STLProfile( [ STLStream( isg = 10.0, # star in delay 
                            name    ='S0',
                            packet = STLPktBuilder(pkt = base_pkt/pad),
                            mode = STLTXSingleBurst( pps = 10, total_pkts = self.burst_size),
                            next = 'S1'), # point to next stream 

                 STLStream( self_start = False, # stream is  disabled enable trow S0
                            name    ='S1',
                            packet  = STLPktBuilder(pkt = base_pkt1/pad),
                            mode    = STLTXSingleBurst( pps = 10, total_pkts = self.burst_size),
                            next    = 'S2' ),

                 STLStream(  self_start = False, # stream is  disabled enable trow S0
                             name   ='S2',
                             packet = STLPktBuilder(pkt = base_pkt2/pad),
                             mode = STLTXSingleBurst( pps = 10, total_pkts = self.burst_size )
                            )
                ]).get_streams()
Parameters
streamslist of trex.stl.trex_stl_streams.STLStream

a list of stream objects

get_streams()[source]

Get the list of streams

static load_yaml(yaml_file)[source]

Load (from YAML file) a profile with a number of streams

static load_json(json_file)[source]

Load (from JSON file) a profile with a number of streams

static load_py(python_file, direction=0, port_id=0, **kwargs)[source]

Load from Python profile

static load_pcap(pcap_file, ipg_usec=None, speedup=1.0, loop_count=1, vm=None, packet_hook=None, split_mode=None, min_ipg_usec=None, src_mac_pcap=False, dst_mac_pcap=False)[source]

Convert a pcap file with a number of packets to a list of connected streams.

packet1->packet2->packet3 etc

parameters
pcap_filestring

Name of the pcap file

ipg_usecfloat

Inter packet gap in usec. If IPG is None, IPG is taken from pcap file

speedupfloat

When reading the pcap file, divide IPG by this “speedup” factor. Resulting IPG is sped up by this factor.

loop_countuint16_t

Number of loops to repeat the pcap file

vmlist

List of Field engine instructions

packet_hookCallable or function

will be applied to every packet

split_modestr

should this PCAP be split to two profiles based on IPs / MACs used for dual mode can be ‘MAC’ or ‘IP’

min_ipg_usecfloat

Minimum inter packet gap in usec. Used to guard from too small IPGs.

src_mac_pcapbool

Source MAC address will be taken from pcap file if True.

dst_mac_pcapbool

Destination MAC address will be taken from pcap file if True.

return

STLProfile

static load(filename, direction=0, port_id=0, **kwargs)[source]

Load a profile by its type. Supported types are: * py * json * pcap file that converted to profile automatically

Parameters

filename : string as filename direction : profile’s direction (if supported by the profile) port_id : which port ID this profile is being loaded to kwargs : forward those key-value pairs to the profile

dump_as_pkt()[source]

Dump the profile as Scapy packet. If the packet is raw, convert it to Scapy before dumping it.

to_json()[source]

convert profile to JSON object

static from_json(json_data)[source]

create profile object from JSON object

dump_to_code(profile_file=None)[source]

Convert the profile to Python native profile.

STLStream

class trex.stl.trex_stl_streams.STLStream(name=None, packet=None, mode=<trex.stl.trex_stl_streams.STLTXCont object>, enabled=True, self_start=True, isg=0.0, flow_stats=None, next=None, stream_id=None, action_count=0, random_seed=0, mac_src_override_by_pkt=None, mac_dst_override_mode=None, dummy_stream=False, start_paused=False, core_id=-1)[source]

One stream object. Includes mode, Field Engine mode packet template and Rx stats

# STLStream Example


base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
pad = max(0, size - len(base_pkt)) * 'x'

STLStream( isg = 10.0, # star in delay 
           name    ='S0',
           packet = STLPktBuilder(pkt = base_pkt/pad),
           mode = STLTXSingleBurst( pps = 10, total_pkts = 1),
           next = 'S1'), # point to next stream 

Stream object

Parameters
namestring

Name of the stream. Required if this stream is dependent on another stream, and another stream needs to refer to this stream by name.

packetSTLPktBuilder see trex.stl.trex_stl_packet_builder_scapy.STLPktBuilder

Template packet and field engine program. Example: packet = STLPktBuilder(pkt = base_pkt/pad)

mode : trex.stl.trex_stl_streams.STLTXCont or trex.stl.trex_stl_streams.STLTXSingleBurst or trex.stl.trex_stl_streams.STLTXMultiBurst

enabledbool

Indicates whether the stream is enabled.

self_startbool

If False, another stream activates it.

isgfloat

Inter-stream gap in usec. Time to wait until the stream sends the first packet.

flow_statstrex.stl.trex_stl_streams.STLFlowStats

Per stream statistic object. See: STLFlowStats

nextstring

Name of the stream to activate.

stream_id :

For use by HLTAPI.

action_countuint16_t

If there is a next stream, number of loops before stopping. Default: 0 (unlimited).

random_seed: uint32_t

If given, the seed for this stream will be this value. Useful if you need a deterministic random value.

mac_src_override_by_pktbool

Template packet sets src MAC.

mac_dst_override_mode=NoneSTLStreamDstMAC_xx

Template packet sets dst MAC.

dummy_streambool

For delay purposes, will not be sent.

start_pausedbool

Experimental flag, might be removed in future! Stream will not be transmitted until un-paused.

core_id: int

Pins the stream to core_id in case core_id is specified and 0 <= core_id < number of cores. Default value = -1. Negative value (default) keeps the current behavior.

get_id()[source]

Get the stream id after resolution

has_custom_mac_addr()[source]

Return True if src or dst MAC were set as custom

get_name()[source]

Get the stream name

get_next()[source]

Get next stream object

has_flow_stats()[source]

Return True if stream was configured with flow stats

get_pg_id()[source]

Returns packet group ID if exists

get_flow_stats_type()[source]

Returns flow stats type if exists

get_pkt()[source]

Get packet as string

get_pkt_len(count_crc=True)[source]

Get packet number of bytes

is_dummy()[source]

return true if stream is marked as dummy stream

get_pkt_type()[source]

Get packet description. Example: IP:UDP

static get_rate_from_field(rate_json)[source]

Get rate from json

to_pkt_dump()[source]

Print packet description from Scapy

to_code()[source]

Convert to Python code as profile

to_json()[source]

convert stream object to JSON

STLStream modes

class trex.stl.trex_stl_streams.STLTXMode(pps=None, bps_L1=None, bps_L2=None, percentage=None)[source]

mode rate speed

Speed can be given in packets per second (pps), L2/L1 bps, or port percent Use only one unit. you can enter pps =10000 oe bps_L1=10

Parameters
ppsfloat

Packets per second

bps_L1float

Bits per second L1 (with IPG)

bps_L2float

Bits per second L2 (Ethernet-FCS)

percentagefloat

Link interface percent (0-100). Example: 10 is 10% of the port link setup

# STLTXMode Example

mode = STLTXCont(pps = 10)

mode = STLTXCont(bps_L1 = 10000000) #10mbps L1

mode = STLTXCont(bps_L2 = 10000000) #10mbps L2

mode = STLTXCont(percentage = 10)   #10%
class trex.stl.trex_stl_streams.STLTXCont(**kwargs)[source]

Continuous mode

Continuous mode

# STLTXCont Example

mode = STLTXCont(pps = 10)
class trex.stl.trex_stl_streams.STLTXSingleBurst(total_pkts=1, **kwargs)[source]

Single burst mode

Single burst mode

parameters
total_pktsint

Number of packets for this burst

see trex.stl.trex_stl_streams.STLTXMode for rate

# STLTXSingleBurst Example

mode = STLTXSingleBurst( pps = 10, total_pkts = 1)
class trex.stl.trex_stl_streams.STLTXMultiBurst(pkts_per_burst=1, ibg=0.0, count=1, **kwargs)[source]

Multi-burst mode

Multi-burst mode

Parameters
pkts_per_burst: int

Number of packets per burst

ibgfloat

Inter-burst gap in usec 1,000,000.0 is 1 sec

countint

Number of bursts

see trex.stl.trex_stl_streams.STLTXMode for rate

# STLTXMultiBurst Example

mode = STLTXMultiBurst(pps = 10, pkts_per_burst = 1,count 10, ibg=10.0)
class trex.stl.trex_stl_streams.STLFlowStats(pg_id, vxlan=False, ieee_1588=False)[source]

Define per stream basic stats

# STLFlowStats Example

flow_stats = STLFlowStats(pg_id = 7)
class trex.stl.trex_stl_streams.STLTaggedPktGroup(tpgid)[source]

Define per stream Tagged Packet Group statistics.

The tagged packet group appends a TPG header to the end of the payload (overriding the last 16 bytes) and keeps sequence of the packets.

It calculates statistics per tag, which can be Dot1Q or QinQ.

Note

You can’t apply the same tpgid to more than one stream.

Note

Supported only in Software mode.

# STLTaggedPktGroup Example

tpg_stats = STLTaggedPktGroup(tpgid = 7)
class trex.stl.trex_stl_streams.STLFlowLatencyStats(pg_id, vxlan=False, ieee_1588=False)[source]

Define per stream basic stats + latency, jitter, packet reorder/loss

# STLFlowLatencyStats Example

flow_stats = STLFlowLatencyStats(pg_id = 7)

STLTaggedPktGroupTagConf

class trex.stl.trex_stl_streams.STLTaggedPktGroupTagConf[source]

A class to facilitates the loading of Tagged Packet Group Tag Configurations.

classmethod load(tpg_conf_path, **kwargs)[source]

Load the Tagged Packet Group Tag Configuration. The configuration can be loaded by a Python file or a Json file.

Parameters

tpg_conf_path: Path to a Json or Python file.

static load_py(tpg_conf_path, **kwargs)[source]

Load the Tagged Packet Group Tag Configuration from a Python file. Any tunables for the Python file must be passed through the kwargs parameter. The kwargs supports the following two formats:

kwargs = {
    "tunable1": '1',
    "tunable2": "value"
}

or

kwargs = {
    "tunables": [
        '--tunable1', '1',
        '--tunable2', 'value'
    ]
}

Note

The old way of passing tunables in the format of tunable1=1,tunable2=value is not supported for this class.

Parameters

tpg_conf_path: Path to a Python file that contains the tag configuration. One such example can be seen in stl/tpg_tags_conf.py.

static load_json(tpg_conf_path)[source]

Load the Tagged Packet Group Tag Configuration from a Json file.

Parameters

tpg_conf_path: Path to a Json file that contains the tag configuration. One such example can be seen in stl/tpg_tags_conf.json.

# Tagged Packet Group Tag Configuration - Python File

import argparse


MIN_VLAN, MAX_VLAN = 1, (1 << 12) - 1


class TPGConf():

    def get_tpg_conf(self, tunables, **kwargs):
        parser = argparse.ArgumentParser(description="TPG Configuration File for Dot1Q",
                                        formatter_class=argparse.ArgumentDefaultsHelpFormatter)

        parser.add_argument("--min-vlan", type=int, default=1, help="Min Vlan Tag to have in the configuration")
        parser.add_argument("--max-vlan", type=int, default=MAX_VLAN-1, help="Max Vlan Tag to have in configuration")
        args = parser.parse_args(tunables)

        if args.min_vlan < MIN_VLAN:
            raise Exception("Min Vlan must be greater or equal to {}".format(MIN_VLAN))

        if args.max_vlan >= MAX_VLAN:
            raise Exception("Max Vlan must be smaller than {}".format(MAX_VLAN))

        tpg_conf = [
            {
                "type": "Dot1Q",
                "value": {
                    "vlan": i
                }
            } for i in range(args.min_vlan, args.max_vlan)]
        return tpg_conf


def register():
    return TPGConf()

STLProfile snippet

# STLProfile Example1


    size = self.fsize - 4; # no FCS
    base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    base_pkt1 =  Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    base_pkt2 =  Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025)
    pad = max(0, size - len(base_pkt)) * 'x'


    return STLProfile( [ STLStream( isg = 10.0, # star in delay
                                    name    ='S0',
                                    packet = STLPktBuilder(pkt = base_pkt/pad),
                                    mode = STLTXSingleBurst( pps = 10, total_pkts = 10),
                                    next = 'S1'), # point to next stream

                         STLStream( self_start = False, # stream is  disabled enable trow S0
                                    name    ='S1',
                                    packet  = STLPktBuilder(pkt = base_pkt1/pad),
                                    mode    = STLTXSingleBurst( pps = 10, total_pkts = 20),
                                    next    = 'S2' ),

                         STLStream(  self_start = False, # stream is  disabled enable trow S0
                                     name   ='S2',
                                     packet = STLPktBuilder(pkt = base_pkt2/pad),
                                     mode = STLTXSingleBurst( pps = 10, total_pkts = 30 )
                                    )
                        ]).get_streams()
# STLProfile Example2


    class STLS1(object):

        def get_streams (self, direction = 0):
            return [STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap"),
                              mode = STLTXCont(pps=1000),
                              flow_stats = STLFlowStats(pg_id = 7)),

                    STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_594B_no_crc.pcap"),
                              mode = STLTXCont(pps=5000),
                              flow_stats = STLFlowStats(pg_id = 12))
                   ]