docs/guides/quickstart.rst

   1 Getting Started with 'vsperf'
   2 =============================
   3
   4 Hardware Requirements
   5 ---------------------
   6
   7 VSPERF requires one of the following traffic generators to run tests:
   8
   9 - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA client software
  10 - Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual in a VM) and a
  11 VM to run the Spirent Virtual Deployment Service image, formerly known as "Spirent LabServer".
  12
  13 Both test configurations, above, also require a CentOS Linux release 7.1.1503 (Core) host.
  14
  15 vSwitch Requirements
  16 --------------------
  17
  18 The vSwitch must support Open Flow 1.3 or greater.
  19
  20 Installation
  21 ------------
  22
  23 Follow the `installation instructions <installation.html>`__ to install.
  24
  25 IXIA Setup
  26 ----------
  27
  28 On the CentOS 7 system
  29 ~~~~~~~~~~~~~~~~~~~~~~
  30
  31 You need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
  32
  33 On the IXIA client software system
  34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35
  36 Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
  37 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
  38
  39 Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
  40 the Target dialogue box make sure there is the argument "-tclport xxxx"
  41 where xxxx is your port number (take note of this port number you will
  42 need it for the 10\_custom.conf file).
  43
  44 |Alt text|
  45
  46 Hit Ok and start the TCL server application
  47
  48 Spirent Setup
  49 -------------
  50
  51 Spirent installation files and instructions are available on the
  52 Spirent support website at:
  53
  54 http://support.spirent.com
  55
  56 Select a version of Spirent TestCenter software to utilize. This example
  57 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
  58 version in place of 'v4.57' in the examples, below.
  59
  60 On the CentOS 7 System
  61 ~~~~~~~~~~~~~~~~~~~~~~
  62
  63 Download and install the following:
  64
  65 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
  66
  67 Spirent Virtual Deployment Service (VDS)
  68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69
  70 Spirent VDS is required for both TestCenter hardware and virtual
  71 chassis in the vsperf environment. For installation, select the version
  72 that matches the Spirent TestCenter Application version. For v4.57,
  73 the matching VDS version is 1.0.55. Download either the ova (VMware)
  74 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
  75 according to Spirent installation instructions.
  76
  77 Using Spirent TestCenter Virtual (STCv)
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
  81 VMware, download:
  82
  83 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
  84
  85 Virtual test port performance is affected by the hypervisor configuration. For
  86 best practice results in deploying STCv, the following is suggested:
  87
  88 - Create a single VM with two test ports rather than two VMs with one port each
  89 - Set STCv in DPDK mode
  90 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
  91 - Turning off hyperthreading and pinning these cores will improve performance
  92 - Give STCv 2 GB of RAM
  93
  94 To get the highest performance and accuracy, Spirent TestCenter hardware is
  95 recommended. vsperf can run with either stype test ports.
  96
  97 Cloning and building src dependencies
  98 -------------------------------------
  99
 100 In order to run VSPERF, you will need to download DPDK and OVS. You can
 101 do this manually and build them in a preferred location, or you could
 102 use vswitchperf/src. The vswitchperf/src directory contains makefiles
 103 that will allow you to clone and build the libraries that VSPERF depends
 104 on, such as DPDK and OVS. To clone and build simply:
 105
 106   .. code-block:: console
 107
 108     cd src
 109     make
 110
 111 VSPERF can be used with OVS without DPDK support. In this case you have
 112 to specify path to the kernel sources by WITH\_LINUX parameter:
 113
 114   .. code-block:: console
 115
 116      cd src
 117      make WITH_LINUX=/lib/modules/`uname -r`/build
 118
 119 To build DPDK and OVS for PVP and PVVP testing with vhost_user as the guest
 120 access method, use:
 121
 122   .. code-block:: console
 123
 124      make VHOST_USER=y
 125
 126 To delete a src subdirectory and its contents to allow you to re-clone simply
 127 use:
 128
 129   .. code-block:: console
 130
 131      make clobber
 132
 133 Configure the ``./conf/10_custom.conf`` file
 134 --------------------------------------------
 135
 136 The supplied ``10_custom.conf`` file must be modified, as it contains
 137 configuration items for which there are no reasonable default values.
 138
 139 The configuration items that can be added is not limited to the initial
 140 contents. Any configuration item mentioned in any .conf file in
 141 ``./conf`` directory can be added and that item will be overridden by
 142 the custom configuration value.
 143
 144 Using a custom settings file
 145 ----------------------------
 146
 147 Alternatively a custom settings file can be passed to ``vsperf`` via the
 148 ``--conf-file`` argument.
 149
 150   .. code-block:: console
 151
 152     ./vsperf --conf-file <path_to_settings_py> ...
 153
 154 Note that configuration passed in via the environment (``--load-env``)
 155 or via another command line argument will override both the default and
 156 your custom configuration files. This "priority hierarchy" can be
 157 described like so (1 = max priority):
 158
 159 1. Command line arguments
 160 2. Environment variables
 161 3. Configuration file(s)
 162
 163 --------------
 164
 165 Executing tests
 166 ---------------
 167
 168 Before running any tests make sure you have root permissions by adding
 169 the following line to /etc/sudoers:
 170
 171   .. code-block:: console
 172
 173     username ALL=(ALL)       NOPASSWD: ALL
 174
 175 username in the example above should be replaced with a real username.
 176
 177 To list the available tests:
 178
 179   .. code-block:: console
 180
 181     ./vsperf --list-tests
 182
 183 To run a group of tests, for example all tests with a name containing
 184 'RFC2544':
 185
 186   .. code-block:: console
 187
 188     ./vsperf --conf-file=user_settings.py --tests="RFC2544"
 189
 190 To run all tests:
 191
 192   .. code-block:: console
 193
 194     ./vsperf --conf-file=user_settings.py
 195
 196 Some tests allow for configurable parameters, including test duration
 197 (in seconds) as well as packet sizes (in bytes).
 198
 199 .. code:: bash
 200
 201     ./vsperf --conf-file user_settings.py
 202         --tests RFC2544Tput
 203         --test-param "rfc2544_duration=10;packet_sizes=128"
 204
 205 For all available options, check out the help dialog:
 206
 207   .. code-block:: console
 208
 209     ./vsperf --help
 210
 211 Executing PVP and PVVP tests
 212 ----------------------------
 213 To run tests using vhost-user as guest access method:
 214
 215 1. Set VHOST_METHOD and VNF of your settings file to:
 216
 217   .. code-block:: console
 218
 219    VHOST_METHOD='user'
 220    VNF = 'QemuDpdkVhost'
 221
 222 2. Recompile src for VHOST USER testing
 223
 224   .. code-block:: console
 225
 226      cd src
 227      make cleanse
 228      make VHOST_USER=y
 229
 230 3. Run test:
 231
 232   .. code-block:: console
 233
 234      ./vsperf --conf-file <path_to_settings_py>
 235
 236 To run tests using vhost-cuse as guest access method:
 237
 238 1. Set VHOST_METHOD and VNF of your settings file to:
 239
 240   .. code-block:: console
 241
 242      VHOST_METHOD='cuse'
 243      VNF = 'QemuDpdkVhostCuse'
 244
 245 2. Recompile src for VHOST USER testing
 246
 247   .. code-block:: console
 248
 249      cd src
 250      make cleanse
 251      make VHOST_USER=n
 252
 253 3. Run test:
 254
 255   .. code-block:: console
 256
 257      ./vsperf --conf-file <path_to_settings_py>
 258
 259 Executing PVP tests using Vanilla OVS
 260 -------------------------------------
 261 To run tests using Vanilla OVS:
 262
 263 1. Set the following variables:
 264
 265   .. code-block:: console
 266
 267    VSWITCH = 'OvsVanilla'
 268    VNF = 'QemuVirtioNet'
 269
 270    VANILLA_TGEN_PORT1_IP = n.n.n.n
 271    VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
 272
 273    VANILLA_TGEN_PORT2_IP = n.n.n.n
 274    VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
 275
 276    VANILLA_BRIDGE_IP = n.n.n.n
 277
 278    or use --test-param
 279
 280    ./vsperf --conf-file user_settings.py
 281             --test-param "vanilla_tgen_tx_ip=n.n.n.n;
 282                           vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
 283
 284
 285 2. Recompile src for Vanilla OVS testing
 286
 287   .. code-block:: console
 288
 289      cd src
 290      make cleanse
 291      make WITH_LINUX=/lib/modules/`uname -r`/build
 292
 293 3. Run test:
 294
 295   .. code-block:: console
 296
 297      ./vsperf --conf-file <path_to_settings_py>
 298
 299 Code change verification by pylint
 300 ----------------------------------
 301 Every developer participating in VSPERF project should run
 302 pylint before his python code is submitted for review. Project
 303 specific configuration for pylint is available at 'pylint.rc'.
 304
 305 Example of manual pylint invocation:
 306
 307   .. code-block:: console
 308
 309           pylint --rcfile ./pylintrc ./vsperf
 310
 311 GOTCHAs:
 312 --------
 313
 314 OVS with DPDK and QEMU
 315 ~~~~~~~~~~~~~~~~~~~~~~~
 316 If you encounter the following error: "before (last 100 chars):
 317 '-path=/dev/hugepages,share=on: unable to map backing store for
 318 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
 319 deployment scenario, check the amount of hugepages on your system:
 320
 321 .. code:: bash
 322
 323     cat /proc/meminfo | grep HugePages
 324
 325
 326 By default the vswitchd is launched with 1Gb of memory, to  change
 327 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
 328 an appropriate amount of memory:
 329
 330 .. code:: bash
 331
 332     VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
 333
 334 --------------
 335
 336 .. |Alt text| image:: ../images/TCLServerProperties.png