1 Getting Started with 'vsperf'
2 =============================
7 VSPERF requires one of the following traffic generators to run tests:
9 - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA client software
10 - Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual in a VM) and a
11 VM to run the Spirent Virtual Deployment Service image, formerly known as "Spirent LabServer".
13 Both test configurations, above, also require a CentOS Linux release 7.1.1503 (Core) host.
18 The vSwitch must support Open Flow 1.3 or greater.
23 Follow the `installation instructions <installation.html>`__ to install.
28 On the CentOS 7 system
29 ~~~~~~~~~~~~~~~~~~~~~~
31 You need to install IxNetworkTclClient$(VER\_NUM)Linux.bin.tgz.
33 On the IXIA client software system
34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 Find the IxNetwork TCL server app (start -> All Programs -> IXIA ->
37 IxNetwork -> IxNetwork\_$(VER\_NUM) -> IxNetwork TCL Server)
39 Right click on IxNetwork TCL Server, select properties - Under shortcut tab in
40 the Target dialogue box make sure there is the argument "-tclport xxxx"
41 where xxxx is your port number (take note of this port number you will
42 need it for the 10\_custom.conf file).
46 Hit Ok and start the TCL server application
51 Spirent installation files and instructions are available on the
52 Spirent support website at:
54 http://support.spirent.com
56 Select a version of Spirent TestCenter software to utilize. This example
57 will use Spirent TestCenter v4.57 as an example. Substitute the appropriate
58 version in place of 'v4.57' in the examples, below.
60 On the CentOS 7 System
61 ~~~~~~~~~~~~~~~~~~~~~~
63 Download and install the following:
65 Spirent TestCenter Application, v4.57 for 64-bit Linux Client
67 Spirent Virtual Deployment Service (VDS)
68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70 Spirent VDS is required for both TestCenter hardware and virtual
71 chassis in the vsperf environment. For installation, select the version
72 that matches the Spirent TestCenter Application version. For v4.57,
73 the matching VDS version is 1.0.55. Download either the ova (VMware)
74 or qcow2 (QEMU) image and create a VM with it. Initialize the VM
75 according to Spirent installation instructions.
77 Using Spirent TestCenter Virtual (STCv)
78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80 STCv is available in both ova (VMware) and qcow2 (QEMU) formats. For
83 Spirent TestCenter Virtual Machine for VMware, v4.57 for Hypervisor - VMware ESX.ESXi
85 Virtual test port performance is affected by the hypervisor configuration. For
86 best practice results in deploying STCv, the following is suggested:
88 - Create a single VM with two test ports rather than two VMs with one port each
89 - Set STCv in DPDK mode
90 - Give STCv 2*n + 1 cores, where n = the number of ports. For vsperf, cores = 5.
91 - Turning off hyperthreading and pinning these cores will improve performance
92 - Give STCv 2 GB of RAM
94 To get the highest performance and accuracy, Spirent TestCenter hardware is
95 recommended. vsperf can run with either stype test ports.
97 Cloning and building src dependencies
98 -------------------------------------
100 In order to run VSPERF, you will need to download DPDK and OVS. You can
101 do this manually and build them in a preferred location, or you could
102 use vswitchperf/src. The vswitchperf/src directory contains makefiles
103 that will allow you to clone and build the libraries that VSPERF depends
104 on, such as DPDK and OVS. To clone and build simply:
106 .. code-block:: console
111 VSPERF can be used with OVS without DPDK support. In this case you have
112 to specify path to the kernel sources by WITH\_LINUX parameter:
114 .. code-block:: console
117 make WITH_LINUX=/lib/modules/`uname -r`/build
119 To build DPDK and OVS for PVP and PVVP testing with vhost_user as the guest
122 .. code-block:: console
126 To delete a src subdirectory and its contents to allow you to re-clone simply
129 .. code-block:: console
133 Configure the ``./conf/10_custom.conf`` file
134 --------------------------------------------
136 The supplied ``10_custom.conf`` file must be modified, as it contains
137 configuration items for which there are no reasonable default values.
139 The configuration items that can be added is not limited to the initial
140 contents. Any configuration item mentioned in any .conf file in
141 ``./conf`` directory can be added and that item will be overridden by
142 the custom configuration value.
144 Using a custom settings file
145 ----------------------------
147 Alternatively a custom settings file can be passed to ``vsperf`` via the
148 ``--conf-file`` argument.
150 .. code-block:: console
152 ./vsperf --conf-file <path_to_settings_py> ...
154 Note that configuration passed in via the environment (``--load-env``)
155 or via another command line argument will override both the default and
156 your custom configuration files. This "priority hierarchy" can be
157 described like so (1 = max priority):
159 1. Command line arguments
160 2. Environment variables
161 3. Configuration file(s)
168 Before running any tests make sure you have root permissions by adding
169 the following line to /etc/sudoers:
171 .. code-block:: console
173 username ALL=(ALL) NOPASSWD: ALL
175 username in the example above should be replaced with a real username.
177 To list the available tests:
179 .. code-block:: console
181 ./vsperf --list-tests
183 To run a group of tests, for example all tests with a name containing
186 .. code-block:: console
188 ./vsperf --conf-file=user_settings.py --tests="RFC2544"
192 .. code-block:: console
194 ./vsperf --conf-file=user_settings.py
196 Some tests allow for configurable parameters, including test duration
197 (in seconds) as well as packet sizes (in bytes).
201 ./vsperf --conf-file user_settings.py
203 --test-param "rfc2544_duration=10;packet_sizes=128"
205 For all available options, check out the help dialog:
207 .. code-block:: console
211 Executing PVP and PVVP tests
212 ----------------------------
213 To run tests using vhost-user as guest access method:
215 1. Set VHOST_METHOD and VNF of your settings file to:
217 .. code-block:: console
220 VNF = 'QemuDpdkVhost'
222 2. Recompile src for VHOST USER testing
224 .. code-block:: console
232 .. code-block:: console
234 ./vsperf --conf-file <path_to_settings_py>
236 To run tests using vhost-cuse as guest access method:
238 1. Set VHOST_METHOD and VNF of your settings file to:
240 .. code-block:: console
243 VNF = 'QemuDpdkVhostCuse'
245 2. Recompile src for VHOST USER testing
247 .. code-block:: console
255 .. code-block:: console
257 ./vsperf --conf-file <path_to_settings_py>
259 Executing PVP tests using Vanilla OVS
260 -------------------------------------
261 To run tests using Vanilla OVS:
263 1. Set the following variables:
265 .. code-block:: console
267 VSWITCH = 'OvsVanilla'
268 VNF = 'QemuVirtioNet'
270 VANILLA_TGEN_PORT1_IP = n.n.n.n
271 VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn
273 VANILLA_TGEN_PORT2_IP = n.n.n.n
274 VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn
276 VANILLA_BRIDGE_IP = n.n.n.n
280 ./vsperf --conf-file user_settings.py
281 --test-param "vanilla_tgen_tx_ip=n.n.n.n;
282 vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
285 2. Recompile src for Vanilla OVS testing
287 .. code-block:: console
291 make WITH_LINUX=/lib/modules/`uname -r`/build
295 .. code-block:: console
297 ./vsperf --conf-file <path_to_settings_py>
299 Code change verification by pylint
300 ----------------------------------
301 Every developer participating in VSPERF project should run
302 pylint before his python code is submitted for review. Project
303 specific configuration for pylint is available at 'pylint.rc'.
305 Example of manual pylint invocation:
307 .. code-block:: console
309 pylint --rcfile ./pylint.rc ./vsperf
314 OVS with DPDK and QEMU
315 ~~~~~~~~~~~~~~~~~~~~~~~
316 If you encounter the following error: "before (last 100 chars):
317 '-path=/dev/hugepages,share=on: unable to map backing store for
318 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
319 deployment scenario, check the amount of hugepages on your system:
323 cat /proc/meminfo | grep HugePages
326 By default the vswitchd is launched with 1Gb of memory, to change
327 this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate
328 an appropriate amount of memory:
332 VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
336 .. |Alt text| image:: images/TCLServerProperties.png