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.
5 .. _trafficgen-installation:
7 ===========================
8 'vsperf' Traffic Gen Guide
9 ===========================
14 VSPERF supports the following traffic generators:
18 * `Spirent TestCenter`_
23 To see the list of traffic gens from the cli:
25 .. code-block:: console
27 $ ./vsperf --list-trafficgens
29 This guide provides the details of how to install
30 and configure the various traffic generators.
32 Background Information
33 ----------------------
34 The traffic default configuration can be found in **conf/03_traffic.conf**,
35 and is configured as follows:
37 .. code-block:: console
40 'traffic_type' : 'rfc2544_throughput',
43 'bidir' : 'True', # will be passed as string in title format to tgen
46 'pre_installed_flows' : 'No', # used by vswitch implementation
47 'flow_type' : 'port', # used by vswitch implementation
48 'flow_control' : False, # supported only by IxNet
49 'learning_frames' : True, # supported only by IxNet
52 'srcmac': '00:00:00:00:00:00',
53 'dstmac': '00:00:00:00:00:00',
59 'dstip': '90.90.90.90',
81 '0' : 'Ether(src={Ether_src}, dst={Ether_dst})/'
82 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
83 'IP(proto={IP_proto}, src={IP_src}, dst={IP_dst})/'
84 '{IP_PROTO}(sport={IP_PROTO_sport}, dport={IP_PROTO_dport})',
85 '1' : 'Ether(src={Ether_dst}, dst={Ether_src})/'
86 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
87 'IP(proto={IP_proto}, src={IP_dst}, dst={IP_src})/'
88 '{IP_PROTO}(sport={IP_PROTO_dport}, dport={IP_PROTO_sport})',
92 A detailed description of the ``TRAFFIC`` dictionary can be found at
93 :ref:`configuration-of-traffic-dictionary`.
95 The framesize parameter can be overridden from the configuration
96 files by adding the following to your custom configuration file
99 .. code-block:: console
101 TRAFFICGEN_PKT_SIZES = (64, 128,)
103 OR from the commandline:
105 .. code-block:: console
107 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y)" $TESTNAME
109 You can also modify the traffic transmission duration and the number
110 of tests run by the traffic generator by extending the example
111 commandline above to:
113 .. code-block:: console
115 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y);TRAFFICGEN_DURATION=10;" \
116 "TRAFFICGEN_RFC2544_TESTS=1" $TESTNAME
118 .. _trafficgen-dummy:
123 The Dummy traffic generator can be used to test VSPERF installation or
124 to demonstrate VSPERF functionality at DUT without connection
125 to a real traffic generator.
127 You could also use the Dummy generator in case, that your external
128 traffic generator is not supported by VSPERF. In such case you could
129 use VSPERF to setup your test scenario and then transmit the traffic.
130 After the transmission is completed you could specify values for all
131 collected metrics and VSPERF will use them to generate final reports.
136 To select the Dummy generator please add the following to your
137 custom configuration file ``10_custom.conf``.
139 .. code-block:: console
143 OR run ``vsperf`` with the ``--trafficgen`` argument
145 .. code-block:: console
147 $ ./vsperf --trafficgen Dummy $TESTNAME
149 Where $TESTNAME is the name of the vsperf test you would like to run.
150 This will setup the vSwitch and the VNF (if one is part of your test)
151 print the traffic configuration and prompt you to transmit traffic
152 when the setup is complete.
154 .. code-block:: console
156 Please send 'continuous' traffic with the following stream config:
157 30mS, 90mpps, multistream False
158 and the following flow config:
165 "dstip": "90.90.90.90"
167 "traffic_type": "rfc2544_continuous",
183 "dstmac": "00:00:00:00:00:00",
184 "srcmac": "00:00:00:00:00:00",
188 What was the result for 'frames tx'?
190 When your traffic generator has completed traffic transmission and provided
191 the results please input these at the VSPERF prompt. VSPERF will try
194 .. code-block:: console
196 Is '$input_value' correct?
198 Please answer with y OR n.
200 VSPERF will ask you to provide a value for every of collected metrics. The list
201 of metrics can be found at traffic-type-metrics_.
202 Finally vsperf will print out the results for your test and generate the
203 appropriate logs and report files.
205 .. _traffic-type-metrics:
207 Metrics collected for supported traffic types
208 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210 Below you could find a list of metrics collected by VSPERF for each of supported
213 RFC2544 Throughput and Continuous:
227 Dummy result pre-configuration
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230 In case of a Dummy traffic generator it is possible to pre-configure the test
231 results. This is useful for creation of demo testcases, which do not require
232 a real traffic generator. Such testcase can be run by any user and it will still
233 generate all reports and result files.
235 Result values can be specified within ``TRAFFICGEN_DUMMY_RESULTS`` dictionary,
236 where every of collected metrics must be properly defined. Please check the list
237 of traffic-type-metrics_.
239 Dictionary with dummy results can be passed by CLI argument ``--test-params``
240 or specified in ``Parameters`` section of testcase definition.
242 Example of testcase execution with dummy results defined by CLI argument:
244 .. code-block:: console
246 $ ./vsperf back2back --trafficgen Dummy --test-params \
247 "TRAFFICGEN_DUMMY_RESULTS={'b2b frames':'3000','b2b frame loss %':'0.0'}"
249 Example of testcase definition with pre-configured dummy results:
251 .. code-block:: python
255 "Traffic Type": "rfc2544_back2back",
257 "biDirectional": "True",
258 "Description": "LTD.Throughput.RFC2544.BackToBackFrames",
260 'TRAFFICGEN_DUMMY_RESULTS' : {'b2b frames':'3000','b2b frame loss %':'0.0'}
264 **NOTE:** Pre-configured results for the Dummy traffic generator will be used only
265 in case, that the Dummy traffic generator is used. Otherwise the option
266 ``TRAFFICGEN_DUMMY_RESULTS`` will be ignored.
273 VSPERF can use both IxNetwork and IxExplorer TCL servers to control Ixia chassis.
274 However, usage of IxNetwork TCL server is a preferred option. The following sections
275 will describe installation and configuration of IxNetwork components used by VSPERF.
280 On the system under the test you need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
282 On the IXIA client software system you need to install IxNetwork TCL server. After its
283 installation you should configure it as follows:
285 1. Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
286 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
287 2. Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
288 the Target dialogue box make sure there is the argument "-tclport xxxx"
289 where xxxx is your port number (take note of this port number as you will
290 need it for the 10\_custom.conf file).
292 .. image:: TCLServerProperties.png
294 3. Hit Ok and start the TCL server application
299 There are several configuration options specific to the IxNetwork traffic generator
300 from IXIA. It is essential to set them correctly, before the VSPERF is executed
303 Detailed description of options follows:
305 * ``TRAFFICGEN_IXNET_MACHINE`` - IP address of server, where IxNetwork TCL Server is running
306 * ``TRAFFICGEN_IXNET_PORT`` - PORT, where IxNetwork TCL Server is accepting connections from
308 * ``TRAFFICGEN_IXNET_USER`` - username, which will be used during communication with IxNetwork
309 TCL Server and IXIA chassis
310 * ``TRAFFICGEN_IXIA_HOST`` - IP address of IXIA traffic generator chassis
311 * ``TRAFFICGEN_IXIA_CARD`` - identification of card with dedicated ports at IXIA chassis
312 * ``TRAFFICGEN_IXIA_PORT1`` - identification of the first dedicated port at ``TRAFFICGEN_IXIA_CARD``
313 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
314 unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
315 at DUT, i.e. to the first PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
316 be able to pass through the vSwitch.
317 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
318 same value, then VSPERF will assume, that there is only one port connection between IXIA
319 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
320 first NIC from ``WHITELIST_NICS`` list.
321 * ``TRAFFICGEN_IXIA_PORT2`` - identification of the second dedicated port at ``TRAFFICGEN_IXIA_CARD``
322 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
323 unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
324 at DUT, i.e. to the second PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
325 be able to pass through the vSwitch.
326 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
327 same value, then VSPERF will assume, that there is only one port connection between IXIA
328 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
329 first NIC from ``WHITELIST_NICS`` list.
330 * ``TRAFFICGEN_IXNET_LIB_PATH`` - path to the DUT specific installation of IxNetwork TCL API
331 * ``TRAFFICGEN_IXNET_TCL_SCRIPT`` - name of the TCL script, which VSPERF will use for
332 communication with IXIA TCL server
333 * ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` - folder accessible from IxNetwork TCL server,
334 where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
335 * ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` - directory accessible from the DUT, where test
336 results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
339 .. _test-results-share:
344 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
345 results are stored at IxNetwork TCL server. Results are stored at folder defined by
346 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
347 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
348 VSPERF is executed. VSPERF expects, that test results will be available at directory
349 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
351 Example of sharing configuration:
353 * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
354 * Modify sharing options of ``ixia_results`` folder to share it with everybody
355 * Create a new directory at DUT, where shared directory with results
356 will be mounted, e.g. ``/mnt/ixia_results``
357 * Update your custom VSPERF configuration file as follows:
359 .. code-block:: python
361 TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
362 TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
364 **NOTE:** It is essential to use slashes '/' also in path
365 configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
366 * Install cifs-utils package.
368 e.g. at rpm based Linux distribution:
370 .. code-block:: console
372 yum install cifs-utils
374 * Mount shared directory, so VSPERF can access test results.
376 e.g. by adding new record into ``/etc/fstab``
378 .. code-block:: console
380 mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
381 -o file_mode=0777,dir_mode=0777,nounix
383 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
384 is visible at DUT inside ``/mnt/ixia_results`` directory.
386 .. _`Spirent TestCenter`:
391 Spirent installation files and instructions are available on the
392 Spirent support website at:
394 http://support.spirent.com
396 Select a version of Spirent TestCenter software to utilize. This example
397 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
398 version in place of 'v4.57' in the examples, below.
400 On the CentOS 7 System
401 ~~~~~~~~~~~~~~~~~~~~~~
403 Download and install the following:
405 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
407 Spirent Virtual Deployment Service (VDS)
408 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
410 Spirent VDS is required for both TestCenter hardware and virtual
411 chassis in the vsperf environment. For installation, select the version
412 that matches the Spirent TestCenter Application version. For v4.57,
413 the matching VDS version is 1.0.55. Download either the ova (VMware)
414 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
415 according to Spirent installation instructions.
417 Using Spirent TestCenter Virtual (STCv)
418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
420 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
423 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
425 Virtual test port performance is affected by the hypervisor configuration. For
426 best practice results in deploying STCv, the following is suggested:
428 - Create a single VM with two test ports rather than two VMs with one port each
429 - Set STCv in DPDK mode
430 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
431 - Turning off hyperthreading and pinning these cores will improve performance
432 - Give STCv 2 GB of RAM
434 To get the highest performance and accuracy, Spirent TestCenter hardware is
435 recommended. vsperf can run with either stype test ports.
437 Using STC REST Client
438 ~~~~~~~~~~~~~~~~~~~~~
439 The stcrestclient package provides the stchttp.py ReST API wrapper module.
440 This allows simple function calls, nearly identical to those provided by
441 StcPython.py, to be used to access TestCenter server sessions via the
442 STC ReST API. Basic ReST functionality is provided by the resthttp module,
443 and may be used for writing ReST clients independent of STC.
445 - Project page: <https://github.com/Spirent/py-stcrestclient>
446 - Package download: <http://pypi.python.org/pypi/stcrestclient>
448 To use REST interface, follow the instructions in the Project page to
449 install the package. Once installed, the scripts named with 'rest' keyword
450 can be used. For example: testcenter-rfc2544-rest.py can be used to run
451 RFC 2544 tests using the REST interface.
456 1. The Labserver and license server addresses. These parameters applies to
457 all the tests, and are mandatory for all tests.
459 .. code-block:: console
461 TRAFFICGEN_STC_LAB_SERVER_ADDR = " "
462 TRAFFICGEN_STC_LICENSE_SERVER_ADDR = " "
463 TRAFFICGEN_STC_PYTHON2_PATH = " "
464 TRAFFICGEN_STC_TESTCENTER_PATH = " "
465 TRAFFICGEN_STC_TEST_SESSION_NAME = " "
466 TRAFFICGEN_STC_CSV_RESULTS_FILE_PREFIX = " "
468 2. For RFC2544 tests, the following parameters are mandatory
470 .. code-block:: console
472 TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
473 TRAFFICGEN_STC_EAST_SLOT_NUM = " "
474 TRAFFICGEN_STC_EAST_PORT_NUM = " "
475 TRAFFICGEN_STC_EAST_INTF_ADDR = " "
476 TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
477 TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
478 TRAFFICGEN_STC_WEST_SLOT_NUM = " "
479 TRAFFICGEN_STC_WEST_PORT_NUM = " "
480 TRAFFICGEN_STC_WEST_INTF_ADDR = " "
481 TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
482 TRAFFICGEN_STC_RFC2544_TPUT_TEST_FILE_NAME
484 3. RFC2889 tests: Currently, the forwarding, address-caching, and
485 address-learning-rate tests of RFC2889 are supported.
486 The testcenter-rfc2889-rest.py script implements the rfc2889 tests.
487 The configuration for RFC2889 involves test-case definition, and parameter
488 definition, as described below. New results-constants, as shown below, are
489 added to support these tests.
491 Example of testcase definition for RFC2889 tests:
493 .. code-block:: python
496 "Name": "phy2phy_forwarding",
498 "Description": "LTD.Forwarding.RFC2889.MaxForwardingRate",
501 "traffic_type" : "rfc2889_forwarding",
506 For RFC2889 tests, specifying the locations for the monitoring ports is mandatory.
507 Necessary parameters are:
509 .. code-block:: console
511 TRAFFICGEN_STC_RFC2889_TEST_FILE_NAME
512 TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
513 TRAFFICGEN_STC_EAST_SLOT_NUM = " "
514 TRAFFICGEN_STC_EAST_PORT_NUM = " "
515 TRAFFICGEN_STC_EAST_INTF_ADDR = " "
516 TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
517 TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
518 TRAFFICGEN_STC_WEST_SLOT_NUM = " "
519 TRAFFICGEN_STC_WEST_PORT_NUM = " "
520 TRAFFICGEN_STC_WEST_INTF_ADDR = " "
521 TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
522 TRAFFICGEN_STC_VERBOSE = "True"
523 TRAFFICGEN_STC_RFC2889_LOCATIONS="//10.1.1.1/1/1,//10.1.1.1/2/2"
525 Other Configurations are :
527 .. code-block:: console
529 TRAFFICGEN_STC_RFC2889_MIN_LR = 1488
530 TRAFFICGEN_STC_RFC2889_MAX_LR = 14880
531 TRAFFICGEN_STC_RFC2889_MIN_ADDRS = 1000
532 TRAFFICGEN_STC_RFC2889_MAX_ADDRS = 65536
533 TRAFFICGEN_STC_RFC2889_AC_LR = 1000
535 The first 2 values are for address-learning test where as other 3 values are
536 for the Address caching capacity test. LR: Learning Rate. AC: Address Caching.
537 Maximum value for address is 16777216. Whereas, maximum for LR is 4294967295.
539 Results for RFC2889 Tests: Forwarding tests outputs following values:
541 .. code-block:: console
543 TX_RATE_FPS : "Transmission Rate in Frames/sec"
544 THROUGHPUT_RX_FPS: "Received Throughput Frames/sec"
545 TX_RATE_MBPS : " Transmission rate in MBPS"
546 THROUGHPUT_RX_MBPS: "Received Throughput in MBPS"
547 TX_RATE_PERCENT: "Transmission Rate in Percentage"
548 FRAME_LOSS_PERCENT: "Frame loss in Percentage"
549 FORWARDING_RATE_FPS: " Maximum Forwarding Rate in FPS"
552 Whereas, the address caching test outputs following values,
554 .. code-block:: console
556 CACHING_CAPACITY_ADDRS = 'Number of address it can cache'
557 ADDR_LEARNED_PERCENT = 'Percentage of address successfully learned'
559 and address learning test outputs just a single value:
561 .. code-block:: console
563 OPTIMAL_LEARNING_RATE_FPS = 'Optimal learning rate in fps'
565 Note that 'FORWARDING_RATE_FPS', 'CACHING_CAPACITY_ADDRS',
566 'ADDR_LEARNED_PERCENT' and 'OPTIMAL_LEARNING_RATE_FPS' are the new
567 result-constants added to support RFC2889 tests.
577 Xena Networks traffic generator requires specific files and packages to be
578 installed. It is assumed the user has access to the Xena2544.exe file which
579 must be placed in VSPerf installation location under the tools/pkt_gen/xena
580 folder. Contact Xena Networks for the latest version of this file. The user
581 can also visit www.xenanetworks/downloads to obtain the file with a valid
584 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
586 To execute the Xena2544.exe file under Linux distributions the mono-complete
587 package must be installed. To install this package follow the instructions
588 below. Further information can be obtained from
589 http://www.mono-project.com/docs/getting-started/install/linux/
591 .. code-block:: console
593 rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
594 yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
595 yum -y install mono-complete-5.8.0.127-0.xamarin.3.epel7.x86_64
597 To prevent gpg errors on future yum installation of packages the mono-project
598 repo should be disabled once installed.
600 .. code-block:: console
602 yum-config-manager --disable download.mono-project.com_repo_centos_
607 Connection information for your Xena Chassis must be supplied inside the
608 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
609 set to allow for proper connections to the chassis.
611 .. code-block:: console
613 TRAFFICGEN_XENA_IP = ''
614 TRAFFICGEN_XENA_PORT1 = ''
615 TRAFFICGEN_XENA_PORT2 = ''
616 TRAFFICGEN_XENA_USER = ''
617 TRAFFICGEN_XENA_PASSWORD = ''
618 TRAFFICGEN_XENA_MODULE1 = ''
619 TRAFFICGEN_XENA_MODULE2 = ''
621 RFC2544 Throughput Testing
622 ~~~~~~~~~~~~~~~~~~~~~~~~~~
624 Xena traffic generator testing for rfc2544 throughput can be modified for
625 different behaviors if needed. The default options for the following are
626 optimized for best results.
628 .. code-block:: console
630 TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
631 TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
632 TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
633 TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
634 TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
635 TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
637 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
638 Xena documentation to understand the behavior changes in modifying these
641 Xena RFC2544 testing inside VSPerf also includes a final verification option.
642 This option allows for a faster binary search with a longer final verification
643 of the binary search result. This feature can be enabled in the configuration
644 files as well as the length of the final verification in seconds.
646 ..code-block:: python
648 TRAFFICGEN_XENA_RFC2544_VERIFY = False
649 TRAFFICGEN_XENA_RFC2544_VERIFY_DURATION = 120
651 If the final verification does not pass the test with the lossrate specified
652 it will continue the binary search from its previous point. If the smart search
653 option is enabled the search will continue by taking the current pass rate minus
654 the minimum and divided by 2. The maximum is set to the last pass rate minus the
657 For example if the settings are as follows
659 ..code-block:: python
661 TRAFFICGEN_XENA_RFC2544_BINARY_RESTART_SMART_SEARCH = True
662 TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.5'
663 TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
665 and the verification attempt was 64.5, smart search would take 64.5 - 0.5 / 2.
666 This would continue the search at 32 but still have a maximum possible value of
669 If smart is not enabled it will just resume at the last pass rate minus the
672 Continuous Traffic Testing
673 ~~~~~~~~~~~~~~~~~~~~~~~~~~
675 Xena continuous traffic by default does a 3 second learning preemption to allow
676 the DUT to receive learning packets before a continuous test is performed. If
677 a custom test case requires this learning be disabled, you can disable the option
678 or modify the length of the learning by modifying the following settings.
680 .. code-block:: console
682 TRAFFICGEN_XENA_CONT_PORT_LEARNING_ENABLED = False
683 TRAFFICGEN_XENA_CONT_PORT_LEARNING_DURATION = 3
691 MoonGen architecture overview and general installation instructions
694 https://github.com/emmericp/MoonGen
696 * Note: Today, MoonGen with VSPERF only supports 10Gbps line speeds.
698 For VSPERF use, MoonGen should be cloned from here (as opposed to the
699 previously mentioned GitHub):
701 .. code-block:: console
703 git clone https://github.com/atheurer/lua-trafficgen
705 and use the master branch:
707 .. code-block:: console
711 VSPERF uses a particular Lua script with the MoonGen project:
715 Follow MoonGen set up and execution instructions here:
717 https://github.com/atheurer/lua-trafficgen/blob/master/README.md
719 Note one will need to set up ssh login to not use passwords between the server
720 running MoonGen and the device under test (running the VSPERF test
721 infrastructure). This is because VSPERF on one server uses 'ssh' to
722 configure and run MoonGen upon the other server.
724 One can set up this ssh access by doing the following on both servers:
726 .. code-block:: console
728 ssh-keygen -b 2048 -t rsa
729 ssh-copy-id <other server>
734 Connection information for MoonGen must be supplied inside the
735 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
736 set to allow for proper connections to the host with MoonGen.
738 .. code-block:: console
740 TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
741 TRAFFICGEN_MOONGEN_USER = ""
742 TRAFFICGEN_MOONGEN_BASE_DIR = ""
743 TRAFFICGEN_MOONGEN_PORTS = ""
744 TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""
752 Trex architecture overview and general installation instructions
755 https://trex-tgn.cisco.com/trex/doc/trex_stateless.html
757 You can directly download from GitHub:
759 .. code-block:: console
761 git clone https://github.com/cisco-system-traffic-generator/trex-core
763 and use the same Trex version for both server and client API.
765 **NOTE:** The Trex API version used by VSPERF is defined by variable ``TREX_TAG``
766 in file ``src/package-list.mk``.
768 .. code-block:: console
772 or Trex latest release you can download from here:
774 .. code-block:: console
776 wget --no-cache http://trex-tgn.cisco.com/trex/release/latest
778 After download, Trex repo has to be built:
780 .. code-block:: console
782 cd trex-core/linux_dpdk
783 ./b configure (run only once)
786 Next step is to create a minimum configuration file. It can be created by script ``dpdk_setup_ports.py``.
787 The script with parameter ``-i`` will run in interactive mode and it will create file ``/etc/trex_cfg.yaml``.
789 .. code-block:: console
792 sudo ./dpdk_setup_ports.py -i
794 Or example of configuration file can be found at location below, but it must be updated manually:
796 .. code-block:: console
798 cp trex-core/scripts/cfg/simple_cfg /etc/trex_cfg.yaml
800 For additional information about configuration file see official documentation (chapter 3.1.2):
802 https://trex-tgn.cisco.com/trex/doc/trex_manual.html#_creating_minimum_configuration_file
804 After compilation and configuration it is possible to run trex server in stateless mode.
805 It is neccesary for proper connection between Trex server and VSPERF.
807 .. code-block:: console
809 cd trex-core/scripts/
812 **NOTE:** Please check your firewall settings at both DUT and T-Rex server.
813 Firewall must allow a connection from DUT (VSPERF) to the T-Rex server running
816 **NOTE:** For high speed cards it may be advantageous to start T-Rex with more transmit queues/cores.
818 .. code-block:: console
820 cd trex-cores/scripts/
823 For additional information about Trex stateless mode see Trex stateless documentation:
825 https://trex-tgn.cisco.com/trex/doc/trex_stateless.html
827 **NOTE:** One will need to set up ssh login to not use passwords between the server
828 running Trex and the device under test (running the VSPERF test
829 infrastructure). This is because VSPERF on one server uses 'ssh' to
830 configure and run Trex upon the other server.
832 One can set up this ssh access by doing the following on both servers:
834 .. code-block:: console
836 ssh-keygen -b 2048 -t rsa
837 ssh-copy-id <other server>
842 Connection information for Trex must be supplied inside the custom configuration
843 file. The following parameters must be set to allow for proper connections to the host with Trex.
844 Example of this configuration is in conf/03_traffic.conf or conf/10_custom.conf.
846 .. code-block:: console
848 TRAFFICGEN_TREX_HOST_IP_ADDR = ''
849 TRAFFICGEN_TREX_USER = ''
850 TRAFFICGEN_TREX_BASE_DIR = ''
852 TRAFFICGEN_TREX_USER has to have sudo permission and password-less access.
853 TRAFFICGEN_TREX_BASE_DIR is the place, where is stored 't-rex-64' file.
855 It is possible to specify the accuracy of RFC2544 Throughput measurement.
856 Threshold below defines maximal difference between frame rate of successful
857 (i.e. defined frameloss was reached) and unsuccessful (i.e. frameloss was
858 exceeded) iterations.
860 Default value of this parameter is defined in conf/03_traffic.conf as follows:
862 .. code-block:: console
864 TRAFFICGEN_TREX_RFC2544_TPUT_THRESHOLD = ''
866 T-Rex can have learning packets enabled. For certain tests it may be beneficial
867 to send some packets before starting test traffic to allow switch learning to take
868 place. This can be adjusted with the following configurations:
870 .. code-block:: console
872 TRAFFICGEN_TREX_LEARNING_MODE=True
873 TRAFFICGEN_TREX_LEARNING_DURATION=5
875 Latency measurements have impact on T-Rex performance. Thus vswitchperf uses a separate
876 latency stream for each direction with limited speed. This workaround is used for RFC2544
877 **Throughput** and **Continuous** traffic types. In case of **Burst** traffic type,
878 the latency statistics are measured for all frames in the burst. Collection of latency
879 statistics is driven by configuration option ``TRAFFICGEN_TREX_LATENCY_PPS`` as follows:
881 * value ``0`` - disables latency measurements
882 * non zero integer value - enables latency measurements; In case of Throughput
883 and Continuous traffic types, it specifies a speed of latency specific stream
884 in PPS. In case of burst traffic type, it enables latency measurements for all frames.
886 .. code-block:: console
888 TRAFFICGEN_TREX_LATENCY_PPS = 1000
890 SR-IOV and Multistream layer 2
891 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
892 T-Rex by default only accepts packets on the receive side if the destination mac matches the
893 MAC address specified in the /etc/trex-cfg.yaml on the server side. For SR-IOV this creates
894 challenges with modifying the MAC address in the traffic profile to correctly flow packets
895 through specified VFs. To remove this limitation enable promiscuous mode on T-Rex to allow
896 all packets regardless of the destination mac to be accepted.
898 This also creates problems when doing multistream at layer 2 since the source macs will be
899 modified. Enable Promiscuous mode when doing multistream at layer 2 testing with T-Rex.
901 .. code-block:: console
903 TRAFFICGEN_TREX_PROMISCUOUS=True
905 Card Bandwidth Options
906 ~~~~~~~~~~~~~~~~~~~~~~
908 T-Rex API will attempt to retrieve the highest possible speed from the card using internal
909 calls to port information. If you are using two separate cards then it will take the lowest
910 of the two cards as the max speed. If necessary you can try to force the API to use a
911 specific maximum speed per port. The below configurations can be adjusted to enable this.
913 .. code-block:: console
915 TRAFFICGEN_TREX_FORCE_PORT_SPEED = True
916 TRAFFICGEN_TREX_PORT_SPEED = 40000 # 40 gig
918 **Note::** Setting higher than possible speeds will result in unpredictable behavior when running
919 tests such as duration inaccuracy and/or complete test failure.
924 T-Rex can perform a verification run for a longer duration once the binary search of the
925 RFC2544 trials have completed. This duration should be at least 60 seconds. This is similar
926 to other traffic generator functionality where a more sustained time can be attempted to
927 verify longer runs from the result of the search. This can be configured with the following
930 .. code-block:: console
932 TRAFFICGEN_TREX_VERIFICATION_MODE = False
933 TRAFFICGEN_TREX_VERIFICATION_DURATION = 60
934 TRAFFICGEN_TREX_MAXIMUM_VERIFICATION_TRIALS = 10
936 The duration and maximum number of attempted verification trials can be set to change the
937 behavior of this step. If the verification step fails, it will resume the binary search
938 with new values where the maximum output will be the last attempted frame rate minus the
939 current set thresh hold.
941 Scapy frame definition
942 ~~~~~~~~~~~~~~~~~~~~~~
944 It is possible to use a SCAPY frame definition to generate various network protocols
945 by the **T-Rex** traffic generator. In case that particular network protocol layer
946 is disabled by the TRAFFIC dictionary (e.g. TRAFFIC['vlan']['enabled'] = False),
947 then disabled layer will be removed from the scapy format definition by VSPERF.
949 The scapy frame definition can refer to values defined by the TRAFFIC dictionary
950 by following keywords. These keywords are used in next examples.
952 * ``Ether_src`` - refers to ``TRAFFIC['l2']['srcmac']``
953 * ``Ether_dst`` - refers to ``TRAFFIC['l2']['dstmac']``
954 * ``IP_proto`` - refers to ``TRAFFIC['l3']['proto']``
955 * ``IP_PROTO`` - refers to upper case version of ``TRAFFIC['l3']['proto']``
956 * ``IP_src`` - refers to ``TRAFFIC['l3']['srcip']``
957 * ``IP_dst`` - refers to ``TRAFFIC['l3']['dstip']``
958 * ``IP_PROTO_sport`` - refers to ``TRAFFIC['l4']['srcport']``
959 * ``IP_PROTO_dport`` - refers to ``TRAFFIC['l4']['dstport']``
960 * ``Dot1Q_prio`` - refers to ``TRAFFIC['vlan']['priority']``
961 * ``Dot1Q_id`` - refers to ``TRAFFIC['vlan']['cfi']``
962 * ``Dot1Q_vlan`` - refers to ``TRAFFIC['vlan']['id']``
964 In following examples of SCAPY frame definition only relevant parts of TRAFFIC
965 dictionary are shown. The rest of the TRAFFIC dictionary is set to default values
966 as they are defined in ``conf/03_traffic.conf``.
968 Please check official documentation of SCAPY project for details about SCAPY frame
969 definition and supported network layers at: http://www.secdev.org/projects/scapy
971 #. Generate ICMP frames:
973 .. code-block:: console
977 '0' : 'Ether(src={Ether_src}, dst={Ether_dst})/IP(proto={IP_proto}, src={IP_src}, dst={IP_dst})/ICMP()',
978 '1' : 'Ether(src={Ether_dst}, dst={Ether_src})/IP(proto={IP_proto}, src={IP_dst}, dst={IP_src})/ICMP()',
981 #. Generate IPv6 ICMP Echo Request
983 .. code-block:: console
991 '0' : 'Ether(src={Ether_src}, dst={Ether_dst})/IPv6(src={IP_src}, dst={IP_dst})/ICMPv6EchoRequest()',
992 '1' : 'Ether(src={Ether_dst}, dst={Ether_src})/IPv6(src={IP_dst}, dst={IP_src})/ICMPv6EchoRequest()',
995 #. Generate SCTP frames:
997 Example uses default SCAPY frame definition, which can reflect ``TRAFFIC['l3']['proto']`` settings. The same
998 approach can be used to generate other protocols, e.g. TCP.
1000 .. code-block:: console