docs/testing/user/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 .. _trafficgen-installation:
   6
   7 ===========================
   8 'vsperf' Traffic Gen Guide
   9 ===========================
  10
  11 Overview
  12 --------
  13
  14 VSPERF supports the following traffic generators:
  15
  16   * Dummy_ (DEFAULT)
  17   * Ixia_
  18   * `Spirent TestCenter`_
  19   * `Xena Networks`_
  20   * MoonGen_
  21
  22 To see the list of traffic gens from the cli:
  23
  24 .. code-block:: console
  25
  26     $ ./vsperf --list-trafficgens
  27
  28 This guide provides the details of how to install
  29 and configure the various traffic generators.
  30
  31 Background Information
  32 ----------------------
  33 The traffic default configuration can be found in **conf/03_traffic.conf**,
  34 and is configured as follows:
  35
  36 .. code-block:: console
  37
  38     TRAFFIC = {
  39         'traffic_type' : 'rfc2544_throughput',
  40         'frame_rate' : 100,
  41         'bidir' : 'True',  # will be passed as string in title format to tgen
  42         'multistream' : 0,
  43         'stream_type' : 'L4',
  44         'pre_installed_flows' : 'No',           # used by vswitch implementation
  45         'flow_type' : 'port',                   # used by vswitch implementation
  46
  47         'l2': {
  48             'framesize': 64,
  49             'srcmac': '00:00:00:00:00:00',
  50             'dstmac': '00:00:00:00:00:00',
  51         },
  52         'l3': {
  53             'enabled': True,
  54             'proto': 'udp',
  55             'srcip': '1.1.1.1',
  56             'dstip': '90.90.90.90',
  57         },
  58         'l4': {
  59             'enabled': True,
  60             'srcport': 3000,
  61             'dstport': 3001,
  62         },
  63         'vlan': {
  64             'enabled': False,
  65             'id': 0,
  66             'priority': 0,
  67             'cfi': 0,
  68         },
  69     }
  70
  71 The framesize parameter can be overridden from the configuration
  72 files by adding the following to your custom configuration file
  73 ``10_custom.conf``:
  74
  75 .. code-block:: console
  76
  77     TRAFFICGEN_PKT_SIZES = (64, 128,)
  78
  79 OR from the commandline:
  80
  81 .. code-block:: console
  82
  83     $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y)" $TESTNAME
  84
  85 You can also modify the traffic transmission duration and the number
  86 of tests run by the traffic generator by extending the example
  87 commandline above to:
  88
  89 .. code-block:: console
  90
  91     $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y);TRAFFICGEN_DURATION=10;" \
  92                              "TRAFFICGEN_RFC2544_TESTS=1" $TESTNAME
  93
  94 .. _trafficgen-dummy:
  95
  96 Dummy
  97 -----
  98
  99 The Dummy traffic generator can be used to test VSPERF installation or
 100 to demonstrate VSPERF functionality at DUT without connection
 101 to a real traffic generator.
 102
 103 You could also use the Dummy generator in case, that your external
 104 traffic generator is not supported by VSPERF. In such case you could
 105 use VSPERF to setup your test scenario and then transmit the traffic.
 106 After the transmission is completed you could specify values for all
 107 collected metrics and VSPERF will use them to generate final reports.
 108
 109 Setup
 110 ~~~~~
 111
 112 To select the Dummy generator please add the following to your
 113 custom configuration file ``10_custom.conf``.
 114
 115 .. code-block:: console
 116
 117      TRAFFICGEN = 'Dummy'
 118
 119 OR run ``vsperf`` with the ``--trafficgen`` argument
 120
 121 .. code-block:: console
 122
 123     $ ./vsperf --trafficgen Dummy $TESTNAME
 124
 125 Where $TESTNAME is the name of the vsperf test you would like to run.
 126 This will setup the vSwitch and the VNF (if one is part of your test)
 127 print the traffic configuration and prompt you to transmit traffic
 128 when the setup is complete.
 129
 130 .. code-block:: console
 131
 132     Please send 'continuous' traffic with the following stream config:
 133     30mS, 90mpps, multistream False
 134     and the following flow config:
 135     {
 136         "flow_type": "port",
 137         "l3": {
 138             "enabled": True,
 139             "srcip": "1.1.1.1",
 140             "proto": "udp",
 141             "dstip": "90.90.90.90"
 142         },
 143         "traffic_type": "rfc2544_continuous",
 144         "multistream": 0,
 145         "bidir": "True",
 146         "vlan": {
 147             "cfi": 0,
 148             "priority": 0,
 149             "id": 0,
 150             "enabled": False
 151         },
 152         "l4": {
 153             "enabled": True,
 154             "srcport": 3000,
 155             "dstport": 3001,
 156         },
 157         "frame_rate": 90,
 158         "l2": {
 159             "dstmac": "00:00:00:00:00:00",
 160             "srcmac": "00:00:00:00:00:00",
 161             "framesize": 64
 162         }
 163     }
 164     What was the result for 'frames tx'?
 165
 166 When your traffic generator has completed traffic transmission and provided
 167 the results please input these at the VSPERF prompt. VSPERF will try
 168 to verify the input:
 169
 170 .. code-block:: console
 171
 172     Is '$input_value' correct?
 173
 174 Please answer with y OR n.
 175
 176 VSPERF will ask you to provide a value for every of collected metrics. The list
 177 of metrics can be found at traffic-type-metrics_.
 178 Finally vsperf will print out the results for your test and generate the
 179 appropriate logs and report files.
 180
 181 .. _traffic-type-metrics:
 182
 183 Metrics collected for supported traffic types
 184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 185
 186 Below you could find a list of metrics collected by VSPERF for each of supported
 187 traffic types.
 188
 189 RFC2544 Throughput and Continuous:
 190
 191   * frames tx
 192   * frames rx
 193   * min latency
 194   * max latency
 195   * avg latency
 196   * frameloss
 197
 198 RFC2544 Back2back:
 199
 200   * b2b frames
 201   * b2b frame loss %
 202
 203 Dummy result pre-configuration
 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 205
 206 In case of a Dummy traffic generator it is possible to pre-configure the test
 207 results. This is useful for creation of demo testcases, which do not require
 208 a real traffic generator. Such testcase can be run by any user and it will still
 209 generate all reports and result files.
 210
 211 Result values can be specified within ``TRAFFICGEN_DUMMY_RESULTS`` dictionary,
 212 where every of collected metrics must be properly defined. Please check the list
 213 of traffic-type-metrics_.
 214
 215 Dictionary with dummy results can be passed by CLI argument ``--test-params``
 216 or specified in ``Parameters`` section of testcase definition.
 217
 218 Example of testcase execution with dummy results defined by CLI argument:
 219
 220 .. code-block:: console
 221
 222     $ ./vsperf back2back --trafficgen Dummy --test-params \
 223       "TRAFFICGEN_DUMMY_RESULTS={'b2b frames':'3000','b2b frame loss %':'0.0'}"
 224
 225 Example of testcase definition with pre-configured dummy results:
 226
 227 .. code-block:: python
 228
 229     {
 230         "Name": "back2back",
 231         "Traffic Type": "rfc2544_back2back",
 232         "Deployment": "p2p",
 233         "biDirectional": "True",
 234         "Description": "LTD.Throughput.RFC2544.BackToBackFrames",
 235         "Parameters" : {
 236             'TRAFFICGEN_DUMMY_RESULTS' : {'b2b frames':'3000','b2b frame loss %':'0.0'}
 237         },
 238     },
 239
 240 **NOTE:** Pre-configured results for the Dummy traffic generator will be used only
 241 in case, that the Dummy traffic generator is used. Otherwise the option
 242 ``TRAFFICGEN_DUMMY_RESULTS`` will be ignored.
 243
 244 .. _Ixia:
 245
 246 Ixia
 247 ----
 248
 249 VSPERF can use both IxNetwork and IxExplorer TCL servers to control Ixia chassis.
 250 However usage of IxNetwork TCL server is a preferred option. Following sections
 251 will describe installation and configuration of IxNetwork components used by VSPERF.
 252
 253 Installation
 254 ~~~~~~~~~~~~
 255
 256 On the system under the test you need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
 257
 258 On the IXIA client software system you need to install IxNetwork TCL server. After its
 259 installation you should configure it as follows:
 260
 261     1. Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
 262        IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
 263     2. Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
 264        the Target dialogue box make sure there is the argument "-tclport xxxx"
 265        where xxxx is your port number (take note of this port number as you will
 266        need it for the 10\_custom.conf file).
 267
 268        .. image:: TCLServerProperties.png
 269
 270     3. Hit Ok and start the TCL server application
 271
 272 VSPERF configuration
 273 ~~~~~~~~~~~~~~~~~~~~
 274
 275 There are several configuration options specific to the IxNetwork traffic generator
 276 from IXIA. It is essential to set them correctly, before the VSPERF is executed
 277 for the first time.
 278
 279 Detailed description of options follows:
 280
 281  * ``TRAFFICGEN_IXNET_MACHINE`` - IP address of server, where IxNetwork TCL Server is running
 282  * ``TRAFFICGEN_IXNET_PORT`` - PORT, where IxNetwork TCL Server is accepting connections from
 283    TCL clients
 284  * ``TRAFFICGEN_IXNET_USER`` - username, which will be used during communication with IxNetwork
 285    TCL Server and IXIA chassis
 286  * ``TRAFFICGEN_IXIA_HOST`` - IP address of IXIA traffic generator chassis
 287  * ``TRAFFICGEN_IXIA_CARD`` - identification of card with dedicated ports at IXIA chassis
 288  * ``TRAFFICGEN_IXIA_PORT1`` - identification of the first dedicated port at ``TRAFFICGEN_IXIA_CARD``
 289    at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
 290    unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
 291    at DUT, i.e. to the first PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
 292    be able to pass through the vSwitch.
 293  * ``TRAFFICGEN_IXIA_PORT2`` - identification of the second dedicated port at ``TRAFFICGEN_IXIA_CARD``
 294    at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
 295    unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
 296    at DUT, i.e. to the second PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
 297    be able to pass through the vSwitch.
 298  * ``TRAFFICGEN_IXNET_LIB_PATH`` - path to the DUT specific installation of IxNetwork TCL API
 299  * ``TRAFFICGEN_IXNET_TCL_SCRIPT`` - name of the TCL script, which VSPERF will use for
 300    communication with IXIA TCL server
 301  * ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` - folder accessible from IxNetwork TCL server,
 302    where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
 303  * ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` - directory accessible from the DUT, where test
 304    results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
 305    test-results-share_
 306
 307 .. _test-results-share:
 308
 309 Test results share
 310 ~~~~~~~~~~~~~~~~~~
 311
 312 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
 313 results are stored at IxNetwork TCL server. Results are stored at folder defined by
 314 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
 315 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
 316 VSPERF is executed. VSPERF expects, that test results will be available at directory
 317 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
 318
 319 Example of sharing configuration:
 320
 321  * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
 322  * Modify sharing options of ``ixia_results`` folder to share it with everybody
 323  * Create a new directory at DUT, where shared directory with results
 324    will be mounted, e.g. ``/mnt/ixia_results``
 325  * Update your custom VSPERF configuration file as follows:
 326
 327    .. code-block:: python
 328
 329        TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
 330        TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
 331
 332    **NOTE:** It is essential to use slashes '/' also in path
 333    configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
 334  * Install cifs-utils package.
 335
 336    e.g. at rpm based Linux distribution:
 337
 338    .. code-block:: console
 339
 340        yum install cifs-utils
 341
 342  * Mount shared directory, so VSPERF can access test results.
 343
 344    e.g. by adding new record into ``/etc/fstab``
 345
 346    .. code-block:: console
 347
 348        mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
 349              -o file_mode=0777,dir_mode=0777,nounix
 350
 351 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
 352 is visible at DUT inside ``/mnt/ixia_results`` directory.
 353
 354 .. _`Spirent TestCenter`:
 355
 356 Spirent Setup
 357 -------------
 358
 359 Spirent installation files and instructions are available on the
 360 Spirent support website at:
 361
 362 http://support.spirent.com
 363
 364 Select a version of Spirent TestCenter software to utilize. This example
 365 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
 366 version in place of 'v4.57' in the examples, below.
 367
 368 On the CentOS 7 System
 369 ~~~~~~~~~~~~~~~~~~~~~~
 370
 371 Download and install the following:
 372
 373 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
 374
 375 Spirent Virtual Deployment Service (VDS)
 376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 377
 378 Spirent VDS is required for both TestCenter hardware and virtual
 379 chassis in the vsperf environment. For installation, select the version
 380 that matches the Spirent TestCenter Application version. For v4.57,
 381 the matching VDS version is 1.0.55. Download either the ova (VMware)
 382 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
 383 according to Spirent installation instructions.
 384
 385 Using Spirent TestCenter Virtual (STCv)
 386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 387
 388 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
 389 VMware, download:
 390
 391 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
 392
 393 Virtual test port performance is affected by the hypervisor configuration. For
 394 best practice results in deploying STCv, the following is suggested:
 395
 396 - Create a single VM with two test ports rather than two VMs with one port each
 397 - Set STCv in DPDK mode
 398 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
 399 - Turning off hyperthreading and pinning these cores will improve performance
 400 - Give STCv 2 GB of RAM
 401
 402 To get the highest performance and accuracy, Spirent TestCenter hardware is
 403 recommended. vsperf can run with either stype test ports.
 404
 405 Using STC REST Client
 406 ~~~~~~~~~~~~~~~~~~~~~
 407 The stcrestclient package provides the stchttp.py ReST API wrapper module.
 408 This allows simple function calls, nearly identical to those provided by
 409 StcPython.py, to be used to access TestCenter server sessions via the
 410 STC ReST API. Basic ReST functionality is provided by the resthttp module,
 411 and may be used for writing ReST clients independent of STC.
 412
 413 - Project page: <https://github.com/Spirent/py-stcrestclient>
 414 - Package download: <http://pypi.python.org/pypi/stcrestclient>
 415
 416 To use REST interface, follow the instructions in the Project page to
 417 install the package. Once installed, the scripts named with 'rest' keyword
 418 can be used. For example: testcenter-rfc2544-rest.py can be used to run
 419 RFC 2544 tests using the REST interface.
 420
 421 Configuration:
 422 ~~~~~~~~~~~~~~
 423
 424 1. The Labserver and license server addresses. These parameters applies to
 425    all the tests, and are mandatory for all tests.
 426
 427 .. code-block:: console
 428
 429     TRAFFICGEN_STC_LAB_SERVER_ADDR = " "
 430     TRAFFICGEN_STC_LICENSE_SERVER_ADDR = " "
 431     TRAFFICGEN_STC_PYTHON2_PATH = " "
 432     TRAFFICGEN_STC_TESTCENTER_PATH = " "
 433     TRAFFICGEN_STC_TEST_SESSION_NAME = " "
 434     TRAFFICGEN_STC_CSV_RESULTS_FILE_PREFIX = " "
 435
 436 2. For RFC2544 tests, the following parameters are mandatory
 437
 438 .. code-block:: console
 439
 440     TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
 441     TRAFFICGEN_STC_EAST_SLOT_NUM = " "
 442     TRAFFICGEN_STC_EAST_PORT_NUM = " "
 443     TRAFFICGEN_STC_EAST_INTF_ADDR = " "
 444     TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
 445     TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
 446     TRAFFICGEN_STC_WEST_SLOT_NUM = " "
 447     TRAFFICGEN_STC_WEST_PORT_NUM = " "
 448     TRAFFICGEN_STC_WEST_INTF_ADDR = " "
 449     TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
 450     TRAFFICGEN_STC_RFC2544_TPUT_TEST_FILE_NAME
 451
 452 3. RFC2889 tests: Currently, the forwarding, address-caching, and
 453    address-learning-rate tests of RFC2889 are supported.
 454    The testcenter-rfc2889-rest.py script implements the rfc2889 tests.
 455    The configuration for RFC2889 involves test-case definition, and parameter
 456    definition, as described below. New results-constants, as shown below, are
 457    added to support these tests.
 458
 459 Example of testcase definition for RFC2889 tests:
 460
 461 .. code-block:: python
 462
 463     {
 464         "Name": "phy2phy_forwarding",
 465         "Deployment": "p2p",
 466         "Description": "LTD.Forwarding.RFC2889.MaxForwardingRate",
 467         "Parameters" : {
 468             "TRAFFIC" : {
 469                 "traffic_type" : "rfc2889_forwarding",
 470             },
 471         },
 472     }
 473
 474 For RFC2889 tests, specifying the locations for the monitoring ports is mandatory.
 475 Necessary parameters are:
 476
 477 .. code-block:: console
 478
 479     TRAFFICGEN_STC_RFC2889_TEST_FILE_NAME
 480     TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
 481     TRAFFICGEN_STC_EAST_SLOT_NUM = " "
 482     TRAFFICGEN_STC_EAST_PORT_NUM = " "
 483     TRAFFICGEN_STC_EAST_INTF_ADDR = " "
 484     TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
 485     TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
 486     TRAFFICGEN_STC_WEST_SLOT_NUM = " "
 487     TRAFFICGEN_STC_WEST_PORT_NUM = " "
 488     TRAFFICGEN_STC_WEST_INTF_ADDR = " "
 489     TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
 490     TRAFFICGEN_STC_VERBOSE = "True"
 491     TRAFFICGEN_STC_RFC2889_LOCATIONS="//10.1.1.1/1/1,//10.1.1.1/2/2"
 492
 493 Other Configurations are :
 494
 495 .. code-block:: console
 496
 497     TRAFFICGEN_STC_RFC2889_MIN_LR = 1488
 498     TRAFFICGEN_STC_RFC2889_MAX_LR = 14880
 499     TRAFFICGEN_STC_RFC2889_MIN_ADDRS = 1000
 500     TRAFFICGEN_STC_RFC2889_MAX_ADDRS = 65536
 501     TRAFFICGEN_STC_RFC2889_AC_LR = 1000
 502
 503 The first 2 values are for address-learning test where as other 3 values are
 504 for the Address caching capacity test. LR: Learning Rate. AC: Address Caching.
 505 Maximum value for address is 16777216. Whereas, maximum for LR is 4294967295.
 506
 507 Results for RFC2889 Tests: Forwarding tests outputs following values:
 508
 509 .. code-block:: console
 510
 511     TX_RATE_FPS : "Transmission Rate in Frames/sec"
 512     THROUGHPUT_RX_FPS: "Received Throughput Frames/sec"
 513     TX_RATE_MBPS : " Transmission rate in MBPS"
 514     THROUGHPUT_RX_MBPS: "Received Throughput in MBPS"
 515     TX_RATE_PERCENT: "Transmission Rate in Percentage"
 516     FRAME_LOSS_PERCENT: "Frame loss in Percentage"
 517     FORWARDING_RATE_FPS: " Maximum Forwarding Rate in FPS"
 518
 519
 520 Whereas, the address caching test outputs following values,
 521
 522 .. code-block:: console
 523
 524     CACHING_CAPACITY_ADDRS = 'Number of address it can cache'
 525     ADDR_LEARNED_PERCENT = 'Percentage of address successfully learned'
 526
 527 and address learning test outputs just a single value:
 528
 529 .. code-block:: console
 530
 531     OPTIMAL_LEARNING_RATE_FPS = 'Optimal learning rate in fps'
 532
 533 Note that 'FORWARDING_RATE_FPS', 'CACHING_CAPACITY_ADDRS',
 534 'ADDR_LEARNED_PERCENT' and 'OPTIMAL_LEARNING_RATE_FPS' are the new
 535 result-constants added to support RFC2889 tests.
 536
 537 .. _`Xena Networks`:
 538
 539 Xena Networks
 540 -------------
 541
 542 Installation
 543 ~~~~~~~~~~~~
 544
 545 Xena Networks traffic generator requires specific files and packages to be
 546 installed. It is assumed the user has access to the Xena2544.exe file which
 547 must be placed in VSPerf installation location under the tools/pkt_gen/xena
 548 folder. Contact Xena Networks for the latest version of this file. The user
 549 can also visit www.xenanetworks/downloads to obtain the file with a valid
 550 support contract.
 551
 552 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
 553
 554 To execute the Xena2544.exe file under Linux distributions the mono-complete
 555 package must be installed. To install this package follow the instructions
 556 below. Further information can be obtained from
 557 http://www.mono-project.com/docs/getting-started/install/linux/
 558
 559 .. code-block:: console
 560
 561     rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
 562     yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
 563     yum -y install mono-complete
 564
 565 To prevent gpg errors on future yum installation of packages the mono-project
 566 repo should be disabled once installed.
 567
 568 .. code-block:: console
 569
 570     yum-config-manager --disable download.mono-project.com_repo_centos_
 571
 572 Configuration
 573 ~~~~~~~~~~~~~
 574
 575 Connection information for your Xena Chassis must be supplied inside the
 576 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 577 set to allow for proper connections to the chassis.
 578
 579 .. code-block:: console
 580
 581     TRAFFICGEN_XENA_IP = ''
 582     TRAFFICGEN_XENA_PORT1 = ''
 583     TRAFFICGEN_XENA_PORT2 = ''
 584     TRAFFICGEN_XENA_USER = ''
 585     TRAFFICGEN_XENA_PASSWORD = ''
 586     TRAFFICGEN_XENA_MODULE1 = ''
 587     TRAFFICGEN_XENA_MODULE2 = ''
 588
 589 RFC2544 Throughput Testing
 590 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 591
 592 Xena traffic generator testing for rfc2544 throughput can be modified for
 593 different behaviors if needed. The default options for the following are
 594 optimized for best results.
 595
 596 .. code-block:: console
 597
 598     TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
 599     TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
 600     TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
 601     TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
 602     TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
 603     TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
 604
 605 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
 606 Xena documentation to understand the behavior changes in modifying these
 607 values.
 608
 609 Xena RFC2544 testing inside VSPerf also includes a final verification option.
 610 This option allows for a faster binary search with a longer final verification
 611 of the binary search result. This feature can be enabled in the configuration
 612 files as well as the length of the final verification in seconds.
 613
 614 ..code-block:: python
 615
 616     TRAFFICGEN_XENA_RFC2544_VERIFY = False
 617     TRAFFICGEN_XENA_RFC2544_VERIFY_DURATION = 120
 618
 619 If the final verification does not pass the test with the lossrate specified
 620 it will continue the binary search from its previous point. If the smart search
 621 option is enabled the search will continue by taking the current pass rate minus
 622 the minimum and divided by 2. The maximum is set to the last pass rate minus the
 623 threshold value set.
 624
 625 For example if the settings are as follows
 626
 627 ..code-block:: python
 628
 629     TRAFFICGEN_XENA_RFC2544_BINARY_RESTART_SMART_SEARCH = True
 630     TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.5'
 631     TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
 632
 633 and the verification attempt was 64.5, smart search would take 64.5 - 0.5 / 2.
 634 This would continue the search at 32 but still have a maximum possible value of
 635 64.
 636
 637 If smart is not enabled it will just resume at the last pass rate minus the
 638 threshold value.
 639
 640 Continuous Traffic Testing
 641 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 642
 643 Xena continuous traffic by default does a 3 second learning preemption to allow
 644 the DUT to receive learning packets before a continuous test is performed. If
 645 a custom test case requires this learning be disabled, you can disable the option
 646 or modify the length of the learning by modifying the following settings.
 647
 648 .. code-block:: console
 649
 650     TRAFFICGEN_XENA_CONT_PORT_LEARNING_ENABLED = False
 651     TRAFFICGEN_XENA_CONT_PORT_LEARNING_DURATION = 3
 652
 653 MoonGen
 654 -------
 655
 656 Installation
 657 ~~~~~~~~~~~~
 658
 659 MoonGen architecture overview and general installation instructions
 660 can be found here:
 661
 662 https://github.com/emmericp/MoonGen
 663
 664 * Note:  Today, MoonGen with VSPERF only supports 10Gbps line speeds.
 665
 666 For VSPERF use, MoonGen should be cloned from here (as opposed to the
 667 previously mentioned GitHub):
 668
 669 git clone https://github.com/atheurer/lua-trafficgen
 670
 671 and use the master branch:
 672
 673 git checkout master
 674
 675 VSPERF uses a particular Lua script with the MoonGen project:
 676
 677 trafficgen.lua
 678
 679 Follow MoonGen set up and execution instructions here:
 680
 681 https://github.com/atheurer/lua-trafficgen/blob/master/README.md
 682
 683 Note one will need to set up ssh login to not use passwords between the server
 684 running MoonGen and the device under test (running the VSPERF test
 685 infrastructure).  This is because VSPERF on one server uses 'ssh' to
 686 configure and run MoonGen upon the other server.
 687
 688 One can set up this ssh access by doing the following on both servers:
 689
 690 .. code-block:: console
 691
 692     ssh-keygen -b 2048 -t rsa
 693     ssh-copy-id <other server>
 694
 695 Configuration
 696 ~~~~~~~~~~~~~
 697
 698 Connection information for MoonGen must be supplied inside the
 699 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
 700 set to allow for proper connections to the host with MoonGen.
 701
 702 .. code-block:: console
 703
 704     TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
 705     TRAFFICGEN_MOONGEN_USER = ""
 706     TRAFFICGEN_MOONGEN_BASE_DIR = ""
 707     TRAFFICGEN_MOONGEN_PORTS = ""
 708     TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""