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