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 Getting Started with 'vsperf'
7 =============================
12 VSPERF requires a traffic generators to run tests, automated traffic gen
13 support in VSPERF includes:
15 - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA
17 - Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual
18 in a VM) and a VM to run the Spirent Virtual Deployment Service image,
19 formerly known as "Spirent LabServer".
21 If you want to use another traffic generator, please select the Dummy generator
22 option as shown in `Traffic generator instructions
23 <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 -----------------------
34 Follow the `Traffic generator instructions
35 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__ to
36 install and configure a suitable traffic generator.
38 Cloning and building src dependencies
39 -------------------------------------
41 In order to run VSPERF, you will need to download DPDK and OVS. You can
42 do this manually and build them in a preferred location, OR you could
43 use vswitchperf/src. The vswitchperf/src directory contains makefiles
44 that will allow you to clone and build the libraries that VSPERF depends
45 on, such as DPDK and OVS. To clone and build simply:
47 .. code-block:: console
52 VSPERF can be used with stock OVS (without DPDK support). When build
53 is finished, the libraries are stored in src_vanilla directory.
55 The 'make' builds all options in src:
58 * OVS with vhost_user as the guest access method (with DPDK support)
59 * OVS with vhost_cuse s the guest access method (with DPDK support)
61 The vhost_user build will reside in src/ovs/
62 The vhost_cuse build will reside in vswitchperf/src_cuse
63 The Vanilla OVS build will reside in vswitchperf/src_vanilla
65 To delete a src subdirectory and its contents to allow you to re-clone simply
68 .. code-block:: console
72 Configure the ``./conf/10_custom.conf`` file
73 --------------------------------------------
74 The ``10_custom.conf`` file is the configuration file that overrides
75 default configurations in all the other configuration files in ``./conf``
76 The supplied ``10_custom.conf`` file **MUST** be modified, as it contains
77 configuration items for which there are no reasonable default values.
79 The configuration items that can be added is not limited to the initial
80 contents. Any configuration item mentioned in any .conf file in
81 ``./conf`` directory can be added and that item will be overridden by
82 the custom configuration value.
84 Using a custom settings file
85 ----------------------------
87 If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
88 of if you want to use an alternative configuration file, the file can
89 be passed to ``vsperf`` via the ``--conf-file`` argument.
91 .. code-block:: console
93 $ ./vsperf --conf-file <path_to_custom_conf> ...
95 Note that configuration passed in via the environment (``--load-env``)
96 or via another command line argument will override both the default and
97 your custom configuration files. This "priority hierarchy" can be
98 described like so (1 = max priority):
100 1. Command line arguments
101 2. Environment variables
102 3. Configuration file(s)
106 vsperf uses a VM called vloop_vnf for looping traffic in the PVP and PVVP
107 deployment scenarios. The image can be downloaded from
108 `<http://artifacts.opnfv.org/>`__.
110 .. code-block:: console
112 $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2
114 vloop_vnf forwards traffic through a VM using one of:
117 * l2fwd kernel Module.
119 Alternatively you can use your own QEMU image.
123 A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with
124 support for Destination Network Address Translation (DNAT) for both the MAC and
125 IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd
130 Before running any tests make sure you have root permissions by adding
131 the following line to /etc/sudoers:
133 .. code-block:: console
135 username ALL=(ALL) NOPASSWD: ALL
137 username in the example above should be replaced with a real username.
139 To list the available tests:
141 .. code-block:: console
145 To run a single test:
147 .. code-block:: console
151 Where $TESTNAME is the name of the vsperf test you would like to run.
153 To run a group of tests, for example all tests with a name containing
156 .. code-block:: console
158 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
162 .. code-block:: console
164 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
166 Some tests allow for configurable parameters, including test duration
167 (in seconds) as well as packet sizes (in bytes).
171 $ ./vsperf --conf-file user_settings.py
173 --test-param "duration=10;pkt_sizes=128"
175 For all available options, check out the help dialog:
177 .. code-block:: console
181 Executing Vanilla OVS tests
182 ----------------------------
184 1. If needed, recompile src for all OVS variants
186 .. code-block:: console
192 2. Update your ''10_custom.conf'' file to use the appropriate variables
195 .. code-block:: console
197 VSWITCH = 'OvsVanilla'
198 VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1']
200 Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind
205 .. code-block:: console
207 $ ./vsperf --conf-file=<path_to_custom_conf>
209 Please note if you don't want to configure Vanilla OVS through the
210 configuration file, you can pass it as a CLI argument; BUT you must
213 .. code-block:: console
215 $ ./vsperf --vswitch OvsVanilla
218 Executing PVP and PVVP tests
219 ----------------------------
220 To run tests using vhost-user as guest access method:
222 1. Set VHOST_METHOD and VNF of your settings file to:
224 .. code-block:: console
227 VNF = 'QemuDpdkVhost'
229 2. If needed, recompile src for all OVS variants
231 .. code-block:: console
239 .. code-block:: console
241 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
243 To run tests using vhost-cuse as guest access method:
245 1. Set VHOST_METHOD and VNF of your settings file to:
247 .. code-block:: console
250 VNF = 'QemuDpdkVhostCuse'
252 2. If needed, recompile src for all OVS variants
254 .. code-block:: console
262 .. code-block:: console
264 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
266 Executing PVP tests using Vanilla OVS
267 -------------------------------------
268 To run tests using Vanilla OVS:
270 1. Set the following variables:
272 .. code-block:: console
274 VSWITCH = 'OvsVanilla'
275 VNF = 'QemuVirtioNet'
277 VANILLA_TGEN_PORT1_IP = n.n.n.n
278 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
280 VANILLA_TGEN_PORT2_IP = n.n.n.n
281 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
283 VANILLA_BRIDGE_IP = n.n.n.n
287 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
288 --test-param "vanilla_tgen_tx_ip=n.n.n.n;
289 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
292 2. If needed, recompile src for all OVS variants
294 .. code-block:: console
302 .. code-block:: console
304 $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
306 Selection of loopback application for PVP and PVVP tests
307 --------------------------------------------------------
308 To select loopback application, which will perform traffic forwarding
309 inside VM, following configuration parameter should be configured:
311 .. code-block:: console
313 GUEST_LOOPBACK = ['testpmd', 'testpmd']
317 .. code-block:: console
319 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
320 --test-param "guest_loopback=testpmd"
322 Supported loopback applications are:
324 .. code-block:: console
326 'testpmd' - testpmd from dpdk will be built and used
327 'l2fwd' - l2fwd module provided by Huawei will be built and used
328 'linux_bridge' - linux bridge will be configured
329 'buildin' - nothing will be configured by vsperf; VM image must
330 ensure traffic forwarding between its interfaces
332 Guest loopback application must be configured, otherwise traffic
333 will not be forwarded by VM and testcases with PVP and PVVP deployments
334 will fail. Guest loopback application is set to 'testpmd' by default.
336 Executing Packet Forwarding tests
337 -----------------------------------
339 To select application, which will perform packet forwarding,
340 following configuration parameter should be configured:
342 .. code-block:: console
347 or use --vswitch and --fwdapp
349 $ ./vsperf --conf-file user_settings.py
353 Supported Packet Forwarding applications are:
355 .. code-block:: console
357 'testpmd' - testpmd from dpdk
360 1. Update your ''10_custom.conf'' file to use the appropriate variables
361 for selected Packet Forwarder:
362 .. code-block:: console
364 # testpmd configuration
366 # packet forwarding mode: io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho
367 TESTPMD_FWD_MODE = 'csum'
368 # checksum calculation layer: ip|udp|tcp|sctp|outer-ip
369 TESTPMD_CSUM_LAYER = 'ip'
370 # checksum calculation place: hw (hardware) | sw (software)
371 TESTPMD_CSUM_CALC = 'sw'
372 # recognize tunnel headers: on|off
373 TESTPMD_CSUM_PARSE_TUNNEL = 'off'
377 .. code-block:: console
379 $ ./vsperf --conf-file <path_to_settings_py>
381 VSPERF modes of operation
382 -------------------------
383 VSPERF can be run in different modes. By default it will configure vSwitch,
384 traffic generator and VNF. However it can be used just for configuration
385 and execution of traffic generator. Another option is execution of all
386 components except traffic generator itself.
388 Mode of operation is driven by configuration parameter -m or --mode
390 .. code-block:: console
392 -m MODE, --mode MODE vsperf mode of operation;
394 "normal" - execute vSwitch, VNF and traffic generator
395 "trafficgen" - execute only traffic generator
396 "trafficgen-off" - execute vSwitch and VNF
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']