summaryrefslogtreecommitdiffstats
path: root/docs/userguide/apexlake_installation.rst
diff options
context:
space:
mode:
authorAna C <ana.cunha@ericsson.com>2016-02-10 19:07:13 +0100
committerAna Cunha <ana.cunha@ericsson.com>2016-02-11 15:05:18 +0000
commit95cdd0ea41e3892422de92f13fac39871585706e (patch)
treed8703d6411af6614b299a1005495c389327793ad /docs/userguide/apexlake_installation.rst
parent5f2938cc116f5c8769317e043440d79a0fb2045f (diff)
Add license info and update structure
This change adds license to all .rst files under userguide. It also combines all configguide files into user guide. New reference.rst with list of links. Updated glossary, removed separate directories for apexlake and yardstick framework. Change-Id: I6532ed073905b0fa85a17e759ea7dc3c24acb91f Signed-off-by: Ana C <ana.cunha@ericsson.com> (cherry picked from commit 702eebbf78b29fb9046436dd71575b4f210f4731)
Diffstat (limited to 'docs/userguide/apexlake_installation.rst')
-rw-r--r--docs/userguide/apexlake_installation.rst262
1 files changed, 262 insertions, 0 deletions
diff --git a/docs/userguide/apexlake_installation.rst b/docs/userguide/apexlake_installation.rst
new file mode 100644
index 000000000..4870c2e21
--- /dev/null
+++ b/docs/userguide/apexlake_installation.rst
@@ -0,0 +1,262 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Intel Corporation and others.
+
+
+.. _DPDK: http://dpdk.org/doc/nics
+.. _DPDK-pktgen: https://github.com/Pktgen/Pktgen-DPDK/
+.. _SRIOV: https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking
+.. _here: https://wiki.opnfv.org/vtc
+
+
+============================
+Apexlake Installation Guide
+============================
+
+Abstract
+--------
+
+ApexLake is a framework that provides automatic execution of experiments and
+related data collection to enable a user validate infrastructure from the
+perspective of a Virtual Network Function (:term:`VNF`).
+
+In the context of Yardstick, a virtual Traffic Classifier (:term:`VTC`) network
+function is utilized.
+
+
+Framework Hardware Dependencies
+===============================
+
+In order to run the framework there are some hardware related dependencies for
+ApexLake.
+
+The framework needs to be installed on the same physical node where DPDK-pktgen_
+is installed.
+
+The installation requires the physical node hosting the packet generator must
+have 2 NICs which are DPDK_ compatible.
+
+The 2 NICs will be connected to the switch where the OpenStack VM
+network is managed.
+
+The switch used must support multicast traffic and :term:`IGMP` snooping.
+Further details about the configuration are provided at the following here_.
+
+The corresponding ports to which the cables are connected need to be configured
+as VLAN trunks using two of the VLAN IDs available for Neutron.
+Note the VLAN IDs used as they will be required in later configuration steps.
+
+
+Framework Software Dependencies
+===============================
+Before starting the framework, a number of dependencies must first be installed.
+The following describes the set of instructions to be executed via the Linux
+shell in order to install and configure the required dependencies.
+
+1. Install Dependencies.
+
+To support the framework dependencies the following packages must be installed.
+The example provided is based on Ubuntu and needs to be executed in root mode.
+
+::
+
+ apt-get install python-dev
+ apt-get install python-pip
+ apt-get install python-mock
+ apt-get install tcpreplay
+ apt-get install libpcap-dev
+
+2. Install the Framework on the Target System.
+
+After entering the Apexlake directory, run the following command.
+
+::
+
+ python setup.py install
+
+3. Source OpenStack openrc file.
+
+::
+
+ source openrc
+
+4. Create Two Networks based on VLANs in Neutron.
+
+To enable network communications between the packet generator and the compute
+node, two networks must be created via Neutron and mapped to the VLAN IDs
+that were previously used in the configuration of the physical switch.
+The following shows the typical set of commands required to configure Neutron
+correctly.
+
+::
+
+ VLAN_1=2025
+ VLAN_2=2021
+ neutron net-create apexlake_inbound_network \
+ --provider:network_type vlan \
+ --provider:segmentation_id $VLAN_1 \
+ --provider:physical_network physnet1
+
+ neutron subnet-create apexlake_inbound_network \
+ 192.168.0.0/24 --name apexlake_inbound_subnet
+
+ neutron net-create apexlake_outbound_network \
+ --provider:network_type vlan \
+ --provider:physical_network physnet1
+
+ neutron net-create apexlake_inbound_network \
+ --provider:network_type vlan \
+ --provider:segmentation_id $VLAN_2 \
+ --provider:physical_network physnet1
+
+ neutron subnet-create apexlake_outbound_network 192.168.1.0/24 \
+ --name apexlake_outbound_subnet
+
+
+5. Configure the Test Cases
+
+The VLAN tags must also be included in the test case Yardstick yaml file
+as parameters for the following test cases:
+
+ * :doc:`opnfv_yardstick_tc006`
+
+ * :doc:`opnfv_yardstick_tc007`
+
+ * :doc:`opnfv_yardstick_tc020`
+
+ * :doc:`opnfv_yardstick_tc021`
+
+
+Install and Configure DPDK Pktgen
++++++++++++++++++++++++++++++++++
+
+Execution of the framework is based on DPDK Pktgen.
+If DPDK Pktgen has not installed, it is necessary to download, install, compile
+and configure it.
+The user can create a directory and download the dpdk packet generator source
+code:
+
+::
+
+ cd experimental_framework/libraries
+ mkdir dpdk_pktgen
+ git clone https://github.com/pktgen/Pktgen-DPDK.git
+
+For instructions on the installation and configuration of DPDK and DPDK Pktgen
+please follow the official DPDK Pktgen README file.
+Once the installation is completed, it is necessary to load the DPDK kernel
+driver, as follow:
+
+::
+
+ insmod uio
+ insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
+
+It is necessary to set the configuration file to support the desired Pktgen
+configuration.
+A description of the required configuration parameters and supporting examples
+is provided in the following:
+
+::
+
+ [PacketGen]
+ packet_generator = dpdk_pktgen
+
+ # 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).
+ pktgen_directory = /home/user/software/dpdk_pktgen/dpdk/examples/pktgen/
+
+ # This is the directory where DPDK is installed
+ dpdk_directory = /home/user/apexlake/experimental_framework/libraries/Pktgen-DPDK/dpdk/
+
+ # Name of the dpdk-pktgen program that starts the packet generator
+ program_name = app/app/x86_64-native-linuxapp-gcc/pktgen
+
+ # DPDK coremask (see DPDK-Pktgen readme)
+ coremask = 1f
+
+ # DPDK memory channels (see DPDK-Pktgen readme)
+ memory_channels = 3
+
+ # Name of the interface of the pktgen to be used to send traffic (vlan_sender)
+ name_if_1 = p1p1
+
+ # Name of the interface of the pktgen to be used to receive traffic (vlan_receiver)
+ name_if_2 = p1p2
+
+ # PCI bus address correspondent to if_1
+ bus_slot_nic_1 = 01:00.0
+
+ # PCI bus address correspondent to if_2
+ bus_slot_nic_2 = 01:00.1
+
+
+To find the parameters related to names of the NICs and the addresses of the PCI buses
+the user may find it useful to run the :term:`DPDK` tool nic_bind as follows:
+
+::
+
+ DPDK_DIR/tools/dpdk_nic_bind.py --status
+
+Lists the NICs available on the system, and shows the available drivers and bus addresses for each interface.
+Please make sure to select NICs which are :term:`DPDK` compatible.
+
+Installation and Configuration of smcroute
+++++++++++++++++++++++++++++++++++++++++++
+
+The user is required to install smcroute which is used by the framework to
+support multicast communications.
+
+The following is the list of commands required to download and install smroute.
+
+::
+
+ cd ~
+ git clone https://github.com/troglobit/smcroute.git
+ cd smcroute
+ sed -i 's/aclocal-1.11/aclocal/g' ./autogen.sh
+ sed -i 's/automake-1.11/automake/g' ./autogen.sh
+ ./autogen.sh
+ ./configure
+ make
+ sudo make install
+ cd ..
+
+It is also requires the creation a configuration file using the following
+command:
+
+ SMCROUTE_NIC=(name of the nic)
+
+where name of the nic is the name used previously for the variable "name_if_2".
+For example:
+
+::
+
+ SMCROUTE_NIC=p1p2
+
+Then create the smcroute configuration file /etc/smcroute.conf
+
+::
+
+ echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf
+
+
+At the end of this procedure it will be necessary to perform the following
+actions to add the user to the sudoers:
+
+::
+
+ adduser USERNAME sudo
+ echo "user ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+
+Experiment using SR-IOV Configuration on the Compute Node
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+To enable :term:`SR-IOV` interfaces on the physical NIC of the compute node, a
+compatible NIC is required.
+NIC configuration depends on model and vendor. After proper configuration to
+support :term:`SR-IOV`, a proper configuration of OpenStack is required.
+For further information, please refer to the SRIOV_ configuration guide