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