1 .. This work is licensed under a Creative Commons Attribution 4.0 International
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) OPNFV, Intel Corporation and others.
7 .. _DPDK: http://dpdk.org/doc/nics
8 .. _DPDK-pktgen: https://github.com/Pktgen/Pktgen-DPDK/
9 .. _SRIOV: https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking
10 .. _PORTSEC: https://wiki.openstack.org/wiki/Neutron/ML2PortSecurityExtensionDriver
11 .. _here: https://wiki.opnfv.org/vtc
14 ============================
15 Apexlake Installation Guide
16 ============================
21 ApexLake is a framework that provides automatic execution of experiments and
22 related data collection to enable a user validate infrastructure from the
23 perspective of a Virtual Network Function (:term:`VNF`).
25 In the context of Yardstick, a virtual Traffic Classifier (:term:`VTC`) network
29 Framework Hardware Dependencies
30 ===============================
32 In order to run the framework there are some hardware related dependencies for
35 The framework needs to be installed on the same physical node where DPDK-pktgen_
38 The installation requires the physical node hosting the packet generator must
39 have 2 NICs which are DPDK_ compatible.
41 The 2 NICs will be connected to the switch where the OpenStack VM
44 The switch used must support multicast traffic and :term:`IGMP` snooping.
45 Further details about the configuration are provided at the following here_.
47 The corresponding ports to which the cables are connected need to be configured
48 as VLAN trunks using two of the VLAN IDs available for Neutron.
49 Note the VLAN IDs used as they will be required in later configuration steps.
52 Framework Software Dependencies
53 ===============================
54 Before starting the framework, a number of dependencies must first be installed.
55 The following describes the set of instructions to be executed via the Linux
56 shell in order to install and configure the required dependencies.
58 1. Install Dependencies.
60 To support the framework dependencies the following packages must be installed.
61 The example provided is based on Ubuntu and needs to be executed in root mode.
65 apt-get install python-dev
66 apt-get install python-pip
67 apt-get install python-mock
68 apt-get install tcpreplay
69 apt-get install libpcap-dev
71 2. Source OpenStack openrc file.
77 3. Configure Openstack Neutron
79 In order to support traffic generation and management by the virtual
80 Traffic Classifier, the configuration of the port security driver
81 extension is required for Neutron.
83 For further details please follow the following link: PORTSEC_
84 This step can be skipped in case the target OpenStack is Juno or Kilo release,
85 but it is required to support Liberty.
86 It is therefore required to indicate the release version in the configuration
87 file located in ./yardstick/vTC/apexlake/apexlake.conf
90 4. Create Two Networks based on VLANs in Neutron.
92 To enable network communications between the packet generator and the compute
93 node, two networks must be created via Neutron and mapped to the VLAN IDs
94 that were previously used in the configuration of the physical switch.
95 The following shows the typical set of commands required to configure Neutron
97 The physical switches need to be configured accordingly.
104 neutron net-create apexlake_inbound_network \
105 --provider:network_type vlan \
106 --provider:segmentation_id $VLAN_1 \
107 --provider:physical_network $PHYSNET
109 neutron subnet-create apexlake_inbound_network \
110 192.168.0.0/24 --name apexlake_inbound_subnet
112 neutron net-create apexlake_outbound_network \
113 --provider:network_type vlan \
114 --provider:segmentation_id $VLAN_2 \
115 --provider:physical_network $PHYSNET
117 neutron subnet-create apexlake_outbound_network 192.168.1.0/24 \
118 --name apexlake_outbound_subnet
121 5. Download Ubuntu Cloud Image and load it on Glance
123 The virtual Traffic Classifier is supported on top of Ubuntu 14.04 cloud image.
124 The image can be downloaded on the local machine and loaded on Glance
125 using the following commands:
129 wget cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
130 glance image-create \
134 --container-format bare \
135 --file trusty-server-cloudimg-amd64-disk1.img
139 6. Configure the Test Cases
141 The VLAN tags must also be included in the test case Yardstick yaml file
142 as parameters for the following test cases:
144 * :doc:`opnfv_yardstick_tc006`
146 * :doc:`opnfv_yardstick_tc007`
148 * :doc:`opnfv_yardstick_tc020`
150 * :doc:`opnfv_yardstick_tc021`
153 Install and Configure DPDK Pktgen
154 +++++++++++++++++++++++++++++++++
156 Execution of the framework is based on DPDK Pktgen.
157 If DPDK Pktgen has not installed, it is necessary to download, install, compile
159 The user can create a directory and download the dpdk packet generator source
164 cd experimental_framework/libraries
166 git clone https://github.com/pktgen/Pktgen-DPDK.git
168 For instructions on the installation and configuration of DPDK and DPDK Pktgen
169 please follow the official DPDK Pktgen README file.
170 Once the installation is completed, it is necessary to load the DPDK kernel
176 insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
178 It is necessary to set the configuration file to support the desired Pktgen
180 A description of the required configuration parameters and supporting examples
181 is provided in the following:
186 packet_generator = dpdk_pktgen
188 # This is the directory where the packet generator is installed
189 # (if the user previously installed dpdk-pktgen,
190 # it is required to provide the director where it is installed).
191 pktgen_directory = /home/user/software/dpdk_pktgen/dpdk/examples/pktgen/
193 # This is the directory where DPDK is installed
194 dpdk_directory = /home/user/apexlake/experimental_framework/libraries/Pktgen-DPDK/dpdk/
196 # Name of the dpdk-pktgen program that starts the packet generator
197 program_name = app/app/x86_64-native-linuxapp-gcc/pktgen
199 # DPDK coremask (see DPDK-Pktgen readme)
202 # DPDK memory channels (see DPDK-Pktgen readme)
205 # Name of the interface of the pktgen to be used to send traffic (vlan_sender)
208 # Name of the interface of the pktgen to be used to receive traffic (vlan_receiver)
211 # PCI bus address correspondent to if_1
212 bus_slot_nic_1 = 01:00.0
214 # PCI bus address correspondent to if_2
215 bus_slot_nic_2 = 01:00.1
218 To find the parameters related to names of the NICs and the addresses of the PCI buses
219 the user may find it useful to run the :term:`DPDK` tool nic_bind as follows:
223 DPDK_DIR/tools/dpdk_nic_bind.py --status
225 Lists the NICs available on the system, and shows the available drivers and bus addresses for each interface.
226 Please make sure to select NICs which are :term:`DPDK` compatible.
228 Installation and Configuration of smcroute
229 ++++++++++++++++++++++++++++++++++++++++++
231 The user is required to install smcroute which is used by the framework to
232 support multicast communications.
234 The following is the list of commands required to download and install smroute.
239 git clone https://github.com/troglobit/smcroute.git
241 git reset --hard c3f5c56
242 sed -i 's/aclocal-1.11/aclocal/g' ./autogen.sh
243 sed -i 's/automake-1.11/automake/g' ./autogen.sh
250 It is required to do the reset to the specified commit ID.
251 It is also requires the creation a configuration file using the following
254 SMCROUTE_NIC=(name of the nic)
256 where name of the nic is the name used previously for the variable "name_if_2".
263 Then create the smcroute configuration file /etc/smcroute.conf
267 echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf
270 At the end of this procedure it will be necessary to perform the following
271 actions to add the user to the sudoers:
275 adduser USERNAME sudo
276 echo "user ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
279 Experiment using SR-IOV Configuration on the Compute Node
280 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
282 To enable :term:`SR-IOV` interfaces on the physical NIC of the compute node, a
283 compatible NIC is required.
284 NIC configuration depends on model and vendor. After proper configuration to
285 support :term:`SR-IOV`, a proper configuration of OpenStack is required.
286 For further information, please refer to the SRIOV_ configuration guide
288 Finalize installation the framework on the system
289 =================================================
291 The installation of the framework on the system requires the setup of the project.
292 After entering into the apexlake directory, it is sufficient to run the following
297 python setup.py install
299 Since some elements are copied into the /tmp directory (see configuration file)
300 it could be necessary to repeat this step after a reboot of the host.