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