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