summaryrefslogtreecommitdiffstats
path: root/docs/configguide
diff options
context:
space:
mode:
authorMaryam Tahhan <maryam.tahhan@intel.com>2016-01-25 10:58:47 +0000
committerMaryam Tahhan <maryam.tahhan@intel.com>2016-01-25 16:41:08 +0000
commit276d16fd75a717e5f5004e117cb9d3b18fd37363 (patch)
tree98381c5cd8cc76f67a04c38f67da01aaf8b9bf09 /docs/configguide
parentcdda1e1aaaae6c22a592980cabd6f301d661f737 (diff)
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 <maryam.tahhan@intel.com> Reviewed-by: Martin Klozik <martinx.klozik@intel.com> Reviewed-by: Radek Zetik <radekx.zetik@intel.com> Reviewed-by: Dino Simeon Madarang <dino.simeonx.madarang@intel.com> Reviewed-by: Brian Castelli <brian.castelli@spirent.com>
Diffstat (limited to 'docs/configguide')
-rw-r--r--docs/configguide/TCLServerProperties.pngbin0 -> 11667 bytes
-rw-r--r--docs/configguide/index.rst10
-rwxr-xr-xdocs/configguide/installation.rst101
-rw-r--r--docs/configguide/trafficgen.rst218
4 files changed, 329 insertions, 0 deletions
diff --git a/docs/configguide/TCLServerProperties.png b/docs/configguide/TCLServerProperties.png
new file mode 100644
index 00000000..682de7c5
--- /dev/null
+++ b/docs/configguide/TCLServerProperties.png
Binary files 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.