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/docs/guides/trafficgen.html>`__
21 Supported OSes include:
23 * CentOS Linux release 7.1.1503 (Core) host.
30 The vSwitch must support Open Flow 1.3 or greater. VSPERF supports both:
38 Follow the `installation instructions
39 <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/index.html>`__ to
42 Traffic Generator Setup
43 -----------------------
44 Follow the `Traffic generator instructions
45 <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__ to
46 install and configure a suitable traffic generator.
48 Cloning and building src dependencies
49 -------------------------------------
51 In order to run VSPERF, you will need to download DPDK and OVS. You can
52 do this manually and build them in a preferred location, OR you could
53 use vswitchperf/src. The vswitchperf/src directory contains makefiles
54 that will allow you to clone and build the libraries that VSPERF depends
55 on, such as DPDK and OVS. To clone and build simply:
57 .. code-block:: console
62 VSPERF can be used with stock OVS (without DPDK support). In this case you have
63 to specify path to the kernel sources when building OVS in src by specifying
64 WITH\_LINUX parameter:
66 .. code-block:: console
69 $ make WITH_LINUX=/lib/modules/`uname -r`/build
71 To build DPDK and OVS in the src directory for PVP and PVVP testing with
72 vhost_user as the guest access method, use:
74 .. code-block:: console
78 To build all options in src:
81 * OVS with vhost_user as the guest access method (with DPDK support)
82 * OVS with vhost_cuse s the guest access method (with DPDK support)
84 simply call 'make' in the src directory :
86 .. code-block:: console
90 The vhost_user build will reside in src/ovs/
91 The vhost_cuse build will reside in vswitchperf/src_cuse
92 The Vanilla OVS build will reside in vswitchperf/src_vanilla
94 To delete a src subdirectory and its contents to allow you to re-clone simply
97 .. code-block:: console
101 Configure the ``./conf/10_custom.conf`` file
102 --------------------------------------------
103 The ``10_custom.conf`` file is the configuration file that overrides
104 default configurations in all the other configuration files in ``./conf``
105 The supplied ``10_custom.conf`` file **MUST** be modified, as it contains
106 configuration items for which there are no reasonable default values.
108 The configuration items that can be added is not limited to the initial
109 contents. Any configuration item mentioned in any .conf file in
110 ``./conf`` directory can be added and that item will be overridden by
111 the custom configuration value.
113 Using a custom settings file
114 ----------------------------
116 If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
117 of if you want to use an alternative configuration file, the file can
118 be passed to ``vsperf`` via the ``--conf-file`` argument.
120 .. code-block:: console
122 $ ./vsperf --conf-file <path_to_custom_conf> ...
124 Note that configuration passed in via the environment (``--load-env``)
125 or via another command line argument will override both the default and
126 your custom configuration files. This "priority hierarchy" can be
127 described like so (1 = max priority):
129 1. Command line arguments
130 2. Environment variables
131 3. Configuration file(s)
138 Before running any tests make sure you have root permissions by adding
139 the following line to /etc/sudoers:
141 .. code-block:: console
143 username ALL=(ALL) NOPASSWD: ALL
145 username in the example above should be replaced with a real username.
147 To list the available tests:
149 .. code-block:: console
153 To run a single test:
155 .. code-block:: console
159 Where $TESTNAME is the name of the vsperf test you would like to run.
161 To run a group of tests, for example all tests with a name containing
164 .. code-block:: console
166 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
170 .. code-block:: console
172 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
174 Some tests allow for configurable parameters, including test duration
175 (in seconds) as well as packet sizes (in bytes).
179 $ ./vsperf --conf-file user_settings.py
181 --test-param "duration=10;pkt_sizes=128"
183 For all available options, check out the help dialog:
185 .. code-block:: console
189 Executing Vanilla OVS tests
190 ----------------------------
191 If you have compiled all the variants of OVS in ''src/'' please skip
194 1. Recompile src for Vanilla OVS testing
196 .. code-block:: console
200 $ make WITH_LINUX=/lib/modules/`uname -r`/build
202 2. Update your ''10_custom.conf'' file to use the appropriate variables
205 .. code-block:: console
207 VSWITCH = 'OvsVanilla'
208 VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1']
210 Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind
215 .. code-block:: console
217 $ ./vsperf --conf-file=<path_to_custom_conf>
219 Please note if you don't want to configure Vanilla OVS through the
220 configuration file, you can pass it as a CLI argument; BUT you must
223 .. code-block:: console
225 $ ./vsperf --vswitch OvsVanilla
228 Executing PVP and PVVP tests
229 ----------------------------
230 To run tests using vhost-user as guest access method:
232 1. Set VHOST_METHOD and VNF of your settings file to:
234 .. code-block:: console
237 VNF = 'QemuDpdkVhost'
239 2. Recompile src for VHOST USER testing
241 .. code-block:: console
249 .. code-block:: console
251 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
253 To run tests using vhost-cuse as guest access method:
255 1. Set VHOST_METHOD and VNF of your settings file to:
257 .. code-block:: console
260 VNF = 'QemuDpdkVhostCuse'
262 2. Recompile src for VHOST USER testing
264 .. code-block:: console
272 .. code-block:: console
274 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
276 Executing PVP tests using Vanilla OVS
277 -------------------------------------
278 To run tests using Vanilla OVS:
280 1. Set the following variables:
282 .. code-block:: console
284 VSWITCH = 'OvsVanilla'
285 VNF = 'QemuVirtioNet'
287 VANILLA_TGEN_PORT1_IP = n.n.n.n
288 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
290 VANILLA_TGEN_PORT2_IP = n.n.n.n
291 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
293 VANILLA_BRIDGE_IP = n.n.n.n
297 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
298 --test-param "vanilla_tgen_tx_ip=n.n.n.n;
299 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
302 2. Recompile src for Vanilla OVS testing
304 .. code-block:: console
308 $ make WITH_LINUX=/lib/modules/`uname -r`/build
312 .. code-block:: console
314 $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
316 Selection of loopback application for PVP and PVVP tests
317 --------------------------------------------------------
318 To select loopback application, which will perform traffic forwarding
319 inside VM, following configuration parameter should be configured:
321 .. code-block:: console
323 GUEST_LOOPBACK = ['testpmd', 'testpmd']
327 .. code-block:: console
329 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
330 --test-param "guest_loopback=testpmd"
332 Supported loopback applications are:
334 .. code-block:: console
336 'testpmd' - testpmd from dpdk will be built and used
337 'l2fwd' - l2fwd module provided by Huawei will be built and used
338 'linux_bridge' - linux bridge will be configured
339 'buildin' - nothing will be configured by vsperf; VM image must
340 ensure traffic forwarding between its interfaces
342 Guest loopback application must be configured, otherwise traffic
343 will not be forwarded by VM and testcases with PVP and PVVP deployments
344 will fail. Guest loopback application is set to 'testpmd' by default.
346 Executing Packet Forwarding tests
347 -----------------------------------
349 To select application, which will perform packet forwarding,
350 following configuration parameter should be configured:
352 .. code-block:: console
357 or use --vswitch and --fwdapp
359 $ ./vsperf --conf-file user_settings.py
363 Supported Packet Forwarding applications are:
365 .. code-block:: console
367 'testpmd' - testpmd from dpdk
370 1. Update your ''10_custom.conf'' file to use the appropriate variables
371 for selected Packet Forwarder:
372 .. code-block:: console
374 # testpmd configuration
376 # packet forwarding mode: io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho
377 TESTPMD_FWD_MODE = 'csum'
378 # checksum calculation layer: ip|udp|tcp|sctp|outer-ip
379 TESTPMD_CSUM_LAYER = 'ip'
380 # checksum calculation place: hw (hardware) | sw (software)
381 TESTPMD_CSUM_CALC = 'sw'
382 # recognize tunnel headers: on|off
383 TESTPMD_CSUM_PARSE_TUNNEL = 'off'
387 .. code-block:: console
389 $ ./vsperf --conf-file <path_to_settings_py>
391 VSPERF modes of operation
392 -------------------------
393 VSPERF can be run in different modes. By default it will configure vSwitch,
394 traffic generator and VNF. However it can be used just for configuration
395 and execution of traffic generator. Another option is execution of all
396 components except traffic generator itself.
398 Mode of operation is driven by configuration parameter -m or --mode
400 .. code-block:: console
402 -m MODE, --mode MODE vsperf mode of operation;
404 "normal" - execute vSwitch, VNF and traffic generator
405 "trafficgen" - execute only traffic generator
406 "trafficgen-off" - execute vSwitch and VNF
408 In case, that VSPERF is executed in "trafficgen" mode, then configuration
409 of traffic generator should be configured through --test-param option.
410 Supported CLI options useful for traffic generator configuration are:
412 .. code-block:: console
414 'traffic_type' - One of the supported traffic types. E.g. rfc2544,
415 back2back or continuous
416 Default value is "rfc2544".
417 'bidirectional' - Specifies if generated traffic will be full-duplex (true)
418 or half-duplex (false)
419 Default value is "false".
420 'iload' - Defines desired percentage of frame rate used during
421 continuous stream tests.
422 Default value is 100.
423 'multistream' - Defines number of flows simulated by traffic generator.
424 Value 0 disables MultiStream feature
426 'stream_type' - Stream Type is an extension of the "MultiStream" feature.
427 If MultiStream is disabled, then Stream Type will be
428 ignored. Stream Type defines ISO OSI network layer used
429 for simulation of multiple streams.
430 Default value is "L4".
432 Example of execution of VSPERF in "trafficgen" mode:
434 .. code-block:: console
436 $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf
437 --test-params "traffic_type=continuous;bidirectional=True;iload=60"
439 Code change verification by pylint
440 ----------------------------------
441 Every developer participating in VSPERF project should run
442 pylint before his python code is submitted for review. Project
443 specific configuration for pylint is available at 'pylint.rc'.
445 Example of manual pylint invocation:
447 .. code-block:: console
449 $ pylint --rcfile ./pylintrc ./vsperf
454 OVS with DPDK and QEMU
455 ~~~~~~~~~~~~~~~~~~~~~~~
456 If you encounter the following error: "before (last 100 chars):
457 '-path=/dev/hugepages,share=on: unable to map backing store for
458 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
459 deployment scenario, check the amount of hugepages on your system:
461 .. code-block:: console
463 $ cat /proc/meminfo | grep HugePages
466 By default the vswitchd is launched with 1Gb of memory, to change
467 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
468 an appropriate amount of memory:
470 .. code-block:: console
472 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']