--- /dev/null
+
+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.
+
+==== 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)
+
+----
+
+=== 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*
+
----
=== Port Service Mode
-
-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.
+include::trex_port_service_mode.asciidoc[]
=== Neighboring Protocols
Code Review / trex.git / commitdiff
