doc/guides/tools/dumpcap.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Microsoft Corporation.
   3
   4 dpdk-dumpcap Application
   5 ========================
   6
   7 The ``dpdk-dumpcap`` tool is a Data Plane Development Kit (DPDK)
   8 network traffic dump tool.
   9 The interface is similar to the dumpcap tool in Wireshark.
  10 It runs as a secondary DPDK process and lets you capture packets
  11 that are coming into and out of a DPDK primary process.
  12 The ``dpdk-dumpcap`` writes files in Pcapng packet format.
  13
  14 Without any options set, it will use DPDK to capture traffic
  15 from the first available DPDK interface
  16 and write the received raw packet data,
  17 along with timestamps into a pcapng file.
  18
  19 If the ``-w`` option is not specified, ``dpdk-dumpcap`` writes
  20 to a newly created file with a name chosen
  21 based on interface name and timestamp.
  22 If ``-w`` option is specified, then that file is used.
  23
  24 .. note::
  25
  26    * The ``dpdk-dumpcap`` tool can only be used in conjunction with a primary
  27      application which has the packet capture framework initialized already.
  28      In DPDK, only the ``dpdk-testpmd`` is modified to initialize
  29      packet capture framework, other applications remain untouched.
  30      So, if the ``dpdk-dumpcap`` tool has to be used with any application
  31      other than the ``dpdk-testpmd``, user needs to explicitly modify
  32      that application to call packet capture framework initialization code.
  33      Refer ``app/test-pmd/testpmd.c`` code to see how this is done.
  34
  35    * The ``dpdk-dumpcap`` tool runs as a DPDK secondary process.
  36      It exits when the primary application exits.
  37
  38
  39 Running the Application
  40 -----------------------
  41
  42 To list interfaces available for capture, use ``--list-interfaces``.
  43
  44 To filter packets in style of *tshark*, use the ``-f`` flag.
  45
  46 To capture on multiple interfaces at once, use multiple ``-I`` flags.
  47
  48
  49 Example
  50 -------
  51
  52 .. code-block:: console
  53
  54    # <build_dir>/app/dpdk-dumpcap --list-interfaces
  55    0. 000:00:03.0
  56    1. 000:00:03.1
  57
  58    # <build_dir>/app/dpdk-dumpcap -I 0000:00:03.0 -c 6 -w /tmp/sample.pcapng
  59    Packets captured: 6
  60    Packets received/dropped on interface '0000:00:03.0' 6/0
  61
  62    # <build_dir>/app/dpdk-dumpcap -f 'tcp port 80'
  63    Packets captured: 6
  64    Packets received/dropped on interface '0000:00:03.0' 10/8
  65
  66
  67 Limitations
  68 -----------
  69
  70 The following option of Wireshark ``dumpcap`` is not yet implemented:
  71
  72    * ``-b|--ring-buffer`` -- more complex file management.
  73
  74 The following options do not make sense in the context of DPDK.
  75
  76    * ``-C <byte_limit>`` -- it's a kernel thing.
  77
  78    * ``-t`` -- use a thread per interface.
  79
  80    * Timestamp type.
  81
  82    * Link data types. Only EN10MB (Ethernet) is supported.
  83
  84    * Wireless related options: ``-I|--monitor-mode`` and  ``-k <freq>``
  85
  86
  87 .. note::
  88
  89    * The options to ``dpdk-dumpcap`` are like the Wireshark dumpcap program
  90      and are not the same as ``dpdk-pdump`` and other DPDK applications.