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