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