docs/quickstart.rst

   1 Getting Started with 'vsperf'
   2 =============================
   3
   4 Hardware Requirements
   5 ---------------------
   6
   7 VSPERF requires the following hardware to run tests: IXIA traffic
   8 generator (IxNetwork), a machine that runs the IXIA client software and
   9 a CentOS Linux release 7.1.1503 (Core) host.
  10
  11 vSwitch Requirements
  12 --------------------
  13
  14 The vSwitch must support Open Flow 1.3 or greater.
  15
  16 Installation
  17 ------------
  18
  19 Follow the `installation instructions <installation.md>`__ to install.
  20
  21 IXIA Setup
  22 ----------
  23
  24 On the CentOS 7 system
  25 ~~~~~~~~~~~~~~~~~~~~~~
  26
  27 You need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
  28
  29 On the IXIA client software system
  30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  31
  32 Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
  33 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
  34
  35 Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
  36 the Target dialogue box make sure there is the argument "-tclport xxxx"
  37 where xxxx is your port number (take note of this port number you will
  38 need it for the 10\_custom.conf file).
  39
  40 |Alt text|
  41
  42 Hit Ok and start the TCL server application
  43
  44 Cloning and building src dependencies
  45 -------------------------------------
  46
  47 In order to run VSPERF, you will need to download DPDK and OVS. You can
  48 do this manually and build them in a preferred location, or you could
  49 use vswitchperf/src. The vswitchperf/src directory contains makefiles
  50 that will allow you to clone and build the libraries that VSPERF depends
  51 on, such as DPDK and OVS. To clone and build simply:
  52
  53   .. code-block:: console
  54
  55     cd src
  56     make
  57
  58 VSPERF can be used with OVS without DPDK support. In this case you have
  59 to specify path to the kernel sources by WITH\_LINUX parameter:
  60
  61   .. code-block:: console
  62
  63      cd src
  64      make WITH_LINUX=/lib/modules/`uname -r`/build
  65
  66 To build DPDK and OVS for PVP testing with vhost_user as the guest access
  67 method, use:
  68
  69   .. code-block:: console
  70
  71      make VHOST_USER=y
  72
  73 To delete a src subdirectory and its contents to allow you to re-clone simply
  74 use:
  75
  76   .. code-block:: console
  77
  78      make clobber
  79
  80 Configure the ``./conf/10_custom.conf`` file
  81 --------------------------------------------
  82
  83 The supplied ``10_custom.conf`` file must be modified, as it contains
  84 configuration items for which there are no reasonable default values.
  85
  86 The configuration items that can be added is not limited to the initial
  87 contents. Any configuration item mentioned in any .conf file in
  88 ``./conf`` directory can be added and that item will be overridden by
  89 the custom configuration value.
  90
  91 Using a custom settings file
  92 ----------------------------
  93
  94 Alternatively a custom settings file can be passed to ``vsperf`` via the
  95 ``--conf-file`` argument.
  96
  97   .. code-block:: console
  98
  99     ./vsperf --conf-file <path_to_settings_py> ...
 100
 101 Note that configuration passed in via the environment (``--load-env``)
 102 or via another command line argument will override both the default and
 103 your custom configuration files. This "priority hierarchy" can be
 104 described like so (1 = max priority):
 105
 106 1. Command line arguments
 107 2. Environment variables
 108 3. Configuration file(s)
 109
 110 --------------
 111
 112 Executing tests
 113 ---------------
 114
 115 Before running any tests make sure you have root permissions by adding
 116 the following line to /etc/sudoers:
 117
 118   .. code-block:: console
 119
 120     username ALL=(ALL)       NOPASSWD: ALL
 121
 122 username in the example above should be replaced with a real username.
 123
 124 To list the available tests:
 125
 126   .. code-block:: console
 127
 128     ./vsperf --list-tests
 129
 130 To run a group of tests, for example all tests with a name containing
 131 'RFC2544':
 132
 133   .. code-block:: console
 134
 135     ./vsperf --conf-file=user_settings.py --tests="RFC2544"
 136
 137 To run all tests:
 138
 139   .. code-block:: console
 140
 141     ./vsperf --conf-file=user_settings.py
 142
 143 Some tests allow for configurable parameters, including test duration
 144 (in seconds) as well as packet sizes (in bytes).
 145
 146 .. code:: bash
 147
 148     ./vsperf --conf-file user_settings.py
 149         --tests RFC2544Tput
 150         --test-param "rfc2544_duration=10;packet_sizes=128"
 151
 152 For all available options, check out the help dialog:
 153
 154   .. code-block:: console
 155
 156     ./vsperf --help
 157
 158
 159 GOTCHAs:
 160 --------
 161
 162 OVS with DPDK and QEMU
 163 ~~~~~~~~~~~~~~~~~~~~~~~
 164 If you encounter the following error: "before (last 100 chars):
 165 '-path=/dev/hugepages,share=on: unable to map backing store for
 166 hugepages: Cannot allocate memory\r\n\r\n" with the PVP deployment
 167 scenario, check the amount of hugepages on your system:
 168
 169 .. code:: bash
 170
 171     cat /proc/meminfo | grep HugePages
 172
 173
 174 By default the vswitchd is launched with 1Gb of memory, to  change
 175 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
 176 an appropriate amount of memory:
 177
 178 .. code:: bash
 179
 180     VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
 181
 182 --------------
 183
 184 .. |Alt text| image:: images/TCLServerProperties.png