======================
:author: TRex team
-:revnumber: 1.95
+:revnumber: 1.96
:quotes.++:
:numbered:
:web_server_url: http://trex-tgn.cisco.com/trex
== Stateless support (Alpha stage)
-=== High level functionality
+=== High level functionality
// maybe Feature overview
* Large scale - Supports a line rate of 14 million packets per second (mpps) per core, scalable with the number of cores
* Blazingly fast automation support
** Python 2.7/3.0 Client API
** Python HLTAPI Client API
-* Multi-user support - multiple users can interact with the same TRex instance simultaneously // added "instance"
+* Multi-user support - multiple users can interact with the same TRex instance simultaneously
==== Traffic profile example
-// Need explanation of example in figure.
+The following example shows three streams configured for Continuous, Burst, and Multi-burst traffic.
-image::images/stl_streams_example.png[title="Streams example",align="left",width={p_width}, link="images/stl_streams_example.png"]
+image::images/stl_streams_example.png[title="Stream example",align="left",width={p_width}, link="images/stl_streams_example.png"]
==== High level functionality - near future
| Tx Mode | Continuous/Burst/Multi-burst | Continuous/Burst/Multi-burst|
| ARP Emulation | Yes | Not yet - workaround |
| Automation | TCL/Python wrapper to TCL | [green]*native Python/Scapy* |
-| Automation speed sec| 30 sec | [green]*1 msec* | test of load/start/stop/get counters
+| Automation speed sec| 30 sec | [green]*1 msec* | Test of load/start/stop/get counters
| HLTAPI | Full support. 2000 pages of documentation | Limited. 20 pages of documentation|
| Per Stream statistics | 255 streams with 4 global masks | 128 rules for XL710/X710 hardware and software impl for 82599/I350/X550| Some packet type restrictions apply to XL710/X710.
| Latency Jitter | Yes | Yes |
*Interfaces*::
* Automation API: Python is the first client to implement the Python automation API.
* User interface: The console uses the Python API to implement a user interface for TRex.
-* GUI : The GUI works on top JSON-RPC2 layer
+* GUI : The GUI works on top of the JSON-RPC2 layer.
*Control of TRex interfaces*::
* Numerous users can control a single TRex server together, from different interfaces.
* A client in read-write mode can acquire a statistic in real time (with ASYNC ZMQ). This enables viewing statistics through numerous user interfaces (console and GUI) simultaneously.
*Synchronization*::
-* A client should sync with the TRex server to get the state in connection time, and cache the server information locally once the state was changed. // Not clear; avoid "should".
-* If a client crashes or exits, it should sync again after reconnecting.
-// Avoid "should". Meaning will be more clear without "should".
+* A client syncs with the TRex server to get the state in connection time, and caches the server information locally after the state has changed.
+* If a client crashes or exits, it syncs again after reconnecting.
image::images/trex_stateless_multi_user.png[title="Multiple users, per interface",align="left",width={p_width}, link="images/trex_stateless_multi_user.png"]
* *TRex*: Each TRex instance supports numerous interfaces.
// "one or more"?
-* *Interface*: Each interface supports one or more traffic profiles (TP).
+* *Interface*: Each interface supports one or more traffic profiles.
* *Traffic profile*: Each traffic profile supports one or more streams.
* *Stream*: Each stream includes:
** *Packet*: Packet template up to 9 KB
** *Mode*: Specifies how to send packets: Continuous/Burst/Multi-burst
** *Rx Stats*: Statistics to collect for each stream
** *Rate*: Rate (packets per second or bandwidth)
-** *Action*: Specifies stream to follow when the current stream is complete. (valid for Continuous or Burst modes)
+** *Action*: Specifies stream to follow when the current stream is complete (valid for Continuous or Burst modes).
=== Stateful vs Stateless
TRex Stateless support enables basic L2/L3 testing, relevant mostly for a switch or router. Using Statelss mode, it is possible to define a stream with a *one* packet template, define a program to change any fields in the packet, and run the stream in continuous, burst, or multi-burst mode.
With Stateless, you *cannot* learn NAT translation; there is no context of flow/client/server.
-* In Stateful mode, the basic building block is a flow/application (composed from many packets).
+* In Stateful mode, the basic building block is a flow/application (composed of many packets).
* Stateless mode is much more flexible, enabling you to define any type of packet, and build a simple program.
.Stateful vs Stateless features
a->b->c->d-> back to a
You can then create a program for each stream to change src_ip=10. 0.0.1-10.0.0.254. This creates traffic similar to that of Stateful mode, but with a completely different basis.
-If you are confused you probably need Stateless.
+If you are confused you probably need Stateless. :-)
=== TRex package folders
def register(): <4>
return STLS1()
----
-<1> Defines the packet. In this case, the packet is IP/UDP with 10 bytes of 'x'. For more information, see: link:http://www.secdev.org/projects/scapy/doc/[Scapy]
+<1> Defines the packet. In this case, the packet is IP/UDP with 10 bytes of 'x'. For more information, see the link:http://www.secdev.org/projects/scapy/doc/[Scapy documentation].
<2> Mode: Continuous. Rate: 1 PPS (default rate is 1 PPS)
<3> The `get_streams` function is mandatory
<4> Each traffic profile module requires a `register` function.
* (Optional) Use `-c` to add more cores.
* (Optional) Use `--cfg` to specify a different configuration file. The default is link:trex_manual.html#_create_minimum_configuration_file[trex_cfg.yaml].
+// IGNORE: this line helps rendering of next line
*Connect with console*::
In this example all the packets will be routed to `TenGigabitEthernet0/1/0` port. The following example uses the `direction` flag to change this.
-*file*:: link:{github_stl_path}/udp_1pkt_simple_bdir.py[stl/udp_1pkt_simple_bdir.py]
+*File*:: link:{github_stl_path}/udp_1pkt_simple_bdir.py[stl/udp_1pkt_simple_bdir.py]
[source,python]
----
Ether(dst="00:bb:12:34:56:01"),trex_cfg(src),"00:bb:12:34:56:01"
|=================
-Example:
*File*:: link:{github_stl_path}/udp_1pkt_1mac_override.py[stl/udp_1pkt_1mac_override.py]
print 'Done'
----
-<1> Imports native TRex API.
-<2> Imports HLT API.
+<1> Imports the native TRex API.
+<2> Imports the HLT API.
==== Tutorial: Simple IPv4/UDP packet - Simulator
Example traffic profile:
-*file*:: link:{github_stl_path}/udp_1pkt_simple.py[stl/udp_1pkt_simple.py]
+*File*:: link:{github_stl_path}/udp_1pkt_simple.py[stl/udp_1pkt_simple.py]
[source,python]
----
=== Traffic profile Tutorials
-==== Tutorial: Simple Interleave streams
+==== Tutorial: Simple Interleaving streams
*Goal*:: Demonstrate interleaving of multiple streams.
2. Burst of 10 packets
3. One stream activating another stream (see `self_start=False` in the traffic profile)
-*file*:: link:{github_stl_path}/burst_3pkt_60pkt.py[stl/burst_3pkt_60pkt.py]
+*File*:: link:{github_stl_path}/burst_3pkt_60pkt.py[stl/burst_3pkt_60pkt.py]
[source,python]
*Goal* : Use Multi-burst transmit mode
-*file*:: link:{github_stl_path}/multi_burst_2st_1000pkt.py[stl/multi_burst_2st_1000pkt.py]
+*File*:: link:{github_stl_path}/multi_burst_2st_1000pkt.py[stl/multi_burst_2st_1000pkt.py]
[source,python]
----
*Goal* : Demonstrate a limited loop of streams
-*file*:: link:{github_stl_path}/burst_3st_loop_x_times.py[stl/burst_3st_loop_x_times.py]
+*File*:: link:{github_stl_path}/burst_3st_loop_x_times.py[stl/burst_3st_loop_x_times.py]
[source,python]
----
This profile defines 3 streams, with packets of different sizes. The rate is different for each stream/size. See the link:https://en.wikipedia.org/wiki/Internet_Mix[Wikipedia article on Internet Mix].
-*file*:: link:{github_stl_path}/imix.py[stl/imix.py]
+*File*:: link:{github_stl_path}/imix.py[stl/imix.py]
[source,python]
----
----
<1> Constructs a diffrent stream for each direction (replaces src and dest).
<2> Even port id has direction==0 and odd has direction==1.
+// direction==1 not shown explicitly in the code?
<3> Field Engine program to change fields within the packets.
// we can link "Field Engine" to an appropriate location for for more info.
The following example demonstrates creating a SYN attack from many src addresses to one server.
-*file*:: link:{github_stl_path}/syn_attack.py[stl/syn_attack.py]
+*File*:: link:{github_stl_path}/syn_attack.py[stl/syn_attack.py]
[source,python]
----
The following example creates multiple flows from the same packet template. The Tuple Generator instructions are used to create two stream variables for IP and port. See link:trex_rpc_server_spec.html#_object_type_em_vm_em_a_id_vm_obj_a[here]
// clarify link
-*file*:: link:{github_stl_path}/udp_1pkt_tuple_gen.py[stl/udp_1pkt_tuple_gen.py]
+*File*:: link:{github_stl_path}/udp_1pkt_tuple_gen.py[stl/udp_1pkt_tuple_gen.py]
[source,python]
----
----
<1> Defines a struct with two dependent variables: tuple.ip, tuple.port
<2> Writes the tuple.ip variable to `IPv4.src` field offset.
-<3> Writes the tuple.port variable to `UDP.sport` field offset. Set UDP.checksum to 0.
+<3> Writes the tuple.port variable to `UDP.sport` field offset. Set `UDP.checksum` to 0.
// Hanoch: add how to set UDP.checksum to 0
0|1|2|3|4|5|6|7|8|9|0|1|2|3|4|5|6|7|8|9|0|1|2|3|4|5|6|7|8|9|0|1|
|====
-*file*:: link:{github_stl_path}/udp_1pkt_mpls_vm.py[stl/udp_1pkt_mpls_vm.py]
+*File*:: link:{github_stl_path}/udp_1pkt_mpls_vm.py[stl/udp_1pkt_mpls_vm.py]
[source,python]
----
2. Trims the packet to the size you want.
3. Updates the packet fields according to the new size.
-*file*:: link:{github_stl_path}/udp_rand_len_9k.py[stl/udp_rand_len_9k.py]
+*File*:: link:{github_stl_path}/udp_rand_len_9k.py[stl/udp_rand_len_9k.py]
[source,python]
----
)
----
<1> Defines a random stream variable with the maximum size of the packet.
-<2> Trims the packet size to the fv_rand value.
+<2> Trims the packet size to the `fv_rand` value.
<3> Fixes ip.len to reflect the packet size.
<4> Fixes udp.len to reflect the packet size.
The following example uses a header that is not supported by Scapy by default. The example demonstrates VXLAN support.
-*file*:: link:{github_stl_path}/udp_1pkt_vxlan.py[stl/udp_1pkt_vxlan.py]
+*File*:: link:{github_stl_path}/udp_1pkt_vxlan.py[stl/udp_1pkt_vxlan.py]
[source,python]
----
image::images/stl_tut_12.png[title="client->server",align="left",width={p_width}, link="images/stl_tut_12.png"]
-1. Send gratuitous ARP from B->D with server IP/MAC (58.55.1.1).
+1. Send a gratuitous ARP from B->D with server IP/MAC (58.55.1.1).
2. DUT learns the ARP of server IP/MAC (58.55.1.1).
3. Send traffic from A->C with many client IP/MAC addresses.
Then traffic can be sent from client side: A->C
-*file*:: link:{github_stl_path}/udp_1pkt_range_clients_split.py[stl/udp_1pkt_range_clients_split.py]
+*File*:: link:{github_stl_path}/udp_1pkt_range_clients_split.py[stl/udp_1pkt_range_clients_split.py]
[source,python]
----
----
<1> Stream variable.
-<2> Write it to IPv4.src.
+<2> Write it to `IPv4.src`.
.Variable per thread
Assumption: The pcap file has one packet. If the pcap file has more than one packet, this procedure loads only the first packet.
-*file*:: link:{github_stl_path}/udp_1pkt_pcap.py[stl/udp_1pkt_pcap.py]
+*File*:: link:{github_stl_path}/udp_1pkt_pcap.py[stl/udp_1pkt_pcap.py]
[source,python]
----
<1> Takes the packet from the pcap file, relative to current directory (pwd) in which you are running the script.
-*file*:: link:{github_stl_path}/udp_1pkt_pcap_relative_path.py[udp_1pkt_pcap_relative_path.py]
+*File*:: link:{github_stl_path}/udp_1pkt_pcap_relative_path.py[udp_1pkt_pcap_relative_path.py]
[source,python]
*Goal*:: Load a pcap file with a *number* of packets, creating a stream with a burst value of 1 for each packet. The inter-stream gap (ISG) for each stream is equal to the inter-packet gap (IPG).
-*file*:: link:{github_stl_path}/pcap.py[pcap.py]
+*File*:: link:{github_stl_path}/pcap.py[pcap.py]
[source,python]
----
image::images/stl_tut_pcap_file1.png[title="pcap file",align="left",width={p_width/2}, link="images/stl_tut_pcap_file1.png"]
-This figure the streams for a pcap file with 3 packets.
+This figure shows the streams for a pcap file with 3 packets.
+
* Each stream is configured to Burst mode, with 1 packet
* Each stream triggers the next stream.
* The last stream triggers the first with `action_loop=loop_count` if `loop_count` > 1.
+
The profile runs on one DP thread because it has a burst with 1 packet. (Split cannot work in this case).
-To run this example:
+To run this example, enter:
[source,bash]
----
The following example loads a pcap file to many streams, and attaches a Field Engine program to each stream. For example, the Field Engine can change the `IP.src` of all the streams to a random IP address.
-*file*:: link:{github_stl_path}/pcap_with_vm.py[stl/pcap_with_vm.py]
+*File*:: link:{github_stl_path}/pcap_with_vm.py[stl/pcap_with_vm.py]
[source,python]
----
The following example demonstrates creating an IPv6 packet within an IPv4 packet, and creating a range of IP addresses.
-*file*:: link:{github_stl_path}/udp_1pkt_ipv6_in_ipv4.py[stl/udp_1pkt_ipv6_in_ipv4.py]
+*File*:: link:{github_stl_path}/udp_1pkt_ipv6_in_ipv4.py[stl/udp_1pkt_ipv6_in_ipv4.py]
[source,python]
----
==== Tutorial: Mask instruction
-The STLVmWrMaskFlowVar is single-instruction-multiple-data Field Engine instruction. The pseudocode is as follows:
+STLVmWrMaskFlowVar is single-instruction-multiple-data Field Engine instruction. The pseudocode is as follows:
.Pseudocode
[source,bash]
*Example 1*::
-This use of STLVmWrMaskFlowVar casts a stream variable with 2 bytes to be 1 byte.
+Here, STLVmWrMaskFlowVar casts a stream variable with 2 bytes to be 1 byte.
[source,python]
----
*Example 2*::
-This use of STLVmWrMaskFlowVar shifts a variable by 8, which effectively multiplies by 256.
+Here, STLVmWrMaskFlowVar shifts a variable by 8, which effectively multiplies by 256.
[source,python]
----
*Example 3*::
-This use of STLVmWrMaskFlowVar instruction to generate the values shown in the table below as offset values for `pkt_offset`.
+Here, STLVmWrMaskFlowVar instruction to generate the values shown in the table below as offset values for `pkt_offset`.
[source,python]
----
* Automatic values such as 'port_id' which are not tunables will be provided on kwargs.
-*file*:: link:{github_stl_path}/pcap_with_vm.py[stl/pcap_with_vm.py]
+*File*:: link:{github_stl_path}/pcap_with_vm.py[stl/pcap_with_vm.py]
[source,python]
----
* Maximum number of concurrent streams on which statistics may be collected: 128
Two examples follow, one using the console and the other using the Python API.
+// immediately below is the console example; where's the Python API example?
*Console*::
The following simple traffic profile defines 2 streams and configures them with 2 different PG IDs.
-*file*:: link:{github_stl_path}/flow_stats.py[stl/flow_stats.py]
+*File*:: link:{github_stl_path}/flow_stats.py[stl/flow_stats.py]
[source,python]
----
----
-==== Tutorial: Per stream latency/Jitter [TODO]
+==== Tutorial: Per stream latency/Jitter
+
+// [TODO]
*(Future Feature - not yet implemented)*
The API creates native Scapy/Field Engine instructions.
For limitations see xref:altapi-support[here].
-*file*:: link:{github_stl_path}/hlt/hlt_udp_inc_dec_len_9k.py[stl/hlt/hlt_udp_inc_dec_len_9k.py]
+*File*:: link:{github_stl_path}/hlt/hlt_udp_inc_dec_len_9k.py[stl/hlt/hlt_udp_inc_dec_len_9k.py]
[source,python]
----
$ ./stl-sim -f stl/hlt/hlt_udp_inc_dec_len_9k.py --native
----
-.Auto generated code
+.Auto-generated code
[source,python]
----
# !!! Auto-generated code !!!
| WORK (pause) -> PAUSE (resume )---
| |
| |
- --------------------------------------
-
------
+ --------------------------------------
+----
==== Common Arguments
* Syncs with the port info and stream info state
* Reads all counter stats for reference
+// IGNORE: this line helps rendering of next line
+
*Example*::
[source,bash]
- Stops all traffic on all ports
- Removes all streams from all ports
+// IGNORE: this line helps rendering of next line
+
*Example*::
[source,bash]
-g show only global stats
-p only ports stats
-ps only port status (type/driver/link-up/down/negotion type etc)
-
----
+// IGNORE - this line helps rendering
===== streams
Shows the configured streams on each port, from the client cache.
-// clarify "should"
+
*Example*::
* Acts only on ports in "stopped: mode. Using `--force` first stops the port(s).
* Note: If any ports are not in "stopped" mode, the command fails.
+// IGNORE: this line helps rendering of next line
+
*Example*::
[source,bash]
* Changes the mode of the port to "stopped"
* Does not remove streams
+// IGNORE: this line helps rendering of next line
+
*Example*::
Use this command to stop the specified ports.
* Changes a working set of port to a "resume" state
* All ports should be in "paused" status. If any of the ports are not paused, the command fails.
+// IGNORE: this line helps rendering of next line
+
*Example*::
See the port mask description.
Update the bandwidth multiplier for a mask of ports.
-* All ports must be in "work" state. If any ports are not in "work" state, the command fails.
+* All ports must be in "work" state. If any ports are not in "work" state, the command fails
+
+// IGNORE: this line helps rendering of next line
*Example*::
[NOTE]
=====================================
- Here we could add the ability to disable/enable specific stream, load new stream dynamically etc.
+ Here we could add the ability to disable/enable specific stream, load a new stream dynamically, and so on.
=====================================
+// clarify note above
===== TUI
Code Review / trex.git / commitdiff