docs/testing/user/userguide/quickstart_docker.rst

   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
   4
   5 ===========================================
   6 NFVbench Installation and Quick Start Guide
   7 ===========================================
   8
   9 .. _docker_installation:
  10
  11 Make sure you satisfy the `hardware and software requirements <requirements>` before you start .
  12
  13
  14 1. Container installation
  15 -------------------------
  16
  17 To pull the latest NFVbench container image:
  18
  19 .. code-block:: bash
  20
  21     docker pull opnfv/nfvbench
  22
  23 2. Docker Container configuration
  24 ---------------------------------
  25
  26 The NFVbench container requires the following Docker options to operate properly.
  27
  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 /usr/src/kernels:/usr/src/kernels                  | needed by TRex to build kernel modules when needed    |
  34 +-------------------------------------------------------+-------------------------------------------------------+
  35 | -v /dev:/dev                                          | needed by kernel modules in the container             |
  36 +-------------------------------------------------------+-------------------------------------------------------+
  37 | -v $PWD:/tmp/nfvbench                                 | optional but recommended to pass files between the    |
  38 |                                                       | host and the docker space (see examples below)        |
  39 |                                                       | Here we map the current directory on the host to the  |
  40 |                                                       | /tmp/nfvbench director in the container but any       |
  41 |                                                       | other similar mapping can work as well                |
  42 +-------------------------------------------------------+-------------------------------------------------------+
  43 | --net=host                                            | (optional) needed if you run the NFVbench             |
  44 |                                                       | server in the container (or use any appropriate       |
  45 |                                                       | docker network mode other than "host")                |
  46 +-------------------------------------------------------+-------------------------------------------------------+
  47 | --privileged                                          | (optional) required if SELinux is enabled on the host |
  48 +-------------------------------------------------------+-------------------------------------------------------+
  49 | -e HOST="127.0.0.1"                                   | (optional) required if REST server is enabled         |
  50 +-------------------------------------------------------+-------------------------------------------------------+
  51 | -e PORT=7556                                          | (optional) required if REST server is enabled         |
  52 +-------------------------------------------------------+-------------------------------------------------------+
  53 | -e CONFIG_FILE="/root/nfvbenchconfig.json             | (optional) required if REST server is enabled         |
  54 +-------------------------------------------------------+-------------------------------------------------------+
  55
  56 It can be convenient to write a shell script (or an alias) to automatically insert the necessary options.
  57
  58 The minimal configuration file required must specify the PCI addresses of the 2 NIC ports to use.
  59 If OpenStack is used, the openrc_file property must be defined to point to a valid OpenStack rc file.
  60
  61
  62 Here is an example of mimimal configuration using OpenStack where:
  63
  64 - the openrc file is located on the host current directory which is mapped under /tmp/nfvbench in the container (this is achieved using -v $PWD:/tmp/nfvbench)
  65 - the 2 NIC ports to use for generating traffic have the PCI addresses "04:00.0" and "04:00.1"
  66
  67 .. code-block:: bash
  68
  69     {
  70         "openrc_file": "/tmp/nfvbench/openrc",
  71         "traffic_generator": {
  72             "generator_profile": [
  73                 {
  74                     "interfaces": [
  75                         {
  76                             "pci": "04:00.0",
  77                             "port": 0,
  78                         },
  79                         {
  80                             "pci": "04:00.1",
  81                             "port": 1,
  82                         }
  83                     ],
  84                     "intf_speed": "",
  85                     "ip": "127.0.0.1",
  86                     "name": "trex-local",
  87                     "software_mode": false,
  88                     "tool": "TRex"
  89                 }
  90             ]
  91         }
  92     }
  93
  94 The other options in the minimal configuration must be present and must have the same values as above.
  95
  96 3. Start the Docker container
  97 -----------------------------
  98 As for any Docker container, you can execute NFVbench measurement sessions using a temporary container ("docker run" - which exits after each NFVbench run)
  99 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").
 100
 101 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).
 102 The second approach is more responsive as the delay is only incurred once when starting the container.
 103
 104 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)
 105
 106 First create a new working directory, and change the current working directory to there. A "nfvbench_ws" directory under your home directory is good place for that, and this is where the OpenStack RC file and NFVbench config file will sit.
 107
 108 To run NFVBench without server mode
 109
 110 .. code-block:: bash
 111
 112     cd ~/nfvbench_ws
 113     docker run --detach --net=host --privileged -v $PWD:/tmp/nfvbench -v /dev:/dev -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels --name nfvbench opnfv/nfvbench
 114
 115 To run NFVBench enabling REST server (mount the configuration json and the path for openrc)
 116
 117 .. code-block:: bash
 118
 119     cd ~/nfvbench_ws
 120     docker run --detach --net=host --privileged -e HOST="127.0.0.1" -e PORT=7556 -e CONFIG_FILE="/tmp/nfvbench/nfvbenchconfig.json -v $PWD:/tmp/nfvbench -v /dev:/dev -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels --name nfvbench opnfv/nfvbench start_rest_server
 121
 122
 123 The create an alias to make it easy to execute nfvbench commands directly from the host shell prompt:
 124
 125 .. code-block:: bash
 126
 127     alias nfvbench='docker exec -it nfvbench nfvbench'
 128
 129 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.
 130
 131 To verify it is working:
 132
 133 .. code-block:: bash
 134
 135     nfvbench --version
 136     nfvbench --help
 137
 138
 139 4. NFVbench configuration
 140 -------------------------
 141
 142 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:
 143
 144 .. code-block:: bash
 145
 146   openrc_file:
 147   traffic_generator:
 148       generator_profile:
 149           - name: trex-local
 150             tool: TRex
 151             ip: 127.0.0.1
 152             cores: 3
 153             software_mode: false,
 154             interfaces:
 155               - port: 0
 156                 pci:
 157               - port: 1
 158                 pci:
 159             intf_speed:
 160
 161 If OpenStack is used, 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
 162 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).
 163
 164 If OpenStack is not used, remove the openrc_file property.
 165
 166 The PCI address of the 2 physical interfaces that will be used by the traffic generator must be configured.
 167 The PCI address can be obtained for example by using the "lspci" Linux command. For example:
 168
 169 .. code-block:: bash
 170
 171     [root@sjc04-pod6-build ~]# lspci | grep 710
 172     0a:00.0 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 173     0a:00.1 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 174     0a:00.2 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 175     0a:00.3 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 176
 177
 178 Example of edited configuration with an OpenStack RC file stored in the current directory with the "openrc" name, and
 179 PCI addresses "0a:00.0" and "0a:00.1" (first 2 ports of the quad port NIC):
 180
 181 .. code-block:: bash
 182
 183   openrc_file: /tmp/nfvbench/openrc
 184   traffic_generator:
 185       generator_profile:
 186           - name: trex-local
 187             tool: TRex
 188             ip: 127.0.0.1
 189             cores: 3
 190             software_mode: false,
 191             interfaces:
 192               - port: 0
 193                 switch_port:
 194                 pci: "0a:00.0"
 195               - port: 1
 196                 switch_port:
 197                 pci: "0a:00.1"
 198             intf_speed:
 199
 200 .. warning::
 201
 202     You have to put quotes around the pci addresses as shown in the above example, otherwise TRex will read it wrong.
 203
 204 Alternatively, the full template with comments can be obtained using the --show-default-config option in yaml format:
 205
 206 .. code-block:: bash
 207
 208     nfvbench --show-default-config > my_nfvbench.cfg
 209
 210 Edit the nfvbench.cfg file to only keep those properties that need to be modified (preserving the nesting).
 211
 212 Make sure you have your nfvbench configuration file (my_nfvbench.cfg) and - if OpenStack is used - OpenStack RC file in your pre-created working directory.
 213
 214
 215 5. Run NFVbench
 216 ---------------
 217
 218 To do a single run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:
 219
 220 .. code-block:: bash
 221
 222    nfvbench -c /tmp/nfvbench/my_nfvbench.cfg --rate 10kpps
 223
 224 NFVbench options used:
 225
 226 * ``-c /tmp/nfvbench/my_nfvbench.cfg`` : specify the config file to use (this must reflect the file path from inside the container)
 227 * ``--rate 10kpps`` : specify rate of packets for test for both directions using the kpps unit (thousands of packets per second)
 228
 229 This should produce a result similar to this (a simple run with the above options should take less than 5 minutes):
 230
 231 .. code-block:: none
 232
 233   [TBP]
 234
 235
 236 7. Terminating the NFVbench container
 237 -------------------------------------
 238 When no longer needed, the container can be terminated using the usual docker commands:
 239
 240 .. code-block:: bash
 241
 242     docker kill nfvbench
 243     docker rm nfvbench