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 These VMs 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 Pre-requisites
  99 --------------
 100 To use openstack APIs, NFVbench generator VM will use `clouds.yaml` file as openstack configuration.
 101 The OpenStack clouds configuration from clouds.yaml file to use.
 102 clouds.yaml file must be in one of the following paths:
 103 - ~/.config/openstack
 104 - /etc/openstack
 105
 106 Example of `clouds.yaml`:
 107
 108 .. code-block:: yaml
 109
 110     clouds:
 111       devstack:
 112         auth:
 113           auth_url: http://192.168.122.10:35357/
 114           project_name: demo
 115           username: demo
 116           password: 0penstack
 117         region_name: RegionOne
 118
 119 .. note:: Add `CLOUD_DETAIL` property with the accurate value for your openstack configuration (`devstack` in the above example) in ``/etc/nfvbenchvm.conf``
 120
 121 Interface Requirements
 122 ----------------------
 123 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.
 124 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)
 125 and a flavor with:
 126
 127 - 6 vCPU
 128 - 8 GB RAM
 129 - cpu pinning set to exclusive
 130
 131 .. 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.
 132 .. note:: CPU pinning: 1 core dedicated for guest OS and NFVbench process, other provided cores are used by TRex
 133
 134 Template of a genarator profile using CPU pinning:
 135
 136 .. code-block:: bash
 137
 138     generator_profile:
 139         - name: {{name}}
 140           tool: {{tool}}
 141           ip: {{ip}}
 142           zmq_pub_port: {{zmq_pub_port}}
 143           zmq_rpc_port: {{zmq_rpc_port}}
 144           software_mode: {{software_mode}}
 145           cores: {{CORES}}
 146           platform:
 147             master_thread_id: '0'
 148             latency_thread_id: '1'
 149             dual_if:
 150               - socket: 0
 151                 threads: [{{CORE_THREADS}}]
 152
 153           interfaces:
 154             - port: 0
 155               pci: "{{PCI_ADDRESS_1}}"
 156               switch:
 157             - port: 1
 158               pci: "{{PCI_ADDRESS_2}}"
 159               switch:
 160           intf_speed:
 161
 162 .. note:: `CORE_THREADS` value is determined automatically based on the cores available on the VM starting from 2 to last worker core available.
 163
 164 Auto-configuration
 165 ------------------
 166 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).
 167 This applies to the management interface as well.
 168
 169 nfvbenchvm Config
 170 -----------------
 171 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
 172
 173 Example of configuration:
 174
 175 .. code-block:: bash
 176
 177     ACTION=e2e
 178     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 179     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 180     E2E_INTF_MAC1=FA:16:3E:B0:E2:43
 181     E2E_INTF_MAC2=FA:16:3E:D3:6A:FC
 182
 183 .. note:: `ACTION` parameter is not mandatory but will permit to start NFVbench with the accurate ports (loopback or e2e).
 184 .. note:: Set of MAC parameters cannot be used in parallel as only one NFVbench/TRex process is running.
 185 .. 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.
 186
 187 nfvbenchvm config file with management interface:
 188
 189 .. code-block:: bash
 190
 191     ACTION=e2e
 192     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 193     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 194     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 195     INTF_MGMT_CIDR=172.20.56.228/2
 196     INTF_MGMT_IP_GW=172.20.56.225
 197
 198 .. 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.
 199
 200
 201 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:
 202
 203 .. code-block:: bash
 204
 205     LOOPBACK_PORT_NAME1=nfvbench-pf1
 206     LOOPBACK_PORT_NAME2=nfvbench-pf2
 207     E2E_PORT_NAME1=nfvbench-pf1
 208     E2E_PORT_NAME1=nfvbench-pf3
 209     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 210     INTF_MGMT_CIDR=172.20.56.228/2
 211     INTF_MGMT_IP_GW=172.20.56.225
 212     DNS_SERVERS=8.8.8.8,dns.server.com
 213
 214 .. 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).
 215 .. note:: NFVbench VM will call openstack API through the management interface to retrieve mac address for these ports
 216 .. 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 `,`)
 217
 218 Control nfvbenchvm VM and run test
 219 ----------------------------------
 220
 221 By default, NFVbench will be started in server mode (`--server`) and will act as an API.
 222
 223 NFVbench VM will be accessible through SSH or HTTP using the management interface IP.
 224
 225 NFVbench API endpoint is : `http://<management_ip>:<port>`
 226 .. note:: by default port value is 7555
 227
 228 Get NFVbench status
 229 ^^^^^^^^^^^^^^^^^^^
 230
 231 To check NFVbench is up and running use REST request:
 232
 233 .. code-block:: bash
 234
 235 curl -XGET '<management_ip>:<port>/status'
 236
 237 Example of answer:
 238
 239 .. code-block:: bash
 240
 241     {
 242       "error_message": "nfvbench run still pending",
 243       "status": "PENDING"
 244     }
 245
 246 Start NFVbench test
 247 ^^^^^^^^^^^^^^^^^^^
 248
 249 To start a test run using NFVbench API use this type of REST request:
 250
 251 .. code-block:: bash
 252
 253 curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
 254
 255 Example of return when the submission is successful:
 256
 257 .. code-block:: bash
 258
 259     {
 260       "error_message": "NFVbench run still pending",
 261       "request_id": "42cccb7effdc43caa47f722f0ca8ec96",
 262       "status": "PENDING"
 263     }
 264
 265
 266 Start NFVbench test using Xtesting
 267 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 268
 269 To start a test run using Xtesting python library and NFVbench API use this type of command on the VM:
 270
 271 .. code-block:: bash
 272
 273 run_tests -t nfvbench-demo
 274
 275 .. note:: `-t` option determine which test case to be runned by Xtesting
 276  (see `xtesting/testcases.yaml` file content to see available list of test cases)
 277
 278
 279 Connect to the VM using SSH keypair
 280 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 281
 282 If a key is provided at VM creation you can use it to log on the VM using `cloud-user` username:
 283
 284 .. code-block:: bash
 285
 286     ssh -i key.pem cloud-user@<management_ip>
 287
 288
 289 Connect to VM using SSH username/password
 290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 291
 292 VM is accessible over SSH using the hardcoded username and password (see below):
 293
 294 .. code-block:: bash
 295
 296     ssh nfvbench@<management_ip>
 297
 298
 299 Launching nfvbenchvm VM
 300 -----------------------
 301
 302 Normally this image will be deployed using Ansible role, and the required configurations will be automatically generated and pushed to VM by Ansible.
 303 If launched manually, users will have the full control to configure and run NFVbench via VNC console.
 304
 305 To check if NFVbench is running, you can run this command in VNC console:
 306
 307 .. code-block:: bash
 308
 309     sudo screen -r nfvbench
 310
 311
 312 Hardcoded Username and Password
 313 --------------------------------
 314 - Username: nfvbench
 315 - Password: nfvbench
 316