From 00985d31991a1e1b91fcff87e82ff99957611396 Mon Sep 17 00:00:00 2001 From: Maryam Tahhan Date: Wed, 16 Dec 2015 13:43:37 +0000 Subject: docs: update userguides after reviewing Review and update userguides for Release B. JIRA: VSPERF-160 Change-Id: I54c4dd37fa5951cab9d0e17bb2f3a4d273741cb0 Signed-off-by: Maryam Tahhan --- docs/userguides/quickstart.rst | 199 +++++++++++++++++++++++------------------ 1 file changed, 112 insertions(+), 87 deletions(-) (limited to 'docs/userguides/quickstart.rst') 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 +`__ + +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 `__ to install. +VSPERF Installation +-------------------- + +Follow the `installation instructions +`__ to +install. Traffic Generator Setup ----------------------- -Follow the `Traffic generator instructions `__ to install and configure a suitable traffic generator. +Follow the `Traffic generator instructions +`__ 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 ... + $ ./vsperf --conf-file ... 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=/10_custom.conf --tests="RFC2544" To run all tests: - .. code-block:: console +.. code-block:: console - ./vsperf --conf-file=user_settings.py + $ ./vsperf --conf-file=/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 + $ ./vsperf --conf-file= 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 + $ ./vsperf --conf-file=/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 + $ ./vsperf --conf-file=/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=/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 + $ ./vsperf --conf-file/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=/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'] - -- cgit 1.2.3-korg