yardstick/vTC/apexlake/README.rst

   1 .. _DPDK: http://dpdk.org/doc/nics
   2 .. _DPDK-pktgen: https://github.com/Pktgen/Pktgen-DPDK/
   3 .. _SRIOV: https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking
   4 .. _PORTSEC: https://wiki.openstack.org/wiki/Neutron/ML2PortSecurityExtensionDriver
   5
   6 ===========================
   7 Apexlake installation guide
   8 ===========================
   9 ApexLake is a framework that provides automatic execution of experiments and related data collection to help
  10 the user validating the infrastructure from the perspective of a Virtual Network Function.
  11 To do so in the context of Yardstick, the virtual Traffic Classifier network function is utilized.
  12
  13
  14 Hardware dependencies to run the framework
  15 ==========================================
  16 In order to run the framework some hardware dependencies are required to run ApexLake.
  17
  18 The framework needs to be installed on a physical node where the DPDK packet DPDK-pktgen_
  19 can be correctly installed and executed.
  20 That requires for the packet generator to have 2 NICs DPDK_ Compatible.
  21
  22 The 2 NICs will be connected to the switch where the Openstack VM network is managed.
  23
  24 The switch is required to support multicast traffic and snooping protocol.
  25
  26 The corresponding ports to which the cables are connected will be configured as VLAN trunks
  27 using two of the VLAN IDs available for Neutron.
  28 The mentioned VLAN IDs will be required in further configuration steps.
  29
  30
  31 Software dependencies to run the framework
  32 ==========================================
  33 Before to start the framework, a set of dependencies are required to be installed.
  34 In the following a set of instructions to be executed on the Linux shell to install dependencies
  35 and configure the environment is presented.
  36
  37 1. Install dependencies.
  38
  39 To install the dependencies required by the framework it is necessary install the following packages.
  40 The following example is provided for Ubuntu and need to be executed as root.
  41 ::
  42
  43     apt-get install python-dev
  44     apt-get install python-pip
  45     apt-get install python-mock
  46     apt-get install tcpreplay
  47     apt-get install libpcap-dev
  48
  49 2. Source OpenStack openrc file.
  50
  51 ::
  52
  53     source openrc
  54
  55 3. Configure Openstack Neutron
  56
  57 In order to support traffic generation and management by the virtual Traffic Classifier,
  58 the configuration of the port security driver extension is required for Neutron.
  59 For further details please follow the following link: PORTSEC_
  60 This step can be skipped in case the target OpenStack is Juno or Kilo release,
  61 but it is required to support Liberty.
  62 It is therefore required to indicate the release version in the configuration file apexlake.conf.
  63
  64 4. Create 2 Networks based on VLANs in Neutron.
  65
  66 In order for the network communication between the packet generator and the Compute node to
  67 work fine, it is required to create through Neutron two networks and map those on the VLAN IDs
  68 that have been previously used for the configuration on the physical switch.
  69 The underlying switch needs to be configured accordingly.
  70 ::
  71
  72     VLAN_1=2032
  73     VLAN_2=2033
  74     PHYSNET=physnet2
  75     neutron net-create apexlake_inbound_network \
  76             --provider:network_type vlan \
  77             --provider:segmentation_id $VLAN_1 \
  78             --provider:physical_network $PHYSNET
  79
  80     neutron subnet-create apexlake_inbound_network \
  81             192.168.0.0/24 --name apexlake_inbound_subnet
  82
  83     neutron net-create apexlake_outbound_network \
  84             --provider:network_type vlan \
  85             --provider:segmentation_id $VLAN_2 \
  86             --provider:physical_network $PHYSNET
  87
  88     neutron subnet-create apexlake_outbound_network 192.168.1.0/24 \
  89             --name apexlake_outbound_subnet
  90
  91 5. Download Ubuntu Cloud Image and load it on Glance
  92
  93 The virtual Traffic Classifier is supported on top of Ubuntu 14.04 cloud image.
  94 The image can be downloaded on the local machine and loaded on Glance using the following commands:
  95 ::
  96
  97     wget cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
  98     glance image-create \
  99             --name ubuntu1404 \
 100             --is-public true \
 101             --disk-format qcow \
 102             --container-format bare \
 103             --file trusty-server-cloudimg-amd64-disk1.img
 104
 105 6. Configure the Test Cases.
 106
 107 The VLAN tags are also required into the test case Yardstick yaml file as parameters the following test cases:
 108     - TC 006
 109     - TC 007
 110     - TC 020
 111     - TC 021
 112
 113
 114 Install and configure DPDK Pktgen
 115 +++++++++++++++++++++++++++++++++
 116 The execution of the framework is based on DPDK Pktgen.
 117 If DPDK Pktgen has not been installed on the system by the user, it is necessary to download, compile and configure it.
 118 The user can create a directory and download the dpdk packet generator source code:
 119 ::
 120
 121     cd experimental_framework/libraries
 122     mkdir dpdk_pktgen
 123     git clone https://github.com/pktgen/Pktgen-DPDK.git
 124
 125 For the installation and configuration of DPDK and DPDK Pktgen please follow the official DPDK Pktgen README file.
 126 Once the installation is completed, it is necessary to load the DPDK kernel driver, as follow:
 127 ::
 128
 129     insmod uio
 130     insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 131
 132 It is required to properly set the configuration file according to the system on Pktgen runs on.
 133 A description of the required configuration parameters and examples is provided in the following:
 134 ::
 135
 136     [PacketGen]
 137     packet_generator = dpdk_pktgen
 138
 139     # This is the directory where the packet generator is installed
 140     # (if the user previously installed dpdk-pktgen,
 141     # it is required to provide the director where it is installed).
 142     pktgen_directory = /home/user/software/dpdk_pktgen/dpdk/examples/pktgen/
 143
 144     # This is the directory where DPDK is installed
 145     dpdk_directory = /home/user/apexlake/experimental_framework/libraries/Pktgen-DPDK/dpdk/
 146
 147     # Name of the dpdk-pktgen program that starts the packet generator
 148     program_name = app/app/x86_64-native-linuxapp-gcc/pktgen
 149
 150     # DPDK coremask (see DPDK-Pktgen readme)
 151     coremask = 1f
 152
 153     # DPDK memory channels (see DPDK-Pktgen readme)
 154     memory_channels = 3
 155
 156     # Name of the interface of the pktgen to be used to send traffic (vlan_sender)
 157     name_if_1 = p1p1
 158
 159     # Name of the interface of the pktgen to be used to receive traffic (vlan_receiver)
 160     name_if_2 = p1p2
 161
 162     # PCI bus address correspondent to if_1
 163     bus_slot_nic_1 = 01:00.0
 164
 165     # PCI bus address correspondent to if_2
 166     bus_slot_nic_2 = 01:00.1
 167
 168
 169 To find the parameters related to names of the NICs and addresses of the PCI buses
 170 the user may find useful to run the DPDK tool nic_bind as follows:
 171 ::
 172
 173     DPDK_DIR/tools/dpdk_nic_bind.py --status
 174
 175 which lists the NICs available on the system, show the available drivers and bus addresses for each interface.
 176 Please make sure to select NICs which are DPDK compatible.
 177
 178 Installation and configuration of smcroute
 179 ++++++++++++++++++++++++++++++++++++++++++
 180 The user is required to install smcroute which is used by the framework to support multicast communications.
 181 In the following a list of commands to be ran to download and install smroute is provided.
 182 ::
 183
 184     cd ~
 185     git clone https://github.com/troglobit/smcroute.git
 186     cd smcroute
 187     git reset --hard c3f5c56
 188     sed -i 's/aclocal-1.11/aclocal/g' ./autogen.sh
 189     sed -i 's/automake-1.11/automake/g' ./autogen.sh
 190     ./autogen.sh
 191     ./configure
 192     make
 193     sudo make install
 194     cd ..
 195
 196 It is required to do the reset to the specified commit ID.
 197 It is also required to create a configuration file using the following command:
 198
 199     SMCROUTE_NIC=(name of the nic)
 200
 201 where name of the nic is the name used previously for the variable "name_if_2".
 202 In the example it would be:
 203 ::
 204
 205     SMCROUTE_NIC=p1p2
 206
 207 Then create the smcroute configuration file /etc/smcroute.conf
 208 ::
 209
 210     echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf
 211
 212
 213 At the end of this procedure it will be necessary to perform the following actions to add the user to the sudoers:
 214 ::
 215
 216     adduser USERNAME sudo
 217     echo "user ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
 218
 219
 220 Experiment using SR-IOV configuration on the compute node
 221 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 222 In order to enable SR-IOV interfaces on the physical NIC of the compute node, a compatible NIC is required.
 223 NIC configuration depends on model and vendor. After proper configuration to support SR-IOV,
 224 a proper configuration of openstack is required.
 225 For further information, please look at the _SRIOV configuration guide
 226
 227
 228 Finalize installation the framework on the system
 229 =================================================
 230
 231 The installation of the framework on the system requires the setup of the project.
 232 After entering into the apexlake directory, it is sufficient to run the following command.
 233 ::
 234
 235     python setup.py install
 236
 237 Since some elements are copied into the /tmp directory (see configuration file) it could be necessary
 238 to repeat this step after a reboot of the host.