diff options
Diffstat (limited to 'docs/userguides')
| -rw-r--r-- | docs/userguides/TCLServerProperties.png | bin | 0 -> 11667 bytes | |||
| -rw-r--r-- | docs/userguides/index.rst | 11 | ||||
| -rwxr-xr-x | docs/userguides/installation.rst | 49 | ||||
| -rwxr-xr-x | docs/userguides/quickstart.rst | 355 | ||||
| -rw-r--r-- | docs/userguides/trafficgen.rst | 218 |
5 files changed, 633 insertions, 0 deletions
diff --git a/docs/userguides/TCLServerProperties.png b/docs/userguides/TCLServerProperties.png Binary files differnew file mode 100644 index 00000000..682de7c5 --- /dev/null +++ b/docs/userguides/TCLServerProperties.png diff --git a/docs/userguides/index.rst b/docs/userguides/index.rst new file mode 100644 index 00000000..c796e6c3 --- /dev/null +++ b/docs/userguides/index.rst @@ -0,0 +1,11 @@ +****************************** +VSPERF Guides and Installation +****************************** + +.. toctree:: + :numbered: + :maxdepth: 3 + + quickstart.rst + installation.rst + trafficgen.rst diff --git a/docs/userguides/installation.rst b/docs/userguides/installation.rst new file mode 100755 index 00000000..96970bdb --- /dev/null +++ b/docs/userguides/installation.rst @@ -0,0 +1,49 @@ +====================== +Installing vswitchperf +====================== + +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. To +install Python 3.3 in CentOS 7, an additional repository, Software +Collections (`a link`_) should be enabled. + +Installation of required packages and preparation of Python 3 virtual +environment is performed by 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 account before script is executed. + +Execution of installation script: + +.. code:: bash + + cd systems + ./build_base_machine.sh + +Please note: you don't need to go into any of the systems subdirectories, +simply run the top level build_base_machine.sh, your OS will be detected +automatically. + +You will 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 $HOME/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=proxy.mycompany.com:123 + export https_proxy=proxy.mycompany.com:123 + +.. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/ diff --git a/docs/userguides/quickstart.rst b/docs/userguides/quickstart.rst new file mode 100755 index 00000000..91162f88 --- /dev/null +++ b/docs/userguides/quickstart.rst @@ -0,0 +1,355 @@ +============================= +Getting Started with 'vsperf' +============================= + +Hardware Requirements +--------------------- + +VSPERF requires one of the following traffic generators to run tests: + +- 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. + +vSwitch Requirements +-------------------- + +The vSwitch must support Open Flow 1.3 or greater. + +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. + +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-block:: console + + cd src + make + +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 + + cd src + make WITH_LINUX=/lib/modules/`uname -r`/build + +To build DPDK and OVS for PVP and PVVP testing with vhost_user as the guest +access method, use: + + .. code-block:: console + + make VHOST_USER=y + +To build everything: Vanilla OVS, OVS with vhost_user as the guest access +method and OVS with vhost_cuse access simply: + + .. code-block:: console + + make + +The vhost_user build will reside in src/ovs/ +The vhost_cuse build will reside in vswitchperf/src_cuse +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 + + 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 +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 +---------------------------- + +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 + + ./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) + +-------------- + +Executing tests +--------------- + +Before running any tests make sure you have root permissions by adding +the following line to /etc/sudoers: + + .. code-block:: console + + username ALL=(ALL) NOPASSWD: ALL + +username in the example above should be replaced with a real username. + +To list the available tests: + + .. code-block:: console + + ./vsperf --list + +To run a single test: + + .. code-block:: console + + ./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 + + ./vsperf --conf-file=user_settings.py --tests="RFC2544" + +To run all tests: + + .. code-block:: console + + ./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 "duration=10;pkt_sizes=128" + +For all available options, check out the help dialog: + + .. code-block:: console + + ./vsperf --help + +Executing Vanilla OVS tests +---------------------------- +If you have compiled all the variants of OVS in ''src/'' please skip +step 1. + +1. Recompile src for Vanilla OVS testing + + .. code-block:: console + + 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 + + VSWITCH = 'OvsVanilla' + VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1'] + +Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind +to the vswitch. + +3. Run test: + + .. code-block:: console + + ./vsperf --conf-file <path_to_settings_py> + +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 + + ./vsperf --vswitch OvsVanilla + + +Executing PVP and PVVP tests +---------------------------- +To run tests using vhost-user as guest access method: + +1. Set VHOST_METHOD and VNF of your settings file to: + + .. code-block:: console + + VHOST_METHOD='user' + VNF = 'QemuDpdkVhost' + +2. Recompile src for VHOST USER testing + + .. code-block:: console + + cd src + make cleanse + make VHOST_USER=y + +3. Run test: + + .. code-block:: console + + ./vsperf --conf-file <path_to_settings_py> + +To run tests using vhost-cuse as guest access method: + +1. Set VHOST_METHOD and VNF of your settings file to: + + .. code-block:: console + + VHOST_METHOD='cuse' + VNF = 'QemuDpdkVhostCuse' + +2. Recompile src for VHOST USER testing + + .. code-block:: console + + cd src + make cleanse + make VHOST_USER=n + +3. Run test: + + .. code-block:: console + + ./vsperf --conf-file <path_to_settings_py> + +Executing PVP tests using Vanilla OVS +------------------------------------- +To run tests using Vanilla OVS: + +1. Set the following variables: + + .. code-block:: console + + VSWITCH = 'OvsVanilla' + VNF = 'QemuVirtioNet' + + VANILLA_TGEN_PORT1_IP = n.n.n.n + VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn + + VANILLA_TGEN_PORT2_IP = n.n.n.n + VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn + + VANILLA_BRIDGE_IP = n.n.n.n + + or use --test-param + + ./vsperf --conf-file user_settings.py + --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 + + cd src + make cleanse + make WITH_LINUX=/lib/modules/`uname -r`/build + +3. Run test: + + .. code-block:: console + + ./vsperf --conf-file <path_to_settings_py> + +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 + + GUEST_LOOPBACK = ['testpmd', 'testpmd'] + + or use --test-param + + ./vsperf --conf-file user_settings.py + --test-param "guest_loopback=testpmd" + +Supported loopback applications are: + + .. code-block:: console + + 'testpmd' - testpmd from dpdk will be built and used + 'l2fwd' - l2fwd module provided by Huawei will be built and used + 'linux_bridge' - linux bridge will be configured + 'buildin' - nothing will be configured by vsperf; VM image must + ensure traffic forwarding between its interfaces + +Guest loopback application must be configured, otherwise traffic +will not be forwarded by VM and testcases with PVP and PVVP deployments +will fail. Guest loopback application is set to 'testpmd' by default. + +Code change verification by pylint +---------------------------------- +Every developer participating in VSPERF project should run +pylint before his python code is submitted for review. Project +specific configuration for pylint is available at 'pylint.rc'. + +Example of manual pylint invocation: + + .. code-block:: console + + pylint --rcfile ./pylintrc ./vsperf + +GOTCHAs: +-------- + +OVS with DPDK and QEMU +~~~~~~~~~~~~~~~~~~~~~~~ +If you encounter the following error: "before (last 100 chars): +'-path=/dev/hugepages,share=on: unable to map backing store for +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 + + 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 + + VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0'] + + diff --git a/docs/userguides/trafficgen.rst b/docs/userguides/trafficgen.rst new file mode 100644 index 00000000..1bb09103 --- /dev/null +++ b/docs/userguides/trafficgen.rst @@ -0,0 +1,218 @@ +=========================== +'vsperf' Traffic Gen Guide +=========================== + +Overview +--------------------- +VSPERF supports the following traffic generators: + + * Dummy (DEFAULT): Allows you to use your own external + traffic generator. + * IXIA (IxNet and IxOS) + * Spirent TestCenter + +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. + +Background Information +---------------------- +The traffic default configuration can be found in +tools/pkt_gen/trafficgen/trafficgenhelper.py, and is configured as +follows: + + .. code-block:: console + + TRAFFIC_DEFAULTS = { + 'l2': { + 'framesize': 64, + 'srcmac': '00:00:00:00:00:00', + 'dstmac': '00:00:00:00:00:00', + 'srcport': 3000, + 'dstport': 3001, + }, + 'l3': { + 'proto': 'tcp', + 'srcip': '1.1.1.1', + 'dstip': '90.90.90.90', + }, + 'vlan': { + 'enabled': False, + 'id': 0, + 'priority': 0, + 'cfi': 0, + }, + } + +The framesize paramter can be overridden from the configuration +files by adding the following to your custom configuration file +``10_custom.conf``: + + .. code-block:: console + + TRAFFICGEN_PKT_SIZES = (64, 128,) + +OR from the commandline: + + .. code-block:: console + + ./vsperf --test-param "pkt_sizes=x,y" $TESTNAME + +You can also modify the traffic transmission duration and the number +of trials run by the traffic generator by extending the example +commandline above to: + + .. code-block:: console + + ./vsperf --test-param "pkt_sizes=x,y;duration=10;rfc2455_trials=3" $TESTNAME + +Dummy Setup +------------ +To select the Dummy generator please add the following to your +custom configuration file ``10_custom.conf``. + + + .. code-block:: console + + TRAFFICGEN = 'Dummy' + +OR run ``vsperf`` with the ``--trafficgen`` argument + + .. code-block:: console + + ./vsperf --trafficgen Dummy $TESTNAME + +Where $TESTNAME is the name of the vsperf test you would like to run. +This will setup the vSwitch and the VNF (if one is part of your test) +print the traffic configuration and prompt you to transmit traffic +when the setup is complete. + + .. code-block:: console + + Please send 'continuous' traffic with the following stream config: + 30mS, 90mpps, multistream False + and the following flow config: + { + "flow_type": "port", + "l3": { + "srcip": "1.1.1.1", + "proto": "tcp", + "dstip": "90.90.90.90" + }, + "traffic_type": "continuous", + "multistream": 0, + "bidir": "True", + "vlan": { + "cfi": 0, + "priority": 0, + "id": 0, + "enabled": false + }, + "frame_rate": 90, + "l2": { + "dstport": 3001, + "srcport": 3000, + "dstmac": "00:00:00:00:00:00", + "srcmac": "00:00:00:00:00:00", + "framesize": 64 + } + } + What was the result for 'frames tx'? + +When your traffic gen has completed traffic transmission and provided +the results please input these at the vsperf prompt. vsperf will try +to verify the input: + + .. code-block:: console + + Is '$input_value' correct? + +Please answer with y OR n. + +VPSERF will ask you for: + * Result for 'frames tx' + * Result for 'frames rx' + * Result for 'min latency' + * Result for 'max latency' + * Result for 'avg latency' + +Finally vsperf will print out the results for your test and generate the +appropriate logs and csv files. + + +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). + +.. image:: TCLServerProperties.png + +Hit Ok and start the TCL server application + +Spirent Setup +------------- + +Spirent installation files and instructions are available on the +Spirent support website at: + +http://support.spirent.com + +Select a version of Spirent TestCenter software to utilize. This example +will use Spirent TestCenter v4.57 as an example. Substitute the appropriate +version in place of 'v4.57' in the examples, below. + +On the CentOS 7 System +~~~~~~~~~~~~~~~~~~~~~~ + +Download and install the following: + +Spirent TestCenter Application, v4.57 for 64-bit Linux Client + +Spirent Virtual Deployment Service (VDS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Spirent VDS is required for both TestCenter hardware and virtual +chassis in the vsperf environment. For installation, select the version +that matches the Spirent TestCenter Application version. For v4.57, +the matching VDS version is 1.0.55. Download either the ova (VMware) +or qcow2 (QEMU) image and create a VM with it. Initialize the VM +according to Spirent installation instructions. + +Using Spirent TestCenter Virtual (STCv) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For +VMware, download: + +Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi + +Virtual test port performance is affected by the hypervisor configuration. For +best practice results in deploying STCv, the following is suggested: + +- Create a single VM with two test ports rather than two VMs with one port each +- Set STCv in DPDK mode +- Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5. +- Turning off hyperthreading and pinning these cores will improve performance +- Give STCv 2 GB of RAM + +To get the highest performance and accuracy, Spirent TestCenter hardware is +recommended. vsperf can run with either stype test ports. |
