nfvbenchvm/README.rst

   1 NFVBENCH VM IMAGES FOR OPENSTACK
   2 ++++++++++++++++++++++++++++++++
   3
   4 This repo will build two centos 7 images with:
   5     - testpmd and VPP installed for loop VM use case
   6     - NFVbench and TRex installed for generator VM use case
   7 The VM will come with a pre-canned user/password: nfvbench/nfvbench
   8
   9 BUILD INSTRUCTIONS
  10 ==================
  11
  12 Pre-requisites
  13 --------------
  14 - must run on Linux
  15 - the following packages must be installed prior to using this script:
  16     - git
  17     - qemu-utils
  18     - kpartx
  19
  20 Build the image
  21 ---------------
  22 - cd dib
  23 - update the version number for the image (if needed) by modifying __version__ in build-image.sh
  24 - setup your http_proxy if needed
  25 - to build loop VM image only:
  26     - `bash build-image.sh -l`
  27 - to build generator VM image only:
  28     - `bash build-image.sh -g`
  29 - to build both images only:
  30     - `bash build-image.sh`
  31
  32 LOOP VM IMAGE INSTANCE AND CONFIG
  33 =================================
  34
  35 Interface Requirements
  36 ----------------------
  37 The instance must be launched using OpenStack with 2 network interfaces.
  38 For best performance, it should use a flavor with:
  39
  40 - 2 vCPU
  41 - 4 GB RAM
  42 - cpu pinning set to exclusive
  43
  44 Auto-configuration
  45 ------------------
  46 nfvbench VM will automatically find the two virtual interfaces to use, and use the forwarder specifed in the config file.
  47
  48 In the case testpmd is used, testpmd will be launched with mac forwarding mode where the destination macs rewritten according to the config file.
  49
  50 In the case VPP is used, VPP will set up a L3 router, and forwarding traffic from one port to the other.
  51
  52 nfvbenchvm Config
  53 -----------------
  54 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
  55
  56 .. code-block:: bash
  57
  58     FORWARDER=testpmd
  59     INTF_MAC1=FA:16:3E:A2:30:41
  60     INTF_MAC2=FA:16:3E:10:DA:10
  61     TG_MAC1=00:10:94:00:0A:00
  62     TG_MAC2=00:11:94:00:0A:00
  63     VNF_GATEWAY1_CIDR=1.1.0.2/8
  64     VNF_GATEWAY2_CIDR=2.2.0.2/8
  65     TG_NET1=10.0.0.0/8
  66     TG_NET2=20.0.0.0/8
  67     TG_GATEWAY1_IP=1.1.0.100
  68     TG_GATEWAY2_IP=2.2.0.100
  69
  70
  71 Launching nfvbenchvm VM
  72 -----------------------
  73
  74 Normally this image will be used together with NFVBench, and the required configurations will be automatically generated and pushed to VM by NFVBench. If launched manually, no forwarder will be run. Users will have the full control to run either testpmd or VPP via VNC console.
  75
  76 To check if testpmd is running, you can run this command in VNC console:
  77
  78 .. code-block:: bash
  79
  80     sudo screen -r testpmd
  81
  82 To check if VPP is running, you can run this command in VNC console:
  83
  84 .. code-block:: bash
  85
  86     service vpp status
  87
  88
  89 Hardcoded Username and Password
  90 --------------------------------
  91 - Username: nfvbench
  92 - Password: nfvbench
  93
  94
  95 GENERATOR IMAGE INSTANCE AND CONFIG
  96 ===================================
  97
  98 Interface Requirements
  99 ----------------------
 100 The instance must be launched using OpenStack with 2 network interfaces for dataplane traffic (using SR-IOV function) and 1 management interface to control nfvbench.
 101 For best performance, it should use network interfaces for dataplane traffic with a `vnic_type` to `direct-physical` (or `direct` if physical function is not possible)
 102 and a flavor with:
 103
 104 - 6 vCPU
 105 - 8 GB RAM
 106 - cpu pinning set to exclusive
 107
 108 .. note:: For the management interface: any interface type can be used. This interface required a routable IP (through floating IP or direct) and an access to the openstack APIs.
 109 .. note:: CPU pinning: 1 core dedicated for guest OS and NFVbench process, other provided cores are used by TRex
 110
 111 Template of a genarator profile using CPU pinning:
 112
 113 .. code-block:: bash
 114
 115     generator_profile:
 116         - name: {{name}}
 117           tool: {{tool}}
 118           ip: {{ip}}
 119           zmq_pub_port: {{zmq_pub_port}}
 120           zmq_rpc_port: {{zmq_rpc_port}}
 121           software_mode: {{software_mode}}
 122           cores: {{CORES}}
 123           platform:
 124             master_thread_id: '0'
 125             latency_thread_id: '1'
 126             dual_if:
 127               - socket: 0
 128                 threads: [{{CORE_THREADS}}]
 129
 130           interfaces:
 131             - port: 0
 132               pci: "{{PCI_ADDRESS_1}}"
 133               switch:
 134             - port: 1
 135               pci: "{{PCI_ADDRESS_2}}"
 136               switch:
 137           intf_speed:
 138 .. note:: `CORE_THREADS` value is determined automatically based on the cores available on the VM starting from 2 to last worker core available.
 139
 140 Auto-configuration
 141 ------------------
 142 nfvbench VM will automatically find the two virtual interfaces to use for dataplane based on MAC addresses or openstack port name (see config part below).
 143 This applies to the management interface as well.
 144
 145 nfvbenchvm Config
 146 -----------------
 147 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
 148
 149 Example of configuration:
 150
 151 .. code-block:: bash
 152
 153     ACTION=e2e
 154     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 155     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 156     E2E_INTF_MAC1=FA:16:3E:B0:E2:43
 157     E2E_INTF_MAC2=FA:16:3E:D3:6A:FC
 158 .. note:: `ACTION` parameter is not mandatory but will permit to start NFVbench with the accurate ports (loopback or e2e).
 159 .. note:: Set of MAC parameters cannot be used in parallel as only one NFVbench/TRex process is running.
 160 .. note:: Switching from `loopback` to `e2e` action can be done manually using `/nfvbench/start-nfvbench.sh <action>` with the accurate keyword for `action` parameter. This script will restart NFVbench with the good set of MAC.
 161
 162 nfvbenchvm config file with management interface:
 163
 164 .. code-block:: bash
 165
 166     ACTION=e2e
 167     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 168     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 169     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 170     INTF_MGMT_CIDR=172.20.56.228/2
 171     INTF_MGMT_IP_GW=172.20.56.225
 172
 173 .. note:: `INTF_MGMT_IP_GW` and `INTF_MGMT_CIDR` parameters are used by the VM to automatically configure virtual interface and route to allow an external access through SSH.
 174
 175
 176 Using pre-created direct-physical ports on openstack, mac addresses value are only known when VM is deployed. In this case, you can pass the port name in config:
 177
 178 .. code-block:: bash
 179
 180     LOOPBACK_PORT_NAME1=nfvbench-pf1
 181     LOOPBACK_PORT_NAME2=nfvbench-pf2
 182     E2E_PORT_NAME1=nfvbench-pf1
 183     E2E_PORT_NAME1=nfvbench-pf3
 184     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 185     INTF_MGMT_CIDR=172.20.56.228/2
 186     INTF_MGMT_IP_GW=172.20.56.225
 187     DNS_SERVERS=8.8.8.8,dns.server.com
 188 .. note:: A management interface is required to automatically find the virtual interface to use according to the MAC address provided (see `INTF_MAC_MGMT` parameter).
 189 .. note:: NFVbench VM will call openstack API through the management interface to retrieve mac address for these ports
 190 .. note:: If openstack API required a host name resolution, add the parameter DNS_SERVERS to add IP or DNS server names (multiple servers can be added separated by a `,`)
 191
 192 Control nfvbenchvm VM and run test
 193 ----------------------------------
 194
 195 By default, NFVbench will be started in server mode (`--server`) and will act as an API.
 196
 197 NFVbench VM will be accessible through SSH or HTTP using the management interface IP.
 198
 199 NFVbench API endpoint is : `http://<management_ip>:<port>`
 200 .. note:: by default port value is 7555
 201
 202 Get NFVbench status
 203 ^^^^^^^^^^^^^^^^^^^
 204
 205 To check NFVbench is up and running use REST request:
 206
 207 .. code-block:: bash
 208
 209 curl -XGET '<management_ip>:<port>/status'
 210
 211 Example of answer:
 212
 213 .. code-block:: bash
 214
 215     {
 216       "error_message": "nfvbench run still pending",
 217       "status": "PENDING"
 218     }
 219
 220 Start NFVbench test
 221 ^^^^^^^^^^^^^^^^^^^
 222
 223 To start a test run using NFVbench API use this type of REST request:
 224
 225 .. code-block:: bash
 226
 227 curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
 228
 229 Example of return when the submission is successful:
 230
 231 .. code-block:: bash
 232
 233     {
 234       "error_message": "NFVbench run still pending",
 235       "request_id": "42cccb7effdc43caa47f722f0ca8ec96",
 236       "status": "PENDING"
 237     }
 238
 239 Connect to the VM using SSH keypair
 240 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 241
 242 If a key is provided at VM creation you can use it to log on the VM using `cloud-user` username:
 243
 244 .. code-block:: bash
 245
 246     ssh -i key.pem cloud-user@<management_ip>
 247
 248
 249 Connect to VM using SSH username/password
 250 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 251
 252 VM is accessible over SSH using the hardcoded username and password (see below):
 253
 254 .. code-block:: bash
 255
 256     ssh nfvbench@<management_ip>
 257
 258
 259 Launching nfvbenchvm VM
 260 -----------------------
 261
 262 Normally this image will be deployed using Ansible role, and the required configurations will be automatically generated and pushed to VM by Ansible.
 263 If launched manually, users will have the full control to configure and run NFVbench via VNC console.
 264
 265 To check if NFVbench is running, you can run this command in VNC console:
 266
 267 .. code-block:: bash
 268
 269     sudo screen -r nfvbench
 270
 271
 272 Hardcoded Username and Password
 273 --------------------------------
 274 - Username: nfvbench
 275 - Password: nfvbench
 276