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>`__
26 To see the supported Operating Systems, vSwitches and system requirements,
27 please follow the `installation instructions
28 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/installation.html>`__ to
31 Traffic Generator Setup
32 -----------------------
33 Follow the `Traffic generator instructions
34 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__ to
35 install and configure a suitable traffic generator.
37 Cloning and building src dependencies
38 -------------------------------------
40 In order to run VSPERF, you will need to download DPDK and OVS. You can
41 do this manually and build them in a preferred location, OR you could
42 use vswitchperf/src. The vswitchperf/src directory contains makefiles
43 that will allow you to clone and build the libraries that VSPERF depends
44 on, such as DPDK and OVS. To clone and build simply:
46 .. code-block:: console
51 VSPERF can be used with stock OVS (without DPDK support). When build
52 is finished, the libraries are stored in src_vanilla directory.
54 The 'make' builds all options in src:
57 * OVS with vhost_user as the guest access method (with DPDK support)
58 * OVS with vhost_cuse s the guest access method (with DPDK support)
60 The vhost_user build will reside in src/ovs/
61 The vhost_cuse build will reside in vswitchperf/src_cuse
62 The Vanilla OVS build will reside in vswitchperf/src_vanilla
64 To delete a src subdirectory and its contents to allow you to re-clone simply
67 .. code-block:: console
71 Configure the ``./conf/10_custom.conf`` file
72 --------------------------------------------
73 The ``10_custom.conf`` file is the configuration file that overrides
74 default configurations in all the other configuration files in ``./conf``
75 The supplied ``10_custom.conf`` file **MUST** be modified, as it contains
76 configuration items for which there are no reasonable default values.
78 The configuration items that can be added is not limited to the initial
79 contents. Any configuration item mentioned in any .conf file in
80 ``./conf`` directory can be added and that item will be overridden by
81 the custom configuration value.
83 Using a custom settings file
84 ----------------------------
86 If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
87 of if you want to use an alternative configuration file, the file can
88 be passed to ``vsperf`` via the ``--conf-file`` argument.
90 .. code-block:: console
92 $ ./vsperf --conf-file <path_to_custom_conf> ...
94 Note that configuration passed in via the environment (``--load-env``)
95 or via another command line argument will override both the default and
96 your custom configuration files. This "priority hierarchy" can be
97 described like so (1 = max priority):
99 1. Command line arguments
100 2. Environment variables
101 3. Configuration file(s)
105 vsperf uses a VM called vloop_vnf for looping traffic in the PVP and PVVP
106 deployment scenarios. The image can be downloaded from
107 `<http://artifacts.opnfv.org/>`__.
109 .. code-block:: console
111 $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2
113 vloop_vnf forwards traffic through a VM using one of:
116 * l2fwd kernel Module.
118 Alternatively you can use your own QEMU image.
122 A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with
123 support for Destination Network Address Translation (DNAT) for both the MAC and
124 IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd
129 Before running any tests make sure you have root permissions by adding
130 the following line to /etc/sudoers:
132 .. code-block:: console
134 username ALL=(ALL) NOPASSWD: ALL
136 username in the example above should be replaced with a real username.
138 To list the available tests:
140 .. code-block:: console
144 To run a single test:
146 .. code-block:: console
150 Where $TESTNAME is the name of the vsperf test you would like to run.
152 To run a group of tests, for example all tests with a name containing
155 .. code-block:: console
157 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
161 .. code-block:: console
163 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
165 Some tests allow for configurable parameters, including test duration
166 (in seconds) as well as packet sizes (in bytes).
170 $ ./vsperf --conf-file user_settings.py
172 --test-param "duration=10;pkt_sizes=128"
174 For all available options, check out the help dialog:
176 .. code-block:: console
180 Executing Vanilla OVS tests
181 ----------------------------
183 1. If needed, recompile src for all OVS variants
185 .. code-block:: console
191 2. Update your ''10_custom.conf'' file to use the appropriate variables
194 .. code-block:: console
196 VSWITCH = 'OvsVanilla'
197 VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT2']
199 Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind
204 .. code-block:: console
206 $ ./vsperf --conf-file=<path_to_custom_conf>
208 Please note if you don't want to configure Vanilla OVS through the
209 configuration file, you can pass it as a CLI argument; BUT you must
212 .. code-block:: console
214 $ ./vsperf --vswitch OvsVanilla
217 Executing PVP and PVVP tests
218 ----------------------------
219 To run tests using vhost-user as guest access method:
221 1. Set VHOST_METHOD and VNF of your settings file to:
223 .. code-block:: console
226 VNF = 'QemuDpdkVhost'
228 2. If needed, recompile src for all OVS variants
230 .. code-block:: console
238 .. code-block:: console
240 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
242 To run tests using vhost-cuse as guest access method:
244 1. Set VHOST_METHOD and VNF of your settings file to:
246 .. code-block:: console
249 VNF = 'QemuDpdkVhostCuse'
251 2. If needed, recompile src for all OVS variants
253 .. code-block:: console
261 .. code-block:: console
263 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
265 Executing PVP tests using Vanilla OVS
266 -------------------------------------
267 To run tests using Vanilla OVS:
269 1. Set the following variables:
271 .. code-block:: console
273 VSWITCH = 'OvsVanilla'
274 VNF = 'QemuVirtioNet'
276 VANILLA_TGEN_PORT1_IP = n.n.n.n
277 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
279 VANILLA_TGEN_PORT2_IP = n.n.n.n
280 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
282 VANILLA_BRIDGE_IP = n.n.n.n
286 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
287 --test-param "vanilla_tgen_tx_ip=n.n.n.n;
288 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
291 2. If needed, recompile src for all OVS variants
293 .. code-block:: console
301 .. code-block:: console
303 $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
305 Selection of loopback application for PVP and PVVP tests
306 --------------------------------------------------------
307 To select loopback application, which will perform traffic forwarding
308 inside VM, following configuration parameter should be configured:
310 .. code-block:: console
312 GUEST_LOOPBACK = ['testpmd', 'testpmd']
316 .. code-block:: console
318 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
319 --test-param "guest_loopback=testpmd"
321 Supported loopback applications are:
323 .. code-block:: console
325 'testpmd' - testpmd from dpdk will be built and used
326 'l2fwd' - l2fwd module provided by Huawei will be built and used
327 'linux_bridge' - linux bridge will be configured
328 'buildin' - nothing will be configured by vsperf; VM image must
329 ensure traffic forwarding between its interfaces
331 Guest loopback application must be configured, otherwise traffic
332 will not be forwarded by VM and testcases with PVP and PVVP deployments
333 will fail. Guest loopback application is set to 'testpmd' by default.
335 Executing Packet Forwarding tests
336 -----------------------------------
338 To select application, which will perform packet forwarding,
339 following configuration parameter should be configured:
341 .. code-block:: console
346 or use --vswitch and --fwdapp
348 $ ./vsperf --conf-file user_settings.py
352 Supported Packet Forwarding applications are:
354 .. code-block:: console
356 'testpmd' - testpmd from dpdk
359 1. Update your ''10_custom.conf'' file to use the appropriate variables
360 for selected Packet Forwarder:
361 .. code-block:: console
363 # testpmd configuration
365 # packet forwarding mode: io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho
366 TESTPMD_FWD_MODE = 'csum'
367 # checksum calculation layer: ip|udp|tcp|sctp|outer-ip
368 TESTPMD_CSUM_LAYER = 'ip'
369 # checksum calculation place: hw (hardware) | sw (software)
370 TESTPMD_CSUM_CALC = 'sw'
371 # recognize tunnel headers: on|off
372 TESTPMD_CSUM_PARSE_TUNNEL = 'off'
376 .. code-block:: console
378 $ ./vsperf --conf-file <path_to_settings_py>
380 VSPERF modes of operation
381 -------------------------
382 VSPERF can be run in different modes. By default it will configure vSwitch,
383 traffic generator and VNF. However it can be used just for configuration
384 and execution of traffic generator. Another option is execution of all
385 components except traffic generator itself.
387 Mode of operation is driven by configuration parameter -m or --mode
389 .. code-block:: console
391 -m MODE, --mode MODE vsperf mode of operation;
393 "normal" - execute vSwitch, VNF and traffic generator
394 "trafficgen" - execute only traffic generator
395 "trafficgen-off" - execute vSwitch and VNF
396 "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission
398 In case, that VSPERF is executed in "trafficgen" mode, then configuration
399 of traffic generator should be configured through --test-param option.
400 Supported CLI options useful for traffic generator configuration are:
402 .. code-block:: console
404 'traffic_type' - One of the supported traffic types. E.g. rfc2544,
405 back2back or continuous
406 Default value is "rfc2544".
407 'bidirectional' - Specifies if generated traffic will be full-duplex (true)
408 or half-duplex (false)
409 Default value is "false".
410 'iload' - Defines desired percentage of frame rate used during
411 continuous stream tests.
412 Default value is 100.
413 'multistream' - Defines number of flows simulated by traffic generator.
414 Value 0 disables MultiStream feature
416 'stream_type' - Stream Type is an extension of the "MultiStream" feature.
417 If MultiStream is disabled, then Stream Type will be
418 ignored. Stream Type defines ISO OSI network layer used
419 for simulation of multiple streams.
420 Default value is "L4".
422 Example of execution of VSPERF in "trafficgen" mode:
424 .. code-block:: console
426 $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf
427 --test-params "traffic_type=continuous;bidirectional=True;iload=60"
429 Code change verification by pylint
430 ----------------------------------
431 Every developer participating in VSPERF project should run
432 pylint before his python code is submitted for review. Project
433 specific configuration for pylint is available at 'pylint.rc'.
435 Example of manual pylint invocation:
437 .. code-block:: console
439 $ pylint --rcfile ./pylintrc ./vsperf
444 OVS with DPDK and QEMU
445 ~~~~~~~~~~~~~~~~~~~~~~~
446 If you encounter the following error: "before (last 100 chars):
447 '-path=/dev/hugepages,share=on: unable to map backing store for
448 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
449 deployment scenario, check the amount of hugepages on your system:
451 .. code-block:: console
453 $ cat /proc/meminfo | grep HugePages
456 By default the vswitchd is launched with 1Gb of memory, to change
457 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
458 an appropriate amount of memory:
460 .. code-block:: console
462 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
467 For more information and details refer to the vSwitchPerf user guide at:
468 http://artifacts.opnfv.org/vswitchperf/brahmaputra/userguide/index.html