diff options
Diffstat (limited to 'docs/userguide/packet_forwarding.userguide.rst')
-rw-r--r-- | docs/userguide/packet_forwarding.userguide.rst | 633 |
1 files changed, 0 insertions, 633 deletions
diff --git a/docs/userguide/packet_forwarding.userguide.rst b/docs/userguide/packet_forwarding.userguide.rst deleted file mode 100644 index 31341a908..000000000 --- a/docs/userguide/packet_forwarding.userguide.rst +++ /dev/null @@ -1,633 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. http://creativecommons.org/licenses/by/4.0 - -================= -Packet Forwarding -================= - -About Packet Forwarding ------------------------ - -Packet Forwarding is a test suite of KVM4NFV. 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 ----------------- - -+-----------------------------+---------------------------------------------------+ -| | | -| **Release** | **Features** | -| | | -+=============================+===================================================+ -| | - Packet Forwarding is not part of Colorado | -| Colorado | release of KVM4NFV | -| | | -+-----------------------------+---------------------------------------------------+ -| | - Packet Forwarding is a testcase in KVM4NFV | -| | - Implements three scenarios (Host/Guest/SRIOV) | -| | as part of testing in KVM4NFV | -| 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 -tests, that will serve as a basis for validating the suitability of different vSwitch -implementations in a Telco NFV deployment environment. The output of this project will be utilized -by the OPNFV Performance and Test group and its associated projects, as part of OPNFV Platform and -VNF level testing and validation. - -For complete VSPERF documentation go to `link.`_ - -.. _link.: http://artifacts.opnfv.org/vswitchperf/danube/index.html - - -Installation -~~~~~~~~~~~~ - -Guidelines of installating `VSPERF`_. - -.. _VSPERF: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html - -Supported Operating Systems -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* CentOS 7 -* Fedora 20 -* Fedora 21 -* Fedora 22 -* RedHat 7.2 -* 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.6. - -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. - -Installation of required packages, preparation of Python 3 virtual -environment and compilation of OVS, DPDK and QEMU is performed by -script **systems/build_base_machine.sh**. It should be executed under -user account, which will be used for vsperf execution. - - **Please Note:** Password-less sudo access must be configured for given user before script is executed. - -Execution of installation script: - -.. code:: bash - - $ cd vswitchperf - $ cd systems - $ ./build_base_machine.sh - -Script **build_base_machine.sh** will install all the vsperf dependencies -in terms of system packages, Python 3.x and required Python modules. -In case of CentOS 7 it will install Python 3.3 from an additional repository -provided by Software Collections (`a link`_). In case of RedHat 7 it will -install Python 3.4 as an alternate installation in /usr/local/bin. Installation -script will also use `virtualenv`_ to create a vsperf virtual environment, -which is isolated from the default Python environment. This environment will -reside in a directory called **vsperfenv** in $HOME. - -You will need to activate the virtual environment every time you start a -new shell session. Its activation is specific to your OS: - -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 - -For CentOS 7 -~~~~~~~~~~~~~~ - -## Python 3 Packages - -To avoid file permission errors and Python version issues, use virtualenv to create an isolated environment with Python3. -The required Python 3 packages can be found in the `requirements.txt` file in the root of the test suite. -They can be installed in your virtual environment like so: - -.. code:: bash - - scl enable python33 bash - # Create virtual environment - virtualenv vsperfenv - cd vsperfenv - source bin/activate - pip install -r requirements.txt - - -You need to activate the virtual environment every time you start a new shell session. -To activate, simple run: - -.. code:: bash - - scl enable python33 bash - cd vsperfenv - source bin/activate - - -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="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/ - -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 - -VSPERF supports the following traffic generators: - - * Dummy (DEFAULT): Allows you to use your own external - traffic generator. - * IXIA (IxNet and IxOS) - * Spirent TestCenter - * Xena Networks - * MoonGen - -To see the list of traffic gens from the cli: - -.. code-block:: console - - $ ./vsperf --list-trafficgens - -This guide provides the details of how to install -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 - -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. - -Installation -~~~~~~~~~~~~ - -Follow the installation instructions to install. - -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). - -.. figure:: images/IXIA1.png - :name: IXIA1 setup - :width: 100% - :align: center - -- Hit Ok and start the TCL server application - -VSPERF configuration --------------------- - -There are several configuration options specific to the IxNetworks traffic generator -from IXIA. It is essential to set them correctly, before the VSPERF is executed -for the first time. - -Detailed description of options follows: - - * TRAFFICGEN_IXNET_MACHINE - IP address of server, where IxNetwork TCL Server is running - * TRAFFICGEN_IXNET_PORT - PORT, where IxNetwork TCL Server is accepting connections from - TCL clients - * TRAFFICGEN_IXNET_USER - username, which will be used during communication with IxNetwork - TCL Server and IXIA chassis - * TRAFFICGEN_IXIA_HOST - IP address of IXIA traffic generator chassis - * TRAFFICGEN_IXIA_CARD - identification of card with dedicated ports at IXIA chassis - * TRAFFICGEN_IXIA_PORT1 - identification of the first dedicated port at TRAFFICGEN_IXIA_CARD - at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of - unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC - at DUT, i.e. to the first PCI handle from WHITELIST_NICS list. Otherwise traffic may not - be able to pass through the vSwitch. - * TRAFFICGEN_IXIA_PORT2 - identification of the second dedicated port at TRAFFICGEN_IXIA_CARD - at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of - unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC - at DUT, i.e. to the second PCI handle from WHITELIST_NICS list. Otherwise traffic may not - be able to pass through the vSwitch. - * TRAFFICGEN_IXNET_LIB_PATH - path to the DUT specific installation of IxNetwork TCL API - * TRAFFICGEN_IXNET_TCL_SCRIPT - name of the TCL script, which VSPERF will use for - communication with IXIA TCL server - * TRAFFICGEN_IXNET_TESTER_RESULT_DIR - folder accessible from IxNetwork TCL server, - where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_ - * TRAFFICGEN_IXNET_DUT_RESULT_DIR - directory accessible from the DUT, where test - results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see - test-results-share_ - -.. _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 -``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this -folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where -VSPERF is executed. VSPERF expects, that test results will be available at directory -configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter. - -Example of sharing configuration: - - * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results`` - * Modify sharing options of ``ixia_results`` folder to share it with everybody - * Create a new directory at DUT, where shared directory with results - will be mounted, e.g. ``/mnt/ixia_results`` - * Update your custom VSPERF configuration file as follows: - - .. code-block:: python - - TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results' - TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results' - - Note: It is essential to use slashes '/' also in path - configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter. - -* Install cifs-utils package. - - e.g. at rpm based Linux distribution: - -.. code-block:: console - - yum install cifs-utils - -* Mount shared directory, so VSPERF can access test results. - - e.g. by adding new record into ``/etc/fstab`` - -.. code-block:: console - - mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results - -o file_mode=0777,dir_mode=0777,nounix - -It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder -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, -such as DPDK and OVS. To clone and build simply: - -.. code:: bash - - cd src - make - -To delete a src subdirectory and its contents to allow you to re-clone simply use: - -.. code:: bash - - make cleanse - -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 -configuration value. - -Using a custom settings file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Alternatively a custom settings file can be passed to `vsperf` via the `--conf-file` argument. - -.. code:: bash - - ./vsperf --conf-file <path_to_settings_py> ... - -Note that configuration passed in via the environment (`--load-env`) or via another command line -argument will override both the default and your custom configuration files. This -"priority hierarchy" can be described like so (1 = max priority): - -1. Command line arguments -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 - -Executing tests -~~~~~~~~~~~~~~~~ - -Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers: -.. code:: bash - - username ALL=(ALL) NOPASSWD: ALL - -username in the example above should be replaced with a real username. - -To list the available tests: - -.. code:: bash - - ./vsperf --list-tests - - -To run a group of tests, for example all tests with a name containing -'RFC2544': - -.. code:: bash - - ./vsperf --conf-file=user_settings.py --tests="RFC2544" - -To run all tests: - -.. code:: bash - - ./vsperf --conf-file=user_settings.py - -Some tests allow for configurable parameters, including test duration (in seconds) as well as packet sizes (in bytes). - -.. code:: bash - - ./vsperf --conf-file user_settings.py - --tests RFC2544Tput - --test-param` "rfc2544_duration=10;packet_sizes=128" - -For all available options, check out the help dialog: - -.. code:: bash - - ./vsperf --help - - -Testcases ----------- - -Available Tests in VSPERF are: - - * phy2phy_tput - * phy2phy_forwarding - * back2back - * phy2phy_tput_mod_vlan - * phy2phy_cont - * pvp_cont - * pvvp_cont - * pvpv_cont - * phy2phy_scalability - * pvp_tput - * pvp_back2back - * pvvp_tput - * pvvp_back2back - * phy2phy_cpu_load - * phy2phy_mem_load - -VSPERF modes of operation --------------------------- - -VSPERF can be run in different modes. By default it will configure vSwitch, -traffic generator and VNF. However it can be used just for configuration -and execution of traffic generator. Another option is execution of all -components except traffic generator itself. - -Mode of operation is driven by configuration parameter -m or --mode - -.. code-block:: console - - -m MODE, --mode MODE vsperf mode of operation; - Values: - "normal" - execute vSwitch, VNF and traffic generator - "trafficgen" - execute only traffic generator - "trafficgen-off" - execute vSwitch and VNF - "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission - -In case, that VSPERF is executed in "trafficgen" mode, then configuration -of traffic generator can be modified through ``TRAFFIC`` dictionary passed to the -``--test-params`` option. It is not needed to specify all values of ``TRAFFIC`` -dictionary. It is sufficient to specify only values, which should be changed. -Detailed description of ``TRAFFIC`` dictionary can be found at: ref:`configuration-of-traffic-dictionary`. - -Example of execution of VSPERF in "trafficgen" mode: - -.. code-block:: console - - $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf \ - --test-params "TRAFFIC={'traffic_type':'rfc2544_continuous','bidir':'False','framerate':60}" - - -Packet Forwarding Test Scenarios --------------------------------- - -KVM4NFV currently implements three scenarios as part of testing: - - * Host Scenario - * Guest Scenario. - * SR-IOV Scenario. - - -Packet Forwarding Host Scenario -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 - :name: Host_Scenario - :width: 100% - :align: center - -Packet Forwarding Guest Scenario -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -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: - -.. code-block:: python - - PATHS['dpdk']['src']['modules'] = ['uio', 'vfio-pci'] - - -**NOTE:** In case, that DPDK is installed from binary package, then please - - set ``PATHS['dpdk']['bin']['modules']`` instead. - -**NOTE:** Please ensure that Intel VT-d is enabled in BIOS. - -**NOTE:** Please ensure your boot/grub parameters include -the following: - -.. code-block:: console - - iommu=pt intel_iommu=on - -To check that IOMMU is enabled on your platform: - -.. code-block:: console - - $ dmesg | grep IOMMU - [ 0.000000] Intel-IOMMU: enabled - [ 0.139882] dmar: IOMMU 0: reg_base_addr fbffe000 ver 1:0 cap d2078c106f0466 ecap f020de - [ 0.139888] dmar: IOMMU 1: reg_base_addr ebffc000 ver 1:0 cap d2078c106f0466 ecap f020de - [ 0.139893] IOAPIC id 2 under DRHD base 0xfbffe000 IOMMU 0 - [ 0.139894] IOAPIC id 0 under DRHD base 0xebffc000 IOMMU 1 - [ 0.139895] IOAPIC id 1 under DRHD base 0xebffc000 IOMMU 1 - [ 3.335744] IOMMU: dmar0 using Queued invalidation - [ 3.335746] IOMMU: dmar1 using Queued invalidation - .... - -.. _SRIOV-support: - -Using SRIOV support -~~~~~~~~~~~~~~~~~~~ - -To use virtual functions of NIC with SRIOV support, use extended form -of NIC PCI slot definition: - -.. code-block:: python - - WHITELIST_NICS = ['0000:03:00.0|vf0', '0000:03:00.1|vf3'] - -Where ``vf`` is an indication of virtual function usage and following -number defines a VF to be used. In case that VF usage is detected, -then vswitchperf will enable SRIOV support for given card and it will -detect PCI slot numbers of selected VFs. - -So in example above, one VF will be configured for NIC '0000:05:00.0' -and four VFs will be configured for NIC '0000:05:00.1'. Vswitchperf -will detect PCI addresses of selected VFs and it will use them during -test execution. - -At the end of vswitchperf execution, SRIOV support will be disabled. - -SRIOV support is generic and it can be used in different testing scenarios. -For example: - - -* vSwitch tests with DPDK or without DPDK support to verify impact - of VF usage on vSwitch performance -* tests without vSwitch, where traffic is forwared directly - between VF interfaces by packet forwarder (e.g. testpmd application) -* 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. - -Results -~~~~~~~ - -The results for the packet forwarding test cases are uploaded to artifacts. -The link for the same can be found below - -.. code:: bash - - http://artifacts.opnfv.org/kvmfornfv.html |