From 276d16fd75a717e5f5004e117cb9d3b18fd37363 Mon Sep 17 00:00:00 2001 From: Maryam Tahhan Date: Mon, 25 Jan 2016 10:58:47 +0000 Subject: docs: updates and final fixes Migrate the installation guide for vsperf to a configguide directory, update the links to the installation guide. Re-add top level index.rst and remove the all directory. Update release documentation with vsperf Rel B support. Change-Id: Ib643b9d3581d8109b85c377027c8cc6be4b797fc Signed-off-by: Maryam Tahhan Reviewed-by: Martin Klozik Reviewed-by: Radek Zetik Reviewed-by: Dino Simeon Madarang Reviewed-by: Brian Castelli --- docs/all/index.rst | 33 --- docs/configguide/TCLServerProperties.png | Bin 0 -> 11667 bytes docs/configguide/index.rst | 10 + docs/configguide/installation.rst | 101 +++++++++ docs/configguide/trafficgen.rst | 218 ++++++++++++++++++ docs/index.rst | 36 +++ docs/release/NEWS.rst | 38 ++++ docs/userguide/index.rst | 9 + docs/userguide/quickstart.rst | 366 ++++++++++++++++++++++++++++++ docs/userguides/TCLServerProperties.png | Bin 11667 -> 0 bytes docs/userguides/index.rst | 11 - docs/userguides/installation.rst | 76 ------- docs/userguides/quickstart.rst | 371 ------------------------------- docs/userguides/trafficgen.rst | 218 ------------------ 14 files changed, 778 insertions(+), 709 deletions(-) delete mode 100755 docs/all/index.rst create mode 100644 docs/configguide/TCLServerProperties.png create mode 100644 docs/configguide/index.rst create mode 100755 docs/configguide/installation.rst create mode 100644 docs/configguide/trafficgen.rst create mode 100755 docs/index.rst create mode 100644 docs/userguide/index.rst create mode 100755 docs/userguide/quickstart.rst delete mode 100644 docs/userguides/TCLServerProperties.png delete mode 100644 docs/userguides/index.rst delete mode 100755 docs/userguides/installation.rst delete mode 100755 docs/userguides/quickstart.rst delete mode 100644 docs/userguides/trafficgen.rst diff --git a/docs/all/index.rst b/docs/all/index.rst deleted file mode 100755 index 311a2e2d..00000000 --- a/docs/all/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. OPNFV VSPERF Documentation master file. - -====== -VSPERF -====== -Welcome to VSPERF's documentation ! - -.. _VSPERF: https://wiki.opnfv.org/characterize_vswitch_performance_for_telco_nfv_use_cases -.. _REPO: https://gerrit.opnfv.org/gerrit/#/q/vswitchperf - -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. - -.. toctree:: - :maxdepth: 3 - :numbered: 5 - - http://artifacts.opnfv.org/vswitchperf/docs/userguides/index.html - http://artifacts.opnfv.org/vswitchperf/docs/design/index.html - http://artifacts.opnfv.org/vswitchperf/docs/requirements/index.html - http://artifacts.opnfv.org/vswitchperf/docs/release/index.html - - -Indices -======= -* :ref:`search` - diff --git a/docs/configguide/TCLServerProperties.png b/docs/configguide/TCLServerProperties.png new file mode 100644 index 00000000..682de7c5 Binary files /dev/null and b/docs/configguide/TCLServerProperties.png differ diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst new file mode 100644 index 00000000..3aaf238f --- /dev/null +++ b/docs/configguide/index.rst @@ -0,0 +1,10 @@ +****************************** +VSPERF Installation Guide +****************************** + +.. toctree:: + :numbered: + :maxdepth: 3 + + installation.rst + trafficgen.rst diff --git a/docs/configguide/installation.rst b/docs/configguide/installation.rst new file mode 100755 index 00000000..ebc73bad --- /dev/null +++ b/docs/configguide/installation.rst @@ -0,0 +1,101 @@ +====================== +Installing vswitchperf +====================== + +Supported Operating Systems +--------------------------- + +* CentOS 7 +* Fedora 20 +* Fedora 21 +* Fedora 22 +* 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. + +Available VNFs +-------------- +A simple VNF that forwards traffic through a VM, using: + +* DPDK testpmd +* Linux Brigde +* custom l2fwd module + +The VM image can be downloaded from: +http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2 + +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 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. + +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`_). 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: + +CentOS 7 +======== + +.. code:: bash + + $ scl enable python33 bash + $ cd $HOME/vsperfenv + $ source bin/activate + +Fedora and Ubuntu +================= + +.. code:: 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/ +.. _virtualenv: https://virtualenv.readthedocs.org/en/latest/ diff --git a/docs/configguide/trafficgen.rst b/docs/configguide/trafficgen.rst new file mode 100644 index 00000000..f510a596 --- /dev/null +++ b/docs/configguide/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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100755 index 00000000..59323795 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,36 @@ +.. OPNFV VSPERF Documentation master file. + +====== +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. + +Project Wiki: +https://wiki.opnfv.org/characterize_vswitch_performance_for_telco_nfv_use_cases + +Project Repository: https://gerrit.opnfv.org/gerrit/#/q/vswitchperf + +Continuous Integration https://build.opnfv.org/ci/view/vswitchperf/ + +.. toctree:: + :maxdepth: 3 + :numbered: 5 + + ./configguide/index.rst + ./userguide/index.rst + ./design/index.rst + ./requirements/index.rst + ./release/index.rst + + +Indices +======= +* :ref:`search` + diff --git a/docs/release/NEWS.rst b/docs/release/NEWS.rst index 1593cb88..21c56379 100755 --- a/docs/release/NEWS.rst +++ b/docs/release/NEWS.rst @@ -1,3 +1,41 @@ +OPNFV Brahmaputra Release +========================= +Supports both OVS and OVS with DPDK. + +Available tests: + +* phy2phy_tput: LTD.Throughput.RFC2544.PacketLossRatio +* back2back: LTD.Throughput.RFC2544.BackToBackFrames +* phy2phy_tput_mod_vlan:LTD.Throughput.RFC2544.PacketLossRatioFrameModification +* phy2phy_cont: Phy2Phy Continuous Stream +* pvp_cont: PVP Continuous Stream +* pvvp_cont: PVVP Continuous Stream +* phy2phy_scalability:LTD.Scalability.RFC2544.0PacketLoss +* pvp_tput: LTD.Throughput.RFC2544.PacketLossRatio +* pvp_back2back: LTD.Throughput.RFC2544.BackToBackFrames +* pvvp_tput: LTD.Throughput.RFC2544.PacketLossRatio +* pvvp_back2back: LTD.Throughput.RFC2544.BackToBackFrames +* phy2phy_cpu_load: LTD.CPU.RFC2544.0PacketLoss +* phy2phy_mem_load: LTD.Memory.RFC2544.0PacketLoss + +Supported deployment scenarios: + +* Physical port -> vSwitch -> Physical port. +* Physical port -> vSwitch -> VNF -> vSwitch -> Physical port. +* Physical port -> vSwitch -> VNF -> vSwitch -> VNF -> vSwitch -> Physical port. + +Loopback applications in the Guest can be: + +* DPDK testpmd. +* Linux Bridge. +* l2fwd Kernel Module. + +Supported traffic generators: + +* Ixia: IxOS and IxNet. +* Spirent. +* Dummy. + November 2015 ============== diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 00000000..1e02eb21 --- /dev/null +++ b/docs/userguide/index.rst @@ -0,0 +1,9 @@ +****************************** +VSPERF User Guide +****************************** + +.. toctree:: + :numbered: + :maxdepth: 3 + + quickstart.rst diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst new file mode 100755 index 00000000..30718233 --- /dev/null +++ b/docs/userguide/quickstart.rst @@ -0,0 +1,366 @@ +============================= +Getting Started with 'vsperf' +============================= + +General +------- + +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". + +If you want to use another traffic generator, please select the Dummy generator +option as shown in `Traffic generator instructions +`__ + +VSPERF Installation +-------------------- +To see the supported Operating Systems, vSwitches and system requirements, +please follow the `installation instructions +`__ to +install. + +Traffic Generator Setup +----------------------- +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 +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 stock OVS (without DPDK support). When build +is finished, the libraries are stored in src_vanilla directory. + +The 'make' builds all options in src: + +* 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) + +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 ... + +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 called vloop_vnf for looping traffic in the PVP and PVVP +deployment scenarios. The image can be downloaded from +``__. + +.. code-block:: console + + $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2 + +vloop_vnf forwards traffic through a VM using one of: +* DPDK testpmd +* Linux Bridge +* l2fwd kernel Module. + +Alternatively you can use your own QEMU image. + +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 /src/l2fwd + +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=/10_custom.conf --tests="RFC2544" + +To run all tests: + +.. code-block:: console + + $ ./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 + --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 +---------------------------- + +1. If needed, recompile src for all OVS variants + +.. code-block:: console + + $ cd src + $ make distclean + $ make + +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= + +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. If needed, recompile src for all OVS variants + +.. code-block:: console + + $ cd src + $ make distclean + $ make + +3. Run test: + +.. code-block:: console + + $ ./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 + + VHOST_METHOD='cuse' + VNF = 'QemuDpdkVhostCuse' + +2. If needed, recompile src for all OVS variants + +.. code-block:: console + + $ cd src + $ make distclean + $ make + +3. Run test: + +.. code-block:: console + + $ ./vsperf --conf-file=/10_custom.conf + +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=/10_custom.conf + --test-param "vanilla_tgen_tx_ip=n.n.n.n; + vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn" + + +2. If needed, recompile src for all OVS variants + +.. code-block:: console + + $ cd src + $ make distclean + $ make + +3. Run test: + +.. code-block:: console + + $ ./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 + + GUEST_LOOPBACK = ['testpmd', 'testpmd'] + +or use --test-param + +.. code-block:: console + + $ ./vsperf --conf-file=/10_custom.conf + --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-block:: console + + $ 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-block:: console + + VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0'] + diff --git a/docs/userguides/TCLServerProperties.png b/docs/userguides/TCLServerProperties.png deleted file mode 100644 index 682de7c5..00000000 Binary files a/docs/userguides/TCLServerProperties.png and /dev/null differ diff --git a/docs/userguides/index.rst b/docs/userguides/index.rst deleted file mode 100644 index c796e6c3..00000000 --- a/docs/userguides/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -****************************** -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 deleted file mode 100755 index abd09cb4..00000000 --- a/docs/userguides/installation.rst +++ /dev/null @@ -1,76 +0,0 @@ -====================== -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. - -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 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. - -Currently supported operating systems are: - - - CentOS 7 - - Fedora 20 - - Fedora 21 - - Fedora 22 - - Ubuntu 14.04 - -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`_). 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: - -CentOS 7: - -.. code:: bash - - $ scl enable python33 bash - $ cd $HOME/vsperfenv - $ source bin/activate - -Fedora and Ubuntu: - -.. code:: 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/ -.. _virtualenv: https://virtualenv.readthedocs.org/en/latest/ diff --git a/docs/userguides/quickstart.rst b/docs/userguides/quickstart.rst deleted file mode 100755 index fd5c6779..00000000 --- a/docs/userguides/quickstart.rst +++ /dev/null @@ -1,371 +0,0 @@ -============================= -Getting Started with 'vsperf' -============================= - -Requirements -------------- - -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". - -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. VSPERF supports both: - -* OVS -* OVS with DPDK - -VSPERF Installation --------------------- - -Follow the `installation instructions -`__ to -install. - -Traffic Generator Setup ------------------------ -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 -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 stock OVS (without DPDK support). When build -is finished, the libraries are stored in src_vanilla directory. - -The 'make' builds all options in src: - -* 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) - -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 ... - -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 called vloop_vnf for looping traffic in the PVP and PVVP -deployment scenarios. The image can be downloaded from -``__. - -.. code-block:: console - - $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2 - -Alternatively you can use your own QEMU image. - --------------- - -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=/10_custom.conf --tests="RFC2544" - -To run all tests: - -.. code-block:: console - - $ ./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 - --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 ----------------------------- - -1. If needed, recompile src for all OVS variants - -.. code-block:: console - - $ cd src - $ make distclean - $ make - -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= - -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. If needed, recompile src for all OVS variants - -.. code-block:: console - - $ cd src - $ make distclean - $ make - -3. Run test: - -.. code-block:: console - - $ ./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 - - VHOST_METHOD='cuse' - VNF = 'QemuDpdkVhostCuse' - -2. If needed, recompile src for all OVS variants - -.. code-block:: console - - $ cd src - $ make distclean - $ make - -3. Run test: - -.. code-block:: console - - $ ./vsperf --conf-file=/10_custom.conf - -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=/10_custom.conf - --test-param "vanilla_tgen_tx_ip=n.n.n.n; - vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn" - - -2. If needed, recompile src for all OVS variants - -.. code-block:: console - - $ cd src - $ make distclean - $ make - -3. Run test: - -.. code-block:: console - - $ ./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 - - GUEST_LOOPBACK = ['testpmd', 'testpmd'] - -or use --test-param - -.. code-block:: console - - $ ./vsperf --conf-file=/10_custom.conf - --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-block:: console - - $ 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-block:: console - - VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0'] - diff --git a/docs/userguides/trafficgen.rst b/docs/userguides/trafficgen.rst deleted file mode 100644 index f510a596..00000000 --- a/docs/userguides/trafficgen.rst +++ /dev/null @@ -1,218 +0,0 @@ -=========================== -'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. -- cgit 1.2.3-korg