1 NFVBENCH VM IMAGES FOR OPENSTACK
2 ++++++++++++++++++++++++++++++++
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
15 - the following packages must be installed prior to using this script:
16 - python3 (+ python3-venv on Ubuntu)
19 - qemu-img (CentOs) or qemu-utils (Ubuntu)
22 .. note:: the image build process is based on `diskimage-builder
23 <https://docs.openstack.org/diskimage-builder/latest/index.html>`_
24 that will be installed in a Python virtual environment by nfvbenchvm
25 build script build-image.sh.
27 .. note:: build-image.sh uses the `gsutil <https://pypi.org/project/gsutil/>`_
28 tool to interact with Google cloud storage (to check if the images
29 exist and to upload the images). This is normally only needed in the
30 context of OPNFV build infrastructure, and build-image.sh can be used
31 without that tool in development environments.
36 - update the version number for the image (if needed) by modifying __version__ in build-image.sh
37 - setup your http_proxy if needed
38 - to build loop VM image only:
39 - `bash build-image.sh -l`
40 - to build generator VM image only:
41 - `bash build-image.sh -g`
42 - to build both images only:
43 - `bash build-image.sh`
45 LOOP VM IMAGE INSTANCE AND CONFIG
46 =================================
48 Interface Requirements
49 ----------------------
50 The instance must be launched using OpenStack with 2 network interfaces.
51 For best performance, it should use a flavor with:
55 - cpu pinning set to exclusive
59 nfvbench VM will automatically find the two virtual interfaces to use, and use the forwarder specifed in the config file.
61 In the case testpmd is used, testpmd will be launched with mac forwarding mode where the destination macs rewritten according to the config file.
63 In the case VPP is used, VPP will set up a L3 router, and forwarding traffic from one port to the other.
67 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
72 INTF_MAC1=FA:16:3E:A2:30:41
73 INTF_MAC2=FA:16:3E:10:DA:10
74 TG_MAC1=00:10:94:00:0A:00
75 TG_MAC2=00:11:94:00:0A:00
76 VNF_GATEWAY1_CIDR=1.1.0.2/8
77 VNF_GATEWAY2_CIDR=2.2.0.2/8
80 TG_GATEWAY1_IP=1.1.0.100
81 TG_GATEWAY2_IP=2.2.0.100
84 Launching nfvbenchvm VM
85 -----------------------
87 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.
89 To check if testpmd is running, you can run this command in VNC console:
93 sudo screen -r testpmd
95 To check if VPP is running, you can run this command in VNC console:
102 Hardcoded Username and Password
103 --------------------------------
108 GENERATOR IMAGE INSTANCE AND CONFIG
109 ===================================
113 To use openstack APIs, NFVbench generator VM will use `clouds.yaml` file as openstack configuration.
114 The OpenStack clouds configuration from clouds.yaml file to use.
115 clouds.yaml file must be in one of the following paths:
116 - ~/.config/openstack
119 Example of `clouds.yaml`:
126 auth_url: http://192.168.122.10:35357/
130 region_name: RegionOne
132 .. note:: Add `CLOUD_DETAIL` property with the accurate value for your openstack configuration (`devstack` in the above example) in ``/etc/nfvbenchvm.conf``
134 Interface Requirements
135 ----------------------
136 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.
137 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)
142 - cpu pinning set to exclusive
144 .. 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.
145 .. note:: CPU pinning: 1 core dedicated for guest OS and NFVbench process, other provided cores are used by TRex
147 Template of a genarator profile using CPU pinning:
155 zmq_pub_port: {{zmq_pub_port}}
156 zmq_rpc_port: {{zmq_rpc_port}}
157 software_mode: {{software_mode}}
160 master_thread_id: '0'
161 latency_thread_id: '1'
164 threads: [{{CORE_THREADS}}]
168 pci: "{{PCI_ADDRESS_1}}"
171 pci: "{{PCI_ADDRESS_2}}"
175 .. note:: `CORE_THREADS` value is determined automatically based on the cores available on the VM starting from 2 to last worker core available.
179 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).
180 This applies to the management interface as well.
184 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
186 Example of configuration:
191 LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
192 LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
193 E2E_INTF_MAC1=FA:16:3E:B0:E2:43
194 E2E_INTF_MAC2=FA:16:3E:D3:6A:FC
196 .. note:: `ACTION` parameter is not mandatory but will permit to start NFVbench with the accurate ports (loopback or e2e).
197 .. note:: Set of MAC parameters cannot be used in parallel as only one NFVbench/TRex process is running.
198 .. 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.
200 nfvbenchvm config file with management interface:
205 LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
206 LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
207 INTF_MAC_MGMT=FA:16:3E:06:11:8A
208 INTF_MGMT_CIDR=172.20.56.228/2
209 INTF_MGMT_IP_GW=172.20.56.225
211 .. 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.
214 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:
218 LOOPBACK_PORT_NAME1=nfvbench-pf1
219 LOOPBACK_PORT_NAME2=nfvbench-pf2
220 E2E_PORT_NAME1=nfvbench-pf1
221 E2E_PORT_NAME1=nfvbench-pf3
222 INTF_MAC_MGMT=FA:16:3E:06:11:8A
223 INTF_MGMT_CIDR=172.20.56.228/2
224 INTF_MGMT_IP_GW=172.20.56.225
225 DNS_SERVERS=8.8.8.8,dns.server.com
227 .. 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).
228 .. note:: NFVbench VM will call openstack API through the management interface to retrieve mac address for these ports
229 .. 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 `,`)
231 Control nfvbenchvm VM and run test
232 ----------------------------------
234 By default, NFVbench will be started in server mode (`--server`) and will act as an API.
236 NFVbench VM will be accessible through SSH or HTTP using the management interface IP.
238 NFVbench API endpoint is : `http://<management_ip>:<port>`
239 .. note:: by default port value is 7555
244 To check NFVbench is up and running use REST request:
248 curl -XGET '<management_ip>:<port>/status'
255 "error_message": "nfvbench run still pending",
262 To start a test run using NFVbench API use this type of REST request:
266 curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
268 Example of return when the submission is successful:
273 "error_message": "NFVbench run still pending",
274 "request_id": "42cccb7effdc43caa47f722f0ca8ec96",
279 Start NFVbench test using Xtesting
280 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
282 To start a test run using Xtesting python library and NFVbench API use this type of command on the VM:
286 run_tests -t nfvbench-demo
288 .. note:: `-t` option determine which test case to be runned by Xtesting
289 (see `xtesting/testcases.yaml` file content to see available list of test cases)
292 Connect to the VM using SSH keypair
293 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
295 If a key is provided at VM creation you can use it to log on the VM using `cloud-user` username:
299 ssh -i key.pem cloud-user@<management_ip>
302 Connect to VM using SSH username/password
303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
305 VM is accessible over SSH using the hardcoded username and password (see below):
309 ssh nfvbench@<management_ip>
312 Launching nfvbenchvm VM
313 -----------------------
315 Normally this image will be deployed using Ansible role, and the required configurations will be automatically generated and pushed to VM by Ansible.
316 If launched manually, users will have the full control to configure and run NFVbench via VNC console.
318 To check if NFVbench is running, you can run this command in VNC console:
322 sudo screen -r nfvbench
325 Hardcoded Username and Password
326 --------------------------------