docs/configguide/installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, AT&T and others.
   4
   5 ======================
   6 Installing vswitchperf
   7 ======================
   8
   9 Supported Operating Systems
  10 ---------------------------
  11
  12 * CentOS 7
  13 * Fedora 20
  14 * Fedora 21
  15 * Fedora 22
  16 * RedHat 7.2
  17 * Ubuntu 14.04
  18
  19 Supported vSwitches
  20 -------------------
  21 The vSwitch must support Open Flow 1.3 or greater.
  22
  23 * OVS (built from source).
  24 * OVS with DPDK (built from source).
  25
  26 Supported Hypervisors
  27 ---------------------
  28
  29 * Qemu version 2.3.
  30
  31 Available VNFs
  32 --------------
  33 A simple VNF that forwards traffic through a VM, using:
  34
  35 * DPDK testpmd
  36 * Linux Brigde
  37 * custom l2fwd module
  38
  39 The official VM image is called vloop-vnf and it is available for free
  40 download at OPNFV website.
  41
  42 vloop-vnf changelog:
  43 ====================
  44
  45 * `vloop-vnf-ubuntu-14.04_20160804`_
  46
  47   * Linux kernel 4.4.0 installed
  48   * libnuma-dev installed
  49   * security updates applied
  50
  51 * `vloop-vnf-ubuntu-14.04_20160303`_
  52
  53   * snmpd service is disabled by default to avoid error messages during VM boot
  54   * security updates applied
  55
  56 * `vloop-vnf-ubuntu-14.04_20151216`_
  57
  58   * version with development tools required for build of DPDK and l2fwd
  59
  60 Other Requirements
  61 ------------------
  62 The test suite requires Python 3.3 and relies on a number of other
  63 packages. These need to be installed for the test suite to function.
  64
  65 Installation of required packages, preparation of Python 3 virtual
  66 environment and compilation of OVS, DPDK and QEMU is performed by
  67 script **systems/build_base_machine.sh**. It should be executed under
  68 user account, which will be used for vsperf execution.
  69
  70 **Please Note**: Password-less sudo access must be configured for given
  71 user account before script is executed.
  72
  73 Execution of installation script:
  74
  75 .. code:: bash
  76
  77     $ cd systems
  78     $ ./build_base_machine.sh
  79
  80 **Please Note**: you don't need to go into any of the systems subdirectories,
  81 simply run the top level **build_base_machine.sh**, your OS will be detected
  82 automatically.
  83
  84 Script **build_base_machine.sh** will install all the vsperf dependencies
  85 in terms of system packages, Python 3.x and required Python modules.
  86 In case of CentOS 7 it will install Python 3.3 from an additional repository
  87 provided by Software Collections (`a link`_). In case of RedHat 7 it will
  88 install Python 3.4 as an alternate installation in /usr/local/bin. Installation
  89 script will also use `virtualenv`_ to create a vsperf virtual environment,
  90 which is isolated from the default Python environment. This environment will
  91 reside in a directory called **vsperfenv** in $HOME.
  92
  93 You will need to activate the virtual environment every time you start a
  94 new shell session. Its activation is specific to your OS:
  95
  96 CentOS 7
  97 ========
  98
  99 .. code:: bash
 100
 101     $ scl enable python33 bash
 102     $ cd $HOME/vsperfenv
 103     $ source bin/activate
 104
 105 Fedora, RedHat and Ubuntu
 106 =========================
 107
 108 .. code:: bash
 109
 110     $ cd $HOME/vsperfenv
 111     $ source bin/activate
 112
 113 Gotcha
 114 ^^^^^^
 115 .. code:: bash
 116
 117    $ source bin/activate
 118    Badly placed ()'s.
 119
 120 Check what type of shell you are using
 121
 122 .. code:: bash
 123
 124    echo $shell
 125    /bin/tcsh
 126
 127 See what scripts are available in $HOME/vsperfenv/bin
 128
 129 .. code:: bash
 130
 131    $ ls bin/
 132    activate          activate.csh      activate.fish     activate_this.py
 133
 134 source the appropriate script
 135
 136 .. code:: bash
 137
 138    $ source bin/activate.csh
 139
 140 Working Behind a Proxy
 141 ======================
 142
 143 If you're behind a proxy, you'll likely want to configure this before
 144 running any of the above. For example:
 145
 146   .. code:: bash
 147
 148     export http_proxy=proxy.mycompany.com:123
 149     export https_proxy=proxy.mycompany.com:123
 150
 151 .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/
 152 .. _virtualenv: https://virtualenv.readthedocs.org/en/latest/
 153 .. _vloop-vnf-ubuntu-14.04_20160804: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160804.qcow2
 154 .. _vloop-vnf-ubuntu-14.04_20160303: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160303.qcow2
 155 .. _vloop-vnf-ubuntu-14.04_20151216: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20151216.qcow2
 156
 157 Hugepage Configuration
 158 ----------------------
 159
 160 Systems running vsperf with either dpdk and/or tests with guests must configure
 161 hugepage amounts to support running these configurations. It is recommended
 162 to configure 1GB hugepages as the pagesize.
 163
 164 The amount of hugepages needed depends on your configuration files in vsperf.
 165 Each guest image requires 4096 by default according to the default settings in
 166 the ``04_vnf.conf`` file.
 167
 168 .. code:: bash
 169
 170     GUEST_MEMORY = ['4096', '4096']
 171
 172 The dpdk startup parameters also require an amount of hugepages depending on
 173 your configuration in the ``02_vswitch.conf`` file.
 174
 175 .. code:: bash
 176
 177     VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,1024']
 178     VSWITCHD_DPDK_CONFIG = {
 179         'dpdk-init' : 'true',
 180         'dpdk-lcore-mask' : '0x4',
 181         'dpdk-socket-mem' : '1024,1024',
 182     }
 183
 184 Note: Option VSWITCHD_DPDK_ARGS is used for vswitchd, which supports --dpdk
 185 parameter. In recent vswitchd versions, option VSWITCHD_DPDK_CONFIG will be
 186 used to configure vswitchd via ovs-vsctl calls.
 187
 188 With the --socket-mem argument set to use 1 hugepage on the specified sockets as
 189 seen above, the configuration will need 10 hugepages total to run all tests
 190 within vsperf if the pagesize is set correctly to 1GB.
 191
 192 VSPerf will verify hugepage amounts are free before executing test
 193 environments. In case of hugepage amounts not being free, test initialization
 194 will fail and testing will stop.
 195
 196 **Please Note**: In some instances on a test failure dpdk resources may not
 197 release hugepages used in dpdk configuration. It is recommended to configure a
 198 few extra hugepages to prevent a false detection by VSPerf that not enough free
 199 hugepages are available to execute the test environment. Normally dpdk would use
 200 previously allocated hugepages upon initialization.
 201
 202 Depending on your OS selection configuration of hugepages may vary. Please refer
 203 to your OS documentation to set hugepages correctly. It is recommended to set
 204 the required amount of hugepages to be allocated by default on reboots.
 205
 206 Information on hugepage requirements for dpdk can be found at
 207 http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
 208
 209 You can review your hugepage amounts by executing the following command
 210
 211 .. code:: bash
 212
 213     cat /proc/meminfo | grep Huge
 214
 215 If no hugepages are available vsperf will try to automatically allocate some.
 216 Allocation is controlled by HUGEPAGE_RAM_ALLOCATION configuration parameter in
 217 ``02_vswitch.conf`` file. Default is 2GB, resulting in either 2 1GB hugepages
 218 or 1024 2MB hugepages.