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})',
90 'latency_histogram': {
97 'genome': 'aaaaaaaddddg',
101 A detailed description of the ``TRAFFIC`` dictionary can be found at
102 :ref:`configuration-of-traffic-dictionary`.
104 The framesize parameter can be overridden from the configuration
105 files by adding the following to your custom configuration file
108 .. code-block:: console
110 TRAFFICGEN_PKT_SIZES = (64, 128,)
112 OR from the commandline:
114 .. code-block:: console
116 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y)" $TESTNAME
118 You can also modify the traffic transmission duration and the number
119 of tests run by the traffic generator by extending the example
120 commandline above to:
122 .. code-block:: console
124 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y);TRAFFICGEN_DURATION=10;" \
125 "TRAFFICGEN_RFC2544_TESTS=1" $TESTNAME
127 If you use imix, set the TRAFFICGEN_PKT_SIZES to 0.
129 .. code-block:: console
131 TRAFFICGEN_PKT_SIZES = (0,)
134 .. _trafficgen-dummy:
139 The Dummy traffic generator can be used to test VSPERF installation or
140 to demonstrate VSPERF functionality at DUT without connection
141 to a real traffic generator.
143 You could also use the Dummy generator in case, that your external
144 traffic generator is not supported by VSPERF. In such case you could
145 use VSPERF to setup your test scenario and then transmit the traffic.
146 After the transmission is completed you could specify values for all
147 collected metrics and VSPERF will use them to generate final reports.
152 To select the Dummy generator please add the following to your
153 custom configuration file ``10_custom.conf``.
155 .. code-block:: console
159 OR run ``vsperf`` with the ``--trafficgen`` argument
161 .. code-block:: console
163 $ ./vsperf --trafficgen Dummy $TESTNAME
165 Where $TESTNAME is the name of the vsperf test you would like to run.
166 This will setup the vSwitch and the VNF (if one is part of your test)
167 print the traffic configuration and prompt you to transmit traffic
168 when the setup is complete.
170 .. code-block:: console
172 Please send 'continuous' traffic with the following stream config:
173 30mS, 90mpps, multistream False
174 and the following flow config:
181 "dstip": "90.90.90.90"
183 "traffic_type": "rfc2544_continuous",
199 "dstmac": "00:00:00:00:00:00",
200 "srcmac": "00:00:00:00:00:00",
204 What was the result for 'frames tx'?
206 When your traffic generator has completed traffic transmission and provided
207 the results please input these at the VSPERF prompt. VSPERF will try
210 .. code-block:: console
212 Is '$input_value' correct?
214 Please answer with y OR n.
216 VSPERF will ask you to provide a value for every of collected metrics. The list
217 of metrics can be found at traffic-type-metrics_.
218 Finally vsperf will print out the results for your test and generate the
219 appropriate logs and report files.
221 .. _traffic-type-metrics:
223 Metrics collected for supported traffic types
224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226 Below you could find a list of metrics collected by VSPERF for each of supported
229 RFC2544 Throughput and Continuous:
243 Dummy result pre-configuration
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246 In case of a Dummy traffic generator it is possible to pre-configure the test
247 results. This is useful for creation of demo testcases, which do not require
248 a real traffic generator. Such testcase can be run by any user and it will still
249 generate all reports and result files.
251 Result values can be specified within ``TRAFFICGEN_DUMMY_RESULTS`` dictionary,
252 where every of collected metrics must be properly defined. Please check the list
253 of traffic-type-metrics_.
255 Dictionary with dummy results can be passed by CLI argument ``--test-params``
256 or specified in ``Parameters`` section of testcase definition.
258 Example of testcase execution with dummy results defined by CLI argument:
260 .. code-block:: console
262 $ ./vsperf back2back --trafficgen Dummy --test-params \
263 "TRAFFICGEN_DUMMY_RESULTS={'b2b frames':'3000','b2b frame loss %':'0.0'}"
265 Example of testcase definition with pre-configured dummy results:
267 .. code-block:: python
271 "Traffic Type": "rfc2544_back2back",
273 "biDirectional": "True",
274 "Description": "LTD.Throughput.RFC2544.BackToBackFrames",
276 'TRAFFICGEN_DUMMY_RESULTS' : {'b2b frames':'3000','b2b frame loss %':'0.0'}
280 **NOTE:** Pre-configured results for the Dummy traffic generator will be used only
281 in case, that the Dummy traffic generator is used. Otherwise the option
282 ``TRAFFICGEN_DUMMY_RESULTS`` will be ignored.
289 VSPERF can use both IxNetwork and IxExplorer TCL servers to control Ixia chassis.
290 However, usage of IxNetwork TCL server is a preferred option. The following sections
291 will describe installation and configuration of IxNetwork components used by VSPERF.
296 On the system under the test you need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
298 On the IXIA client software system you need to install IxNetwork TCL server. After its
299 installation you should configure it as follows:
301 1. Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
302 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
303 2. Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
304 the Target dialogue box make sure there is the argument "-tclport xxxx"
305 where xxxx is your port number (take note of this port number as you will
306 need it for the 10\_custom.conf file).
308 .. image:: TCLServerProperties.png
310 3. Hit Ok and start the TCL server application
315 There are several configuration options specific to the IxNetwork traffic generator
316 from IXIA. It is essential to set them correctly, before the VSPERF is executed
319 Detailed description of options follows:
321 * ``TRAFFICGEN_IXNET_MACHINE`` - IP address of server, where IxNetwork TCL Server is running
322 * ``TRAFFICGEN_IXNET_PORT`` - PORT, where IxNetwork TCL Server is accepting connections from
324 * ``TRAFFICGEN_IXNET_USER`` - username, which will be used during communication with IxNetwork
325 TCL Server and IXIA chassis
326 * ``TRAFFICGEN_IXIA_HOST`` - IP address of IXIA traffic generator chassis
327 * ``TRAFFICGEN_IXIA_CARD`` - identification of card with dedicated ports at IXIA chassis
328 * ``TRAFFICGEN_IXIA_PORT1`` - identification of the first dedicated port at ``TRAFFICGEN_IXIA_CARD``
329 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
330 unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
331 at DUT, i.e. to the first PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
332 be able to pass through the vSwitch.
333 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
334 same value, then VSPERF will assume, that there is only one port connection between IXIA
335 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
336 first NIC from ``WHITELIST_NICS`` list.
337 * ``TRAFFICGEN_IXIA_PORT2`` - identification of the second dedicated port at ``TRAFFICGEN_IXIA_CARD``
338 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
339 unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
340 at DUT, i.e. to the second PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
341 be able to pass through the vSwitch.
342 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
343 same value, then VSPERF will assume, that there is only one port connection between IXIA
344 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
345 first NIC from ``WHITELIST_NICS`` list.
346 * ``TRAFFICGEN_IXNET_LIB_PATH`` - path to the DUT specific installation of IxNetwork TCL API
347 * ``TRAFFICGEN_IXNET_TCL_SCRIPT`` - name of the TCL script, which VSPERF will use for
348 communication with IXIA TCL server
349 * ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` - folder accessible from IxNetwork TCL server,
350 where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
351 * ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` - directory accessible from the DUT, where test
352 results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
355 .. _test-results-share:
360 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
361 results are stored at IxNetwork TCL server. Results are stored at folder defined by
362 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
363 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
364 VSPERF is executed. VSPERF expects, that test results will be available at directory
365 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
367 Example of sharing configuration:
369 * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
370 * Modify sharing options of ``ixia_results`` folder to share it with everybody
371 * Create a new directory at DUT, where shared directory with results
372 will be mounted, e.g. ``/mnt/ixia_results``
373 * Update your custom VSPERF configuration file as follows:
375 .. code-block:: python
377 TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
378 TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
380 **NOTE:** It is essential to use slashes '/' also in path
381 configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
382 * Install cifs-utils package.
384 e.g. at rpm based Linux distribution:
386 .. code-block:: console
388 yum install cifs-utils
390 * Mount shared directory, so VSPERF can access test results.
392 e.g. by adding new record into ``/etc/fstab``
394 .. code-block:: console
396 mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
397 -o file_mode=0777,dir_mode=0777,nounix
399 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
400 is visible at DUT inside ``/mnt/ixia_results`` directory.
402 .. _`Spirent TestCenter`:
407 Spirent installation files and instructions are available on the
408 Spirent support website at:
410 https://support.spirent.com
412 Select a version of Spirent TestCenter software to utilize. This example
413 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
414 version in place of 'v4.57' in the examples, below.
416 On the CentOS 7 System
417 ~~~~~~~~~~~~~~~~~~~~~~
419 Download and install the following:
421 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
423 Spirent Virtual Deployment Service (VDS)
424 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
426 Spirent VDS is required for both TestCenter hardware and virtual
427 chassis in the vsperf environment. For installation, select the version
428 that matches the Spirent TestCenter Application version. For v4.57,
429 the matching VDS version is 1.0.55. Download either the ova (VMware)
430 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
431 according to Spirent installation instructions.
433 Using Spirent TestCenter Virtual (STCv)
434 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
436 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
439 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
441 Virtual test port performance is affected by the hypervisor configuration. For
442 best practice results in deploying STCv, the following is suggested:
444 - Create a single VM with two test ports rather than two VMs with one port each
445 - Set STCv in DPDK mode
446 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
447 - Turning off hyperthreading and pinning these cores will improve performance
448 - Give STCv 2 GB of RAM
450 To get the highest performance and accuracy, Spirent TestCenter hardware is
451 recommended. vsperf can run with either stype test ports.
453 Using STC REST Client
454 ~~~~~~~~~~~~~~~~~~~~~
455 The stcrestclient package provides the stchttp.py ReST API wrapper module.
456 This allows simple function calls, nearly identical to those provided by
457 StcPython.py, to be used to access TestCenter server sessions via the
458 STC ReST API. Basic ReST functionality is provided by the resthttp module,
459 and may be used for writing ReST clients independent of STC.
461 - Project page: <https://github.com/Spirent/py-stcrestclient>
462 - Package download: <https://pypi.python.org/project/stcrestclient>
464 To use REST interface, follow the instructions in the Project page to
465 install the package. Once installed, the scripts named with 'rest' keyword
466 can be used. For example: testcenter-rfc2544-rest.py can be used to run
467 RFC 2544 tests using the REST interface.
472 1. The Labserver and license server addresses. These parameters applies to
473 all the tests, and are mandatory for all tests.
475 .. code-block:: console
477 TRAFFICGEN_STC_LAB_SERVER_ADDR = " "
478 TRAFFICGEN_STC_LICENSE_SERVER_ADDR = " "
479 TRAFFICGEN_STC_PYTHON2_PATH = " "
480 TRAFFICGEN_STC_TESTCENTER_PATH = " "
481 TRAFFICGEN_STC_TEST_SESSION_NAME = " "
482 TRAFFICGEN_STC_CSV_RESULTS_FILE_PREFIX = " "
484 2. For RFC2544 tests, the following parameters are mandatory
486 .. code-block:: console
488 TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
489 TRAFFICGEN_STC_EAST_SLOT_NUM = " "
490 TRAFFICGEN_STC_EAST_PORT_NUM = " "
491 TRAFFICGEN_STC_EAST_INTF_ADDR = " "
492 TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
493 TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
494 TRAFFICGEN_STC_WEST_SLOT_NUM = " "
495 TRAFFICGEN_STC_WEST_PORT_NUM = " "
496 TRAFFICGEN_STC_WEST_INTF_ADDR = " "
497 TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
498 TRAFFICGEN_STC_RFC2544_TPUT_TEST_FILE_NAME
500 3. RFC2889 tests: Currently, the forwarding, address-caching, and
501 address-learning-rate tests of RFC2889 are supported.
502 The testcenter-rfc2889-rest.py script implements the rfc2889 tests.
503 The configuration for RFC2889 involves test-case definition, and parameter
504 definition, as described below. New results-constants, as shown below, are
505 added to support these tests.
507 Example of testcase definition for RFC2889 tests:
509 .. code-block:: python
512 "Name": "phy2phy_forwarding",
514 "Description": "LTD.Forwarding.RFC2889.MaxForwardingRate",
517 "traffic_type" : "rfc2889_forwarding",
522 For RFC2889 tests, specifying the locations for the monitoring ports is mandatory.
523 Necessary parameters are:
525 .. code-block:: console
527 TRAFFICGEN_STC_RFC2889_TEST_FILE_NAME
528 TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
529 TRAFFICGEN_STC_EAST_SLOT_NUM = " "
530 TRAFFICGEN_STC_EAST_PORT_NUM = " "
531 TRAFFICGEN_STC_EAST_INTF_ADDR = " "
532 TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
533 TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
534 TRAFFICGEN_STC_WEST_SLOT_NUM = " "
535 TRAFFICGEN_STC_WEST_PORT_NUM = " "
536 TRAFFICGEN_STC_WEST_INTF_ADDR = " "
537 TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
538 TRAFFICGEN_STC_VERBOSE = "True"
539 TRAFFICGEN_STC_RFC2889_LOCATIONS="//10.1.1.1/1/1,//10.1.1.1/2/2"
541 Other Configurations are :
543 .. code-block:: console
545 TRAFFICGEN_STC_RFC2889_MIN_LR = 1488
546 TRAFFICGEN_STC_RFC2889_MAX_LR = 14880
547 TRAFFICGEN_STC_RFC2889_MIN_ADDRS = 1000
548 TRAFFICGEN_STC_RFC2889_MAX_ADDRS = 65536
549 TRAFFICGEN_STC_RFC2889_AC_LR = 1000
551 The first 2 values are for address-learning test where as other 3 values are
552 for the Address caching capacity test. LR: Learning Rate. AC: Address Caching.
553 Maximum value for address is 16777216. Whereas, maximum for LR is 4294967295.
555 Results for RFC2889 Tests: Forwarding tests outputs following values:
557 .. code-block:: console
559 TX_RATE_FPS : "Transmission Rate in Frames/sec"
560 THROUGHPUT_RX_FPS: "Received Throughput Frames/sec"
561 TX_RATE_MBPS : " Transmission rate in MBPS"
562 THROUGHPUT_RX_MBPS: "Received Throughput in MBPS"
563 TX_RATE_PERCENT: "Transmission Rate in Percentage"
564 FRAME_LOSS_PERCENT: "Frame loss in Percentage"
565 FORWARDING_RATE_FPS: " Maximum Forwarding Rate in FPS"
568 Whereas, the address caching test outputs following values,
570 .. code-block:: console
572 CACHING_CAPACITY_ADDRS = 'Number of address it can cache'
573 ADDR_LEARNED_PERCENT = 'Percentage of address successfully learned'
575 and address learning test outputs just a single value:
577 .. code-block:: console
579 OPTIMAL_LEARNING_RATE_FPS = 'Optimal learning rate in fps'
581 Note that 'FORWARDING_RATE_FPS', 'CACHING_CAPACITY_ADDRS',
582 'ADDR_LEARNED_PERCENT' and 'OPTIMAL_LEARNING_RATE_FPS' are the new
583 result-constants added to support RFC2889 tests.
585 4. Latency Histogram. To enable latency histogram as in results,
586 enable latency_histogram in conf/03_traffic.conf.
588 .. code-block:: python
596 Once, enabled, a 'Histogram.csv' file will be generated in the results folder.
597 The Histogram.csv will include latency histogram in the following order.
598 (a) Packet size (b) Ranges in 10ns (c) Packet counts. These set of 3 lines,
599 will be repeated for every packet-sizes.
609 Xena Networks traffic generator requires specific files and packages to be
610 installed. It is assumed the user has access to the Xena2544.exe file which
611 must be placed in VSPerf installation location under the tools/pkt_gen/xena
612 folder. Contact Xena Networks for the latest version of this file. The user
613 can also visit www.xenanetworks/downloads to obtain the file with a valid
616 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
618 To execute the Xena2544.exe file under Linux distributions the mono-complete
619 package must be installed. To install this package follow the instructions
620 below. Further information can be obtained from
621 https://www.mono-project.com/docs/getting-started/install/linux/
623 .. code-block:: console
625 rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
626 yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
627 yum -y install mono-complete-5.8.0.127-0.xamarin.3.epel7.x86_64
629 To prevent gpg errors on future yum installation of packages the mono-project
630 repo should be disabled once installed.
632 .. code-block:: console
634 yum-config-manager --disable download.mono-project.com_repo_centos_
639 Connection information for your Xena Chassis must be supplied inside the
640 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
641 set to allow for proper connections to the chassis.
643 .. code-block:: console
645 TRAFFICGEN_XENA_IP = ''
646 TRAFFICGEN_XENA_PORT1 = ''
647 TRAFFICGEN_XENA_PORT2 = ''
648 TRAFFICGEN_XENA_USER = ''
649 TRAFFICGEN_XENA_PASSWORD = ''
650 TRAFFICGEN_XENA_MODULE1 = ''
651 TRAFFICGEN_XENA_MODULE2 = ''
653 RFC2544 Throughput Testing
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~
656 Xena traffic generator testing for rfc2544 throughput can be modified for
657 different behaviors if needed. The default options for the following are
658 optimized for best results.
660 .. code-block:: console
662 TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
663 TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
664 TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
665 TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
666 TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
667 TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
669 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
670 Xena documentation to understand the behavior changes in modifying these
673 Xena RFC2544 testing inside VSPerf also includes a final verification option.
674 This option allows for a faster binary search with a longer final verification
675 of the binary search result. This feature can be enabled in the configuration
676 files as well as the length of the final verification in seconds.
678 ..code-block:: python
680 TRAFFICGEN_XENA_RFC2544_VERIFY = False
681 TRAFFICGEN_XENA_RFC2544_VERIFY_DURATION = 120
683 If the final verification does not pass the test with the lossrate specified
684 it will continue the binary search from its previous point. If the smart search
685 option is enabled the search will continue by taking the current pass rate minus
686 the minimum and divided by 2. The maximum is set to the last pass rate minus the
689 For example if the settings are as follows
691 ..code-block:: python
693 TRAFFICGEN_XENA_RFC2544_BINARY_RESTART_SMART_SEARCH = True
694 TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.5'
695 TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
697 and the verification attempt was 64.5, smart search would take 64.5 - 0.5 / 2.
698 This would continue the search at 32 but still have a maximum possible value of
701 If smart is not enabled it will just resume at the last pass rate minus the
704 Continuous Traffic Testing
705 ~~~~~~~~~~~~~~~~~~~~~~~~~~
707 Xena continuous traffic by default does a 3 second learning preemption to allow
708 the DUT to receive learning packets before a continuous test is performed. If
709 a custom test case requires this learning be disabled, you can disable the option
710 or modify the length of the learning by modifying the following settings.
712 .. code-block:: console
714 TRAFFICGEN_XENA_CONT_PORT_LEARNING_ENABLED = False
715 TRAFFICGEN_XENA_CONT_PORT_LEARNING_DURATION = 3
720 Xena has a modifier maximum value or 64k in size. For this reason when specifying
721 Multistream values of greater than 64k for Layer 2 or Layer 3 it will use two
722 modifiers that may be modified to a value that can be square rooted to create the
723 two modifiers. You will see a log notification for the new value that was calculated.
731 MoonGen architecture overview and general installation instructions
734 https://github.com/emmericp/MoonGen
736 * Note: Today, MoonGen with VSPERF only supports 10Gbps line speeds.
738 For VSPERF use, MoonGen should be cloned from here (as opposed to the
739 previously mentioned GitHub):
741 .. code-block:: console
743 git clone https://github.com/atheurer/lua-trafficgen
745 and use the master branch:
747 .. code-block:: console
751 VSPERF uses a particular Lua script with the MoonGen project:
755 Follow MoonGen set up and execution instructions here:
757 https://github.com/atheurer/trafficgen/blob/master/README.md
759 Note one will need to set up ssh login to not use passwords between the server
760 running MoonGen and the device under test (running the VSPERF test
761 infrastructure). This is because VSPERF on one server uses 'ssh' to
762 configure and run MoonGen upon the other server.
764 One can set up this ssh access by doing the following on both servers:
766 .. code-block:: console
768 ssh-keygen -b 2048 -t rsa
769 ssh-copy-id <other server>
774 Connection information for MoonGen must be supplied inside the
775 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
776 set to allow for proper connections to the host with MoonGen.
778 .. code-block:: console
780 TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
781 TRAFFICGEN_MOONGEN_USER = ""
782 TRAFFICGEN_MOONGEN_BASE_DIR = ""
783 TRAFFICGEN_MOONGEN_PORTS = ""
784 TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""
792 Trex architecture overview and general installation instructions
795 https://trex-tgn.cisco.com/trex/doc/trex_stateless.html
797 You can directly download from GitHub:
799 .. code-block:: console
801 git clone https://github.com/cisco-system-traffic-generator/trex-core
803 and use the same Trex version for both server and client API.
805 **NOTE:** The Trex API version used by VSPERF is defined by variable ``TREX_TAG``
806 in file ``src/package-list.mk``.
808 .. code-block:: console
812 or Trex latest release you can download from here:
814 .. code-block:: console
816 wget --no-cache http://trex-tgn.cisco.com/trex/release/latest
818 After download, Trex repo has to be built:
820 .. code-block:: console
822 cd trex-core/linux_dpdk
823 ./b configure (run only once)
826 Next step is to create a minimum configuration file. It can be created by script ``dpdk_setup_ports.py``.
827 The script with parameter ``-i`` will run in interactive mode and it will create file ``/etc/trex_cfg.yaml``.
829 .. code-block:: console
832 sudo ./dpdk_setup_ports.py -i
834 Or example of configuration file can be found at location below, but it must be updated manually:
836 .. code-block:: console
838 cp trex-core/scripts/cfg/simple_cfg /etc/trex_cfg.yaml
840 For additional information about configuration file see official documentation (chapter 3.1.2):
842 https://trex-tgn.cisco.com/trex/doc/trex_manual.html#_creating_minimum_configuration_file
844 After compilation and configuration it is possible to run trex server in stateless mode.
845 It is neccesary for proper connection between Trex server and VSPERF.
847 .. code-block:: console
849 cd trex-core/scripts/
852 **NOTE:** Please check your firewall settings at both DUT and T-Rex server.
853 Firewall must allow a connection from DUT (VSPERF) to the T-Rex server running
856 **NOTE:** For high speed cards it may be advantageous to start T-Rex with more transmit queues/cores.
858 .. code-block:: console
860 cd trex-cores/scripts/
863 For additional information about Trex stateless mode see Trex stateless documentation:
865 https://trex-tgn.cisco.com/trex/doc/trex_stateless.html
867 **NOTE:** One will need to set up ssh login to not use passwords between the server
868 running Trex and the device under test (running the VSPERF test
869 infrastructure). This is because VSPERF on one server uses 'ssh' to
870 configure and run Trex upon the other server.
872 One can set up this ssh access by doing the following on both servers:
874 .. code-block:: console
876 ssh-keygen -b 2048 -t rsa
877 ssh-copy-id <other server>
882 Connection information for Trex must be supplied inside the custom configuration
883 file. The following parameters must be set to allow for proper connections to the host with Trex.
884 Example of this configuration is in conf/03_traffic.conf or conf/10_custom.conf.
886 .. code-block:: console
888 TRAFFICGEN_TREX_HOST_IP_ADDR = ''
889 TRAFFICGEN_TREX_USER = ''
890 TRAFFICGEN_TREX_BASE_DIR = ''
892 TRAFFICGEN_TREX_USER has to have sudo permission and password-less access.
893 TRAFFICGEN_TREX_BASE_DIR is the place, where is stored 't-rex-64' file.
895 It is possible to specify the accuracy of RFC2544 Throughput measurement.
896 Threshold below defines maximal difference between frame rate of successful
897 (i.e. defined frameloss was reached) and unsuccessful (i.e. frameloss was
898 exceeded) iterations.
900 Default value of this parameter is defined in conf/03_traffic.conf as follows:
902 .. code-block:: console
904 TRAFFICGEN_TREX_RFC2544_TPUT_THRESHOLD = ''
906 T-Rex can have learning packets enabled. For certain tests it may be beneficial
907 to send some packets before starting test traffic to allow switch learning to take
908 place. This can be adjusted with the following configurations:
910 .. code-block:: console
912 TRAFFICGEN_TREX_LEARNING_MODE=True
913 TRAFFICGEN_TREX_LEARNING_DURATION=5
915 Latency measurements have impact on T-Rex performance. Thus vswitchperf uses a separate
916 latency stream for each direction with limited speed. This workaround is used for RFC2544
917 **Throughput** and **Continuous** traffic types. In case of **Burst** traffic type,
918 the latency statistics are measured for all frames in the burst. Collection of latency
919 statistics is driven by configuration option ``TRAFFICGEN_TREX_LATENCY_PPS`` as follows:
921 * value ``0`` - disables latency measurements
922 * non zero integer value - enables latency measurements; In case of Throughput
923 and Continuous traffic types, it specifies a speed of latency specific stream
924 in PPS. In case of burst traffic type, it enables latency measurements for all frames.
926 .. code-block:: console
928 TRAFFICGEN_TREX_LATENCY_PPS = 1000
930 SR-IOV and Multistream layer 2
931 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
932 T-Rex by default only accepts packets on the receive side if the destination mac matches the
933 MAC address specified in the /etc/trex-cfg.yaml on the server side. For SR-IOV this creates
934 challenges with modifying the MAC address in the traffic profile to correctly flow packets
935 through specified VFs. To remove this limitation enable promiscuous mode on T-Rex to allow
936 all packets regardless of the destination mac to be accepted.
938 This also creates problems when doing multistream at layer 2 since the source macs will be
939 modified. Enable Promiscuous mode when doing multistream at layer 2 testing with T-Rex.
941 .. code-block:: console
943 TRAFFICGEN_TREX_PROMISCUOUS=True
945 Card Bandwidth Options
946 ~~~~~~~~~~~~~~~~~~~~~~
948 T-Rex API will attempt to retrieve the highest possible speed from the card using internal
949 calls to port information. If you are using two separate cards then it will take the lowest
950 of the two cards as the max speed. If necessary you can try to force the API to use a
951 specific maximum speed per port. The below configurations can be adjusted to enable this.
953 .. code-block:: console
955 TRAFFICGEN_TREX_FORCE_PORT_SPEED = True
956 TRAFFICGEN_TREX_PORT_SPEED = 40000 # 40 gig
958 **Note::** Setting higher than possible speeds will result in unpredictable behavior when running
959 tests such as duration inaccuracy and/or complete test failure.
964 T-Rex can perform a verification run for a longer duration once the binary search of the
965 RFC2544 trials have completed. This duration should be at least 60 seconds. This is similar
966 to other traffic generator functionality where a more sustained time can be attempted to
967 verify longer runs from the result of the search. This can be configured with the following
970 .. code-block:: console
972 TRAFFICGEN_TREX_VERIFICATION_MODE = False
973 TRAFFICGEN_TREX_VERIFICATION_DURATION = 60
974 TRAFFICGEN_TREX_MAXIMUM_VERIFICATION_TRIALS = 10
976 The duration and maximum number of attempted verification trials can be set to change the
977 behavior of this step. If the verification step fails, it will resume the binary search
978 with new values where the maximum output will be the last attempted frame rate minus the
979 current set thresh hold.
981 Scapy frame definition
982 ~~~~~~~~~~~~~~~~~~~~~~
984 It is possible to use a SCAPY frame definition to generate various network protocols
985 by the **T-Rex** traffic generator. In case that particular network protocol layer
986 is disabled by the TRAFFIC dictionary (e.g. TRAFFIC['vlan']['enabled'] = False),
987 then disabled layer will be removed from the scapy format definition by VSPERF.
989 The scapy frame definition can refer to values defined by the TRAFFIC dictionary
990 by following keywords. These keywords are used in next examples.
992 * ``Ether_src`` - refers to ``TRAFFIC['l2']['srcmac']``
993 * ``Ether_dst`` - refers to ``TRAFFIC['l2']['dstmac']``
994 * ``IP_proto`` - refers to ``TRAFFIC['l3']['proto']``
995 * ``IP_PROTO`` - refers to upper case version of ``TRAFFIC['l3']['proto']``
996 * ``IP_src`` - refers to ``TRAFFIC['l3']['srcip']``
997 * ``IP_dst`` - refers to ``TRAFFIC['l3']['dstip']``
998 * ``IP_PROTO_sport`` - refers to ``TRAFFIC['l4']['srcport']``
999 * ``IP_PROTO_dport`` - refers to ``TRAFFIC['l4']['dstport']``
1000 * ``Dot1Q_prio`` - refers to ``TRAFFIC['vlan']['priority']``
1001 * ``Dot1Q_id`` - refers to ``TRAFFIC['vlan']['cfi']``
1002 * ``Dot1Q_vlan`` - refers to ``TRAFFIC['vlan']['id']``
1004 In following examples of SCAPY frame definition only relevant parts of TRAFFIC
1005 dictionary are shown. The rest of the TRAFFIC dictionary is set to default values
1006 as they are defined in ``conf/03_traffic.conf``.
1008 Please check official documentation of SCAPY project for details about SCAPY frame
1009 definition and supported network layers at: https://scapy.net
1011 #. Generate ICMP frames:
1013 .. code-block:: console
1017 '0' : 'Ether(src={Ether_src}, dst={Ether_dst})/IP(proto="icmp", src={IP_src}, dst={IP_dst})/ICMP()',
1018 '1' : 'Ether(src={Ether_dst}, dst={Ether_src})/IP(proto="icmp", src={IP_dst}, dst={IP_src})/ICMP()',
1021 #. Generate IPv6 ICMP Echo Request
1023 .. code-block:: console
1026 'srcip': 'feed::01',
1027 'dstip': 'feed::02',
1031 '0' : 'Ether(src={Ether_src}, dst={Ether_dst})/IPv6(src={IP_src}, dst={IP_dst})/ICMPv6EchoRequest()',
1032 '1' : 'Ether(src={Ether_dst}, dst={Ether_src})/IPv6(src={IP_dst}, dst={IP_src})/ICMPv6EchoRequest()',
1035 #. Generate TCP frames:
1037 Example uses default SCAPY frame definition, which can reflect ``TRAFFIC['l3']['proto']`` settings.
1039 .. code-block:: console