yardstick/vTC/apexlake/README.md

   1 Welcome to ApexLake's documentation!
   2 ====================================
   3 ApexLake is a framework that provides automatic execution of experiment and related data collection to help
   4 the user validating the infrastructure from a Virtual Network Function perspective.
   5
   6 Install framework and dependencies
   7 ----------------------------------
   8 Before to start the framework, a set of dependencies are required.
   9 In the following a set of instructions to be executed on the Linux shell to install dependencies and configure the environment.
  10
  11 1. Install dependencies
  12     - # apt-get install python-dev
  13     - # apt-get install python-pip
  14     - # apt-get install python-mock
  15     - # apt-get install tcpreplay
  16     - # apt-get install libpcap-dev
  17
  18 2. Install the framework on the system
  19     - # python setup.py install
  20
  21 3. Source OpenStack openrc file
  22     - $ source openrc
  23
  24 4. Create 2 Networks (and subnets) based on VLANs (provider:network_type = vlan) in Neutron
  25     - $ neutron net-create apexlake_inbound_network --provider:network_type vlan --provider:physical_network physnet1
  26     - $ neutron subnet-create apexlake_inbound_network 192.168.0.0/24 --name apexlake_inbound_subnet
  27     - $ neutron net-create apexlake_outbound_network --provider:network_type vlan --provider:physical_network physnet1
  28     - $ neutron subnet-create apexlake_outbound_network 192.168.1.0/24 --name apexlake_outbound_subnet
  29
  30 5. Insert VLAN tags related to the networks have to ApexLake, either:
  31     - into the "conf.cfg" configuration file, or
  32     - through the Python API.
  33
  34
  35 Install and configure DPDK Pktgen
  36 +++++++++++++++++++++++++++++++++
  37 The execution of the framework is based on DPDK Pktgen.
  38 If DPDK Pktgen has not been installed on the system by the user, it is necessary to download, compile and configure it.
  39 The user can create a directory and download the dpdk packet generator source code:
  40     - $ cd experimental_framework/libraries
  41     - $ mkdir dpdk_pktgen
  42     - $ git clone https://github.com/pktgen/Pktgen-DPDK.git
  43
  44 For the installation and configuration of DPDK and DPDK Pktgen please follow the official DPDK Pktgen README file.
  45 Once the installation is completed, it is necessary to load the DPDK kernel driver, as follow:
  46     - # insmod uio
  47     - # insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
  48
  49 It is required to properly set the configuration file according to the system on Pktgen runs on.
  50 An example is provided in the following:
  51
  52     - [PacketGen]
  53     - packet_generator = dpdk_pktgen
  54     - pktgen_directory = /home/user/apexlake/experimental_framework/libraries/dpdk_pktgen/dpdk/examples/pktgen/
  55         -- This is the directory where the packet generator is installed (if the user previously installed dpdk-pktgen, it is required to provide the director where it is installed).
  56     - dpdk_directory = /home/user/apexlake/experimental_framework/libraries/Pktgen-DPDK/dpdk/
  57         -- This is the directory where DPDK is installed
  58     - program_name = app/app/x86_64-native-linuxapp-gcc/pktgen
  59         -- This is the name of the dpdk-pktgen program that starts the packet generator
  60     - coremask = 1f
  61         -- DPDK coremask (see DPDK-Pktgen readme)
  62     - memory_channels = 3
  63         -- DPDK memory channels (see DPDK-Pktgen readme)
  64     - name_if_1 = p1p1
  65         -- Name of the interface of the pktgen to be used to send traffic
  66     - name_if_2 = p1p2
  67         -- Name of the interface of the pktgen to be used to receive traffic
  68     - bus_slot_nic_1 = 01:00.0
  69         -- PCI bus address correspondent to the if_1
  70     - bus_slot_nic_2 = 01:00.1
  71         -- PCI bus address correspondent to the if_2
  72
  73
  74 To find the parameters related to names of the NICs and addresses of the PCI buses the user may find useful to run the DPDK tool nic_bind as follows:
  75
  76     - $ DPDK_DIR/tools/dpdk_nic_bind.py --status
  77
  78 which lists the NICs available on the system, show the available drivers and bus addresses for each interface.
  79 Please make sure to select NICs which are DPDK compatible.
  80
  81 Installation and configuration of smcroute
  82 ++++++++++++++++++++++++++++++++++++++++++
  83 The user is required to install smcroute which is used by the framework to support multicast communications.
  84 In the following a list of commands to be ran to download and install smroute is provided.
  85
  86     - $ cd ~
  87     - $ git clone https://github.com/troglobit/smcroute.git
  88     - $ cd smcroute
  89     - $ sed -i 's/aclocal-1.11/aclocal/g' ./autogen.sh
  90     - $ sed -i 's/automake-1.11/automake/g' ./autogen.sh
  91     - $ ./autogen.sh
  92     - $ ./configure
  93     - $ make
  94     - $ sudo make install
  95     - $ cd ..
  96
  97 It is also required to create a configuration file using the following command:
  98
  99     - $ SMCROUTE_NIC=(name of the nic)
 100
 101 where name of the nic is the name used previously for the variable "name_if_2".
 102 In the example it would be:
 103
 104     - $ SMCROUTE_NIC=p1p2
 105
 106 Then create the smcroute configuration file /etc/smcroute.conf
 107
 108     - $echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf
 109
 110
 111 Experiment using SR-IOV configuration on the compute node
 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 113 In order to enable SR-IOV interfaces on the physical NIC of the compute node, a compatible NIC is required.
 114 NIC configuration depends on model and vendor. After proper configuration to support SR-IOV, a proper configuration of openstack is required.
 115 For further information, please look at the following link:
 116 https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking