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