docs/to-be-reorganized/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.html>`__ 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 Executing PVP tests
 159 -------------------
 160 To run tests using vhost-user as guest access method:
 161
 162 1. Set VHOST_METHOD and VNF of your settings file to:
 163
 164   .. code-block:: console
 165
 166    VHOST_METHOD='user'
 167    VNF = 'QemuDpdkVhost'
 168
 169 2. Recompile src for VHOST USER testing
 170
 171   .. code-block:: console
 172
 173      cd src
 174      make cleanse
 175      make VHOST_USER=y
 176
 177 3. Run test:
 178
 179   .. code-block:: console
 180
 181      ./vsperf --conf-file <path_to_settings_py>
 182
 183 To run tests using vhost-cuse as guest access method:
 184
 185 1. Set VHOST_METHOD and VNF of your settings file to:
 186
 187   .. code-block:: console
 188
 189      VHOST_METHOD='cuse'
 190      VNF = 'QemuDpdkVhostCuse'
 191
 192 2. Recompile src for VHOST USER testing
 193
 194   .. code-block:: console
 195
 196      cd src
 197      make cleanse
 198      make VHOST_USER=n
 199
 200 3. Run test:
 201
 202   .. code-block:: console
 203
 204      ./vsperf --conf-file <path_to_settings_py>
 205
 206
 207
 208 GOTCHAs:
 209 --------
 210
 211 OVS with DPDK and QEMU
 212 ~~~~~~~~~~~~~~~~~~~~~~~
 213 If you encounter the following error: "before (last 100 chars):
 214 '-path=/dev/hugepages,share=on: unable to map backing store for
 215 hugepages: Cannot allocate memory\r\n\r\n" with the PVP deployment
 216 scenario, check the amount of hugepages on your system:
 217
 218 .. code:: bash
 219
 220     cat /proc/meminfo | grep HugePages
 221
 222
 223 By default the vswitchd is launched with 1Gb of memory, to  change
 224 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
 225 an appropriate amount of memory:
 226
 227 .. code:: bash
 228
 229     VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
 230
 231 --------------
 232
 233 .. |Alt text| image:: images/TCLServerProperties.png