1 =============================
2 Getting Started with 'vsperf'
3 =============================
8 VSPERF requires a traffic generators to run tests, automated traffic gen
9 support in VSPERF includes:
11 - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA
13 - Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual
14 in a VM) and a VM to run the Spirent Virtual Deployment Service image,
15 formerly known as "Spirent LabServer".
17 If you want to use another traffic generator, please select the Dummy generator
18 option as shown in `Traffic generator instructions
19 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__
23 To see the supported Operating Systems, vSwitches and system requirements,
24 please follow the `installation instructions
25 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/installation.html>`__ to
28 Traffic Generator Setup
29 -----------------------
30 Follow the `Traffic generator instructions
31 <http://artifacts.opnfv.org/vswitchperf/docs/configguide/trafficgen.html>`__ to
32 install and configure a suitable traffic generator.
34 Cloning and building src dependencies
35 -------------------------------------
37 In order to run VSPERF, you will need to download DPDK and OVS. You can
38 do this manually and build them in a preferred location, OR you could
39 use vswitchperf/src. The vswitchperf/src directory contains makefiles
40 that will allow you to clone and build the libraries that VSPERF depends
41 on, such as DPDK and OVS. To clone and build simply:
43 .. code-block:: console
48 VSPERF can be used with stock OVS (without DPDK support). When build
49 is finished, the libraries are stored in src_vanilla directory.
51 The 'make' builds all options in src:
54 * OVS with vhost_user as the guest access method (with DPDK support)
55 * OVS with vhost_cuse s the guest access method (with DPDK support)
57 The vhost_user build will reside in src/ovs/
58 The vhost_cuse build will reside in vswitchperf/src_cuse
59 The Vanilla OVS build will reside in vswitchperf/src_vanilla
61 To delete a src subdirectory and its contents to allow you to re-clone simply
64 .. code-block:: console
68 Configure the ``./conf/10_custom.conf`` file
69 --------------------------------------------
70 The ``10_custom.conf`` file is the configuration file that overrides
71 default configurations in all the other configuration files in ``./conf``
72 The supplied ``10_custom.conf`` file **MUST** be modified, as it contains
73 configuration items for which there are no reasonable default values.
75 The configuration items that can be added is not limited to the initial
76 contents. Any configuration item mentioned in any .conf file in
77 ``./conf`` directory can be added and that item will be overridden by
78 the custom configuration value.
80 Using a custom settings file
81 ----------------------------
83 If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
84 of if you want to use an alternative configuration file, the file can
85 be passed to ``vsperf`` via the ``--conf-file`` argument.
87 .. code-block:: console
89 $ ./vsperf --conf-file <path_to_custom_conf> ...
91 Note that configuration passed in via the environment (``--load-env``)
92 or via another command line argument will override both the default and
93 your custom configuration files. This "priority hierarchy" can be
94 described like so (1 = max priority):
96 1. Command line arguments
97 2. Environment variables
98 3. Configuration file(s)
102 vsperf uses a VM called vloop_vnf for looping traffic in the PVP and PVVP
103 deployment scenarios. The image can be downloaded from
104 `<http://artifacts.opnfv.org/>`__.
106 .. code-block:: console
108 $ wget http://artifacts.opnfv.org/vswitchperf/vloop-vnf-ubuntu-14.04_20151216.qcow2
110 vloop_vnf forwards traffic through a VM using one of:
113 * l2fwd kernel Module.
115 Alternatively you can use your own QEMU image.
119 A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with
120 support for Destination Network Address Translation (DNAT) for both the MAC and
121 IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd
126 Before running any tests make sure you have root permissions by adding
127 the following line to /etc/sudoers:
129 .. code-block:: console
131 username ALL=(ALL) NOPASSWD: ALL
133 username in the example above should be replaced with a real username.
135 To list the available tests:
137 .. code-block:: console
141 To run a single test:
143 .. code-block:: console
147 Where $TESTNAME is the name of the vsperf test you would like to run.
149 To run a group of tests, for example all tests with a name containing
152 .. code-block:: console
154 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
158 .. code-block:: console
160 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
162 Some tests allow for configurable parameters, including test duration
163 (in seconds) as well as packet sizes (in bytes).
167 $ ./vsperf --conf-file user_settings.py
169 --test-param "duration=10;pkt_sizes=128"
171 For all available options, check out the help dialog:
173 .. code-block:: console
177 Executing Vanilla OVS tests
178 ----------------------------
180 1. If needed, recompile src for all OVS variants
182 .. code-block:: console
188 2. Update your ''10_custom.conf'' file to use the appropriate variables
191 .. code-block:: console
193 VSWITCH = 'OvsVanilla'
194 VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1']
196 Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind
201 .. code-block:: console
203 $ ./vsperf --conf-file=<path_to_custom_conf>
205 Please note if you don't want to configure Vanilla OVS through the
206 configuration file, you can pass it as a CLI argument; BUT you must
209 .. code-block:: console
211 $ ./vsperf --vswitch OvsVanilla
214 Executing PVP and PVVP tests
215 ----------------------------
216 To run tests using vhost-user as guest access method:
218 1. Set VHOST_METHOD and VNF of your settings file to:
220 .. code-block:: console
223 VNF = 'QemuDpdkVhost'
225 2. If needed, recompile src for all OVS variants
227 .. code-block:: console
235 .. code-block:: console
237 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
239 To run tests using vhost-cuse as guest access method:
241 1. Set VHOST_METHOD and VNF of your settings file to:
243 .. code-block:: console
246 VNF = 'QemuDpdkVhostCuse'
248 2. If needed, recompile src for all OVS variants
250 .. code-block:: console
258 .. code-block:: console
260 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
262 Executing PVP tests using Vanilla OVS
263 -------------------------------------
264 To run tests using Vanilla OVS:
266 1. Set the following variables:
268 .. code-block:: console
270 VSWITCH = 'OvsVanilla'
271 VNF = 'QemuVirtioNet'
273 VANILLA_TGEN_PORT1_IP = n.n.n.n
274 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
276 VANILLA_TGEN_PORT2_IP = n.n.n.n
277 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
279 VANILLA_BRIDGE_IP = n.n.n.n
283 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
284 --test-param "vanilla_tgen_tx_ip=n.n.n.n;
285 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
288 2. If needed, recompile src for all OVS variants
290 .. code-block:: console
298 .. code-block:: console
300 $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
302 Selection of loopback application for PVP and PVVP tests
303 --------------------------------------------------------
304 To select loopback application, which will perform traffic forwarding
305 inside VM, following configuration parameter should be configured:
307 .. code-block:: console
309 GUEST_LOOPBACK = ['testpmd', 'testpmd']
313 .. code-block:: console
315 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
316 --test-param "guest_loopback=testpmd"
318 Supported loopback applications are:
320 .. code-block:: console
322 'testpmd' - testpmd from dpdk will be built and used
323 'l2fwd' - l2fwd module provided by Huawei will be built and used
324 'linux_bridge' - linux bridge will be configured
325 'buildin' - nothing will be configured by vsperf; VM image must
326 ensure traffic forwarding between its interfaces
328 Guest loopback application must be configured, otherwise traffic
329 will not be forwarded by VM and testcases with PVP and PVVP deployments
330 will fail. Guest loopback application is set to 'testpmd' by default.
332 Executing Packet Forwarding tests
333 -----------------------------------
335 To select application, which will perform packet forwarding,
336 following configuration parameter should be configured:
338 .. code-block:: console
343 or use --vswitch and --fwdapp
345 $ ./vsperf --conf-file user_settings.py
349 Supported Packet Forwarding applications are:
351 .. code-block:: console
353 'testpmd' - testpmd from dpdk
356 1. Update your ''10_custom.conf'' file to use the appropriate variables
357 for selected Packet Forwarder:
358 .. code-block:: console
360 # testpmd configuration
362 # packet forwarding mode: io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho
363 TESTPMD_FWD_MODE = 'csum'
364 # checksum calculation layer: ip|udp|tcp|sctp|outer-ip
365 TESTPMD_CSUM_LAYER = 'ip'
366 # checksum calculation place: hw (hardware) | sw (software)
367 TESTPMD_CSUM_CALC = 'sw'
368 # recognize tunnel headers: on|off
369 TESTPMD_CSUM_PARSE_TUNNEL = 'off'
373 .. code-block:: console
375 $ ./vsperf --conf-file <path_to_settings_py>
377 VSPERF modes of operation
378 -------------------------
379 VSPERF can be run in different modes. By default it will configure vSwitch,
380 traffic generator and VNF. However it can be used just for configuration
381 and execution of traffic generator. Another option is execution of all
382 components except traffic generator itself.
384 Mode of operation is driven by configuration parameter -m or --mode
386 .. code-block:: console
388 -m MODE, --mode MODE vsperf mode of operation;
390 "normal" - execute vSwitch, VNF and traffic generator
391 "trafficgen" - execute only traffic generator
392 "trafficgen-off" - execute vSwitch and VNF
394 In case, that VSPERF is executed in "trafficgen" mode, then configuration
395 of traffic generator should be configured through --test-param option.
396 Supported CLI options useful for traffic generator configuration are:
398 .. code-block:: console
400 'traffic_type' - One of the supported traffic types. E.g. rfc2544,
401 back2back or continuous
402 Default value is "rfc2544".
403 'bidirectional' - Specifies if generated traffic will be full-duplex (true)
404 or half-duplex (false)
405 Default value is "false".
406 'iload' - Defines desired percentage of frame rate used during
407 continuous stream tests.
408 Default value is 100.
409 'multistream' - Defines number of flows simulated by traffic generator.
410 Value 0 disables MultiStream feature
412 'stream_type' - Stream Type is an extension of the "MultiStream" feature.
413 If MultiStream is disabled, then Stream Type will be
414 ignored. Stream Type defines ISO OSI network layer used
415 for simulation of multiple streams.
416 Default value is "L4".
418 Example of execution of VSPERF in "trafficgen" mode:
420 .. code-block:: console
422 $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf
423 --test-params "traffic_type=continuous;bidirectional=True;iload=60"
425 Code change verification by pylint
426 ----------------------------------
427 Every developer participating in VSPERF project should run
428 pylint before his python code is submitted for review. Project
429 specific configuration for pylint is available at 'pylint.rc'.
431 Example of manual pylint invocation:
433 .. code-block:: console
435 $ pylint --rcfile ./pylintrc ./vsperf
440 OVS with DPDK and QEMU
441 ~~~~~~~~~~~~~~~~~~~~~~~
442 If you encounter the following error: "before (last 100 chars):
443 '-path=/dev/hugepages,share=on: unable to map backing store for
444 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
445 deployment scenario, check the amount of hugepages on your system:
447 .. code-block:: console
449 $ cat /proc/meminfo | grep HugePages
452 By default the vswitchd is launched with 1Gb of memory, to change
453 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
454 an appropriate amount of memory:
456 .. code-block:: console
458 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']