1.. BSD LICENSE 2 Copyright(c) 2017 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 32 33DPDK pdump Library and pdump Tool 34================================= 35 36This document describes how the Data Plane Development Kit (DPDK) Packet 37Capture Framework is used for capturing packets on DPDK ports. It is intended 38for users of DPDK who want to know more about the Packet Capture feature and 39for those who want to monitor traffic on DPDK-controlled devices. 40 41The DPDK packet capture framework was introduced in DPDK v16.07. The DPDK 42packet capture framework consists of the DPDK pdump library and DPDK pdump 43tool. 44 45 46Introduction 47------------ 48 49The :ref:`librte_pdump <pdump_library>` library provides the APIs required to 50allow users to initialize the packet capture framework and to enable or 51disable packet capture. The library works on a client/server model and its 52usage is recommended for debugging purposes. 53 54The :ref:`dpdk-pdump <pdump_tool>` tool is developed based on the 55``librte_pdump`` library. It runs as a DPDK secondary process and is capable 56of enabling or disabling packet capture on DPDK ports. The ``dpdk-pdump`` tool 57provides command-line options with which users can request enabling or 58disabling of the packet capture on DPDK ports. 59 60The application which initializes the packet capture framework will act as a 61server and the application that enables or disables the packet capture will 62act as a client. The server sends the Rx and Tx packets from the DPDK ports 63to the client. 64 65In DPDK the ``testpmd`` application can be used to initialize the packet 66capture framework and act as a server, and the ``dpdk-pdump`` tool acts as a 67client. To view Rx or Tx packets of ``testpmd``, the application should be 68launched first, and then the ``dpdk-pdump`` tool. Packets from ``testpmd`` 69will be sent to the tool, which then sends them on to the Pcap PMD device and 70that device writes them to the Pcap file or to an external interface depending 71on the command-line option used. 72 73Some things to note: 74 75* The ``dpdk-pdump`` tool can only be used in conjunction with a primary 76 application which has the packet capture framework initialized already. In 77 dpdk, only ``testpmd`` is modified to initialize packet capture framework, 78 other applications remain untouched. So, if the ``dpdk-pdump`` tool has to 79 be used with any application other than the testpmd, the user needs to 80 explicitly modify that application to call the packet capture framework 81 initialization code. Refer to the ``app/test-pmd/testpmd.c`` code and look 82 for ``pdump`` keyword to see how this is done. 83 84* The ``dpdk-pdump`` tool depends on the libpcap based PMD which is disabled 85 by default in the build configuration files, owing to an external dependency 86 on the libpcap development files. Once the libpcap development files are 87 installed, the libpcap based PMD can be enabled by setting 88 ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` and recompiling the DPDK. 89 90 91Test Environment 92---------------- 93 94The overview of using the Packet Capture Framework and the ``dpdk-pdump`` tool 95for packet capturing on the DPDK port in 96:numref:`figure_packet_capture_framework`. 97 98.. _figure_packet_capture_framework: 99 100.. figure:: img/packet_capture_framework.* 101 102 Packet capturing on a DPDK port using the dpdk-pdump tool. 103 104 105Configuration 106------------- 107 108Modify the DPDK primary application to initialize the packet capture framework 109as mentioned in the above notes and enable the following config options and 110build DPDK:: 111 112 CONFIG_RTE_LIBRTE_PMD_PCAP=y 113 CONFIG_RTE_LIBRTE_PDUMP=y 114 115 116Running the Application 117----------------------- 118 119The following steps demonstrate how to run the ``dpdk-pdump`` tool to capture 120Rx side packets on dpdk_port0 in :numref:`figure_packet_capture_framework` and 121inspect them using ``tcpdump``. 122 123#. Launch testpmd as the primary application:: 124 125 sudo ./app/testpmd -c 0xf0 -n 4 -- -i --port-topology=chained 126 127#. Launch the pdump tool as follows:: 128 129 sudo ./build/app/dpdk-pdump -- \ 130 --pdump 'port=0,queue=*,rx-dev=/tmp/capture.pcap' 131 132#. Send traffic to dpdk_port0 from traffic generator. 133 Inspect packets captured in the file capture.pcap using a tool 134 that can interpret Pcap files, for example tcpdump:: 135 136 $tcpdump -nr /tmp/capture.pcap 137 reading from file /tmp/capture.pcap, link-type EN10MB (Ethernet) 138 11:11:36.891404 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 139 11:11:36.891442 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 140 11:11:36.891445 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 141