path: root/doc/trex_port_service_mode.asciidoc

In 'normal operation mode', to preserve high speed processing of packets,
TRex ignores most of the RX traffic, with the exception of counting/statistic and handling
latency flows.


In the following diagram it is illustrated how RX packets are handled.
Only a portion is forwarded to the RX handling module and none of forward back
to the Python client.

image::images/port_normal_mode.png[title="Port Under Normal Mode",align="left",width={p_width}, link="images/port_normal_mode.png"]



We provide another mode called 'service mode' in which a port will respond to ping, ARP requests
and also provide a capabality in this mode to forward packets to the Python control plane for
applying full duplex protocols (DCHP, IPv6 neighboring and etc.)

The following diagram illustrates of packets can be forwarded back to the Python client

image::images/port_service_mode.png[title="Port Under Service Mode",align="left",width={p_width}, link="images/port_service_mode.png"]

In this mode, it is possible to write python plugins for emulation (e.g. IPV6 ND/DHCP) to prepare the setup and then move to normal mode for high speed testing 


*Example Of Switcing Between 'Service' And 'Normal' Mode*
[source,bash]
----

trex(service)>service --help
usage: service [-h] [--port PORTS [PORTS ...] | -a] [--off]

Configures port for service mode. In service mode ports will reply to ARP,
PING and etc.

optional arguments:
  -h, --help            show this help message and exit
  --port PORTS [PORTS ...], -p PORTS [PORTS ...]
                        A list of ports on which to apply the command
  -a                    Set this flag to apply the command on all available
                        ports
  --off                 Deactivates services on port(s)


trex>service

Enabling service mode on port(s) [0, 1]:                     [SUCCESS]

trex(service)>service --off

Disabling service mode on port(s) [0, 1]:                    [SUCCESS]

----

.*Example Of Switcing Between 'Service' And 'Normal' Mode-API*
[source,Python]
----

  client.set_service_mode(ports = [0, 1], enabled = True)
  
  client.set_service_mode(ports = [0, 1], enabled = False)

----

==== ARP / ICMP response
[IMPORTANT]
Only while in service mode, ports will reply to ICMP echo requests and ARP requests.


==== Packet Capturing
[IMPORTANT]
The following section is available only under service mode

While under service mode TRex provides couple of ways to examine
and manipulate both RX and TX packets.


Packet capturing is implemented by allocating one more more fast in-memory queues
on the server side that will copy-and-store the packet buffer.


Each queue can be defined with storage, which ports on either TX/RX it should capture
and whether it should be 'cyclic' or 'fixed'

image::images/packet_capture_arch.png[title="Packet Captruing Architecture",align="left",width={p_width}, link="images/packet_capture_arch.png"]

The above architecture implies that we can 'capture' at high speed for a short amount of time.

For example,
A queue of 1 million packets can be allocated as a cyclic queue and be active under a rate of couple of Mpps.
It effectively provide a sampling of the last 1 million packets seen by the server with the given filters.

==== Packet Capturing API Usage

The Python API usages is fairly simple:

.Python API:
[source,python]
----

# move port 1 to service mode as we want to capture traffic on it
client.set_service_mode(ports = 1)

# start a capture on port 1 RX side with a limit and a mode
capture = client.start_capture(rx_ports = 1, limit = 100, mode = 'fixed')

# execute your code here

# save the packets to a file or to a list (see the Python API docs)
client.stop_capture(capture['id'], '/home/mydir/port_0_rx.pcap')

# exit service mode on port 1
client.set_service_mode(ports = 1, enabled = False)

----

==== Packet Capturing Console Usage

The console provides couple of flexible ways to handle packet capturing

* *Capture Monitoring*
* *Capture Recording*

===== Capture Monitoring
Capture monitoring is a non-persistent way to capture and show packets from either TX / RX
of one or more ports


Monitoring provides 3 modes:

* *Low Verbose*    - short line per packet will be displayed
* *High Verbose*   - a full scapy show will be displayed per packet
* *Wireshark Pipe* - launches Wireshark with a pipe connected to the traffic being captured


In the first two options, packets information will be displayed *on the console*

So for high amount of traffic being monitored, consider *Wireshark Pipe* or the
*Capture Recording*

.*Example of capturing traffic using the console with verbose on*

[source,python]
----
trex>service                                                                  <1>

Enabling service mode on port(s) [0, 1, 2, 3]:               [SUCCESS]      

trex(service)>capture monitor start --rx 3 -v                                 <2>

Starting stdout capture monitor - verbose: 'high'            [SUCCESS]


*** use 'capture monitor stop' to abort capturing... ***

trex(service)>arp -p 3                                                        <3>

Resolving destination on port(s) [3]:                        [SUCCESS]

Port 3 - Recieved ARP reply from: 1.1.1.1, hw: 90:e2:ba:ae:88:b8              <4>
38.14 [ms]

trex(service)>

