summaryrefslogtreecommitdiffstats
path: root/docs/userguides/quickstart.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/userguides/quickstart.rst')
-rwxr-xr-xdocs/userguides/quickstart.rst199
1 files changed, 112 insertions, 87 deletions
diff --git a/docs/userguides/quickstart.rst b/docs/userguides/quickstart.rst
index 91162f88..e93a040f 100755
--- a/docs/userguides/quickstart.rst
+++ b/docs/userguides/quickstart.rst
@@ -2,66 +2,90 @@
Getting Started with 'vsperf'
=============================
-Hardware Requirements
----------------------
+Requirements
+-------------
-VSPERF requires one of the following traffic generators to run tests:
+VSPERF requires a traffic generators to run tests, automated traffic gen
+support in VSPERF includes:
-- IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA client software
-- Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual in a VM) and a
- VM to run the Spirent Virtual Deployment Service image, formerly known as "Spirent LabServer".
+- IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA
+ client software.
+- Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual
+ in a VM) and a VM to run the Spirent Virtual Deployment Service image,
+ formerly known as "Spirent LabServer".
-Both test configurations, above, also require a CentOS Linux release 7.1.1503 (Core) host.
+If you want to use another traffic generator, please select the Dummy generator
+option as shown in `Traffic generator instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__
+
+Supported OSes include:
+
+* CentOS Linux release 7.1.1503 (Core) host.
+* Fedora 21 and 22.
+* Ubuntu 14.04
vSwitch Requirements
--------------------
-The vSwitch must support Open Flow 1.3 or greater.
+The vSwitch must support Open Flow 1.3 or greater. VSPERF supports both:
-Installation
-------------
+* OVS
+* OVS with DPDK
-Follow the `installation instructions <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/index.html>`__ to install.
+VSPERF Installation
+--------------------
+
+Follow the `installation instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/index.html>`__ to
+install.
Traffic Generator Setup
-----------------------
-Follow the `Traffic generator instructions <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__ to install and configure a suitable traffic generator.
+Follow the `Traffic generator instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__ to
+install and configure a suitable traffic generator.
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
+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-block:: console
+.. code-block:: console
+
+ $ cd src
+ $ make
- cd src
- make
+VSPERF can be used with stock OVS (without DPDK support). In this case you have
+to specify path to the kernel sources when building OVS in src by specifying
+WITH\_LINUX parameter:
-VSPERF can be used with OVS without DPDK support. In this case you have
-to specify path to the kernel sources by WITH\_LINUX parameter:
+.. code-block:: console
- .. code-block:: console
+ $ cd src
+ $ make WITH_LINUX=/lib/modules/`uname -r`/build
- cd src
- make WITH_LINUX=/lib/modules/`uname -r`/build
+To build DPDK and OVS in the src directory for PVP and PVVP testing with
+vhost_user as the guest access method, use:
-To build DPDK and OVS for PVP and PVVP testing with vhost_user as the guest
-access method, use:
+.. code-block:: console
- .. code-block:: console
+ $ make VHOST_USER=y
- make VHOST_USER=y
+To build all options in src:
-To build everything: Vanilla OVS, OVS with vhost_user as the guest access
-method and OVS with vhost_cuse access simply:
+* Vanilla OVS
+* OVS with vhost_user as the guest access method (with DPDK support)
+* OVS with vhost_cuse s the guest access method (with DPDK support)
- .. code-block:: console
+simply call 'make' in the src directory :
- make
+.. code-block:: console
+
+ $ make
The vhost_user build will reside in src/ovs/
The vhost_cuse build will reside in vswitchperf/src_cuse
@@ -70,15 +94,15 @@ The Vanilla OVS build will reside in vswitchperf/src_vanilla
To delete a src subdirectory and its contents to allow you to re-clone simply
use:
- .. code-block:: console
+.. code-block:: console
- make clobber
+ $ make clobber
Configure the ``./conf/10_custom.conf`` file
--------------------------------------------
The ``10_custom.conf`` file is the configuration file that overrides
default configurations in all the other configuration files in ``./conf``
-The supplied ``10_custom.conf`` file must be modified, as it contains
+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
@@ -93,9 +117,9 @@ If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
of if you want to use an alternative configuration file, the file can
be passed to ``vsperf`` via the ``--conf-file`` argument.
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file <path_to_settings_py> ...
+ $ ./vsperf --conf-file <path_to_custom_conf> ...
Note that configuration passed in via the environment (``--load-env``)
or via another command line argument will override both the default and
@@ -114,7 +138,7 @@ Executing tests
Before running any tests make sure you have root permissions by adding
the following line to /etc/sudoers:
- .. code-block:: console
+.. code-block:: console
username ALL=(ALL) NOPASSWD: ALL
@@ -122,45 +146,45 @@ username in the example above should be replaced with a real username.
To list the available tests:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --list
+ $ ./vsperf --list
To run a single test:
- .. code-block:: console
+.. code-block:: console
- ./vsperf $TESTNAME
+ $ ./vsperf $TESTNAME
Where $TESTNAME is the name of the vsperf test you would like to run.
To run a group of tests, for example all tests with a name containing
'RFC2544':
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file=user_settings.py --tests="RFC2544"
+ $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
To run all tests:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file=user_settings.py
+ $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
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
+ $ ./vsperf --conf-file user_settings.py
--tests RFC2544Tput
--test-param "duration=10;pkt_sizes=128"
For all available options, check out the help dialog:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --help
+ $ ./vsperf --help
Executing Vanilla OVS tests
----------------------------
@@ -169,16 +193,16 @@ step 1.
1. Recompile src for Vanilla OVS testing
- .. code-block:: console
+.. code-block:: console
- cd src
- make cleanse
- make WITH_LINUX=/lib/modules/`uname -r`/build
+ $ cd src
+ $ make cleanse
+ $ make WITH_LINUX=/lib/modules/`uname -r`/build
2. Update your ''10_custom.conf'' file to use the appropriate variables
for Vanilla OVS:
- .. code-block:: console
+.. code-block:: console
VSWITCH = 'OvsVanilla'
VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1']
@@ -188,17 +212,17 @@ to the vswitch.
3. Run test:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file <path_to_settings_py>
+ $ ./vsperf --conf-file=<path_to_custom_conf>
Please note if you don't want to configure Vanilla OVS through the
configuration file, you can pass it as a CLI argument; BUT you must
set the ports.
- .. code-block:: console
+.. code-block:: console
- ./vsperf --vswitch OvsVanilla
+ $ ./vsperf --vswitch OvsVanilla
Executing PVP and PVVP tests
@@ -207,47 +231,47 @@ To run tests using vhost-user as guest access method:
1. Set VHOST_METHOD and VNF of your settings file to:
- .. code-block:: console
+.. code-block:: console
VHOST_METHOD='user'
VNF = 'QemuDpdkVhost'
2. Recompile src for VHOST USER testing
- .. code-block:: console
+.. code-block:: console
- cd src
- make cleanse
- make VHOST_USER=y
+ $ cd src
+ $ make cleanse
+ $ make VHOST_USER=y
3. Run test:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file <path_to_settings_py>
+ $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
To run tests using vhost-cuse as guest access method:
1. Set VHOST_METHOD and VNF of your settings file to:
- .. code-block:: console
+.. code-block:: console
VHOST_METHOD='cuse'
VNF = 'QemuDpdkVhostCuse'
2. Recompile src for VHOST USER testing
- .. code-block:: console
+.. code-block:: console
- cd src
- make cleanse
- make VHOST_USER=n
+ $ cd src
+ $ make cleanse
+ $ make VHOST_USER=n
3. Run test:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file <path_to_settings_py>
+ $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
Executing PVP tests using Vanilla OVS
-------------------------------------
@@ -255,7 +279,7 @@ To run tests using Vanilla OVS:
1. Set the following variables:
- .. code-block:: console
+.. code-block:: console
VSWITCH = 'OvsVanilla'
VNF = 'QemuVirtioNet'
@@ -270,42 +294,44 @@ To run tests using Vanilla OVS:
or use --test-param
- ./vsperf --conf-file user_settings.py
+ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
--test-param "vanilla_tgen_tx_ip=n.n.n.n;
vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
2. Recompile src for Vanilla OVS testing
- .. code-block:: console
+.. code-block:: console
- cd src
- make cleanse
- make WITH_LINUX=/lib/modules/`uname -r`/build
+ $ cd src
+ $ make cleanse
+ $ make WITH_LINUX=/lib/modules/`uname -r`/build
3. Run test:
- .. code-block:: console
+.. code-block:: console
- ./vsperf --conf-file <path_to_settings_py>
+ $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
Selection of loopback application for PVP and PVVP tests
--------------------------------------------------------
To select loopback application, which will perform traffic forwarding
inside VM, following configuration parameter should be configured:
- .. code-block:: console
+.. code-block:: console
GUEST_LOOPBACK = ['testpmd', 'testpmd']
- or use --test-param
+or use --test-param
+
+.. code-block:: console
- ./vsperf --conf-file user_settings.py
+ $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
--test-param "guest_loopback=testpmd"
Supported loopback applications are:
- .. code-block:: console
+.. code-block:: console
'testpmd' - testpmd from dpdk will be built and used
'l2fwd' - l2fwd module provided by Huawei will be built and used
@@ -325,9 +351,9 @@ specific configuration for pylint is available at 'pylint.rc'.
Example of manual pylint invocation:
- .. code-block:: console
+.. code-block:: console
- pylint --rcfile ./pylintrc ./vsperf
+ $ pylint --rcfile ./pylintrc ./vsperf
GOTCHAs:
--------
@@ -339,17 +365,16 @@ If you encounter the following error: "before (last 100 chars):
hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
deployment scenario, check the amount of hugepages on your system:
-.. code:: bash
+.. code-block:: console
- cat /proc/meminfo | grep HugePages
+ $ cat /proc/meminfo | grep HugePages
By default the vswitchd is launched with 1Gb of memory, to change
this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
an appropriate amount of memory:
-.. code:: bash
+.. code-block:: console
VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
-