1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
3 .. (c) Cisco Systems, Inc
5 ===========================================
6 NFVbench Installation and Quick Start Guide
7 ===========================================
9 .. _docker_installation:
11 Make sure you satisfy the `hardware and software requirements <requirements>` before you start .
14 1. Container installation
15 -------------------------
17 To pull the latest NFVbench container image:
21 docker pull opnfv/nfvbench/nfvbench
23 2. Docker Container configuration
24 ---------------------------------
26 The NFVbench container requires the following Docker options to operate properly.
28 +------------------------------------------------------+------------------------------------------------------+
29 | Docker options | Description |
30 +======================================================+======================================================+
31 | -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) | needed by kernel modules in the container |
32 +------------------------------------------------------+------------------------------------------------------+
33 | -v /dev:/dev | needed by kernel modules in the container |
34 +------------------------------------------------------+------------------------------------------------------+
35 | -v $PWD:/tmp/nfvbench | optional but recommended to pass files between the |
36 | | host and the docker space (see examples below) |
37 | | Here we map the current directory on the host to the |
38 | | /tmp/nfvbench director in the container but any |
39 | | other similar mapping can work as well |
40 +------------------------------------------------------+------------------------------------------------------+
41 | --net=host | (optional) needed if you run the NFVbench REST |
42 | | server in the container (or use any appropriate |
43 | | docker network mode other than "host") |
44 +------------------------------------------------------+------------------------------------------------------+
45 | --privilege | (optional) required if SELinux is enabled on the host|
46 +------------------------------------------------------+------------------------------------------------------+
48 It can be convenient to write a shell script (or an alias) to automatically insert the necessary options.
50 3. Start the Docker container
51 -----------------------------
52 As for any Docker container, you can execute NFVbench measurement sessions using a temporary container ("docker run" - which exits after each NFVbench run)
53 or you can decide to run the NFVbench container in the background then execute one or more NFVbench measurement sessions on that container ("docker exec").
55 The former approach is simpler to manage (since each container is started and terminated after each command) but incurs a small delay at start time (several seconds).
56 The second approach is more responsive as the delay is only incurred once when starting the container.
58 We will take the second approach and start the NFVbench container in detached mode with the name "nfvbench" (this works with bash, prefix with "sudo" if you do not use the root login)
62 docker run --detach --net=host --privileged -v $PWD:/tmp/nfvbench -v /dev:/dev -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) --name nfvbench opnfv/nfvbench tail -f /dev/null
64 The tail command simply prevents the container from exiting.
66 The create an alias to make it easy to execute nfvbench commands directly from the host shell prompt:
70 alias nfvbench='docker exec -it nfvbench nfvbench'
72 The next to last "nfvbench" refers to the name of the container while the last "nfvbench" refers to the NFVbench binary that is available to run in the container.
74 To verify it is working:
82 4. NFVbench configuration
83 -------------------------
85 Create a new file containing the minimal configuration for NFVbench, we can call it any name, for example "my_nfvbench.cfg" and paste the following yaml template in the file:
105 NFVbench requires an ``openrc`` file to connect to OpenStack using the OpenStack API. This file can be downloaded from the OpenStack Horizon dashboard (refer to the OpenStack documentation on how to
106 retrieve the openrc file). The file pathname in the container must be stored in the "openrc_file" property. If it is stored on the host in the current directory, its full pathname must start with /tmp/nfvbench (since the current directory is mapped to /tmp/nfvbench in the container).
108 The required configuration is the PCI address of the 2 physical interfaces that will be used by the traffic generator. The PCI address can be obtained for example by using the "lspci" Linux command. For example:
112 [root@sjc04-pod6-build ~]# lspci | grep 710
113 0a:00.0 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
114 0a:00.1 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
115 0a:00.2 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
116 0a:00.3 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
119 Example of edited configuration with an OpenStack RC file stored in the current directory with the "openrc" name, and
120 PCI addresses "0a:00.0" and "0a:00.1" (first 2 ports of the quad port NIC):
124 openrc_file: /tmp/nfvbench/openrc
140 Alternatively, the full template with comments can be obtained using the --show-default-config option in yaml format:
144 nfvbench --show-default-config > my_nfvbench.cfg
146 Edit the nfvbench.cfg file to only keep those properties that need to be modified (preserving the nesting)
149 5. Upload the NFVbench loopback VM image to OpenStack
150 -----------------------------------------------------
151 [TBP URL to NFVbench VM image in the OPNFV artifact repository]
157 To do a single run at 5000pps bi-directional using the PVP packet path:
161 nfvbench -c /tmp/nfvbench/my_nfvbench.cfg --rate 5kpps
163 NFVbench options used:
165 * ``-c /tmp/nfvbench/my_nfvbench.cfg`` : specify the config file to use (this must reflect the file path from inside the container)
166 * ``--rate 5kpps`` : specify rate of packets for test using the kpps unit (thousands of packets per second)
168 This should produce a result similar to this (a simple run with the above options should take less than 5 minutes):
172 ========== nfvbench Summary ==========
173 Date: 2016-10-05 21:43:30
174 nfvbench version 0.0.1.dev128
175 Mercury version: 5002
178 > N9K version: {'10.28.108.249': {'BIOS': '07.34', 'NXOS': '7.0(3)I2(2b)'}, '10.28.108.248': {'BIOS': '07.34', 'NXOS': '7.0(3)I2(2b)'}}
179 Traffic generator profile: trex-c45
180 Traffic generator tool: TRex
181 Traffic generator API version: {u'build_date': u'Aug 24 2016', u'version': u'v2.08', u'built_by': u'hhaim', u'build_time': u'16:32:13'}
184 VPP version: {u'sjc04-pod3-compute-6': 'v16.06-rc1~27-gd175728'}
185 > Bidirectional: False
186 Profile: traffic_profile_64B
188 +-----------------+-------------+----------------------+----------------------+----------------------+
189 | L2 Frame Size | Drop Rate | Avg Latency (usec) | Min Latency (usec) | Max Latency (usec) |
190 +=================+=============+======================+======================+======================+
191 | 64 | 0.0000% | 22.1885 | 10 | 503 |
192 +-----------------+-------------+----------------------+----------------------+----------------------+
196 Flow analysis duration: 70.0843 seconds
200 +-------------+------------------+--------------+-----------+
201 | Direction | Duration (sec) | Rate | Rate |
202 +=============+==================+==============+===========+
203 | Forward | 60 | 1.0080 Mbps | 1,500 pps |
204 +-------------+------------------+--------------+-----------+
205 | Reverse | 60 | 672.0000 bps | 1 pps |
206 +-------------+------------------+--------------+-----------+
208 +----------------------+----------+-----------------+---------------+---------------+-----------------+---------------+---------------+
209 | Interface | Device | Packets (fwd) | Drops (fwd) | Drop% (fwd) | Packets (rev) | Drops (rev) | Drop% (rev) |
210 +======================+==========+=================+===============+===============+=================+===============+===============+
211 | traffic-generator | trex | 90,063 | | | 61 | 0 | - |
212 +----------------------+----------+-----------------+---------------+---------------+-----------------+---------------+---------------+
213 | traffic-generator | trex | 90,063 | 0 | - | 61 | | |
214 +----------------------+----------+-----------------+---------------+---------------+-----------------+---------------+---------------+
216 7. Terminating the NFVbench container
217 -------------------------------------
218 When no longer needed, the container can be terminated using the usual docker commands: