summaryrefslogtreecommitdiffstats
path: root/docs/userguide/packet_forwarding.userguide.rst
diff options
context:
space:
mode:
authorJiang, Yunhong <yunhong.jiang@intel.com>2017-03-21 17:44:28 +0000
committerGerrit Code Review <gerrit@opnfv.org>2017-03-21 17:44:28 +0000
commit59ee691ba40e67e4975e0eaf768efb6df286ed3c (patch)
tree040e4d5aaf3a5aa05456a84fde72feaa16fdeda0 /docs/userguide/packet_forwarding.userguide.rst
parentb1495d4fa3175a3ffea301dedb9b0a60ca9ada44 (diff)
parentd4b19c2012c72015c7554ad0b0f098b9dae8aa7c (diff)
Merge "This patch is used to update the documents of D-release."
Diffstat (limited to 'docs/userguide/packet_forwarding.userguide.rst')
-rw-r--r--docs/userguide/packet_forwarding.userguide.rst212
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: