extras/wireshark/readme.md

   1 How to build a vpp dispatch trace aware Wireshark
   2 =================================================
   3
   4 We have upstreamed our vpp pcap dispatch trace dissector. After
   5 working through a laundry list of issues discovered during the
   6 upstreaming process, it appears that the code is close to being
   7 merged. See https://code.wireshark.org/review/#/c/31466.
   8
   9 As of this writing, the simplest way to build a vpp dispatch trace
  10 aware wireshark is to clone the wireshark repo, and apply the vpp
  11 dissector patch.
  12
  13
  14 Download wireshark source code
  15 ------------------------------
  16
  17 The wireshark git repo is large, so it takes a while to clone.
  18
  19 ```
  20      git clone https://code.wireshark.org/review/wireshark
  21 ```
  22
  23 Download Gerrit 31466 using the URL shown above. If you have "git
  24 review" set up, it's as simple as "git review -d 31466" in the wireshark
  25 workspace.
  26
  27 Alternatively, download a patch-file from the gerrit server and apply
  28 the patch.
  29
  30 Install prerequisite Debian packages
  31 ------------------------------------
  32
  33 Here is a list of prerequisite packages which must be present in order
  34 to compile wireshark, beyond what's typically installed on an Ubuntu
  35 18.04 system:
  36
  37 ```
  38         libgcrypt11-dev flex bison qtbase5-dev qttools5-dev-tools qttools5-dev
  39         qtmultimedia5-dev libqt5svg5-dev libpcap-dev qt5-default
  40 ```
  41
  42 Compile Wireshark
  43 -----------------
  44
  45 Wireshark uses cmake, so it's relatively easy to build, at least on
  46 Ubuntu 18.04.
  47
  48 ```
  49      $ cd wireshark
  50      $ mkdir build
  51      $ cd build
  52      $ cmake -G Ninja ../
  53      $ ninja -j 8
  54      $ sudo ninja install
  55 ```
  56
  57 Make a pcap dispatch trace
  58 --------------------------
  59
  60 Configure vpp to pass traffic in some fashion or other, and then:
  61
  62 ```
  63     vpp# pcap dispatch trace on max 10000 file vppcapture buffer-trace dpdk-input 1000
  64
  65 ```
  66
  67 or similar. Run traffic for long enough to capture some data. Save the
  68 dispatch trace capture like so:
  69
  70 ```
  71     vpp# pcap dispatch trace off
  72 ```
  73
  74 Display in Wireshark
  75 --------------------
  76
  77 Display /tmp/vppcapture in the vpp-enabled version of wireshark.
  78 Normal version of wireshark will refuse to process vpp dispatch trace
  79 pcap files because they won't understand the encap type.
  80
  81 Set wireshark to filter on vpp.bufferindex to watch a single packet
  82 traverse the forwarding graph. Otherwise, you'll see a vector of
  83 packets in e.g. ip4-lookup, then a vector of packets in ip4-rewrite,
  84 etc.