docs/user/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 NFVbench can be used in CLI mode or in REST server mode.
  15 The CLI mode allows to run NFVbench benchmarks from the CLI. The REST server mode allows to run NFVbench benchmarks through a REST interface.
  16
  17 1. Container installation
  18 -------------------------
  19
  20 To pull the latest NFVbench container image:
  21
  22 .. code-block:: bash
  23
  24     docker pull opnfv/nfvbench
  25
  26 2. NFVbench configuration file
  27 ------------------------------
  28
  29 Create a directory under $HOME called nfvbench to store the minimal configuration file:
  30
  31 .. code-block:: bash
  32
  33     mkdir $HOME/nfvbench
  34
  35 Create a new file containing the minimal configuration for NFVbench, we can call it any name, for example "nfvbench.cfg" and paste the following yaml template in the file:
  36
  37 .. code-block:: bash
  38
  39   openrc_file: /tmp/nfvbench/openrc
  40   traffic_generator:
  41       generator_profile:
  42           - name: trex-local
  43             tool: TRex
  44             ip: 127.0.0.1
  45             cores: 3
  46             software_mode: false
  47             interfaces:
  48               - port: 0
  49                 pci: "0a:00.0"
  50               - port: 1
  51                 pci: "0a:00.1"
  52             intf_speed:
  53
  54 If OpenStack is not used, the openrc_file property can be removed.
  55
  56 If OpenStack is used, the openrc_file property must contain a valid container pathname of the OpenStack ``openrc`` file to connect to OpenStack using the OpenStack API.
  57 This file can be downloaded from the OpenStack Horizon dashboard (refer to the OpenStack documentation on how to
  58 retrieve the openrc file). This property must point to a valid pathname in the container (/tmp/nfvbench/openrc).
  59 We will map the host $HOME/nfvbench directory to the container /tmp/nfvbench directory and name the file "openrc".
  60 The file name viewed from the container will be "/tmp/nfvbench/openrc" (see container file pathname mapping in the next sections).
  61
  62 The PCI address of the 2 physical interfaces that will be used by the traffic generator must be configured.
  63 The PCI address can be obtained for example by using the "lspci" Linux command. For example:
  64
  65 .. code-block:: bash
  66
  67     [root@sjc04-pod6-build ~]# lspci | grep 710
  68     0a:00.0 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
  69     0a:00.1 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
  70     0a:00.2 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
  71     0a:00.3 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
  72
  73 In the above example, the PCI addresses "0a:00.0" and "0a:00.1" (first 2 ports of the quad port NIC) are used.
  74
  75 .. warning::
  76
  77     You have to put quotes around the pci addresses as shown in the above example, otherwise TRex will read it wrong.
  78     The other fields in the minimal configuration must be present and must have the same values as above.
  79
  80
  81 3. Starting NFVbench in CLI mode
  82 --------------------------------
  83
  84 In this mode, the NFVbench code will reside in a container running in the background. This container will not run anything in the background.
  85 An alias is then used to invoke a new NFVbench benchmark run using docker exec.
  86 The $HOME/nfvbench directory on the host is mapped on the /tmp/nfvbench in the container to facilitate file sharing between the 2 environments.
  87
  88 Start NFVbench container
  89 ~~~~~~~~~~~~~~~~~~~~~~~~
  90 The NFVbench container can be started using docker run command or using docker compose.
  91
  92 To run NFVBench in CLI mode using docker run:
  93
  94 .. code-block:: bash
  95
  96     docker run --name nfvbench --detach --privileged -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels -v /dev:/dev -v $HOME/nfvbench:/tmp/nfvbench opnfv/nfvbench
  97
  98 +-------------------------------------------------------+-------------------------------------------------------+
  99 | Docker options                                        | Description                                           |
 100 +=======================================================+=======================================================+
 101 | --name nfvbench                                       | container name is "nfvbench"                          |
 102 +-------------------------------------------------------+-------------------------------------------------------+
 103 | --detach                                              | run container in background                           |
 104 +-------------------------------------------------------+-------------------------------------------------------+
 105 | --privileged                                          | (optional) required if SELinux is enabled on the host |
 106 +-------------------------------------------------------+-------------------------------------------------------+
 107 | -v /lib/modules:/lib/modules                          | needed by kernel modules in the container             |
 108 +-------------------------------------------------------+-------------------------------------------------------+
 109 | -v /usr/src/kernels:/usr/src/kernels                  | needed by TRex to build kernel modules when needed    |
 110 +-------------------------------------------------------+-------------------------------------------------------+
 111 | -v /dev:/dev                                          | needed by kernel modules in the container             |
 112 +-------------------------------------------------------+-------------------------------------------------------+
 113 | -v $HOME/nfvbench:/tmp/nfvbench                       | folder mapping to pass files between the              |
 114 |                                                       | host and the docker space (see examples below)        |
 115 |                                                       | Here we map the $HOME/nfvbench directory on the host  |
 116 |                                                       | to the /tmp/nfvbench director in the container.       |
 117 |                                                       | Any other mapping can work as well                    |
 118 +-------------------------------------------------------+-------------------------------------------------------+
 119 | opnfv/nfvbench                                        | container image name                                  |
 120 +-------------------------------------------------------+-------------------------------------------------------+
 121
 122 To run NFVbench using docker compose, create the docker-compose.yml file and paste the following content:
 123
 124 .. code-block:: bash
 125
 126     version: '3'
 127     services:
 128         nfvbench:
 129             image: "opnfv/nfvbench"
 130             container_name: "nfvbench"
 131             volumes:
 132                 - /dev:/dev
 133                 - /usr/src/kernels:/usr/src/kernels
 134                 - /lib/modules:/lib/modules
 135                 - ${HOME}/nfvbench:/tmp/nfvbench
 136             network_mode: "host"
 137             privileged: true
 138
 139 Then start the container in detached mode:
 140
 141 .. code-block:: bash
 142
 143     docker-compose up -d
 144
 145 Requesting an NFVbench benchmark run
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 Create an alias to make it easy to execute nfvbench commands directly from the host shell prompt:
 149
 150 .. code-block:: bash
 151
 152     alias nfvbench='docker exec -it nfvbench nfvbench'
 153
 154 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 inside the container.
 155
 156 Once the alias is set, NFVbench runs can simply be requested from teh command line using "nfvbench <options>".
 157
 158 To verify it is working:
 159
 160 .. code-block:: bash
 161
 162     nfvbench --version
 163     nfvbench --help
 164
 165 Example of run
 166 ~~~~~~~~~~~~~~
 167
 168 To do a single run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:
 169
 170 .. code-block:: bash
 171
 172    nfvbench -c /tmp/nfvbench/nfvbench.cfg --rate 10kpps
 173
 174 NFVbench options used:
 175
 176 * ``-c /tmp/nfvbench/nfvbench.cfg`` : specify the config file to use
 177 * ``--rate 10kpps`` : specify rate of packets for test for both directions using the kpps unit (thousands of packets per second)
 178
 179
 180 Retrieve complete configuration file as template
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 The full configuration file template with comments (yaml format) can be obtained using the --show-default-config option in order to use more advanced configuration options:
 184
 185 .. code-block:: bash
 186
 187     nfvbench --show-default-config > $HOME/nfvbench/full_nfvbench.cfg
 188
 189 Edit the full_nfvbench.cfg file to only keep those properties that need to be modified (preserving the nesting).
 190
 191
 192 4. Start NFVbench in REST server mode
 193 -------------------------------------
 194 In this mode, the NFVbench REST server will run in the container.
 195 The $HOME/nfvbench directory on the host is mapped on the /tmp/nfvbench in the container to facilitate file sharing between the 2 environments.
 196
 197 Start NFVbench container
 198 ~~~~~~~~~~~~~~~~~~~~~~~~
 199
 200 To start the NFVbench container with REST server using docker run cli:
 201
 202 .. code-block:: bash
 203
 204     docker run --name nfvbench --detach --privileged --net=host -e CONFIG_FILE="/tmp/nfvbench/nfvbench.cfg" -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels -v /dev:/dev -v $HOME/nfvbench:/tmp/nfvbench opnfv/nfvbench start_rest_server
 205
 206 REST mode requires the same arguments as CLI mode and adds the following options:
 207 +-------------------------------------------------------+-------------------------------------------------------+
 208 | Docker options                                        | Description                                           |
 209 +=======================================================+=======================================================+
 210 | --net=host                                            | use "host" docker networking mode                     |
 211 |                                                       | Other modes (such as NAT) could be used if required   |
 212 |                                                       | with proper adjustment of the port to use for REST    |
 213 +-------------------------------------------------------+-------------------------------------------------------+
 214 | -e CONFIG_FILE="/tmp/nfvbench/nfvbench.cfg"           | (optional)                                            |
 215 |                                                       | specify the initial NFVbench config file to use.      |
 216 |                                                       | defaults to none                                      |
 217 +-------------------------------------------------------+-------------------------------------------------------+
 218 | start_rest_server                                     | to request a REST server to run in background in the  |
 219 |                                                       | container                                             |
 220 +-------------------------------------------------------+-------------------------------------------------------+
 221 | -e HOST="127.0.0.1"                                   | (optional)                                            |
 222 |                                                       | specify the IP address to listen to.                  |
 223 |                                                       | defaults to 127.0.0.1                                 |
 224 +-------------------------------------------------------+-------------------------------------------------------+
 225 | -e PORT=7555                                          | (optional)                                            |
 226 |                                                       | specify the port address to listen to.                |
 227 |                                                       | defaults to 7555                                      |
 228 +-------------------------------------------------------+-------------------------------------------------------+
 229
 230
 231 The initial configuration file is optional but is handy to define mandatory deployment parameters that are common to all subsequent REST requests.
 232 If this initial configuration file is not passed at container start time, it must be included in every REST request.
 233
 234 To start the NFVbench container with REST server using docker compose, use the following compose file:
 235
 236 .. code-block:: bash
 237
 238     version: '3'
 239     services:
 240         nfvbench:
 241             image: "opnfv/nfvbench"
 242             container_name: "nfvbench_server"
 243             command: start_rest_server
 244             volumes:
 245                 - /dev:/dev
 246                 - /usr/src/kernels:/usr/src/kernels
 247                 - /lib/modules:/lib/modules
 248                 - ${HOME}/nfvbench:/tmp/nfvbench
 249             network_mode: "host"
 250             environment:
 251                 - HOST="127.0.0.1"
 252                 - PORT=7555
 253             privileged: true
 254
 255 Requesting an NFVbench benchmark run
 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 257 To request a benchmark run, you must create a JSON document that describes the benchmark and send it to the NFVbench server in the body of a POST request.
 258
 259
 260 Examples of REST requests
 261 ~~~~~~~~~~~~~~~~~~~~~~~~~
 262 In this example, we will use curl to interact with the NFVbench REST server.
 263
 264 Query the NFVbench version:
 265
 266 .. code-block:: bash
 267
 268     [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/version
 269     3.1.1
 270
 271 This is the JSON for a fixed rate run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:
 272
 273 .. code-block:: bash
 274
 275     {"rate": "10kpps"}
 276
 277 This is the curl request to send this benchmark request to the NFVbench server:
 278
 279 .. code-block:: bash
 280
 281     [root@sjc04-pod3-mgmt ~]# curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"rate": "10kpps"}' http://127.0.0.1:7555/start_run
 282     {
 283       "error_message": "nfvbench run still pending",
 284       "status": "PENDING"
 285     }
 286     [root@sjc04-pod3-mgmt ~]#
 287
 288 This request will return immediately with status set to "PENDING" if the request was started successfully.
 289
 290 The status can be polled until the run completes. Here the poll returns a "PENDING" status, indicating the run is still not completed:
 291
 292 .. code-block:: bash
 293
 294     [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
 295     {
 296       "error_message": "nfvbench run still pending",
 297       "status": "PENDING"
 298     }
 299     [root@sjc04-pod3-mgmt ~]#
 300
 301 Finally, the status request returns a "OK" status along with the full results (truncated here):
 302
 303 .. code-block:: bash
 304
 305     [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
 306     {
 307       "result": {
 308         "benchmarks": {
 309           "network": {
 310             "service_chain": {
 311               "PVP": {
 312                 "result": {
 313                   "bidirectional": true,
 314
 315     ...
 316
 317       "status": "OK"
 318     }
 319     [root@sjc04-pod3-mgmt ~]#
 320
 321
 322 Retrieve complete configuration file as template
 323 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 324
 325
 326 7. Terminating the NFVbench container
 327 -------------------------------------
 328 When no longer needed, the container can be terminated using the usual docker commands:
 329
 330 .. code-block:: bash
 331
 332     docker kill nfvbench
 333     docker rm nfvbench