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/configguide/TCLServerProperties.png | Bin 0 -> 11667 bytes docs/configguide/index.rst | 10 ++ docs/configguide/installation.rst | 101 ++++++++++++++ docs/configguide/trafficgen.rst | 218 +++++++++++++++++++++++++++++++ 4 files changed, 329 insertions(+) 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 (limited to 'docs/configguide') 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. -- cgit 1.2.3-korg