From 7753575fb78aaa547fc2573a6d2978671b24ebd8 Mon Sep 17 00:00:00 2001 From: imarom Date: Wed, 8 Feb 2017 10:35:26 +0200 Subject: docs for capture Signed-off-by: imarom --- doc/images/capture_wireshark_pipe.PNG | Bin 0 -> 102156 bytes doc/images/packet_capture_arch.png | Bin 0 -> 40596 bytes doc/trex_port_service_mode.asciidoc | 305 ++++++++++++++++++++++++++++++++++ doc/trex_stateless.asciidoc | 68 +------- 4 files changed, 306 insertions(+), 67 deletions(-) create mode 100644 doc/images/capture_wireshark_pipe.PNG create mode 100644 doc/images/packet_capture_arch.png create mode 100644 doc/trex_port_service_mode.asciidoc (limited to 'doc') diff --git a/doc/images/capture_wireshark_pipe.PNG b/doc/images/capture_wireshark_pipe.PNG new file mode 100644 index 00000000..3102649e Binary files /dev/null and b/doc/images/capture_wireshark_pipe.PNG differ diff --git a/doc/images/packet_capture_arch.png b/doc/images/packet_capture_arch.png new file mode 100644 index 00000000..c85fd830 Binary files /dev/null and b/doc/images/packet_capture_arch.png differ 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 ' 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 -- cgit 1.2.3-korg