diff options
Diffstat (limited to 'docs/userguide/packet_forwarding.userguide.rst')
| -rw-r--r-- | docs/userguide/packet_forwarding.userguide.rst | 212 |
1 files changed, 145 insertions, 67 deletions
diff --git a/docs/userguide/packet_forwarding.userguide.rst b/docs/userguide/packet_forwarding.userguide.rst index ba117508c..594952bdf 100644 --- a/docs/userguide/packet_forwarding.userguide.rst +++ b/docs/userguide/packet_forwarding.userguide.rst @@ -5,14 +5,14 @@ ================= PACKET FORWARDING ================= -======================= + About Packet Forwarding -======================= +----------------------- -Packet Forwarding is a test suite of KVMFORNFV which is used to measure the total time taken by a -**Packet** generated by the traffic generator to return from Guest/Host as per the implemented -scenario. Packet Forwarding is implemented using VSWITCHPERF/``VSPERF software of OPNFV`` and an -``IXIA Traffic Generator``. +Packet Forwarding is a test suite of KVMFORNFV. These latency tests measures the time taken by a +**Packet** generated by the traffic generator to travel from the originating device through the +network to the destination device. Packet Forwarding is implemented using test framework +implemented by OPNFV VSWITCHPERF project and an ``IXIA Traffic Generator``. Version Features ---------------- @@ -29,14 +29,14 @@ Version Features | | - Packet Forwarding is a testcase in KVMFORNFV | | | - Implements three scenarios (Host/Guest/SRIOV) | | | as part of testing in KVMFORNFV | -| Danube | - Uses available testcases of OPNFV's VSWTICHPERF | -| | software (PVP/PVVP) | +| Danube | - Uses automated test framework of OPNFV | +| | VSWITCHPERF software (PVP/PVVP) | +| | | | | - Works with IXIA Traffic Generator | +-----------------------------+---------------------------------------------------+ -====== VSPERF -====== +------ VSPerf is an OPNFV testing project. VSPerf will develop a generic and architecture agnostic vSwitch testing framework and associated @@ -47,17 +47,18 @@ VNF level testing and validation. For complete VSPERF documentation go to `link.`_ -.. _link.: <http://artifacts.opnfv.org/vswitchperf/colorado/index.html> +.. _link.: http://artifacts.opnfv.org/vswitchperf/colorado/index.html Installation ------------- +~~~~~~~~~~~~ + Guidelines of installating `VSPERF`_. -.. _VSPERF: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html> +.. _VSPERF: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html Supported Operating Systems ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ * CentOS 7 * Fedora 20 @@ -67,19 +68,21 @@ Supported Operating Systems * Ubuntu 14.04 Supported vSwitches -------------------- +~~~~~~~~~~~~~~~~~~~ + The vSwitch must support Open Flow 1.3 or greater. * OVS (built from source). * OVS with DPDK (built from source). Supported Hypervisors ---------------------- +~~~~~~~~~~~~~~~~~~~~~ * Qemu version 2.3. Other Requirements ------------------- +~~~~~~~~~~~~~~~~~~ + The test suite requires Python 3.3 and relies on a number of other packages. These need to be installed for the test suite to function. @@ -93,9 +96,9 @@ user account, which will be used for vsperf execution. Execution of installation script: -.. code:: bashFtrace.debugging.tool.userguide.rst +.. code:: bash - $ cd Vswitchperf + $ cd vswitchperf $ cd systems $ ./build_base_machine.sh @@ -115,10 +118,10 @@ For running testcases VSPERF is installed on Intel pod1-node2 in which centos operating system is installed. Only VSPERF installion on Centos is discussed here. For installation steps on other operating systems please refer to `here`_. -.. _here: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html> +.. _here: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html For CentOS 7 ------------------ +~~~~~~~~~~~~~~ ## Python 3 Packages @@ -147,16 +150,16 @@ To activate, simple run: Working Behind a Proxy ------------------------ +~~~~~~~~~~~~~~~~~~~~~~ If you're behind a proxy, you'll likely want to configure this before running any of the above. For example: .. code:: bash - export http_proxy=proxy.mycompany.com:123 - export https_proxy=proxy.mycompany.com:123 - - + export http_proxy="http://<username>:<password>@<proxy>:<port>/"; + export https_proxy="https://<username>:<password>@<proxy>:<port>/"; + export ftp_proxy="ftp://<username>:<password>@<proxy>:<port>/"; + export socks_proxy="socks://<username>:<password>@<proxy>:<port>/"; .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/ .. _virtualenv: https://virtualenv.readthedocs.org/en/latest/ @@ -166,10 +169,11 @@ For other OS specific activation click `this link`_: .. _this link: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/installation.html#other-requirements Traffic-Generators -------------------- +------------------ + VSPERF supports many Traffic-generators. For configuring VSPERF to work with the available traffic-generator go through `this`_. -.. _this: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/trafficgen.html> +.. _this: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/trafficgen.html VSPERF supports the following traffic generators: @@ -191,35 +195,40 @@ and configure the various traffic generators. As KVM4NFV uses only IXIA traffic generator, it is discussed here. For complete documentation regarding traffic generators please follow this `link`_. -.. _link: <https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob;f=docs/configguide/trafficgen.rst;h=85fc35b886d30db3b92a6b7dcce7ca742b70cbdc;hb=HEAD> +.. _link: https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob;f=docs/configguide/trafficgen.rst;h=85fc35b886d30db3b92a6b7dcce7ca742b70cbdc;hb=HEAD -========== IXIA Setup -========== +---------- -===================== Hardware Requirements -===================== -VSPERF requires the following hardware to run tests: IXIA traffic generator (IxNetwork), a machine that runs the IXIA client software and a CentOS Linux release 7.1.1503 (Core) host. +~~~~~~~~~~~~~~~~~~~~~ + +VSPERF requires the following hardware to run tests: IXIA traffic generator (IxNetwork), a machine that +runs the IXIA client software and a CentOS Linux release 7.1.1503 (Core) host. Installation -------------- +~~~~~~~~~~~~ Follow the [installation instructions] to install. -IXIA Setup ------------- On the CentOS 7 system ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ + You need to install IxNetworkTclClient$(VER_NUM)Linux.bin.tgz. On the IXIA client software system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Find the IxNetwork TCL server app (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server) - Right click on IxNetwork TCL Server, select properties - - Under shortcut tab in the Target dialogue box make sure there is the argument "-tclport xxxx" where xxxx is your port number (take note of this port number you will need it for the 10_custom.conf file). + - Under shortcut tab in the Target dialogue box make sure there is the argument "-tclport xxxx" + +where xxxx is your port number (take note of this port number you will need it for the 10_custom.conf file). -.. Figure:: ../images/IXIA1.png +.. figure:: images/IXIA1.png + :name: IXIA1 setup + :width: 100% + :align: center - Hit Ok and start the TCL server application @@ -261,7 +270,7 @@ Detailed description of options follows: .. _test-results-share: Test results share -------------------- +~~~~~~~~~~~~~~~~~~ VSPERF is not able to retrieve test results via TCL API directly. Instead, all test results are stored at IxNetwork TCL server. Results are stored at folder defined by @@ -285,19 +294,20 @@ Example of sharing configuration: Note: It is essential to use slashes '/' also in path configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter. - * Install cifs-utils package. + +* Install cifs-utils package. e.g. at rpm based Linux distribution: - .. code-block:: console +.. code-block:: console yum install cifs-utils - * Mount shared directory, so VSPERF can access test results. +* Mount shared directory, so VSPERF can access test results. e.g. by adding new record into ``/etc/fstab`` - .. code-block:: console +.. code-block:: console mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results -o file_mode=0777,dir_mode=0777,nounix @@ -308,6 +318,7 @@ is visible at DUT inside ``/mnt/ixia_results`` directory. Cloning and building src dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + In order to run VSPERF, you will need to download DPDK and OVS. You can do this manually and build them in a preferred location, or you could use vswitchperf/src. The vswitchperf/src directory contains makefiles that will allow you to clone and build the libraries that VSPERF depends on, @@ -326,13 +337,16 @@ To delete a src subdirectory and its contents to allow you to re-clone simply us Configure the `./conf/10_custom.conf` file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The supplied `10_custom.conf` file must be modified, as it contains configuration items for which there are no reasonable default values. -The configuration items that can be added is not limited to the initial contents. Any configuration item mentioned in any .conf file in `./conf` directory can be added and that item will be overridden by the custom +The configuration items that can be added is not limited to the initial contents. Any configuration item +mentioned in any .conf file in `./conf` directory can be added and that item will be overridden by the custom configuration value. Using a custom settings file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Alternatively a custom settings file can be passed to `vsperf` via the `--conf-file` argument. .. code:: bash @@ -347,8 +361,34 @@ argument will override both the default and your custom configuration files. Thi 2. Environment variables 3. Configuration file(s) +vloop_vnf +~~~~~~~~~ + +VSPERF uses a VM image called vloop_vnf for looping traffic in the deployment +scenarios involving VMs. The image can be downloaded from +`<http://artifacts.opnfv.org/>`__. + +Please see the installation instructions for information on :ref:`vloop-vnf` +images. + +.. _l2fwd-module: + +l2fwd Kernel Module +~~~~~~~~~~~~~~~~~~~ + +A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with +support for Destination Network Address Translation (DNAT) for both the MAC and +IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd + +.. figure:: images/Guest_Scenario.png + :name: Guest_Scenario + :width: 100% + :align: center + + Executing tests ~~~~~~~~~~~~~~~~ + Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers: .. code:: bash @@ -382,7 +422,7 @@ Some tests allow for configurable parameters, including test duration (in second ./vsperf --conf-file user_settings.py --tests RFC2544Tput - --test-param "rfc2544_duration=10;packet_sizes=128" + --test-param` "rfc2544_duration=10;packet_sizes=128" For all available options, check out the help dialog: @@ -393,6 +433,7 @@ For all available options, check out the help dialog: Testcases ---------- + Available Tests in VSPERF are: * phy2phy_tput @@ -444,9 +485,9 @@ Example of execution of VSPERF in "trafficgen" mode: --test-params "TRAFFIC={'traffic_type':'rfc2544_continuous','bidir':'False','framerate':60}" -================================ Packet Forwarding Test Scenarios -================================ +-------------------------------- + KVMFORNFV currently implements three scenarios as part of testing: * Host Scenario @@ -455,32 +496,47 @@ KVMFORNFV currently implements three scenarios as part of testing: Packet Forwarding Host Scenario -------------------------------- -Here Host is NODE-2. It has VSPERF installed in it and is properly configured to use IXIA Traffic-generator by providing IXIA CARD, PORTS and Lib paths along with IP. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here host DUT has VSPERF installed in it and is properly configured to use IXIA Traffic-generator +by providing IXIA CARD, PORTS and Lib paths along with IP. please refer to figure.2 -.. Figure:: ../images/Host_Scenario.png +.. figure:: images/Host_Scenario.png + :name: Host_Scenario + :width: 100% + :align: center Packet Forwarding Guest Scenario --------------------------------- -Here the guest is a Virtual Machine (VM) launched by using a modified CentOS image(vsperf provided) -on Node-2 (Host) using Qemu. In this scenario, the packet is initially forwarded to Host which is -then forwarded to the launched guest. The time taken by the packet to reach the IXIA traffic-generator -via Host and Guest is calculated and published as a test result of this scenario. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. Figure:: ../images/Guest_Scenario.png +Here the guest is a Virtual Machine (VM) launched by using vloop_vnf provided by vsperf project +on host/DUT using Qemu. In this latency test the time taken by the frame/packet to travel from the +originating device through network involving a guest to destination device is calculated. +The resulting latency values will define the performance of installed kernel. + +.. figure:: images/Guest_Scenario.png + :name: Guest_Scenario + :width: 100% + :align: center Packet Forwarding SRIOV Scenario --------------------------------- -Unlike the packet forwarding to Guest-via-Host scenario, here the packet generated at the IXIA is -directly forwarded to the Guest VM launched on Host by implementing SR-IOV interface at NIC level -of Host .i.e., Node-2. The time taken by the packet to reach the IXIA traffic-generator is calculated -and published as a test result for this scenario. SRIOV-support_ is given below, it details how to use SR-IOV. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this test the packet generated at the IXIA is forwarded to the Guest VM launched on Host by +implementing SR-IOV interface at NIC level of host .i.e., DUT. The time taken by the packet to +travel through the network to the destination the IXIA traffic-generator is calculated and +published as a test result for this scenario. -.. Figure:: ../images/SRIOV_Scenario.png +SRIOV-support_ is given below, it details how to use SR-IOV. + +.. figure:: images/SRIOV_Scenario.png + :name: SRIOV_Scenario + :width: 100% + :align: center Using vfio_pci with DPDK ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ To use vfio with DPDK instead of igb_uio add into your custom configuration file the following parameter: @@ -521,7 +577,7 @@ To check that IOMMU is enabled on your platform: .. _SRIOV-support: Using SRIOV support -------------------- +~~~~~~~~~~~~~~~~~~~ To use virtual functions of NIC with SRIOV support, use extended form of NIC PCI slot definition: @@ -553,3 +609,25 @@ For example: * tests without vSwitch, where VM accesses VF interfaces directly by PCI-passthrough to measure raw VM throughput performance. +Using QEMU with PCI passthrough support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Raw virtual machine throughput performance can be measured by execution of PVP +test with direct access to NICs by PCI passthrough. To execute VM with direct +access to PCI devices, enable vfio-pci_. In order to use virtual functions, +SRIOV-support_ must be enabled. + +Execution of test with PCI passthrough with vswitch disabled: + +.. code-block:: console + + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --vswitch none --vnf QemuPciPassthrough pvp_tput + +Any of supported guest-loopback-application_ can be used inside VM with +PCI passthrough support. + +Note: Qemu with PCI passthrough support can be used only with PVP test +deployment. + +.. _guest-loopback-application: |