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 ===========================
6 'vsperf' Traffic Gen Guide
7 ===========================
11 VSPERF supports the following traffic generators:
13 * Dummy (DEFAULT): Allows you to use your own external
15 * IXIA (IxNet and IxOS)
20 To see the list of traffic gens from the cli:
22 .. code-block:: console
24 $ ./vsperf --list-trafficgens
26 This guide provides the details of how to install
27 and configure the various traffic generators.
29 Background Information
30 ----------------------
31 The traffic default configuration can be found in
32 tools/pkt_gen/trafficgen/trafficgenhelper.py, and is configured as
35 .. code-block:: console
40 'srcmac': '00:00:00:00:00:00',
41 'dstmac': '00:00:00:00:00:00',
46 'dstip': '90.90.90.90',
60 The framesize paramter can be overridden from the configuration
61 files by adding the following to your custom configuration file
64 .. code-block:: console
66 TRAFFICGEN_PKT_SIZES = (64, 128,)
68 OR from the commandline:
70 .. code-block:: console
72 $ ./vsperf --test-params "pkt_sizes=x,y" $TESTNAME
74 You can also modify the traffic transmission duration and the number
75 of tests run by the traffic generator by extending the example
78 .. code-block:: console
80 $ ./vsperf --test-params "pkt_sizes=x,y;duration=10;rfc2544_tests=1" $TESTNAME
84 To select the Dummy generator please add the following to your
85 custom configuration file ``10_custom.conf``.
88 .. code-block:: console
92 OR run ``vsperf`` with the ``--trafficgen`` argument
94 .. code-block:: console
96 $ ./vsperf --trafficgen Dummy $TESTNAME
98 Where $TESTNAME is the name of the vsperf test you would like to run.
99 This will setup the vSwitch and the VNF (if one is part of your test)
100 print the traffic configuration and prompt you to transmit traffic
101 when the setup is complete.
103 .. code-block:: console
105 Please send 'continuous' traffic with the following stream config:
106 30mS, 90mpps, multistream False
107 and the following flow config:
113 "dstip": "90.90.90.90"
115 "traffic_type": "continuous",
128 "dstmac": "00:00:00:00:00:00",
129 "srcmac": "00:00:00:00:00:00",
133 What was the result for 'frames tx'?
135 When your traffic gen has completed traffic transmission and provided
136 the results please input these at the vsperf prompt. vsperf will try
139 .. code-block:: console
141 Is '$input_value' correct?
143 Please answer with y OR n.
145 VPSERF will ask you for:
146 * Result for 'frames tx'
147 * Result for 'frames rx'
148 * Result for 'min latency'
149 * Result for 'max latency'
150 * Result for 'avg latency'
152 Finally vsperf will print out the results for your test and generate the
153 appropriate logs and csv files.
159 On the CentOS 7 system
160 ~~~~~~~~~~~~~~~~~~~~~~
162 You need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
164 On the IXIA client software system
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167 Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
168 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
170 Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
171 the Target dialogue box make sure there is the argument "-tclport xxxx"
172 where xxxx is your port number (take note of this port number you will
173 need it for the 10\_custom.conf file).
175 .. image:: TCLServerProperties.png
177 Hit Ok and start the TCL server application
182 There are several configuration options specific to the IxNetworks traffic generator
183 from IXIA. It is essential to set them correctly, before the VSPERF is executed
186 Detailed description of options follows:
188 * TRAFFICGEN_IXNET_MACHINE - IP address of server, where IxNetwork TCL Server is running
189 * TRAFFICGEN_IXNET_PORT - PORT, where IxNetwork TCL Server is accepting connections from
191 * TRAFFICGEN_IXNET_USER - username, which will be used during communication with IxNetwork
192 TCL Server and IXIA chassis
193 * TRAFFICGEN_IXIA_HOST - IP address of IXIA traffic generator chassis
194 * TRAFFICGEN_IXIA_CARD - identification of card with dedicated ports at IXIA chassis
195 * TRAFFICGEN_IXIA_PORT1 - identification of the first dedicated port at TRAFFICGEN_IXIA_CARD
196 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
197 unidirectional traffic, it is essential to correctly connect 1st IXIA port to the 1st NIC
198 at DUT, i.e. to the first PCI handle from WHITELIST_NICS list. Otherwise traffic may not
199 be able to pass through the vSwitch.
200 * TRAFFICGEN_IXIA_PORT2 - identification of the second dedicated port at TRAFFICGEN_IXIA_CARD
201 at IXIA chassis; VSPERF uses two separated ports for traffic generation. In case of
202 unidirectional traffic, it is essential to correctly connect 2nd IXIA port to the 2nd NIC
203 at DUT, i.e. to the second PCI handle from WHITELIST_NICS list. Otherwise traffic may not
204 be able to pass through the vSwitch.
205 * TRAFFICGEN_IXNET_LIB_PATH - path to the DUT specific installation of IxNetwork TCL API
206 * TRAFFICGEN_IXNET_TCL_SCRIPT - name of the TCL script, which VSPERF will use for
207 communication with IXIA TCL server
208 * TRAFFICGEN_IXNET_TESTER_RESULT_DIR - folder accessible from IxNetwork TCL server,
209 where test results are stored, e.g. ``c:/ixia_results``; see test-results-share_
210 * TRAFFICGEN_IXNET_DUT_RESULT_DIR - directory accessible from the DUT, where test
211 results from IxNetwork TCL server are stored, e.g. ``/mnt/ixia_results``; see
214 .. _test-results-share:
219 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
220 results are stored at IxNetwork TCL server. Results are stored at folder defined by
221 ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` configuration parameter. Content of this
222 folder must be shared (e.g. via samba protocol) between TCL Server and DUT, where
223 VSPERF is executed. VSPERF expects, that test results will be available at directory
224 configured by ``TRAFFICGEN_IXNET_DUT_RESULT_DIR`` configuration parameter.
226 Example of sharing configuration:
228 * Create a new folder at IxNetwork TCL server machine, e.g. ``c:\ixia_results``
229 * Modify sharing options of ``ixia_results`` folder to share it with everybody
230 * Create a new directory at DUT, where shared directory with results
231 will be mounted, e.g. ``/mnt/ixia_results``
232 * Update your custom VSPERF configuration file as follows:
234 .. code-block:: python
236 TRAFFICGEN_IXNET_TESTER_RESULT_DIR = 'c:/ixia_results'
237 TRAFFICGEN_IXNET_DUT_RESULT_DIR = '/mnt/ixia_results'
239 Note: It is essential to use slashes '/' also in path
240 configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
241 * Install cifs-utils package.
243 e.g. at rpm based Linux distribution:
245 .. code-block:: console
247 yum install cifs-utils
249 * Mount shared directory, so VSPERF can access test results.
251 e.g. by adding new record into ``/etc/fstab``
253 .. code-block:: console
255 mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
256 -o file_mode=0777,dir_mode=0777,nounix
258 It is recommended to verify, that any new file inserted into ``c:/ixia_results`` folder
259 is visible at DUT inside ``/mnt/ixia_results`` directory.
264 Spirent installation files and instructions are available on the
265 Spirent support website at:
267 http://support.spirent.com
269 Select a version of Spirent TestCenter software to utilize. This example
270 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
271 version in place of 'v4.57' in the examples, below.
273 On the CentOS 7 System
274 ~~~~~~~~~~~~~~~~~~~~~~
276 Download and install the following:
278 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
280 Spirent Virtual Deployment Service (VDS)
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283 Spirent VDS is required for both TestCenter hardware and virtual
284 chassis in the vsperf environment. For installation, select the version
285 that matches the Spirent TestCenter Application version. For v4.57,
286 the matching VDS version is 1.0.55. Download either the ova (VMware)
287 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
288 according to Spirent installation instructions.
290 Using Spirent TestCenter Virtual (STCv)
291 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
296 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
298 Virtual test port performance is affected by the hypervisor configuration. For
299 best practice results in deploying STCv, the following is suggested:
301 - Create a single VM with two test ports rather than two VMs with one port each
302 - Set STCv in DPDK mode
303 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
304 - Turning off hyperthreading and pinning these cores will improve performance
305 - Give STCv 2 GB of RAM
307 To get the highest performance and accuracy, Spirent TestCenter hardware is
308 recommended. vsperf can run with either stype test ports.
310 Using STC REST Client
311 ~~~~~~~~~~~~~~~~~~~~~
312 The stcrestclient package provides the stchttp.py ReST API wrapper module.
313 This allows simple function calls, nearly identical to those provided by
314 StcPython.py, to be used to access TestCenter server sessions via the
315 STC ReST API. Basic ReST functionality is provided by the resthttp module,
316 and may be used for writing ReST clients independent of STC.
318 - Project page: <https://github.com/Spirent/py-stcrestclient>
319 - Package download: <http://pypi.python.org/pypi/stcrestclient>
321 To use REST interface, follow the instructions in the Project page to
322 install the package. Once installed, the scripts named with 'rest' keyword
323 can be used. For example: testcenter-rfc2544-rest.py can be used to run
324 RFC 2544 tests using the REST interface.
332 Xena Networks traffic generator requires certain files and packages to be
333 installed. It is assumed the user has access to the Xena2544.exe file which
334 must be placed in VSPerf installation location under the tools/pkt_gen/xena
335 folder. Contact Xena Networks for the latest version of this file. The user
336 can also visit www.xenanetworks/downloads to obtain the file with a valid
339 **Note** VSPerf has been fully tested with version v2.43 of Xena2544.exe
341 To execute the Xena2544.exe file under Linux distributions the mono-complete
342 package must be installed. To install this package follow the instructions
343 below. Further information can be obtained from
344 http://www.mono-project.com/docs/getting-started/install/linux/
346 .. code-block:: console
348 rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
349 yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
350 yum -y install mono-complete
352 To prevent gpg errors on future yum installation of packages the mono-project
353 repo should be disabled once installed.
355 .. code-block:: console
357 yum-config-manager --disable download.mono-project.com_repo_centos_
362 Connection information for your Xena Chassis must be supplied inside the
363 ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be
364 set to allow for proper connections to the chassis.
366 .. code-block:: console
368 TRAFFICGEN_XENA_IP = ''
369 TRAFFICGEN_XENA_PORT1 = ''
370 TRAFFICGEN_XENA_PORT2 = ''
371 TRAFFICGEN_XENA_USER = ''
372 TRAFFICGEN_XENA_PASSWORD = ''
373 TRAFFICGEN_XENA_MODULE1 = ''
374 TRAFFICGEN_XENA_MODULE2 = ''
383 MoonGen architecture overview and general installation instructions
386 https://github.com/emmericp/MoonGen
388 For VSPerf use, MoonGen should be cloned from here (as opposed to the afore
391 git clone https://github.com/atheurer/MoonGen
393 and use the opnfv-stable branch:
395 git checkout opnfv-stable
397 VSPerf uses a particular example script under the examples directory within
400 MoonGen/examples/opnfv-vsperf.lua
402 Follow MoonGen set up instructions here:
404 https://github.com/atheurer/MoonGen/blob/opnfv-stable/MoonGenSetUp.html
406 Note one will need to set up ssh login to not use passwords between the server
407 running MoonGen and the device under test (running the VSPERF test
408 infrastructure). This is because VSPERF on one server uses 'ssh' to
409 configure and run MoonGen upon the other server.
411 One can set up this ssh access by doing the following on both servers:
413 .. code-block:: console
415 ssh-keygen -b 2048 -t rsa
416 ssh-copy-id <other server>