anchor.diff:  | /automation/trex_control_plane/stl/examples     | Stateless Examples
   |=============================
   
  -=== Port Layer Mode Configuration
  -
  -TRex ports can operate in two different mutual exclusive modes:
  -
  -* *Layer 2 mode* - MAC level configuration
  -* *Layer 3 mode* - IPv4/IPv6 configuration
  -
  -When configuring a port for L2 mode, it is only required to provide
  -the destination MAC address for the port (Legacy mode previous to v2.12 version).
  -
  -When configuring a port for L3, it is required to provide both
  -source IPv4/IPv6 address and a IPv4/IPv6 destination address.
  -
  -As an intergral part of configuring L3, the client will try to ARP resolve the
  -destination address and automatically configure the correct destination MAC.
  -(instead of sending ARP request when starting traffic)
  -
  -[NOTE]
  -While in L3 mode, TRex server will generate *gratuitous ARP* packets to make sure
  -that no ARP timeout on the DUT/router will result in a faliure of the test.
  -
  -.*Example of configuring L2 mode*
  -[source,bash]
  -----
  -
  -trex>service 
  -
  -trex>l2 --help
  -usage: port [-h] --port PORT --dst DST_MAC
  -
  -Configures a port in L2 mode
  -
  -optional arguments:
  -  -h, --help            show this help message and exit
  -  --port PORT, -p PORT  source port for the action
  -  --dst DST_MAC         Configure destination MAC address
  -
  -
  -trex(service)>l2 -p 0 --dst 6A:A7:B5:3A:4E:FF
  -
  -Setting port 0 in L2 mode:                                   [SUCCESS]
  -
  -trex>service --off
  -
  -----
  -
  -
  -.*Example of configuring L2 mode- Python API*
  -[source,Python]
  -----
  -  client.set_service_mode(port = 0, enabled = True)
  -
  -  client.set_l2_mode(port = 0, dst_mac = "6A:A7:B5:3A:4E:FF")
  -
  -  client.set_service_mode(port = 0, enabled = False)
  -
  -----
  -
  -
  -.*Example of configuring L3 mode- Console*
  -[source,bash]
  -----
  -
  -trex>service 
  -
  -
  -trex(service)>l3 --help
  -usage: port [-h] --port PORT --src SRC_IPV4 --dst DST_IPV4
  -
  -Configures a port in L3 mode
  -
  -optional arguments:
  -  -h, --help            show this help message and exit
  -  --port PORT, -p PORT  source port for the action
  -  --src SRC_IPV4        Configure source IPv4 address
  -  --dst DST_IPV4        Configure destination IPv4 address
  -
  -trex(service)>l3 -p 0 --src 1.1.1.2 --dst 1.1.1.1
  -
  -Setting port 0 in L3 mode:                                   [SUCCESS]
  -
  -
  -ARP resolving address '1.1.1.1':                             [SUCCESS]
  -
  -trex>service --off
  -
  -----
  -
  -
  -.*Example of configuring L3 mode - Python API*
  -[source,python]
  -----
  -
  -client.set_service_mode(port = 0, enabled = True)
  -
  -client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.1')
  -
  -client.set_service_mode(port = 0, enabled = False)
  -
  -----
  -
  -=== Port Service Mode
  -include::trex_port_service_mode.asciidoc[]
  -
  -=== Services
  -include::trex_services.asciidoc[]
  -
  -
  -
  -
  -=== Neighboring Protocols
  -As mentioned, in order to preserve high speed traffic generation,
  -TRex handles neighboring protocols in pre test phase.
  -
  -A test that requires running a neighboring protocol should first move
  -to 'service mode', execute the required steps in Python, switch back to 'normal mode'
  -and start the actual test.
  -
  -==== ARP
  -A basic neighboring protocol that is provided as part of TRex is ARP.
  -
  -For example, let's take a look at the following setup:
  -
  -image::images/router_arp.png[title="Router ARP",align="left",width={p_width}, link="images/router_arp.png"]
  -
  -[source,bash]
  -----
  -
  -trex>service                                                                   #<1> 
  -
  -Enabling service mode on port(s) [0, 1]:                     [SUCCESS]   
  -
  -trex(service)>portattr  --port 0
  -
  -             port       |          0           |  
  -        ------------------------------------------
  -        driver          |    rte_ixgbe_pmd     |  
  -        description     |  82599EB 10-Gigabit  |  
  -        link status     |          UP          |  
  -        link speed      |       10 Gb/s        |  
  -        port status     |         IDLE         |  
  -        promiscuous     |         off          |  
  -        flow ctrl       |         none         |  
  -        --              |                      |  
  -        src IPv4        |          -           |  
  -        src MAC         |  00:00:00:01:00:00   |  
  -        ---             |                      |  
  -        Destination     |  00:00:00:01:00:00   |  
  -        ARP Resolution  |          -           |  
  -        ----            |                      |  
  -        PCI Address     |     0000:03:00.0     |  
  -        NUMA Node       |          0           |  
  -        -----           |                      |  
  -        RX Filter Mode  |    hardware match    |  
  -        RX Queueing     |         off          |  
  -        RX sniffer      |         off          |  
  -        Grat ARP        |         off          |  
  -
  -
  -trex(service)>l3 -p -s 1.1.1.1 -d 1.1.1.2                         #<2> 
  -
  -trex(service)>arp -p 0 1                                          #<3>
  -
  -Resolving destination on port(s) [0, 1]:                     [SUCCESS]
  -
  -
  -Port 0 - Recieved ARP reply from: 1.1.1.1, hw: d0:d0:fd:a8:a1:01
  -Port 1 - Recieved ARP reply from: 1.1.2.1, hw: d0:d0:fd:a8:a1:02
  -
  -trex(service)>service --off                                       #<4>
  -
  -----
  -<1> Enable service mode 
  -<2> Set IPv4/default gateway. it will resolve the arp
  -<3> repeat ARP resolution
  -<4> exist from service mode 
  - 
  -
  -
  -to revert  back to MAC address mode (without ARP resolution) you do the following 
  -
  -.Disable L3 mode
  -[source,bash]
  -----
  -
  -trex>l2 -p 0 --dst 00:00:00:01:00:00       #<1>
  -
  -trex>portattr  --port 0
  -
  -             port       |          0           |  
  -        ------------------------------------------
  -        driver          |    rte_ixgbe_pmd     |  
  -        description     |  82599EB 10-Gigabit  |  
  -        link status     |          UP          |  
  -        link speed      |       10 Gb/s        |  
  -        port status     |         IDLE         |  
  -        promiscuous     |         off          |  
  -        flow ctrl       |         none         |  
  -        --              |                      |  
  -        src IPv4        |          -           |  
  -        src MAC         |  00:00:00:01:00:00   |  
  -        ---             |                      |  
  -        Destination     |  00:00:00:01:00:00   |  
  -        ARP Resolution  |          -           |  
  -        ----            |                      |  
  -        PCI Address     |     0000:03:00.0     |  
  -        NUMA Node       |          0           |  
  -        -----           |                      |  
  -        RX Filter Mode  |    hardware match    |  
  -        RX Queueing     |         off          |  
  -        RX sniffer      |         off          |  
  -        Grat ARP        |         off          |  
  -        
  -----
  -<1> disable service mode 
  -
  -
  -
  -.Python API:
  -[source,python]
  -----
  -
  -client.set_service_mode(ports = [0, 1], enabled = True)                  <1>
  -
  -# configure port 0, 1 to Layer 3 mode
  -client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.2') <2>
  -client.set_l3_mode(port = 1, src_ipv4 = '1.1.2.2', dst_ipv4 = '1.1.2.1') 
  -    
  -# ARP resolve ports 0, 1
  -c.resolve(ports = [0, 1])
  -
  -client.set_service_mode(ports = [0, 1], enabled = False)                 <3>
  -
  -----
  -<1> Enable service mode
  -<2> configure IPv4 and Default Gateway 
  -<3> Disable service mode
  -
  -==== ICMP
  -
  -Another basic protocol provided with TRex is ICMP.
  -It is possible, under service mode to ping the DUT or even a TRex port
  -from the console / API.
  -
  -.TRex Console
  -[source,bash]
  -----
  -
  -trex(service)>ping --help
  -usage: ping [-h] --port PORT -d PING_IPV4 [-s PKT_SIZE] [-n COUNT]
  -
  -pings the server / specific IP
  -
  -optional arguments:
  -  -h, --help            show this help message and exit
  -  --port PORT, -p PORT  source port for the action
  -  -d PING_IPV4          which IPv4 to ping
  -  -s PKT_SIZE           packet size to use
  -  -n COUNT, --count COUNT
  -                        How many times to ping [default is 5]
  -
  -trex(service)>ping -p 0 -d 1.1.2.2
  -
  -Pinging 1.1.2.2 from port 0 with 64 bytes of data:
  -Reply from 1.1.2.2: bytes=64, time=27.72ms, TTL=127
  -Reply from 1.1.2.2: bytes=64, time=1.40ms, TTL=127
  -Reply from 1.1.2.2: bytes=64, time=1.31ms, TTL=127
  -Reply from 1.1.2.2: bytes=64, time=1.78ms, TTL=127
  -Reply from 1.1.2.2: bytes=64, time=1.95ms, TTL=127
  -
  -----
  -
  -
  -
  -.Python API
  -[source,python]
  -----
  -
  -# move to service mode
  -client.set_service_mode(ports = ports, enabled = True)
  -    
  -# configure port 0, 1 to Layer 3 mode
  -client.set_l3_mode(port = 0, src_ipv4 = '1.1.1.2', dst_ipv4 = '1.1.1.1')
  -client.set_l3_mode(port = 1, src_ipv4 = '1.1.2.2', dst_ipv4 = '1.1.2.1')
  -
  -# ping port 1 from port 0 through the router
  -client.ping_ip(src_port = 0, dst_ipv4 = '1.1.2.2', pkt_size = 64)        <1>
  -    
  -# disable service mode
  -client.set_service_mode(enabled = False)
  -
  -----
  -<1> Check connectivity
  -
  -
  -==== IPv6 ND client
  -
  -At this phase, implemented scanning of network for IPv6 enabled neighbors and ping nearby devices from the console. +
  -Next phase, planned support at the CPP server. +
  -The advantage of those methods is that they can be easily extended to simulate lots of clients in automation.
  -
  -*Scanning example:*
  -
  -image:images/console_scan6.png[title="Console scan6", align="left", link="images/console_scan6.png"]
  -
  -*Ping example:*
  -
  -image:images/console_ping.png[title="Console ping", align="left", link="images/console_ping.png"]
  -
  -Those utilities (available from API as well) can help user to configure next hop.
  -From the console, one could set "l2" destination MAC taken from the scan6 result:
  -
  -image:images/console_l2_dst_mac.png[title="Console ping", align="left", link="images/console_l2_dst_mac.png"]
  -
  -For setting own IPv6, we use local address as described in link:https://www.ietf.org/rfc/rfc3513.txt[RFC 3513]. +
  -For scanning of network, we ping the multicast address ff02::1 and establish connection via NS/ND conversations.
  -
  -Additional links on scanning network:
  -
  -* link:https://tools.ietf.org/html/draft-ietf-opsec-ipv6-host-scanning-00#page-5[RFC draft of scanning]
  -* Scanning of network in Ubuntu: link:http://manpages.ubuntu.com/manpages/zesty/man1/scan6.1.html[scan6]
  -
  -Example of using IPv6 methods in automation:
  -
  -* link:{github_stl_examples_path}/stl_ipv6_tools.py[stl_ipv6_tools.py]
  -
  -
  -=== Tutorials
  +
  +=== Getting started Tutorials
   
   The tutorials in this section demonstrate basic TRex *stateless* use cases. Examples include common and moderately advanced TRex concepts.
   
  -==== Tutorial: Simple IPv4/UDP packet - TRex 
  +==== Tutorial: Prepare TRex configuration file 
  +
  +*Goal*:: Define the TRex physical or virtual ports and create configuration file.
  +
  +Follow this chapter  link:trex_manual.html#_first_time_running[first time configuration ]
  +
  +
  +==== Tutorial: Load TRex server, Simple IPv4 UDP 
   
   *Goal*:: 
   
  -Send a simple UDP packet from all ports of a TRex server.
  +Send a simple UDP packets from all ports of a TRex server.
   
   *Traffic profile*::  
   
  
positive.code:     
      rx_scapy_pkt.show2()
  ----
  
  === PCAP Based Traffic Tutorials
  
  
negative.code: 
  ----
  
  
  
  === Performance Tweaking
  In this section we provide some advanced features to help get the most of TRex performance.
  The reason that those features are not active out of the box because they might have
  