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/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 /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 ok         |
  42 |                                                      | server in the container (or use any appropriate      |
  43 |                                                      | docker network mode other than "host")               |
  44 +------------------------------------------------------+------------------------------------------------------+
  45 | --privileged                                         | (optional) required if SELinux is enabled on the host|
  46 +------------------------------------------------------+------------------------------------------------------+
  47 | -e HOST="127.0.0.1"                                  | (optional) required if REST server is enabled        |
  48 +------------------------------------------------------+------------------------------------------------------+
  49 | -e PORT=7556                                         | (optional) required if REST server is enabled        |
  50 +------------------------------------------------------+------------------------------------------------------+
  51 | -e CONFIG_FILE="/root/nfvbenchconfig.json            | (optional) required if REST server is enabled        |
  52 +------------------------------------------------------+------------------------------------------------------+
  53
  54 It can be convenient to write a shell script (or an alias) to automatically insert the necessary options.
  55
  56 The minimal configuration file required must specify the openrc file to use (using in-container path), the PCI addresses of the 2 NIC ports to use
  57 for generating traffic and the line rate (in each direction) of each of these 2 interfaces.
  58
  59 Here is an example of mimimal configuration where:
  60 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)
  61 the 2 NIC ports to use for generating traffic have the PCI addresses "04:00.0" and "04:00.1"
  62
  63 .. code-block:: bash
  64
  65     {
  66         "openrc_file": "/tmp/nfvbench/openrc",
  67         "traffic_generator": {
  68             "generator_profile": [
  69                 {
  70                     "interfaces": [
  71                         {
  72                             "pci": "04:00.0",
  73                             "port": 0,
  74                         },
  75                         {
  76                             "pci": "04:00.1",
  77                             "port": 1,
  78                         }
  79                     ],
  80                     "intf_speed": "10Gbps",
  81                     "ip": "127.0.0.1",
  82                     "name": "trex-local",
  83                     "tool": "TRex"
  84                 }
  85             ]
  86         }
  87     }
  88
  89 The other options in the minimal configuration must be present and must have the same values as above.
  90
  91 3. Start the Docker container
  92 -----------------------------
  93 As for any Docker container, you can execute NFVbench measurement sessions using a temporary container ("docker run" - which exits after each NFVbench run)
  94 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").
  95
  96 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).
  97 The second approach is more responsive as the delay is only incurred once when starting the container.
  98
  99 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)
 100
 101 To run NFVBench without server mode
 102
 103 .. code-block:: bash
 104
 105     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
 106
 107 To run NFVBench enabling REST server (mount the configuration json and the path for openrc)
 108
 109 .. code-block:: bash
 110
 111     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) --name nfvbench opnfv/nfvbench start_rest_server
 112
 113
 114 The create an alias to make it easy to execute nfvbench commands directly from the host shell prompt:
 115
 116 .. code-block:: bash
 117
 118     alias nfvbench='docker exec -it nfvbench nfvbench'
 119
 120 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.
 121
 122 To verify it is working:
 123
 124 .. code-block:: bash
 125
 126     nfvbench --version
 127     nfvbench --help
 128
 129
 130 4. NFVbench configuration
 131 -------------------------
 132
 133 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:
 134
 135 .. code-block:: bash
 136
 137   openrc_file:
 138   traffic_generator:
 139       generator_profile:
 140           - name: trex-local
 141             tool: TRex
 142             ip: 127.0.0.1
 143             cores: 3
 144             interfaces:
 145               - port: 0
 146                 switch_port:
 147                 pci:
 148               - port: 1
 149                 switch_port:
 150                 pci:
 151             intf_speed: 10Gbps
 152
 153 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
 154 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).
 155
 156 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:
 157
 158 .. code-block:: bash
 159
 160     [root@sjc04-pod6-build ~]# lspci | grep 710
 161     0a:00.0 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 162     0a:00.1 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 163     0a:00.2 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 164     0a:00.3 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
 165
 166
 167 Example of edited configuration with an OpenStack RC file stored in the current directory with the "openrc" name, and
 168 PCI addresses "0a:00.0" and "0a:00.1" (first 2 ports of the quad port NIC):
 169
 170 .. code-block:: bash
 171
 172   openrc_file: /tmp/nfvbench/openrc
 173   traffic_generator:
 174       generator_profile:
 175           - name: trex-local
 176             tool: TRex
 177             ip: 127.0.0.1
 178             cores: 3
 179             interfaces:
 180               - port: 0
 181                 switch_port:
 182                 pci: 0a:00.0
 183               - port: 1
 184                 switch_port:
 185                 pci: 0a:00.1
 186             intf_speed: 10Gbps
 187
 188 Alternatively, the full template with comments can be obtained using the --show-default-config option in yaml format:
 189
 190 .. code-block:: bash
 191
 192     nfvbench --show-default-config > my_nfvbench.cfg
 193
 194 Edit the nfvbench.cfg file to only keep those properties that need to be modified (preserving the nesting)
 195
 196
 197 5. Run NFVbench
 198 ---------------
 199
 200 To do a single run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:
 201
 202 .. code-block:: bash
 203
 204    nfvbench -c /tmp/nfvbench/my_nfvbench.cfg --rate 10kpps
 205
 206 NFVbench options used:
 207
 208 * ``-c /tmp/nfvbench/my_nfvbench.cfg`` : specify the config file to use (this must reflect the file path from inside the container)
 209 * ``--rate 10kpps`` : specify rate of packets for test for both directions using the kpps unit (thousands of packets per second)
 210
 211 This should produce a result similar to this (a simple run with the above options should take less than 5 minutes):
 212
 213 .. code-block:: none
 214
 215   [TBP]
 216
 217
 218 7. Terminating the NFVbench container
 219 -------------------------------------
 220 When no longer needed, the container can be terminated using the usual docker commands:
 221
 222 .. code-block:: bash
 223
 224     docker kill nfvbench
 225     docker rm nfvbench
 226