docs/testing/user/userguide/09-apexlake_installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Intel Corporation and others.
   5
   6
   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
  12
  13
  14 ============================
  15 Apexlake Installation Guide
  16 ============================
  17
  18 Abstract
  19 --------
  20
  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`).
  24
  25 In the context of Yardstick, a virtual Traffic Classifier (:term:`VTC`) network
  26 function is utilized.
  27
  28
  29 Framework Hardware Dependencies
  30 ===============================
  31
  32 In order to run the framework there are some hardware related dependencies for
  33 ApexLake.
  34
  35 The framework needs to be installed on the same physical node where DPDK-pktgen_
  36 is installed.
  37
  38 The installation requires the physical node hosting the packet generator must
  39 have 2 NICs which are DPDK_ compatible.
  40
  41 The 2 NICs will be connected to the switch where the OpenStack VM
  42 network is managed.
  43
  44 The switch used must support multicast traffic and :term:`IGMP` snooping.
  45 Further details about the configuration are provided at the following here_.
  46
  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.
  50
  51
  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.
  57
  58 1. Install Dependencies.
  59
  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.
  62
  63 ::
  64
  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
  70
  71 2. Source OpenStack openrc file.
  72
  73 ::
  74
  75     source openrc
  76
  77 3. Configure Openstack Neutron
  78
  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.
  82
  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
  88
  89
  90 4. Create Two Networks based on VLANs in Neutron.
  91
  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
  96 correctly.
  97 The physical switches need to be configured accordingly.
  98
  99 ::
 100
 101     VLAN_1=2032
 102     VLAN_2=2033
 103     PHYSNET=physnet2
 104     neutron net-create apexlake_inbound_network \
 105             --provider:network_type vlan \
 106             --provider:segmentation_id $VLAN_1 \
 107             --provider:physical_network $PHYSNET
 108
 109     neutron subnet-create apexlake_inbound_network \
 110             192.168.0.0/24 --name apexlake_inbound_subnet
 111
 112     neutron net-create apexlake_outbound_network \
 113             --provider:network_type vlan \
 114             --provider:segmentation_id $VLAN_2 \
 115             --provider:physical_network $PHYSNET
 116
 117     neutron subnet-create apexlake_outbound_network 192.168.1.0/24 \
 118             --name apexlake_outbound_subnet
 119
 120
 121 5. Download Ubuntu Cloud Image and load it on Glance
 122
 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:
 126
 127 ::
 128
 129     wget cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
 130     glance image-create \
 131             --name ubuntu1404 \
 132             --is-public true \
 133             --disk-format qcow \
 134             --container-format bare \
 135             --file trusty-server-cloudimg-amd64-disk1.img
 136
 137
 138
 139 6. Configure the Test Cases
 140
 141 The VLAN tags must also be included in the test case Yardstick yaml file
 142 as parameters for the following test cases:
 143
 144     * :doc:`opnfv_yardstick_tc006`
 145
 146     * :doc:`opnfv_yardstick_tc007`
 147
 148     * :doc:`opnfv_yardstick_tc020`
 149
 150     * :doc:`opnfv_yardstick_tc021`
 151
 152
 153 Install and Configure DPDK Pktgen
 154 +++++++++++++++++++++++++++++++++
 155
 156 Execution of the framework is based on DPDK Pktgen.
 157 If DPDK Pktgen has not installed, it is necessary to download, install, compile
 158 and configure it.
 159 The user can create a directory and download the dpdk packet generator source
 160 code:
 161
 162 ::
 163
 164     cd experimental_framework/libraries
 165     mkdir dpdk_pktgen
 166     git clone https://github.com/pktgen/Pktgen-DPDK.git
 167
 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
 171 driver, as follow:
 172
 173 ::
 174
 175     insmod uio
 176     insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 177
 178 It is necessary to set the configuration file  to support the desired Pktgen
 179 configuration.
 180 A description of the required configuration parameters and supporting examples
 181 is provided in the following:
 182
 183 ::
 184
 185     [PacketGen]
 186     packet_generator = dpdk_pktgen
 187
 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/
 192
 193     # This is the directory where DPDK is installed
 194     dpdk_directory = /home/user/apexlake/experimental_framework/libraries/Pktgen-DPDK/dpdk/
 195
 196     # Name of the dpdk-pktgen program that starts the packet generator
 197     program_name = app/app/x86_64-native-linuxapp-gcc/pktgen
 198
 199     # DPDK coremask (see DPDK-Pktgen readme)
 200     coremask = 1f
 201
 202     # DPDK memory channels (see DPDK-Pktgen readme)
 203     memory_channels = 3
 204
 205     # Name of the interface of the pktgen to be used to send traffic (vlan_sender)
 206     name_if_1 = p1p1
 207
 208     # Name of the interface of the pktgen to be used to receive traffic (vlan_receiver)
 209     name_if_2 = p1p2
 210
 211     # PCI bus address correspondent to if_1
 212     bus_slot_nic_1 = 01:00.0
 213
 214     # PCI bus address correspondent to if_2
 215     bus_slot_nic_2 = 01:00.1
 216
 217
 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:
 220
 221 ::
 222
 223     DPDK_DIR/tools/dpdk_nic_bind.py --status
 224
 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.
 227
 228 Installation and Configuration of smcroute
 229 ++++++++++++++++++++++++++++++++++++++++++
 230
 231 The user is required to install smcroute which is used by the framework to
 232 support multicast communications.
 233
 234 The following is the list of commands required to download and install smroute.
 235
 236 ::
 237
 238     cd ~
 239     git clone https://github.com/troglobit/smcroute.git
 240     cd smcroute
 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
 244     ./autogen.sh
 245     ./configure
 246     make
 247     sudo make install
 248     cd ..
 249
 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
 252 command:
 253
 254 ::
 255
 256     SMCROUTE_NIC=(name of the nic)
 257
 258 where name of the nic is the name used previously for the variable "name_if_2".
 259 For example:
 260
 261 ::
 262
 263     SMCROUTE_NIC=p1p2
 264
 265 Then create the smcroute configuration file /etc/smcroute.conf
 266
 267 ::
 268
 269     echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf
 270
 271
 272 At the end of this procedure it will be necessary to perform the following
 273 actions to add the user to the sudoers:
 274
 275 ::
 276
 277     adduser USERNAME sudo
 278     echo "user ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
 279
 280
 281 Experiment using SR-IOV Configuration on the Compute Node
 282 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 283
 284 To enable :term:`SR-IOV` interfaces on the physical NIC of the compute node, a
 285 compatible NIC is required.
 286 NIC configuration depends on model and vendor. After proper configuration to
 287 support :term:`SR-IOV`, a proper configuration of OpenStack is required.
 288 For further information, please refer to the SRIOV_ configuration guide
 289
 290 Finalize installation the framework on the system
 291 =================================================
 292
 293 The installation of the framework on the system requires the setup of the project.
 294 After entering into the apexlake directory, it is sufficient to run the following
 295 command.
 296
 297 ::
 298
 299     python setup.py install
 300
 301 Since some elements are copied into the /tmp directory (see configuration file)
 302 it could be necessary to repeat this step after a reboot of the host.