From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mogw1210.ocn.ad.jp (mogw1210.ocn.ad.jp [153.149.235.11]) by dpdk.org (Postfix) with ESMTP id 4104E1B456 for ; Thu, 14 Feb 2019 18:27:04 +0100 (CET) Received: from mf-smf-unw003c3 (mf-smf-unw003c3.ocn.ad.jp [153.138.219.74]) by mogw1210.ocn.ad.jp (Postfix) with ESMTP id D2263F80366; Fri, 15 Feb 2019 02:27:02 +0900 (JST) Received: from ocn-vc-mts-202c1.ocn.ad.jp ([153.138.219.215]) by mf-smf-unw003c3 with ESMTP id uKkTghvRxztfSuKmsgkEPo; Fri, 15 Feb 2019 02:27:02 +0900 Received: from smtp.ocn.ne.jp ([153.149.227.135]) by ocn-vc-mts-202c1.ocn.ad.jp with ESMTP id uKmsg6Cj4VBnyuKmsggbcY; Fri, 15 Feb 2019 02:27:02 +0900 Received: from localhost.localdomain (unknown [192.47.164.146]) by smtp.ocn.ne.jp (Postfix) with ESMTPA; Fri, 15 Feb 2019 02:27:02 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: spp@dpdk.org, ferruh.yigit@intel.com, ogawa.yasufumi@lab.ntt.co.jp Date: Fri, 15 Feb 2019 02:27:00 +0900 Message-Id: <20190214172700.5816-7-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20190214172700.5816-1-ogawa.yasufumi@lab.ntt.co.jp> References: <20190214172700.5816-1-ogawa.yasufumi@lab.ntt.co.jp> Subject: [spp] [PATCH 6/6] docs: update usecase of spp_pcap X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Feb 2019 17:27:04 -0000 From: Yasufumi Ogawa This patch is to revise usecase of spp_pcap. Signed-off-by: Yasufumi Ogawa --- docs/guides/spp_vf/use_cases/pcap_simple.rst | 253 ++++++++++++------- 1 file changed, 162 insertions(+), 91 deletions(-) diff --git a/docs/guides/spp_vf/use_cases/pcap_simple.rst b/docs/guides/spp_vf/use_cases/pcap_simple.rst index c31324e..34efce3 100644 --- a/docs/guides/spp_vf/use_cases/pcap_simple.rst +++ b/docs/guides/spp_vf/use_cases/pcap_simple.rst @@ -1,164 +1,235 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2019 Nippon Telegraph and Telephone Corporation -.. _spp_pcap_use_case: - -Packet Capture -============== +.. _spp_pcap_use_case: -This section describes a usecase for Packet Capture through ``spp_pcap``. +Packet Capture with spp_pcap +============================ -Incoming packets received by ``phy:0`` is captured by ``spp_pcap``. +This section describes a usecase for capturing packets with ``spp_pcap`` +and seeing inside of the captured file with ``tcpdump`` command. +:numref:`figure_simple_capture` shows the overview of scenario in which +incoming packets via ``phy:0`` are dumped as compressed pcap files by using +``spp_pcap``. .. _figure_simple_capture: .. figure:: ../../images/spp_vf/spp_pcap_overview.* :width: 50% - Simple Packet Capture + Packet capture with spp_pcap + + +.. _spp_pcap_use_case_launch_pcap: Launch spp_pcap ~~~~~~~~~~~~~~~ -Change directory to spp and confirm that it is already compiled. +Change directory if you are not in SPP's directory, +and compile if not done yet. .. code-block:: console $ cd /path/to/spp -As spp, launch spp-ctl and spp.py first. +Launch spp-ctl and SPP CLI in different terminals. .. code-block:: console - # Launch spp-ctl and spp.py - $ python3 ./src/spp-ctl/spp-ctl -b 127.0.0.1 - $ python ./src/spp.py -b 127.0.0.1 + # terminal 1 + $ python3 ./src/spp-ctl/spp-ctl -b 192.168.1.100 + +.. code-block:: console + + # terminal 2 + $ python3 ./src/spp.py -b 192.168.1.100 -Then, run ``spp_primary``. +Then, run ``spp_primary`` with one physical port. .. code-block:: console + # terminal 3 $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \ - -c 0x02 -n 4 \ + -l 0 -n 4 \ --socket-mem 512,512 \ - --huge-dir=/run/hugepages/kvm \ - --proc-type=primary \ + --huge-dir /run/hugepages/kvm \ + --proc-type primary \ -- \ - -p 0x03 -n 8 -s 127.0.0.1:5555 + -p 0x01 \ + -n 8 -s 192.168.1.100:5555 -After ``spp_primary`` is launched, run secondary process ``spp_pcap``. -If not ``--output`` directory is not created, please create it first. +After ``spp_primary`` is launched successfully, run ``spp_pcap`` in other +terminal. In this usecase, you use default values for optional arguments. +Output directory of captured file is ``/tmp`` and the size of file is +``1GiB``. +You notice that six lcores are assigned with ``-l 1-6``. +It means that you use one locre for master, one for receiver, and four for +writer threads. .. code-block:: console - $ sudo mkdir /mnt/pcap + # terminal 4 $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \ - -l 0-4 -n 4 --proc-type=secondary \ + -l 1-6 -n 4 --proc-type=secondary \ -- \ - --client-id 1 -s 127.0.0.1:6666 \ - -i phy:0 --output /mnt/pcap --limit_file_size 1073741824 + --client-id 1 -s 192.168.1.100:6666 \ + -c phy:0 -Start capturing -~~~~~~~~~~~~~~~ -When you want to start capture, then type the following command. +You can confirm lcores and worker threads running on from ``status`` command. -.. code-block:: console +.. code-block:: none - spp > pcap SEC_ID; start + # terminal 2 + spp > pcap 1; status + - client-id: 1 + - status: idle + - core:2 receive + - rx: phy:0 + - core:3 write + - filename: + - core:4 write + - filename: + - core:5 write + - filename: + - core:6 write + - filename: -In this usecase, spp_pcap is launched with ID=1. Let's start capturing. -.. code-block:: console +.. _spp_pcap_use_case_start_capture: - # Start packet capture - spp > pcap 1;start +Start Capture +~~~~~~~~~~~~~ -Stop capturing -~~~~~~~~~~~~~~ +If you already started to send packets to ``phy:0`` from outside, +you are ready to start capturing packets. -When you want to stop capture, then type the following command. +.. code-block:: none -.. code-block:: console + # terminal 2 + spp > pcap 1; start + Start packet capture. - spp > pcap SEC_ID; stop +As you run ``start`` command, PCAP files are generated for each of +``writer`` threads for capturing. -In this usecase, spp_pcap is launched with ID=1. Let's stop capturing. +.. code-block:: none -.. code-block:: console + # terminal 2 + spp > pcap 1; status + - client-id: 1 + - status: running + - core:2 receive + - rx: phy:0 + - core:3 write + - filename: /tmp/spp_pcap.20190214161550.phy0.1.1.pcap.lz4 + - core:4 write + - filename: /tmp/spp_pcap.20190214161550.phy0.2.1.pcap.lz4 + - core:5 write + - filename: /tmp/spp_pcap.20190214161550.phy0.3.1.pcap.lz4 + - core:6 write + - filename: /tmp/spp_pcap.20190214161550.phy0.4.1.pcap.lz4 - # Stop packet capture - spp > pcap 1;stop +.. _spp_pcap_use_case_stop_capture: -Now, you can see capture file written in specified directory. +Stop Capture +~~~~~~~~~~~~ -.. code-block:: console +Stop capturing and confirm that compressed PCAP files are generated. - # show the content of directry - $ cd /mnt/pcap - $ ls - spp_pcap.20181108110600.phy0.1.1.pcap.lz4 - spp_pcap.20181108110600.phy0.2.1.pcap.lz4 - spp_pcap.20181108110600.phy0.3.1.pcap.lz4 +.. code-block:: none -Each files are compressed using LZ4, so that to uncompress it, -use lz4 utils. + # terminal 2 + spp > pcap 1; stop + spp > ls /tmp + .... + spp_pcap.20190214175446.phy0.1.1.pcap.lz4 + spp_pcap.20190214175446.phy0.1.2.pcap.lz4 + spp_pcap.20190214175446.phy0.1.3.pcap.lz4 + spp_pcap.20190214175446.phy0.2.1.pcap.lz4 + spp_pcap.20190214175446.phy0.2.2.pcap.lz4 + spp_pcap.20190214175446.phy0.2.3.pcap.lz4 + .... -.. code-block:: console - - # uncompress lz4 files - $ sudo lz4 -d -m spp_pcap.20181108110600.phy0.* - $ ls - spp_pcap.20181108110600.phy0.1.1.pcap - spp_pcap.20181108110600.phy0.2.1.pcap - spp_pcap.20181108110600.phy0.3.1.pcap - spp_pcap.20181108110600.phy0.1.1.pcap.lz4 - spp_pcap.20181108110600.phy0.2.1.pcap.lz4 - spp_pcap.20181108110600.phy0.3.1.pcap.lz4 - -To combine those divided pcap files using mergecap utility. - -.. code-block:: console +Index in the filename, such as ``1.1`` or ``1.2``, is a combination of +``writer`` thread ID and sequenceal number. +In this case, it means each of four threads generate three files. - # merge pcap files - $ sudo mergecap spp_pcap.20181108110600.phy0.1.1.pcap \ - spp_pcap.20181108110600.phy0.2.1.pcap \ - spp_pcap.20181108110600.phy0.3.1.pcap \ - -w test.pcap - $ ls - spp_pcap.20181108110600.phy0.1.1.pcap - spp_pcap.20181108110600.phy0.2.1.pcap - spp_pcap.20181108110600.phy0.3.1.pcap - spp_pcap.20181108110600.phy0.1.1.pcap.lz4 - spp_pcap.20181108110600.phy0.2.1.pcap.lz4 - spp_pcap.20181108110600.phy0.3.1.pcap.lz4 - test.pcap .. _spp_pcap_use_case_shutdown: Shutdown spp_pcap ~~~~~~~~~~~~~~~~~ -Basically, you can shutdown all of SPP processes with ``bye all`` -command. +Run ``exit`` or ``bye sec`` command to terminate ``spp_pcap``. -This section describes graceful shutting down for ``spp_pcap``. +.. code-block:: none -First, stop capturing using the following command if it is not -already stopped. + # terminal 2 + spp > pcap 1; exit + + +.. _spp_pcap_use_case_inspect_file: + +Inspect PCAP Files +~~~~~~~~~~~~~~~~~~ + +You can inspect captured PCAP files by using utilities. + +Merge PCAP Files +^^^^^^^^^^^^^^^^ + +Extract and merge compressed PCAP files. + +For extract several LZ4 files at once, use ``-d`` and ``-m`` options. +``-d`` is for decompression and ``-m`` is for multiple files. + +You had better not to merge divided files into single file, but still +several files because the size of merged file might be huge. +Each of extracted PCAP file is 1GiB in default, so total size of extracted +files is 12GiB in this case. To avoid the situation, merge files for each of +threads and generate four PCAP files of 3GiB. + +First, extract LZ4 files of writer thread ID 1. .. code-block:: console - # Stop packet capture - spp > pcap 1;stop + # terminal 4 + $ lz4 -d -m /tmp/spp_pcap.20190214175446.phy0.1.* + +And confirm that the files are extracted. + +.. code-block:: console + + # terminal 4 + $ ls /tmp | grep pcap$ + spp_pcap.20190214175446.phy0.1.1.pcap + spp_pcap.20190214175446.phy0.1.2.pcap + spp_pcap.20190214175446.phy0.1.3.pcap + +Run ``mergecap`` command to merge extracted files to current directory +as ``spp_pcap1.pcap``. + +.. code-block:: console + + # terminal 4 + $ mergecap /tmp/spp_pcap.20190214175446.phy0.1.*.pcap -w spp_pcap1.pcap + +Inspect PCAP file +^^^^^^^^^^^^^^^^^ -If you want to start capture again then use ``start`` command again. -Else if you want to quit ``spp_pcap`` itself, type the following command -and quit application. +You can use any of applications, for instance ``wireshark`` or ``tcpdump``, +for inspecting PCAP file. +To inspect the merged PCAP file, read packet data from ``tcpdump`` command +in this usecase. ``-r`` option is to dump packet data in human readable format. .. code-block:: console - # Exit packet capture - spp > pcap 1;exit + # terminal 4 + $ tcpdump -r spp_pcap1.pcap | less + 17:54:52.559783 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ... + 17:54:52.559784 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ... + 17:54:52.559785 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ... + 17:54:52.559785 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ... -- 2.17.1