Describes how to use pdump library and dpdk-pdump tool to capture traffic on dpdk ports.
Signed-off-by: Reshma Pattan <reshma.pat...@intel.com> --- doc/guides/howto/img/packet_capture_framework.svg | 128 +++++++++++++++++++ doc/guides/howto/index.rst | 1 + doc/guides/howto/packet_capture_framework.rst | 146 ++++++++++++++++++++++ 3 files changed, 275 insertions(+) create mode 100644 doc/guides/howto/img/packet_capture_framework.svg create mode 100644 doc/guides/howto/packet_capture_framework.rst diff --git a/doc/guides/howto/img/packet_capture_framework.svg b/doc/guides/howto/img/packet_capture_framework.svg new file mode 100644 index 0000000..e0805a3 --- /dev/null +++ b/doc/guides/howto/img/packet_capture_framework.svg @@ -0,0 +1,128 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd";> +<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink"; x="0px" y="0px" width="530px" height="319px" viewBox="0 0 530 319" enable-background="new 0 0 530 319" xml:space="preserve"> <image id="image0" width="530" height="319" x="0" y="0" + xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAhIAAAE/CAMAAAAkOdr4AAAABGdBTUEAAK/INwWK6QAAACBjSFJN +AAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABs1BMVEX////b5OzP2+alvNCg +uM2Dor5xlbVZg6lBcZxTfqV3mbjJ1+PD0uCPq8VNeqK9zt3z9vlHdZ/h6e/n7fN9nrtfh6yxxdb5 ++/xljK+rwNNrkLKVsMibtMuJp8Lt8vbV4Om3ydr//9uQOgAAOpDb//+2ZgDbkDoAAAA6kNsAZrb/ +tmYAAGa2////25A6AAD//7ZmAAAAADqQ2//P58+QZgBmtv+QOjrM//+2kDrq8vq81u6Jt+GEtOBq +pNlbm9Vlodiy0Ovl7/j1+fyZweV/sd7b6fZgntaUvuTG3PDW5vTw9vvL3/LB2e91q9yPu+L6/P6o +yumtzerg7Pd6rt2exOZwqNrbtmbv9+8AaKuraABAoEAAei4uegBJfaxEdqRamtNYls5ZmNJWk8pY +l9BGeadLgbJOhrjR4/O30+xDdJ9UkMejx+hIfKpPiLtCcp5EdaFTj8VXlcxKf7BOh7pVkshKf65R +i8BSjcFbvfH///ixrNVFd6VHeql5z/jmz9uV3///3+P///GVm9Vbm9ux7///7+p5m9Wx7/hbrOrm +///MvdVbm+N5m9vm//hNhLZOhbdSjcNClZWmAAAAAWJLR0QAiAUdSAAAAAd0SU1FB+EHDAYgBpFQ +/AoAABiMSURBVHja7Z2NfxM3mscniRMrCTE2ISQBAgnBcZKWl5KybYEoFNrwUihtgQ2lW6AHpIXt +0te7ctsC2aN3t0v3rvcnn17mRRq/ZKzRSPLM8/t8bI9nZM2jR1/rZaQZeR4IBAKBQJrU1z9QGhwq +owJreGikVBrtt50TbmjH2LDt/HBHlcGdVdsZYpuHwRpxRJn8Q3b077JtjE2N94+WSrsnKBYjeyZt +W2NP/UPEA1OlPtt2uKPx6RH6F9lp2w5L6ttNCsrpcdtmuKbqzr3kf1LEVsXkPoRq+6u2zXBSO0lL +e6Rq2wrTqpI6Y+aAbStc1eR0BZUL1rbaVUaVg7aNcFnjU6gyatsIk+qvoAloRHRUlbS0pm0bYU6j +RawquxZpbA3YtsGUdlXQjG0bekGzCO2wbYMZVctoxLYNvaEBVCvENZvJITRRtW1Ej2gQlYvQK5tB +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 +rkJggg==" /> +</svg> diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst index a483444..468939b 100644 --- a/doc/guides/howto/index.rst +++ b/doc/guides/howto/index.rst @@ -42,3 +42,4 @@ HowTo Guides vfd virtio_user_for_container_networking virtio_user_as_exceptional_path + packet_capture_framework diff --git a/doc/guides/howto/packet_capture_framework.rst b/doc/guides/howto/packet_capture_framework.rst new file mode 100644 index 0000000..e74bee2 --- /dev/null +++ b/doc/guides/howto/packet_capture_framework.rst @@ -0,0 +1,146 @@ +.. BSD LICENSE + Copyright(c) 2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +This doc describes how the Data Plane Development Kit (DPDK) packet capture +framework is used for capturing packets on the DPDK ports. It is written with +users of DPDK in mind who want to know more about the feature and for those +who want to monitor traffic on DPDK-controlled devices. + +The DPDK packet capture framework was introduced in DPDK v16.07. +The DPDK packet capture framework consists of the DPDK pdump library and +DPDK pdump tool. + + +DPDK pdump Library and pdump Tool +================================= + +The ``librte_pdump`` library provides the APIs required to allow users to +initialize the packet capture framework and to enable or disable packet +capture. The library works on a client/server model and its usage is +recommended for debugging purposes. + +The ``dpdk-pdump`` tool is developed based on the ``librte_pdump`` library. +The ``dpdk-pdump`` tool runs as a DPDK secondary process and is capable +of enabling or disabling packet capture on the DPDK ports. +The ``dpdk-pdump`` tool provides command-line options with which users can +request enabling or disabling of the packet capture on DPDK ports. + +The application which initializes the packet capture framework will act as a +server and the application that enables or disables the packet capture will +act as a client. The server sends the Rx and Tx packets from the DPDK ports +to the client. + +In DPDK the ``testpmd`` application is modified to initialize the packet +capture framework and act as a server, and the ``dpdk-pdump`` tool acts +as a client. To view Rx or Tx packets of ``testpmd``, the application should +be launched first, and then the ``dpdk-pdump`` tool. Packets from the +``testpmd`` will be sent to the tool, which then sends them on to the pcap +pmd device and that device writes them to the pcap file or to an external +interface depending on the command-line option used. + + .. Note:: + * The ``dpdk-pdump`` tool can only be used in conjunction with a primary + application which has the packet capture framework initialized already. + In dpdk, only the ``testpmd`` is modified to initialize packet capture + framework, other applications remain untouched. So, if the ``dpdk-pdump`` + tool has to be used with any application other than the testpmd, user + needs to explicitly modify that application to call packet capture + framework initialization code. Refer ``app/test-pmd/testpmd.c`` + code and look for ``pdump`` keyword to see how this is done. + + * The ``dpdk-pdump`` tool depends on libpcap based PMD which is disabled + by default in the build configuration files, + owing to an external dependency on the libpcap development files + which must be installed on the board. + Once the libpcap development files are installed, the libpcap based PMD + can be enabled by setting CONFIG_RTE_LIBRTE_PMD_PCAP=y and recompiling the DPDK. + + +Test Environment +---------------- + +The overview of using packet capture framework and dpdk-pdump tool +for packet capturing on the DPDK port +in :numref:`figure_packet_capture_framework`. + +.. _figure_packet_capture_framework: + +.. figure:: img/packet_capture_framework.* + + Packet capturing on DPDK port using the dpdk-pdump tool. + +Configuration Steps +------------------- + +The following steps demonstrate how to run the ``dpdk-pdump`` tool to +capture Rx side packets of dpdk_port0 +in :numref:`figure_packet_capture_framework` and inspect them using +``tcpdump``. + +#. Modify the DPDK primary application to initialize the packet capture framework + as mentioned in above note, enable below config options and build the DPDK:: + + CONFIG_RTE_LIBRTE_PMD_PCAP=y + CONFIG_RTE_LIBRTE_PDUMP=y + +#. Launch testpmd as the primary application:: + + sudo ./app/testpmd -c 0xf0 -n 4 -- -i --port-topology=chained + +#. Launch the pdump tool as follows:: + + sudo ./build/app/dpdk-pdump -- \ + --pdump 'port=0,queue=*,rx-dev=/tmp/capture.pcap' + +#. Send traffic to dpdk_port0 from traffic generator. + Inspect packets captured in the file capture.pcap using a tool + that can interpret pcap files, for example tcpdump:: + + $tcpdump -nr /tmp/capture.pcap + reading from file /tmp/capture.pcap, link-type EN10MB (Ethernet) + 11:11:36.891404 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 + 11:11:36.891442 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 + 11:11:36.891445 IP 4.4.4.4.whois++ > 3.3.3.3.whois++: UDP, length 18 + +Conclusion +---------- + +In this doc we described the ``librte_pdump`` library and ``dpdk-pdump`` tool +usage for capturing traffic of DPDK ports. + +Additional Information +---------------------- + +More details on ``librte_pdump`` library and ``dpdk-pdump`` tool can be found +at following links. + +#. http://dpdk.org/doc/guides/prog_guide/pdump_lib.html +#. http://dpdk.org/doc/guides/tools/pdump.html -- 2.7.4
