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 Configuration:
 327 ~~~~~~~~~~~~~~
 328 The mandatory configurations are enlisted below.
 329
 330 1. The Labserver and license server addresses. These parameters applies to
 331    all the tests and are mandatory.
 332
 333 .. code-block:: console
 334
 335     TRAFFICGEN_STC_LAB_SERVER_ADDR = " "
 336     TRAFFICGEN_STC_LICENSE_SERVER_ADDR = " "
 337
 338 2. For RFC2544 tests, the following parameters are mandatory
 339
 340
 341 .. code-block:: console
 342
 343     TRAFFICGEN_STC_RFC2544_TPUT_TEST_FILE_NAME = " "
 344     TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
 345     TRAFFICGEN_STC_EAST_SLOT_NUM = " "
 346     TRAFFICGEN_STC_EAST_PORT_NUM = " "
 347     TRAFFICGEN_STC_EAST_INTF_ADDR = " "
 348     TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
 349     TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
 350     TRAFFICGEN_STC_WEST_SLOT_NUM = " "
 351     TRAFFICGEN_STC_WEST_PORT_NUM = " "
 352     TRAFFICGEN_STC_WEST_INTF_ADDR = " "
 353     TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
 354
 355 3. For RFC2889 tests, specifying the locations of the ports is mandatory.
 356
 357 .. code-block:: console
 358
 359     TRAFFICGEN_STC_RFC2889_TEST_FILE_NAME = " "
 360     TRAFFICGEN_STC_RFC2889_LOCATIONS= " "
 361
 362 Xena Networks
 363 -------------
 364
 365 Installation
 366 ~~~~~~~~~~~~
 367
 368 Xena Networks traffic generator requires specific files and packages to be
 369 installed. It is assumed the user has access to the Xena2544.exe file which
 370 must be placed in VSPerf installation location under the tools/pkt_gen/xena
 371 folder. Contact Xena Networks for the latest version of this file. The user
 372 can also visit www.xenanetworks/downloads to obtain the file with a valid
 373 support contract.
 374
 375 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
 376
 377 To execute the Xena2544.exe file under Linux distributions the mono-complete
 378 package must be installed. To install this package follow the instructions
 379 below. Further information can be obtained from
 380 http://www.mono-project.com/docs/getting-started/install/linux/
 381
 382 .. code-block:: console
 383
 384     rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
 385     yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
 386     yum -y install mono-complete
 387
 388 To prevent gpg errors on future yum installation of packages the mono-project
 389 repo should be disabled once installed.
 390
 391 .. code-block:: console
 392
 393     yum-config-manager --disable download.mono-project.com_repo_centos_
 394
 395 Configuration
 396 ~~~~~~~~~~~~~
 397
 398 Connection information for your Xena Chassis must be supplied inside the
 399 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 400 set to allow for proper connections to the chassis.
 401
 402 .. code-block:: console
 403
 404     TRAFFICGEN_XENA_IP = ''
 405     TRAFFICGEN_XENA_PORT1 = ''
 406     TRAFFICGEN_XENA_PORT2 = ''
 407     TRAFFICGEN_XENA_USER = ''
 408     TRAFFICGEN_XENA_PASSWORD = ''
 409     TRAFFICGEN_XENA_MODULE1 = ''
 410     TRAFFICGEN_XENA_MODULE2 = ''
 411
 412 RFC2544 Throughput Testing
 413 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 414
 415 Xena traffic generator testing for rfc2544 throughput can be modified for
 416 different behaviors if needed. The default options for the following are
 417 optimized for best results.
 418
 419 .. code-block:: console
 420
 421     TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
 422     TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
 423     TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
 424     TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
 425     TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
 426     TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
 427
 428 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
 429 Xena documentation to understand the behavior changes in modifying these
 430 values.
 431
 432 MoonGen
 433 -------
 434
 435 Installation
 436 ~~~~~~~~~~~~
 437
 438 MoonGen architecture overview and general installation instructions
 439 can be found here:
 440
 441 https://github.com/emmericp/MoonGen
 442
 443 * Note:  Today, MoonGen with VSPERF only supports 10Gbps line speeds.
 444
 445 For VSPerf use, MoonGen should be cloned from here (as opposed to the previously
 446 mentioned GitHub):
 447
 448 git clone https://github.com/atheurer/MoonGen
 449
 450 and use the opnfv-stable branch:
 451
 452 git checkout opnfv-stable
 453
 454 VSPerf uses a particular example script under the examples directory within
 455 the MoonGen project:
 456
 457 MoonGen/examples/opnfv-vsperf.lua
 458
 459 Follow MoonGen set up instructions here:
 460
 461 https://github.com/atheurer/MoonGen/blob/opnfv-stable/MoonGenSetUp.html
 462
 463 Note one will need to set up ssh login to not use passwords between the server
 464 running MoonGen and the device under test (running the VSPERF test
 465 infrastructure).  This is because VSPERF on one server uses 'ssh' to
 466 configure and run MoonGen upon the other server.
 467
 468 One can set up this ssh access by doing the following on both servers:
 469
 470 .. code-block:: console
 471
 472     ssh-keygen -b 2048 -t rsa
 473     ssh-copy-id <other server>
 474
 475 Configuration
 476 ~~~~~~~~~~~~~
 477
 478 Connection information for MoonGen must be supplied inside the
 479 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 480 set to allow for proper connections to the host with MoonGen.
 481
 482 .. code-block:: console
 483
 484     TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
 485     TRAFFICGEN_MOONGEN_USER = ""
 486     TRAFFICGEN_MOONGEN_BASE_DIR = ""
 487     TRAFFICGEN_MOONGEN_PORTS = ""
 488     TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""