docs/configguide/trafficgen.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, AT&T and others.
   4
   5 ===========================
   6 'vsperf' Traffic Gen Guide
   7 ===========================
   8
   9 Overview
  10 ---------------------
  11 VSPERF supports the following traffic generators:
  12
  13   * Dummy (DEFAULT): Allows you to use your own external
  14     traffic generator.
  15   * IXIA (IxNet and IxOS)
  16   * Spirent TestCenter
  17   * Xena Networks
  18   * MoonGen
  19
  20 To see the list of traffic gens from the cli:
  21
  22 .. code-block:: console
  23
  24     $ ./vsperf --list-trafficgens
  25
  26 This guide provides the details of how to install
  27 and configure the various traffic generators.
  28
  29 Background Information
  30 ----------------------
  31 The traffic default configuration can be found in
  32 tools/pkt_gen/trafficgen/trafficgenhelper.py, and is configured as
  33 follows:
  34
  35 .. code-block:: console
  36
  37     TRAFFIC_DEFAULTS = {
  38         'l2': {
  39             'framesize': 64,
  40             'srcmac': '00:00:00:00:00:00',
  41             'dstmac': '00:00:00:00:00:00',
  42         },
  43         'l3': {
  44             'proto': 'tcp',
  45             'srcip': '1.1.1.1',
  46             'dstip': '90.90.90.90',
  47         },
  48         'l4': {
  49             'srcport': 3000,
  50             'dstport': 3001,
  51         },
  52         'vlan': {
  53             'enabled': False,
  54             'id': 0,
  55             'priority': 0,
  56             'cfi': 0,
  57         },
  58     }
  59
  60 The framesize parameter can be overridden from the configuration
  61 files by adding the following to your custom configuration file
  62 ``10_custom.conf``:
  63
  64 .. code-block:: console
  65
  66     TRAFFICGEN_PKT_SIZES = (64, 128,)
  67
  68 OR from the commandline:
  69
  70 .. code-block:: console
  71
  72     $ ./vsperf --test-params "pkt_sizes=x,y" $TESTNAME
  73
  74 You can also modify the traffic transmission duration and the number
  75 of tests run by the traffic generator by extending the example
  76 commandline above to:
  77
  78 .. code-block:: console
  79
  80     $ ./vsperf --test-params "pkt_sizes=x,y;duration=10;rfc2544_tests=1" $TESTNAME
  81
  82 Dummy Setup
  83 ------------
  84 To select the Dummy generator please add the following to your
  85 custom configuration file ``10_custom.conf``.
  86
  87
  88 .. code-block:: console
  89
  90      TRAFFICGEN = 'Dummy'
  91
  92 OR run ``vsperf`` with the ``--trafficgen`` argument
  93
  94 .. code-block:: console
  95
  96     $ ./vsperf --trafficgen Dummy $TESTNAME
  97
  98 Where $TESTNAME is the name of the vsperf test you would like to run.
  99 This will setup the vSwitch and the VNF (if one is part of your test)
 100 print the traffic configuration and prompt you to transmit traffic
 101 when the setup is complete.
 102
 103 .. code-block:: console
 104
 105     Please send 'continuous' traffic with the following stream config:
 106     30mS, 90mpps, multistream False
 107     and the following flow config:
 108     {
 109         "flow_type": "port",
 110         "l3": {
 111             "srcip": "1.1.1.1",
 112             "proto": "tcp",
 113             "dstip": "90.90.90.90"
 114         },
 115         "traffic_type": "continuous",
 116         "multistream": 0,
 117         "bidir": "True",
 118         "vlan": {
 119             "cfi": 0,
 120             "priority": 0,
 121             "id": 0,
 122             "enabled": false
 123         },
 124         "frame_rate": 90,
 125         "l2": {
 126             "dstport": 3001,
 127             "srcport": 3000,
 128             "dstmac": "00:00:00:00:00:00",
 129             "srcmac": "00:00:00:00:00:00",
 130             "framesize": 64
 131         }
 132     }
 133     What was the result for 'frames tx'?
 134
 135 When your traffic gen has completed traffic transmission and provided
 136 the results please input these at the vsperf prompt. vsperf will try
 137 to verify the input:
 138
 139 .. code-block:: console
 140
 141     Is '$input_value' correct?
 142
 143 Please answer with y OR n.
 144
 145 VPSERF will ask you for:
 146   * Result for 'frames tx'
 147   * Result for 'frames rx'
 148   * Result for 'min latency'
 149   * Result for 'max latency'
 150   * Result for 'avg latency'
 151
 152 Finally vsperf will print out the results for your test and generate the
 153 appropriate logs and csv files.
 154
 155
 156 IXIA Setup
 157 ----------
 158
 159 On the CentOS 7 system
 160 ~~~~~~~~~~~~~~~~~~~~~~
 161
 162 You need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
 163
 164 On the IXIA client software system
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
 168 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
 169
 170 Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
 171 the Target dialogue box make sure there is the argument "-tclport xxxx"
 172 where xxxx is your port number (take note of this port number as you will
 173 need it for the 10\_custom.conf file).
 174
 175 .. image:: TCLServerProperties.png
 176
 177 Hit Ok and start the TCL server application
 178
 179 VSPERF configuration
 180 ~~~~~~~~~~~~~~~~~~~~
 181
 182 There are several configuration options specific to the IxNetworks traffic generator
 183 from IXIA. It is essential to set them correctly, before the VSPERF is executed
 184 for the first time.
 185
 186 Detailed description of options follows:
 187
 188  * TRAFFICGEN_IXNET_MACHINE - IP address of server, where IxNetwork TCL Server is running
 189  * TRAFFICGEN_IXNET_PORT - PORT, where IxNetwork TCL Server is accepting connections from
 190    TCL clients
 191  * TRAFFICGEN_IXNET_USER - username, which will be used during communication with IxNetwork
 192    TCL Server and IXIA chassis
 193  * TRAFFICGEN_IXIA_HOST - IP address of IXIA traffic generator chassis
 194  * TRAFFICGEN_IXIA_CARD - identification of card with dedicated ports at IXIA chassis
 195  * TRAFFICGEN_IXIA_PORT1 - identification of the first dedicated port at TRAFFICGEN_IXIA_CARD
 196    at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
 197    unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
 198    at DUT, i.e. to the first PCI handle from WHITELIST_NICS list. Otherwise traffic may not
 199    be able to pass through the vSwitch.
 200  * TRAFFICGEN_IXIA_PORT2 - identification of the second dedicated port at TRAFFICGEN_IXIA_CARD
 201    at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
 202    unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
 203    at DUT, i.e. to the second PCI handle from WHITELIST_NICS list. Otherwise traffic may not
 204    be able to pass through the vSwitch.
 205  * TRAFFICGEN_IXNET_LIB_PATH - path to the DUT specific installation of IxNetwork TCL API
 206  * TRAFFICGEN_IXNET_TCL_SCRIPT - name of the TCL script, which VSPERF will use for
 207    communication with IXIA TCL server
 208  * TRAFFICGEN_IXNET_TESTER_RESULT_DIR - folder accessible from IxNetwork TCL server,
 209    where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
 210  * TRAFFICGEN_IXNET_DUT_RESULT_DIR - directory accessible from the DUT, where test
 211    results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
 212    test-results-share_
 213
 214 .. _test-results-share:
 215
 216 Test results share
 217 ~~~~~~~~~~~~~~~~~~
 218
 219 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
 220 results are stored at IxNetwork TCL server. Results are stored at folder defined by
 221 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
 222 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
 223 VSPERF is executed. VSPERF expects, that test results will be available at directory
 224 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
 225
 226 Example of sharing configuration:
 227
 228  * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
 229  * Modify sharing options of ``ixia_results`` folder to share it with everybody
 230  * Create a new directory at DUT, where shared directory with results
 231    will be mounted, e.g. ``/mnt/ixia_results``
 232  * Update your custom VSPERF configuration file as follows:
 233
 234    .. code-block:: python
 235
 236        TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
 237        TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
 238
 239    Note: It is essential to use slashes '/' also in path
 240    configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
 241  * Install cifs-utils package.
 242
 243    e.g. at rpm based Linux distribution:
 244
 245    .. code-block:: console
 246
 247        yum install cifs-utils
 248
 249  * Mount shared directory, so VSPERF can access test results.
 250
 251    e.g. by adding new record into ``/etc/fstab``
 252
 253    .. code-block:: console
 254
 255        mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
 256              -o file_mode=0777,dir_mode=0777,nounix
 257
 258 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
 259 is visible at DUT inside ``/mnt/ixia_results`` directory.
 260
 261 Spirent Setup
 262 -------------
 263
 264 Spirent installation files and instructions are available on the
 265 Spirent support website at:
 266
 267 http://support.spirent.com
 268
 269 Select a version of Spirent TestCenter software to utilize. This example
 270 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
 271 version in place of 'v4.57' in the examples, below.
 272
 273 On the CentOS 7 System
 274 ~~~~~~~~~~~~~~~~~~~~~~
 275
 276 Download and install the following:
 277
 278 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
 279
 280 Spirent Virtual Deployment Service (VDS)
 281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 282
 283 Spirent VDS is required for both TestCenter hardware and virtual
 284 chassis in the vsperf environment. For installation, select the version
 285 that matches the Spirent TestCenter Application version. For v4.57,
 286 the matching VDS version is 1.0.55. Download either the ova (VMware)
 287 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
 288 according to Spirent installation instructions.
 289
 290 Using Spirent TestCenter Virtual (STCv)
 291 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 292
 293 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
 294 VMware, download:
 295
 296 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
 297
 298 Virtual test port performance is affected by the hypervisor configuration. For
 299 best practice results in deploying STCv, the following is suggested:
 300
 301 - Create a single VM with two test ports rather than two VMs with one port each
 302 - Set STCv in DPDK mode
 303 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
 304 - Turning off hyperthreading and pinning these cores will improve performance
 305 - Give STCv 2 GB of RAM
 306
 307 To get the highest performance and accuracy, Spirent TestCenter hardware is
 308 recommended. vsperf can run with either stype test ports.
 309
 310 Using STC REST Client
 311 ~~~~~~~~~~~~~~~~~~~~~
 312 The stcrestclient package provides the stchttp.py ReST API wrapper module.
 313 This allows simple function calls, nearly identical to those provided by
 314 StcPython.py, to be used to access TestCenter server sessions via the
 315 STC ReST API. Basic ReST functionality is provided by the resthttp module,
 316 and may be used for writing ReST clients independent of STC.
 317
 318 - Project page: <https://github.com/Spirent/py-stcrestclient>
 319 - Package download: <http://pypi.python.org/pypi/stcrestclient>
 320
 321 To use REST interface, follow the instructions in the Project page to
 322 install the package. Once installed, the scripts named with 'rest' keyword
 323 can be used. For example: testcenter-rfc2544-rest.py can be used to run
 324 RFC 2544 tests using the REST interface.
 325
 326 Xena Networks
 327 -------------
 328
 329 Installation
 330 ~~~~~~~~~~~~
 331
 332 Xena Networks traffic generator requires specific files and packages to be
 333 installed. It is assumed the user has access to the Xena2544.exe file which
 334 must be placed in VSPerf installation location under the tools/pkt_gen/xena
 335 folder. Contact Xena Networks for the latest version of this file. The user
 336 can also visit www.xenanetworks/downloads to obtain the file with a valid
 337 support contract.
 338
 339 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
 340
 341 To execute the Xena2544.exe file under Linux distributions the mono-complete
 342 package must be installed. To install this package follow the instructions
 343 below. Further information can be obtained from
 344 http://www.mono-project.com/docs/getting-started/install/linux/
 345
 346 .. code-block:: console
 347
 348     rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
 349     yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
 350     yum -y install mono-complete
 351
 352 To prevent gpg errors on future yum installation of packages the mono-project
 353 repo should be disabled once installed.
 354
 355 .. code-block:: console
 356
 357     yum-config-manager --disable download.mono-project.com_repo_centos_
 358
 359 Configuration
 360 ~~~~~~~~~~~~~
 361
 362 Connection information for your Xena Chassis must be supplied inside the
 363 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 364 set to allow for proper connections to the chassis.
 365
 366 .. code-block:: console
 367
 368     TRAFFICGEN_XENA_IP = ''
 369     TRAFFICGEN_XENA_PORT1 = ''
 370     TRAFFICGEN_XENA_PORT2 = ''
 371     TRAFFICGEN_XENA_USER = ''
 372     TRAFFICGEN_XENA_PASSWORD = ''
 373     TRAFFICGEN_XENA_MODULE1 = ''
 374     TRAFFICGEN_XENA_MODULE2 = ''
 375
 376 RFC2544 Throughput Testing
 377 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 378
 379 Xena traffic generator testing for rfc2544 throughput can be modified for
 380 different behaviors if needed. The default options for the following are
 381 optimized for best results.
 382
 383 .. code-block:: console
 384
 385     TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
 386     TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
 387     TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
 388     TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
 389     TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
 390     TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
 391
 392 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
 393 Xena documentation to understand the behavior changes in modifying these
 394 values.
 395
 396 MoonGen
 397 -------
 398
 399 Installation
 400 ~~~~~~~~~~~~
 401
 402 MoonGen architecture overview and general installation instructions
 403 can be found here:
 404
 405 https://github.com/emmericp/MoonGen
 406
 407 * Note:  Today, MoonGen with VSPERF only supports 10Gbps line speeds.
 408
 409 For VSPerf use, MoonGen should be cloned from here (as opposed to the previously
 410 mentioned GitHub):
 411
 412 git clone https://github.com/atheurer/MoonGen
 413
 414 and use the opnfv-stable branch:
 415
 416 git checkout opnfv-stable
 417
 418 VSPerf uses a particular example script under the examples directory within
 419 the MoonGen project:
 420
 421 MoonGen/examples/opnfv-vsperf.lua
 422
 423 Follow MoonGen set up instructions here:
 424
 425 https://github.com/atheurer/MoonGen/blob/opnfv-stable/MoonGenSetUp.html
 426
 427 Note one will need to set up ssh login to not use passwords between the server
 428 running MoonGen and the device under test (running the VSPERF test
 429 infrastructure).  This is because VSPERF on one server uses 'ssh' to
 430 configure and run MoonGen upon the other server.
 431
 432 One can set up this ssh access by doing the following on both servers:
 433
 434 .. code-block:: console
 435
 436     ssh-keygen -b 2048 -t rsa
 437     ssh-copy-id <other server>
 438
 439 Configuration
 440 ~~~~~~~~~~~~~
 441
 442 Connection information for your Xena Chassis must be supplied inside the
 443 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 444 set to allow for proper connections to the chassis.
 445
 446 .. code-block:: console
 447
 448     TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
 449     TRAFFICGEN_MOONGEN_USER = ""
 450     TRAFFICGEN_MOONGEN_BASE_DIR = ""
 451     TRAFFICGEN_MOONGEN_PORTS = ""
 452     TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""