docs/usecases/contiv/VPPTRACE.md

   1 ## Using vpptrace.sh for VPP Packet Tracing
   2
   3 VPP allows tracing of incoming packets using CLI commands `trace add` and `show trace`
   4 as explained [here](VPP_PACKET_TRACING_K8S.html), but it is a rather cumbersome process.
   5
   6 The buffer for captured packets is limited in size, and once it gets full the tracing stops. The user has to manually clear the buffer content, and then repeat the trace command to resume the packet capture, losing information about all packets received in the meantime.
   7
   8 Packet filtering exposed via the CLI command `trace filter` is also quite limited in what it can do. Currently there is just one available filter, which allows you to keep only packets that include a certain node in the trace or exclude a certain node in the trace.
   9 It is not possible to filter the traffic by its content (e.g., by the source/destination IP address, protocol, etc.).
  10
  11 Last but not least, it is not possible to trace packets on a selected interface
  12 like `tcpdump`, which allows tracing via the option `-i`. VPP is only able to capture packets
  13 on the *RX side* of selected *devices* (e.g., dpdk, virtio, af-packet). This means
  14 that interfaces based on the same device cannot be traced for incoming packets
  15 individually, but only all at the same time. In Contiv/VPP all pods are connected
  16 with VPP via the same kind of the TAP interface, meaning that it is not possible to
  17 capture packets incoming only from one selected pod.
  18
  19 Contiv/VPP ships with a simple bash script [vpptrace.sh](https://github.com/contiv/vpp/blob/master/scripts/vpptrace.sh),
  20 which helps alleviate the aforementioned VPP limitations. The script automatically
  21 re-initializes buffers and traces whenever it is close to getting full, in order to
  22 avoid packet loss as much as possible. Next it allows you to filter packets
  23 by the content of the trace. There are two modes of filtering:
  24  - *substring mode* (default): packet trace must contain a given sub-string in order to
  25     be included in the output
  26  - *regex mode*: packet trace must match a given regex in order to be printed
  27
  28 The script is still limited, in that capture runs only on the RX side of all interfaces that are built on top of selected devices. Using filtering, however, it is possible to limit
  29 *traffic by interface* simply by using the interface name as a substring to match against.
  30
  31 #### Usage
  32
  33 Run the script with option `-h` to get the usage printed:
  34 ```
  35 Usage: ./vpptrace.sh  [-i <VPP-IF-TYPE>]... [-a <VPP-ADDRESS>] [-r] [-f <REGEXP> / <SUBSTRING>]
  36    -i <VPP-IF-TYPE> : VPP interface *type* to run the packet capture on (e.g., dpdk-input, virtio-input, etc.)
  37                        - available aliases:
  38                          - af-packet-input: afpacket, af-packet, veth
  39                          - virtio-input: tap (version determined from the VPP runtime config), tap2, tapv2
  40                          - tapcli-rx: tap (version determined from the VPP config), tap1, tapv1
  41                          - dpdk-input: dpdk, gbe, phys*
  42                        - multiple interfaces can be watched at the same time - the option can be repeated with
  43                          different values
  44                        - default = dpdk + tap
  45    -a <VPP-ADDRESS> : IP address or hostname of the VPP to capture packets from
  46                       - not supported if VPP listens on a UNIX domain socket
  47                       - default = 127.0.0.1
  48    -r               : apply filter string (passed with -f) as a regexp expression
  49                       - by default the filter is NOT treated as regexp
  50    -f               : filter string that packet must contain (without -r) or match as regexp (with -r) to be printed
  51                       - default is no filtering
  52 ```
  53
  54 `VPP-IF-TYPE` is a repeated option used to select the set of devices (e.g., virtio, dpdk, etc.)
  55 to capture the incoming traffic. Script provides multiple aliases, which
  56 are much easier to remember than the device names. For `dpdk-input` one can enter
  57 just `dpdk`, or anything starting with `phys`, etc. For TAPs, the script is even
  58 smart enough to find out the TAP version used, which allows to enter just `tap`
  59 as the device name.
  60
  61 If `VPP-IF-TYPE` is not specified, then the default behaviour is to capture from both
  62 `dpdk` (traffic entering the node from outside) and `tap` (preferred interface type
  63 for pod-VPP and host-VPP interconnection, receiving node-initiated traffic).
  64
  65 vpptrace.sh can capture packets even from a VPP on a different host, provided that
  66 VPP-CLI listens on a port, and not on a UNIX domain socket (for security reasons IPC
  67 is the default communication link, see `/etc/vpp/contiv-vswitch.conf`). Enter the destination
  68 node IP address via the option `-a`(localhost is the default).
  69
  70 The capture can be filtered via the `-f` option. The output will include only packets
  71 whose trace matches contain the given expression/sub-string.
  72
  73 Option `-r` enables the regex mode for filtering.
  74
  75 #### Examples
  76
  77 - Capture all packets entering VPP via `tapcli-1` interface **AND** all packets
  78    leaving VPP via `tapcli-1` that were sent from a pod, or the host on the *same node*
  79    (sent from tap, not Gbe):
  80 ```
  81 $ vpptrace.sh -i tap -f "tapcli-1"
  82 ```
  83 \ 2
  84 - Capture all packets with source or destination IP address 10.1.1.3:
  85 ```
  86 $ vpptrace.sh -i tap -i dpdk -f "10.1.1.3"
  87
  88 Or just:
  89 $ vpptrace.sh "10.1.1.3"
  90 ```
  91
  92 - Capture all SYN-ACKs received from outside:
  93 ```
  94 $ vpptrace.sh -i dpdk -f "SYN-ACK"
  95 ```