anchor.diff:  
   ----
   
  +
  +
   === 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
  
positive.code: | /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
  
  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 
  
  *Goal*:: 
  
  Send a simple UDP packet from all ports of a TRex server.
  
  *Traffic profile*::  
  
  
negative.code: |=================
  
  
  ==== Tutorial: Port Layer Mode Configuration 
  
  *Goal*:: Configure TRex port with either IPv4 or MAC addrees 
  
  
  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 Console*
  [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[]
  
  
  === 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]
  
  
  
  
  === Traffic profile Tutorials
  
  ==== Tutorial: Simple Interleaving streams
  