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`_
22 To see the list of traffic gens from the cli:
24 .. code-block:: console
26 $ ./vsperf --list-trafficgens
28 This guide provides the details of how to install
29 and configure the various traffic generators.
31 Background Information
32 ----------------------
33 The traffic default configuration can be found in **conf/03_traffic.conf**,
34 and is configured as follows:
36 .. code-block:: console
39 'traffic_type' : 'rfc2544_throughput',
41 'bidir' : 'True', # will be passed as string in title format to tgen
44 'pre_installed_flows' : 'No', # used by vswitch implementation
45 'flow_type' : 'port', # used by vswitch implementation
49 'srcmac': '00:00:00:00:00:00',
50 'dstmac': '00:00:00:00:00:00',
56 'dstip': '90.90.90.90',
71 The framesize parameter can be overridden from the configuration
72 files by adding the following to your custom configuration file
75 .. code-block:: console
77 TRAFFICGEN_PKT_SIZES = (64, 128,)
79 OR from the commandline:
81 .. code-block:: console
83 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y)" $TESTNAME
85 You can also modify the traffic transmission duration and the number
86 of tests run by the traffic generator by extending the example
89 .. code-block:: console
91 $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y);TRAFFICGEN_DURATION=10;" \
92 "TRAFFICGEN_RFC2544_TESTS=1" $TESTNAME
99 The Dummy traffic generator can be used to test VSPERF installation or
100 to demonstrate VSPERF functionality at DUT without connection
101 to a real traffic generator.
103 You could also use the Dummy generator in case, that your external
104 traffic generator is not supported by VSPERF. In such case you could
105 use VSPERF to setup your test scenario and then transmit the traffic.
106 After the transmission is completed you could specify values for all
107 collected metrics and VSPERF will use them to generate final reports.
112 To select the Dummy generator please add the following to your
113 custom configuration file ``10_custom.conf``.
115 .. code-block:: console
119 OR run ``vsperf`` with the ``--trafficgen`` argument
121 .. code-block:: console
123 $ ./vsperf --trafficgen Dummy $TESTNAME
125 Where $TESTNAME is the name of the vsperf test you would like to run.
126 This will setup the vSwitch and the VNF (if one is part of your test)
127 print the traffic configuration and prompt you to transmit traffic
128 when the setup is complete.
130 .. code-block:: console
132 Please send 'continuous' traffic with the following stream config:
133 30mS, 90mpps, multistream False
134 and the following flow config:
141 "dstip": "90.90.90.90"
143 "traffic_type": "rfc2544_continuous",
159 "dstmac": "00:00:00:00:00:00",
160 "srcmac": "00:00:00:00:00:00",
164 What was the result for 'frames tx'?
166 When your traffic generator has completed traffic transmission and provided
167 the results please input these at the VSPERF prompt. VSPERF will try
170 .. code-block:: console
172 Is '$input_value' correct?
174 Please answer with y OR n.
176 VSPERF will ask you to provide a value for every of collected metrics. The list
177 of metrics can be found at traffic-type-metrics_.
178 Finally vsperf will print out the results for your test and generate the
179 appropriate logs and report files.
181 .. _traffic-type-metrics:
183 Metrics collected for supported traffic types
184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186 Below you could find a list of metrics collected by VSPERF for each of supported
189 RFC2544 Throughput and Continuous:
203 Dummy result pre-configuration
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206 In case of a Dummy traffic generator it is possible to pre-configure the test
207 results. This is useful for creation of demo testcases, which do not require
208 a real traffic generator. Such testcase can be run by any user and it will still
209 generate all reports and result files.
211 Result values can be specified within ``TRAFFICGEN_DUMMY_RESULTS`` dictionary,
212 where every of collected metrics must be properly defined. Please check the list
213 of traffic-type-metrics_.
215 Dictionary with dummy results can be passed by CLI argument ``--test-params``
216 or specified in ``Parameters`` section of testcase definition.
218 Example of testcase execution with dummy results defined by CLI argument:
220 .. code-block:: console
222 $ ./vsperf back2back --trafficgen Dummy --test-params \
223 "TRAFFICGEN_DUMMY_RESULTS={'b2b frames':'3000','b2b frame loss %':'0.0'}"
225 Example of testcase definition with pre-configured dummy results:
227 .. code-block:: python
231 "Traffic Type": "rfc2544_back2back",
233 "biDirectional": "True",
234 "Description": "LTD.Throughput.RFC2544.BackToBackFrames",
236 'TRAFFICGEN_DUMMY_RESULTS' : {'b2b frames':'3000','b2b frame loss %':'0.0'}
240 **NOTE:** Pre-configured results for the Dummy traffic generator will be used only
241 in case, that the Dummy traffic generator is used. Otherwise the option
242 ``TRAFFICGEN_DUMMY_RESULTS`` will be ignored.
249 VSPERF can use both IxNetwork and IxExplorer TCL servers to control Ixia chassis.
250 However usage of IxNetwork TCL server is a preferred option. Following sections
251 will describe installation and configuration of IxNetwork components used by VSPERF.
256 On the system under the test you need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
258 On the IXIA client software system you need to install IxNetwork TCL server. After its
259 installation you should configure it as follows:
261 1. Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
262 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
263 2. Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
264 the Target dialogue box make sure there is the argument "-tclport xxxx"
265 where xxxx is your port number (take note of this port number as you will
266 need it for the 10\_custom.conf file).
268 .. image:: TCLServerProperties.png
270 3. Hit Ok and start the TCL server application
275 There are several configuration options specific to the IxNetwork traffic generator
276 from IXIA. It is essential to set them correctly, before the VSPERF is executed
279 Detailed description of options follows:
281 * ``TRAFFICGEN_IXNET_MACHINE`` - IP address of server, where IxNetwork TCL Server is running
282 * ``TRAFFICGEN_IXNET_PORT`` - PORT, where IxNetwork TCL Server is accepting connections from
284 * ``TRAFFICGEN_IXNET_USER`` - username, which will be used during communication with IxNetwork
285 TCL Server and IXIA chassis
286 * ``TRAFFICGEN_IXIA_HOST`` - IP address of IXIA traffic generator chassis
287 * ``TRAFFICGEN_IXIA_CARD`` - identification of card with dedicated ports at IXIA chassis
288 * ``TRAFFICGEN_IXIA_PORT1`` - identification of the first dedicated port at ``TRAFFICGEN_IXIA_CARD``
289 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
290 unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
291 at DUT, i.e. to the first PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
292 be able to pass through the vSwitch.
293 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
294 same value, then VSPERF will assume, that there is only one port connection between IXIA
295 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
296 first NIC from ``WHITELIST_NICS`` list.
297 * ``TRAFFICGEN_IXIA_PORT2`` - identification of the second dedicated port at ``TRAFFICGEN_IXIA_CARD``
298 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
299 unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
300 at DUT, i.e. to the second PCI handle from ``WHITELIST_NICS`` list. Otherwise traffic may not
301 be able to pass through the vSwitch.
302 **NOTE**: In case that ``TRAFFICGEN_IXIA_PORT1`` and ``TRAFFICGEN_IXIA_PORT2`` are set to the
303 same value, then VSPERF will assume, that there is only one port connection between IXIA
304 and DUT. In this case it must be ensured, that chosen IXIA port is physically connected to the
305 first NIC from ``WHITELIST_NICS`` list.
306 * ``TRAFFICGEN_IXNET_LIB_PATH`` - path to the DUT specific installation of IxNetwork TCL API
307 * ``TRAFFICGEN_IXNET_TCL_SCRIPT`` - name of the TCL script, which VSPERF will use for
308 communication with IXIA TCL server
309 * ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` - folder accessible from IxNetwork TCL server,
310 where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
311 * ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` - directory accessible from the DUT, where test
312 results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
315 .. _test-results-share:
320 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
321 results are stored at IxNetwork TCL server. Results are stored at folder defined by
322 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
323 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
324 VSPERF is executed. VSPERF expects, that test results will be available at directory
325 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
327 Example of sharing configuration:
329 * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
330 * Modify sharing options of ``ixia_results`` folder to share it with everybody
331 * Create a new directory at DUT, where shared directory with results
332 will be mounted, e.g. ``/mnt/ixia_results``
333 * Update your custom VSPERF configuration file as follows:
335 .. code-block:: python
337 TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
338 TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
340 **NOTE:** It is essential to use slashes '/' also in path
341 configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
342 * Install cifs-utils package.
344 e.g. at rpm based Linux distribution:
346 .. code-block:: console
348 yum install cifs-utils
350 * Mount shared directory, so VSPERF can access test results.
352 e.g. by adding new record into ``/etc/fstab``
354 .. code-block:: console
356 mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
357 -o file_mode=0777,dir_mode=0777,nounix
359 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
360 is visible at DUT inside ``/mnt/ixia_results`` directory.
362 .. _`Spirent TestCenter`:
367 Spirent installation files and instructions are available on the
368 Spirent support website at:
370 http://support.spirent.com
372 Select a version of Spirent TestCenter software to utilize. This example
373 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
374 version in place of 'v4.57' in the examples, below.
376 On the CentOS 7 System
377 ~~~~~~~~~~~~~~~~~~~~~~
379 Download and install the following:
381 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
383 Spirent Virtual Deployment Service (VDS)
384 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
386 Spirent VDS is required for both TestCenter hardware and virtual
387 chassis in the vsperf environment. For installation, select the version
388 that matches the Spirent TestCenter Application version. For v4.57,
389 the matching VDS version is 1.0.55. Download either the ova (VMware)
390 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
391 according to Spirent installation instructions.
393 Using Spirent TestCenter Virtual (STCv)
394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
396 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
399 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
401 Virtual test port performance is affected by the hypervisor configuration. For
402 best practice results in deploying STCv, the following is suggested:
404 - Create a single VM with two test ports rather than two VMs with one port each
405 - Set STCv in DPDK mode
406 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
407 - Turning off hyperthreading and pinning these cores will improve performance
408 - Give STCv 2 GB of RAM
410 To get the highest performance and accuracy, Spirent TestCenter hardware is
411 recommended. vsperf can run with either stype test ports.
413 Using STC REST Client
414 ~~~~~~~~~~~~~~~~~~~~~
415 The stcrestclient package provides the stchttp.py ReST API wrapper module.
416 This allows simple function calls, nearly identical to those provided by
417 StcPython.py, to be used to access TestCenter server sessions via the
418 STC ReST API. Basic ReST functionality is provided by the resthttp module,
419 and may be used for writing ReST clients independent of STC.
421 - Project page: <https://github.com/Spirent/py-stcrestclient>
422 - Package download: <http://pypi.python.org/pypi/stcrestclient>
424 To use REST interface, follow the instructions in the Project page to
425 install the package. Once installed, the scripts named with 'rest' keyword
426 can be used. For example: testcenter-rfc2544-rest.py can be used to run
427 RFC 2544 tests using the REST interface.
432 1. The Labserver and license server addresses. These parameters applies to
433 all the tests, and are mandatory for all tests.
435 .. code-block:: console
437 TRAFFICGEN_STC_LAB_SERVER_ADDR = " "
438 TRAFFICGEN_STC_LICENSE_SERVER_ADDR = " "
439 TRAFFICGEN_STC_PYTHON2_PATH = " "
440 TRAFFICGEN_STC_TESTCENTER_PATH = " "
441 TRAFFICGEN_STC_TEST_SESSION_NAME = " "
442 TRAFFICGEN_STC_CSV_RESULTS_FILE_PREFIX = " "
444 2. For RFC2544 tests, the following parameters are mandatory
446 .. code-block:: console
448 TRAFFICGEN_STC_EAST_CHASSIS_ADDR = " "
449 TRAFFICGEN_STC_EAST_SLOT_NUM = " "
450 TRAFFICGEN_STC_EAST_PORT_NUM = " "
451 TRAFFICGEN_STC_EAST_INTF_ADDR = " "
452 TRAFFICGEN_STC_EAST_INTF_GATEWAY_ADDR = " "
453 TRAFFICGEN_STC_WEST_CHASSIS_ADDR = ""
454 TRAFFICGEN_STC_WEST_SLOT_NUM = " "
455 TRAFFICGEN_STC_WEST_PORT_NUM = " "
456 TRAFFICGEN_STC_WEST_INTF_ADDR = " "
457 TRAFFICGEN_STC_WEST_INTF_GATEWAY_ADDR = " "
458 TRAFFICGEN_STC_RFC2544_TPUT_TEST_FILE_NAME
460 3. RFC2889 tests: Currently, the forwarding, address-caching, and
461 address-learning-rate tests of RFC2889 are supported.
462 The testcenter-rfc2889-rest.py script implements the rfc2889 tests.
463 The configuration for RFC2889 involves test-case definition, and parameter
464 definition, as described below. New results-constants, as shown below, are
465 added to support these tests.
467 Example of testcase definition for RFC2889 tests:
469 .. code-block:: python
472 "Name": "phy2phy_forwarding",
474 "Description": "LTD.Forwarding.RFC2889.MaxForwardingRate",
477 "traffic_type" : "rfc2889_forwarding",
482 For RFC2889 tests, specifying the locations for the monitoring ports is mandatory.
483 Necessary parameters are:
485 .. code-block:: console
487 TRAFFICGEN_STC_RFC2889_TEST_FILE_NAME
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_VERBOSE = "True"
499 TRAFFICGEN_STC_RFC2889_LOCATIONS="//10.1.1.1/1/1,//10.1.1.1/2/2"
501 Other Configurations are :
503 .. code-block:: console
505 TRAFFICGEN_STC_RFC2889_MIN_LR = 1488
506 TRAFFICGEN_STC_RFC2889_MAX_LR = 14880
507 TRAFFICGEN_STC_RFC2889_MIN_ADDRS = 1000
508 TRAFFICGEN_STC_RFC2889_MAX_ADDRS = 65536
509 TRAFFICGEN_STC_RFC2889_AC_LR = 1000
511 The first 2 values are for address-learning test where as other 3 values are
512 for the Address caching capacity test. LR: Learning Rate. AC: Address Caching.
513 Maximum value for address is 16777216. Whereas, maximum for LR is 4294967295.
515 Results for RFC2889 Tests: Forwarding tests outputs following values:
517 .. code-block:: console
519 TX_RATE_FPS : "Transmission Rate in Frames/sec"
520 THROUGHPUT_RX_FPS: "Received Throughput Frames/sec"
521 TX_RATE_MBPS : " Transmission rate in MBPS"
522 THROUGHPUT_RX_MBPS: "Received Throughput in MBPS"
523 TX_RATE_PERCENT: "Transmission Rate in Percentage"
524 FRAME_LOSS_PERCENT: "Frame loss in Percentage"
525 FORWARDING_RATE_FPS: " Maximum Forwarding Rate in FPS"
528 Whereas, the address caching test outputs following values,
530 .. code-block:: console
532 CACHING_CAPACITY_ADDRS = 'Number of address it can cache'
533 ADDR_LEARNED_PERCENT = 'Percentage of address successfully learned'
535 and address learning test outputs just a single value:
537 .. code-block:: console
539 OPTIMAL_LEARNING_RATE_FPS = 'Optimal learning rate in fps'
541 Note that 'FORWARDING_RATE_FPS', 'CACHING_CAPACITY_ADDRS',
542 'ADDR_LEARNED_PERCENT' and 'OPTIMAL_LEARNING_RATE_FPS' are the new
543 result-constants added to support RFC2889 tests.
553 Xena Networks traffic generator requires specific files and packages to be
554 installed. It is assumed the user has access to the Xena2544.exe file which
555 must be placed in VSPerf installation location under the tools/pkt_gen/xena
556 folder. Contact Xena Networks for the latest version of this file. The user
557 can also visit www.xenanetworks/downloads to obtain the file with a valid
560 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
562 To execute the Xena2544.exe file under Linux distributions the mono-complete
563 package must be installed. To install this package follow the instructions
564 below. Further information can be obtained from
565 http://www.mono-project.com/docs/getting-started/install/linux/
567 .. code-block:: console
569 rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
570 yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
571 yum -y install mono-complete
573 To prevent gpg errors on future yum installation of packages the mono-project
574 repo should be disabled once installed.
576 .. code-block:: console
578 yum-config-manager --disable download.mono-project.com_repo_centos_
583 Connection information for your Xena Chassis must be supplied inside the
584 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
585 set to allow for proper connections to the chassis.
587 .. code-block:: console
589 TRAFFICGEN_XENA_IP = ''
590 TRAFFICGEN_XENA_PORT1 = ''
591 TRAFFICGEN_XENA_PORT2 = ''
592 TRAFFICGEN_XENA_USER = ''
593 TRAFFICGEN_XENA_PASSWORD = ''
594 TRAFFICGEN_XENA_MODULE1 = ''
595 TRAFFICGEN_XENA_MODULE2 = ''
597 RFC2544 Throughput Testing
598 ~~~~~~~~~~~~~~~~~~~~~~~~~~
600 Xena traffic generator testing for rfc2544 throughput can be modified for
601 different behaviors if needed. The default options for the following are
602 optimized for best results.
604 .. code-block:: console
606 TRAFFICGEN_XENA_2544_TPUT_INIT_VALUE = '10.0'
607 TRAFFICGEN_XENA_2544_TPUT_MIN_VALUE = '0.1'
608 TRAFFICGEN_XENA_2544_TPUT_MAX_VALUE = '100.0'
609 TRAFFICGEN_XENA_2544_TPUT_VALUE_RESOLUTION = '0.5'
610 TRAFFICGEN_XENA_2544_TPUT_USEPASS_THRESHHOLD = 'false'
611 TRAFFICGEN_XENA_2544_TPUT_PASS_THRESHHOLD = '0.0'
613 Each value modifies the behavior of rfc 2544 throughput testing. Refer to your
614 Xena documentation to understand the behavior changes in modifying these
617 Continuous Traffic Testing
618 ~~~~~~~~~~~~~~~~~~~~~~~~~~
620 Xena continuous traffic by default does a 3 second learning preemption to allow
621 the DUT to receive learning packets before a continuous test is performed. If
622 a custom test case requires this learning be disabled, you can disable the option
623 or modify the length of the learning by modifying the following settings.
625 .. code-block:: console
627 TRAFFICGEN_XENA_CONT_PORT_LEARNING_ENABLED = False
628 TRAFFICGEN_XENA_CONT_PORT_LEARNING_DURATION = 3
636 MoonGen architecture overview and general installation instructions
639 https://github.com/emmericp/MoonGen
641 * Note: Today, MoonGen with VSPERF only supports 10Gbps line speeds.
643 For VSPERF use, MoonGen should be cloned from here (as opposed to the
644 previously mentioned GitHub):
646 git clone https://github.com/atheurer/lua-trafficgen
648 and use the master branch:
652 VSPERF uses a particular Lua script with the MoonGen project:
656 Follow MoonGen set up and execution instructions here:
658 https://github.com/atheurer/lua-trafficgen/blob/master/README.md
660 Note one will need to set up ssh login to not use passwords between the server
661 running MoonGen and the device under test (running the VSPERF test
662 infrastructure). This is because VSPERF on one server uses 'ssh' to
663 configure and run MoonGen upon the other server.
665 One can set up this ssh access by doing the following on both servers:
667 .. code-block:: console
669 ssh-keygen -b 2048 -t rsa
670 ssh-copy-id <other server>
675 Connection information for MoonGen must be supplied inside the
676 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
677 set to allow for proper connections to the host with MoonGen.
679 .. code-block:: console
681 TRAFFICGEN_MOONGEN_HOST_IP_ADDR = ""
682 TRAFFICGEN_MOONGEN_USER = ""
683 TRAFFICGEN_MOONGEN_BASE_DIR = ""
684 TRAFFICGEN_MOONGEN_PORTS = ""
685 TRAFFICGEN_MOONGEN_LINE_SPEED_GBPS = ""