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 vSwitchPerf test suites userguide
6 ---------------------------------
11 VSPERF requires a traffic generators to run tests, automated traffic gen
12 support in VSPERF includes:
14 - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA
16 - Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual
17 in a VM) and a VM to run the Spirent Virtual Deployment Service image,
18 formerly known as "Spirent LabServer".
20 If you want to use another traffic generator, please select the Dummy generator
21 option as shown in `Traffic generator instructions
22 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__
27 To see the supported Operating Systems, vSwitches and system requirements,
28 please follow the `installation instructions
29 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/installation.html>`__ to
32 Traffic Generator Setup
33 ^^^^^^^^^^^^^^^^^^^^^^^
35 Follow the `Traffic generator instructions
36 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__ to
37 install and configure a suitable traffic generator.
39 Cloning and building src dependencies
40 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42 In order to run VSPERF, you will need to download DPDK and OVS. You can
43 do this manually and build them in a preferred location, OR you could
44 use vswitchperf/src. The vswitchperf/src directory contains makefiles
45 that will allow you to clone and build the libraries that VSPERF depends
46 on, such as DPDK and OVS. To clone and build simply:
48 .. code-block:: console
53 VSPERF can be used with stock OVS (without DPDK support). When build
54 is finished, the libraries are stored in src_vanilla directory.
56 The 'make' builds all options in src:
59 * OVS with vhost_user as the guest access method (with DPDK support)
60 * OVS with vhost_cuse s the guest access method (with DPDK support)
62 The vhost_user build will reside in src/ovs/
63 The vhost_cuse build will reside in vswitchperf/src_cuse
64 The Vanilla OVS build will reside in vswitchperf/src_vanilla
66 To delete a src subdirectory and its contents to allow you to re-clone simply
69 .. code-block:: console
73 Configure the ``./conf/10_custom.conf`` file
74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
76 The ``10_custom.conf`` file is the configuration file that overrides
77 default configurations in all the other configuration files in ``./conf``
78 The supplied ``10_custom.conf`` file **MUST** be modified, as it contains
79 configuration items for which there are no reasonable default values.
81 The configuration items that can be added is not limited to the initial
82 contents. Any configuration item mentioned in any .conf file in
83 ``./conf`` directory can be added and that item will be overridden by
84 the custom configuration value.
86 Using a custom settings file
87 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
89 If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
90 of if you want to use an alternative configuration file, the file can
91 be passed to ``vsperf`` via the ``--conf-file`` argument.
93 .. code-block:: console
95 $ ./vsperf --conf-file <path_to_custom_conf> ...
97 Note that configuration passed in via the environment (``--load-env``)
98 or via another command line argument will override both the default and
99 your custom configuration files. This "priority hierarchy" can be
100 described like so (1 = max priority):
102 1. Command line arguments
103 2. Environment variables
104 3. Configuration file(s)
109 vsperf uses a VM called vloop_vnf for looping traffic in the PVP and PVVP
110 deployment scenarios. The image can be downloaded from
111 `<http://artifacts.opnfv.org/>`__.
113 .. code-block:: console
115 $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2
117 vloop_vnf forwards traffic through a VM using one of:
120 * l2fwd kernel Module.
122 Alternatively you can use your own QEMU image.
127 A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with
128 support for Destination Network Address Translation (DNAT) for both the MAC and
129 IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd
134 Before running any tests make sure you have root permissions by adding
135 the following line to /etc/sudoers:
137 .. code-block:: console
139 username ALL=(ALL) NOPASSWD: ALL
141 username in the example above should be replaced with a real username.
143 To list the available tests:
145 .. code-block:: console
149 To run a single test:
151 .. code-block:: console
155 Where $TESTNAME is the name of the vsperf test you would like to run.
157 To run a group of tests, for example all tests with a name containing
160 .. code-block:: console
162 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
166 .. code-block:: console
168 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
170 Some tests allow for configurable parameters, including test duration
171 (in seconds) as well as packet sizes (in bytes).
175 $ ./vsperf --conf-file user_settings.py
177 --test-params "duration=10;pkt_sizes=128"
179 For all available options, check out the help dialog:
181 .. code-block:: console
185 Executing Vanilla OVS tests
186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
188 1. If needed, recompile src for all OVS variants
190 .. code-block:: console
196 2. Update your ''10_custom.conf'' file to use the appropriate variables
199 .. code-block:: console
201 VSWITCH = 'OvsVanilla'
202 VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT2']
204 Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind
209 .. code-block:: console
211 $ ./vsperf --conf-file=<path_to_custom_conf>
213 Please note if you don't want to configure Vanilla OVS through the
214 configuration file, you can pass it as a CLI argument; BUT you must
217 .. code-block:: console
219 $ ./vsperf --vswitch OvsVanilla
222 Executing PVP and PVVP tests
223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
225 To run tests using vhost-user as guest access method:
227 1. Set VHOST_METHOD and VNF of your settings file to:
229 .. code-block:: console
232 VNF = 'QemuDpdkVhost'
234 2. If needed, recompile src for all OVS variants
236 .. code-block:: console
244 .. code-block:: console
246 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
248 To run tests using vhost-cuse as guest access method:
250 1. Set VHOST_METHOD and VNF of your settings file to:
252 .. code-block:: console
255 VNF = 'QemuDpdkVhostCuse'
257 2. If needed, recompile src for all OVS variants
259 .. code-block:: console
267 .. code-block:: console
269 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
271 Executing PVP tests using Vanilla OVS
272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
274 To run tests using Vanilla OVS:
276 1. Set the following variables:
278 .. code-block:: console
280 VSWITCH = 'OvsVanilla'
281 VNF = 'QemuVirtioNet'
283 VANILLA_TGEN_PORT1_IP = n.n.n.n
284 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
286 VANILLA_TGEN_PORT2_IP = n.n.n.n
287 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
289 VANILLA_BRIDGE_IP = n.n.n.n
293 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
294 --test-params "vanilla_tgen_tx_ip=n.n.n.n;
295 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
298 2. If needed, recompile src for all OVS variants
300 .. code-block:: console
308 .. code-block:: console
310 $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
312 Using vfio_pci with DPDK
313 ^^^^^^^^^^^^^^^^^^^^^^^^^
315 To use vfio with DPDK instead of igb_uio edit 'conf/02_vswitch.conf'
316 with the following parameters:
318 .. code-block:: console
323 SYS_MODULES = ['cuse']
325 **NOTE:** Please ensure that Intel VT-d is enabled in BIOS.
327 **NOTE:** Please ensure your boot/grub parameters include
330 .. code-block:: console
332 iommu=pt intel_iommu=on
334 To check that IOMMU is enabled on your platform:
336 .. code-block:: console
339 [ 0.000000] Intel-IOMMU: enabled
340 [ 0.139882] dmar: IOMMU 0: reg_base_addr fbffe000 ver 1:0 cap d2078c106f0466 ecap f020de
341 [ 0.139888] dmar: IOMMU 1: reg_base_addr ebffc000 ver 1:0 cap d2078c106f0466 ecap f020de
342 [ 0.139893] IOAPIC id 2 under DRHD base 0xfbffe000 IOMMU 0
343 [ 0.139894] IOAPIC id 0 under DRHD base 0xebffc000 IOMMU 1
344 [ 0.139895] IOAPIC id 1 under DRHD base 0xebffc000 IOMMU 1
345 [ 3.335744] IOMMU: dmar0 using Queued invalidation
346 [ 3.335746] IOMMU: dmar1 using Queued invalidation
349 Selection of loopback application for PVP and PVVP tests
350 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352 To select loopback application, which will perform traffic forwarding
353 inside VM, following configuration parameter should be configured:
355 .. code-block:: console
357 GUEST_LOOPBACK = ['testpmd', 'testpmd']
361 .. code-block:: console
363 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
364 --test-params "guest_loopback=testpmd"
366 Supported loopback applications are:
368 .. code-block:: console
370 'testpmd' - testpmd from dpdk will be built and used
371 'l2fwd' - l2fwd module provided by Huawei will be built and used
372 'linux_bridge' - linux bridge will be configured
373 'buildin' - nothing will be configured by vsperf; VM image must
374 ensure traffic forwarding between its interfaces
376 Guest loopback application must be configured, otherwise traffic
377 will not be forwarded by VM and testcases with PVP and PVVP deployments
378 will fail. Guest loopback application is set to 'testpmd' by default.
380 Executing Packet Forwarding tests
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383 To select application, which will perform packet forwarding,
384 following configuration parameter should be configured:
386 .. code-block:: console
391 or use --vswitch and --fwdapp
393 $ ./vsperf --conf-file user_settings.py
397 Supported Packet Forwarding applications are:
399 .. code-block:: console
401 'testpmd' - testpmd from dpdk
404 1. Update your ''10_custom.conf'' file to use the appropriate variables
405 for selected Packet Forwarder:
407 .. code-block:: console
409 # testpmd configuration
411 # packet forwarding mode: io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho
412 TESTPMD_FWD_MODE = 'csum'
413 # checksum calculation layer: ip|udp|tcp|sctp|outer-ip
414 TESTPMD_CSUM_LAYER = 'ip'
415 # checksum calculation place: hw (hardware) | sw (software)
416 TESTPMD_CSUM_CALC = 'sw'
417 # recognize tunnel headers: on|off
418 TESTPMD_CSUM_PARSE_TUNNEL = 'off'
422 .. code-block:: console
424 $ ./vsperf --conf-file <path_to_settings_py>
426 VSPERF modes of operation
427 ^^^^^^^^^^^^^^^^^^^^^^^^^
429 VSPERF can be run in different modes. By default it will configure vSwitch,
430 traffic generator and VNF. However it can be used just for configuration
431 and execution of traffic generator. Another option is execution of all
432 components except traffic generator itself.
434 Mode of operation is driven by configuration parameter -m or --mode
436 .. code-block:: console
438 -m MODE, --mode MODE vsperf mode of operation;
440 "normal" - execute vSwitch, VNF and traffic generator
441 "trafficgen" - execute only traffic generator
442 "trafficgen-off" - execute vSwitch and VNF
443 "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission
445 In case, that VSPERF is executed in "trafficgen" mode, then configuration
446 of traffic generator should be configured through --test-params option.
447 Supported CLI options useful for traffic generator configuration are:
449 .. code-block:: console
451 'traffic_type' - One of the supported traffic types. E.g. rfc2544,
452 back2back or continuous
453 Default value is "rfc2544".
454 'bidirectional' - Specifies if generated traffic will be full-duplex (true)
455 or half-duplex (false)
456 Default value is "false".
457 'iload' - Defines desired percentage of frame rate used during
458 continuous stream tests.
459 Default value is 100.
460 'multistream' - Defines number of flows simulated by traffic generator.
461 Value 0 disables MultiStream feature
463 'stream_type' - Stream Type is an extension of the "MultiStream" feature.
464 If MultiStream is disabled, then Stream Type will be
465 ignored. Stream Type defines ISO OSI network layer used
466 for simulation of multiple streams.
467 Default value is "L4".
469 Example of execution of VSPERF in "trafficgen" mode:
471 .. code-block:: console
473 $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf
474 --test-params "traffic_type=continuous;bidirectional=True;iload=60"
476 Code change verification by pylint
477 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
479 Every developer participating in VSPERF project should run
480 pylint before his python code is submitted for review. Project
481 specific configuration for pylint is available at 'pylint.rc'.
483 Example of manual pylint invocation:
485 .. code-block:: console
487 $ pylint --rcfile ./pylintrc ./vsperf
492 OVS with DPDK and QEMU
493 ~~~~~~~~~~~~~~~~~~~~~~~
495 If you encounter the following error: "before (last 100 chars):
496 '-path=/dev/hugepages,share=on: unable to map backing store for
497 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
498 deployment scenario, check the amount of hugepages on your system:
500 .. code-block:: console
502 $ cat /proc/meminfo | grep HugePages
505 By default the vswitchd is launched with 1Gb of memory, to change
506 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
507 an appropriate amount of memory:
509 .. code-block:: console
511 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
516 For more information and details refer to the vSwitchPerf user guide at:
517 http://artifacts.opnfv.org/vswitchperf/brahmaputra/userguide/index.html