#1 Port: 3 ?-- RX

    Type: ARP, Size: 60 B, TS: 16.98 [sec]

    ###[ Ethernet ]###
      dst       = 90:e2:ba:af:13:89
      src       = 90:e2:ba:ae:88:b8
      type      = 0x806
    ###[ ARP ]###
         hwtype    = 0x1
         ptype     = 0x800
         hwlen     = 6
         plen      = 4
         op        = is-at                                                    <5>
         hwsrc     = 90:e2:ba:ae:88:b8
         psrc      = 1.1.1.1
         hwdst     = 90:e2:ba:af:13:89
         pdst      = 4.4.4.4
    ###[ Padding ]###
            load      = '\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'


trex(service)>
----
<1> Move to *service mode* to allow capturing
<2> Activate a capture monitor on port *3* RX side with *verbose* on
<3> Send an ARP request on port *3*
<4> The console shows the returning packet
<5> *is-at* ARP response was captured



.*Example of capturing traffic using Wireshark pipe*

[source,python]
----
trex(service)>capture monitor start --rx 3 -p                                 <1>

Starting pipe capture monitor                                [SUCCESS]


Trying to locate Wireshark                                   [SUCCESS]


Checking permissions on '/usr/bin/dumpcap'                   [SUCCESS]


Launching '/usr/bin/wireshark -k -i /tmp/tmputa4jf3c'        [SUCCESS]        <2>


Waiting for Wireshark pipe connection                        [SUCCESS]        <3>


*** Capture monitoring started ***                                            <4>

trex(service)>arp                                                             <5>

Resolving destination on port(s) [0, 1, 2, 3]:               [SUCCESS]

Port 0 - Recieved ARP reply from: 4.4.4.4, hw: 90:e2:ba:af:13:89
Port 1 - Recieved ARP reply from: 3.3.3.3, hw: 90:e2:ba:af:13:88
Port 2 - Recieved ARP reply from: 2.2.2.2, hw: 90:e2:ba:ae:88:b9
Port 3 - Recieved ARP reply from: 1.1.1.1, hw: 90:e2:ba:ae:88:b8

----
<1> Activate a monitor using a Wireshark pipe
<2> Try to automatically launch Wireshark with connection the pipe
<3> Console will block until connection was established
<4> Monitor is active
<5> Send ARP request


image::images/capture_wireshark_pipe.png[title="Wireshark Pipe",align="left",width={p_width}, link="images/capture_wireshark_pipe.png"]

===== Capture Recording
In addition to monitoring, the console allows a simple recording as well.

Recording allows the user to define a fixed size queue which then can
be saved to a PCAP file.

.*Example of capturing a traffic to a fixed size queue*

[source,python]
----
trex(service)>capture record start --rx 3 --limit 200                         <1>

Starting packet capturing up to 200 packets                  [SUCCESS]

*** Capturing ID is set to '4' ***                                            <2>
*** Please call 'capture record stop --id 4 -o <out.pcap>' when done ***

trex(service)>capture                                                         <3>

Active Recorders

      ID        |     Status      |     Packets     |      Bytes      |    TX Ports     |    RX Ports
 ------------------------------------------------------------------------------------------------------
       4        |     ACTIVE      |     [0/200]     |       0 B       |        -        |        3



trex(service)>start -f stl/imix.py -m 1kpps -p 0 --force                      <4>

Removing all streams from port(s) [0]:                       [SUCCESS]


Attaching 3 streams to port(s) [0]:                          [SUCCESS]


Starting traffic on port(s) [0]:                             [SUCCESS]

20.42 [ms]

trex(service)>capture                                                         <5>

Active Recorders

      ID        |     Status      |     Packets     |      Bytes      |    TX Ports     |    RX Ports
 ------------------------------------------------------------------------------------------------------
       4        |     ACTIVE      |    [200/200]    |    74.62 KB     |        -        |        3


trex(service)>capture record stop --id 4 -o /tmp/rx_3.pcap                    <6>

Stopping packet capture 4                                    [SUCCESS]


Writing 200 packets to '/tmp/rx_3.pcap'                      [SUCCESS]


Removing PCAP capture 4 from server                          [SUCCESS]

trex(service)>

----

<1> Start a packet record on port *3* RX side with a limit of *200* packets
<2> A new capture was created with an ID *4*
<3> Showing the capture status - currently empty
<4> Start traffic on port *0* which is connected to port *3*
<5> Showing the capture status - full
<6> Save 200 packets to an output file called */tmp/rx_3.pcap*


==== Packet Capturing Video Tutorials 

ifdef::backend-xhtml11[]
++++++++++++++++++

<iframe width="420" height="315"
allowfullscreen="allowfullscreen"
src="https://www.youtube.com/embed/Vsb0A4RNGz0">
</iframe>
++++++++++++++++++
endif::backend-xhtml11[]

The Tutorial shows a little bit of our new packet capture ability