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', '$PORT1']
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
397 In case, that VSPERF is executed in "trafficgen" mode, then configuration
398 of traffic generator should be configured through --test-param option.
399 Supported CLI options useful for traffic generator configuration are:
401 .. code-block:: console
403 'traffic_type' - One of the supported traffic types. E.g. rfc2544,
404 back2back or continuous
405 Default value is "rfc2544".
406 'bidirectional' - Specifies if generated traffic will be full-duplex (true)
407 or half-duplex (false)
408 Default value is "false".
409 'iload' - Defines desired percentage of frame rate used during
410 continuous stream tests.
411 Default value is 100.
412 'multistream' - Defines number of flows simulated by traffic generator.
413 Value 0 disables MultiStream feature
415 'stream_type' - Stream Type is an extension of the "MultiStream" feature.
416 If MultiStream is disabled, then Stream Type will be
417 ignored. Stream Type defines ISO OSI network layer used
418 for simulation of multiple streams.
419 Default value is "L4".
421 Example of execution of VSPERF in "trafficgen" mode:
423 .. code-block:: console
425 $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf
426 --test-params "traffic_type=continuous;bidirectional=True;iload=60"
428 Code change verification by pylint
429 ----------------------------------
430 Every developer participating in VSPERF project should run
431 pylint before his python code is submitted for review. Project
432 specific configuration for pylint is available at 'pylint.rc'.
434 Example of manual pylint invocation:
436 .. code-block:: console
438 $ pylint --rcfile ./pylintrc ./vsperf
443 OVS with DPDK and QEMU
444 ~~~~~~~~~~~~~~~~~~~~~~~
445 If you encounter the following error: "before (last 100 chars):
446 '-path=/dev/hugepages,share=on: unable to map backing store for
447 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
448 deployment scenario, check the amount of hugepages on your system:
450 .. code-block:: console
452 $ cat /proc/meminfo | grep HugePages
455 By default the vswitchd is launched with 1Gb of memory, to change
456 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
457 an appropriate amount of memory:
459 .. code-block:: console
461 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
466 For more information and details refer to the vSwitchPerf user guide at:
467 http://artifacts.opnfv.org/vswitchperf/brahmaputra/userguide/index.html