docs for capture

Signed-off-by: imarom <imarom@cisco.com>

4 files changed, 306 insertions, 67 deletions

diff --git a/doc/images/capture_wireshark_pipe.PNG b/doc/images/capture_wireshark_pipe.PNG
new file mode 100644
index 00000000..3102649e
--- /dev/null
+++ b/doc/images/capture_wireshark_pipe.PNG
diff --git a/doc/images/packet_capture_arch.png b/doc/images/packet_capture_arch.png
new file mode 100644
index 00000000..c85fd830
--- /dev/null
+++ b/doc/images/packet_capture_arch.png
diff --git a/doc/trex_port_service_mode.asciidoc b/doc/trex_port_service_mode.asciidoc
new file mode 100644
index 00000000..202d8e73
--- /dev/null
+++ b/doc/trex_port_service_mode.asciidoc
@@ -0,0 +1,305 @@
+
+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*
+
diff --git a/doc/trex_stateless.asciidoc b/doc/trex_stateless.asciidoc
index 2bd21d91..8edb5df4 100755
--- a/doc/trex_stateless.asciidoc
+++ b/doc/trex_stateless.asciidoc
@@ -336,73 +336,7 @@ client.set_service_mode(port = 0, enabled = False)
 ----
 
 === 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