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 .. _vsperf-installation:
   6
   7 ======================
   8 Installing vswitchperf
   9 ======================
  10
  11 Downloading vswitchperf
  12 -----------------------
  13
  14 The vswitchperf can be downloaded from its official git repository, which is
  15 hosted by OPNFV. It is necessary to install a ``git`` at your DUT before downloading
  16 vswitchperf. Installation of ``git`` is specific to the packaging system used by
  17 Linux OS installed at DUT.
  18
  19 Example of installation of GIT package and its dependencies:
  20
  21 * in case of OS based on RedHat Linux:
  22
  23   .. code:: bash
  24
  25      sudo yum install git
  26
  27
  28 * in case of Ubuntu or Debian:
  29
  30   .. code:: bash
  31
  32      sudo apt-get install git
  33
  34 After the ``git`` is successfully installed at DUT, then vswitchperf can be downloaded
  35 as follows:
  36
  37 .. code:: bash
  38
  39    git clone http://git.opnfv.org/vswitchperf
  40
  41 The last command will create a directory ``vswitchperf`` with a local copy of vswitchperf
  42 repository.
  43
  44 Supported Operating Systems
  45 ---------------------------
  46
  47 * CentOS 7.3
  48 * Fedora 24 (kernel 4.8 requires DPDK 16.11 and newer)
  49 * Fedora 25 (kernel 4.9 requires DPDK 16.11 and newer)
  50 * openSUSE 42.2
  51 * RedHat 7.2 Enterprise Linux
  52 * RedHat 7.3 Enterprise Linux
  53 * Ubuntu 14.04
  54 * Ubuntu 16.04
  55 * Ubuntu 16.10 (kernel 4.8 requires DPDK 16.11 and newer)
  56
  57 Supported vSwitches
  58 -------------------
  59
  60 The vSwitch must support Open Flow 1.3 or greater.
  61
  62 * Open vSwitch
  63 * Open vSwitch with DPDK support
  64 * TestPMD application from DPDK (supports p2p and pvp scenarios)
  65
  66 Supported Hypervisors
  67 ---------------------
  68
  69 * Qemu version 2.3 or greater (version 2.5.0 is recommended)
  70
  71 Supported VNFs
  72 --------------
  73
  74 In theory, it is possible to use any VNF image, which is compatible
  75 with supported hypervisor. However such VNF must ensure, that appropriate
  76 number of network interfaces is configured and that traffic is properly
  77 forwarded among them. For new vswitchperf users it is recommended to start
  78 with official vloop-vnf_ image, which is maintained by vswitchperf community.
  79
  80 .. _vloop-vnf:
  81
  82 vloop-vnf
  83 =========
  84
  85 The official VM image is called vloop-vnf and it is available for free download
  86 from OPNFV artifactory. This image is based on Linux Ubuntu distribution and it
  87 supports following applications for traffic forwarding:
  88
  89 * DPDK testpmd
  90 * Linux Bridge
  91 * Custom l2fwd module
  92
  93 The vloop-vnf can be downloaded to DUT, for example by ``wget``:
  94
  95   .. code:: bash
  96
  97      wget http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160823.qcow2
  98
  99 **NOTE:** In case that ``wget`` is not installed at your DUT, you could install it at RPM
 100 based system by ``sudo yum install wget`` or at DEB based system by ``sudo apt-get install
 101 wget``.
 102
 103 Changelog of vloop-vnf:
 104
 105   * `vloop-vnf-ubuntu-14.04_20160823`_
 106
 107     * ethtool installed
 108     * only 1 NIC is configured by default to speed up boot with 1 NIC setup
 109     * security updates applied
 110
 111   * `vloop-vnf-ubuntu-14.04_20160804`_
 112
 113     * Linux kernel 4.4.0 installed
 114     * libnuma-dev installed
 115     * security updates applied
 116
 117   * `vloop-vnf-ubuntu-14.04_20160303`_
 118
 119     * snmpd service is disabled by default to avoid error messages during VM boot
 120     * security updates applied
 121
 122   * `vloop-vnf-ubuntu-14.04_20151216`_
 123
 124     * version with development tools required for build of DPDK and l2fwd
 125
 126 .. _vsperf-installation-script:
 127
 128 Installation
 129 ------------
 130
 131 The test suite requires Python 3.3 or newer and relies on a number of other
 132 system and python packages. These need to be installed for the test suite
 133 to function.
 134
 135 Installation of required packages, preparation of Python 3 virtual
 136 environment and compilation of OVS, DPDK and QEMU is performed by
 137 script **systems/build_base_machine.sh**. It should be executed under
 138 user account, which will be used for vsperf execution.
 139
 140 **NOTE:** Password-less sudo access must be configured for given
 141 user account before script is executed.
 142
 143 .. code:: bash
 144
 145     $ cd systems
 146     $ ./build_base_machine.sh
 147
 148 **NOTE:** you don't need to go into any of the systems subdirectories,
 149 simply run the top level **build_base_machine.sh**, your OS will be detected
 150 automatically.
 151
 152 Script **build_base_machine.sh** will install all the vsperf dependencies
 153 in terms of system packages, Python 3.x and required Python modules.
 154 In case of CentOS 7 or RHEL it will install Python 3.3 from an additional
 155 repository provided by Software Collections (`a link`_). Installation script
 156 will also use `virtualenv`_ to create a vsperf virtual environment, which is
 157 isolated from the default Python environment. This environment will reside in a
 158 directory called **vsperfenv** in $HOME. It will ensure, that system wide Python
 159 installation is not modified or broken by VSPERF installation. The complete list
 160 of Python packages installed inside virtualenv can be found at file
 161 ``requirements.txt``, which is located at vswitchperf repository.
 162
 163 **NOTE:** For RHEL 7.3 Enterprise and CentOS 7.3 OVS Vanilla is not
 164 built from upstream source due to kernel incompatibilities. Please see the
 165 instructions in the vswitchperf_design document for details on configuring
 166 OVS Vanilla for binary package usage.
 167
 168 .. _vpp-installation:
 169
 170 VPP installation
 171 ================
 172
 173 Currently vswitchperf installation scripts do not support automatic build
 174 of VPP. In order to execute tests with VPP, it is required to install it
 175 manually. Please refer to the official documentation of `fd.io`_ project to
 176 install VPP from `packages`_ or from the `sources`_.
 177
 178 See details about :ref:`vpp-test`.
 179
 180 .. _fd.io: https://fd.io/
 181 .. _packages: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages
 182 .. _sources: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images
 183
 184 Using vswitchperf
 185 -----------------
 186
 187 You will need to activate the virtual environment every time you start a
 188 new shell session. Its activation is specific to your OS:
 189
 190 * CentOS 7 and RHEL
 191
 192   .. code:: bash
 193
 194      $ scl enable python33 bash
 195      $ source $HOME/vsperfenv/bin/activate
 196
 197 * Fedora and Ubuntu
 198
 199   .. code:: bash
 200
 201      $ source $HOME/vsperfenv/bin/activate
 202
 203 After the virtual environment is configued, then VSPERF can be used.
 204 For example:
 205
 206   .. code:: bash
 207
 208      (vsperfenv) $ cd vswitchperf
 209      (vsperfenv) $ ./vsperf --help
 210
 211 Gotcha
 212 ======
 213
 214 In case you will see following error during environment activation:
 215
 216 .. code:: bash
 217
 218    $ source $HOME/vsperfenv/bin/activate
 219    Badly placed ()'s.
 220
 221 then check what type of shell you are using:
 222
 223 .. code:: bash
 224
 225    $ echo $SHELL
 226    /bin/tcsh
 227
 228 See what scripts are available in $HOME/vsperfenv/bin
 229
 230 .. code:: bash
 231
 232    $ ls $HOME/vsperfenv/bin/
 233    activate          activate.csh      activate.fish     activate_this.py
 234
 235 source the appropriate script
 236
 237 .. code:: bash
 238
 239    $ source bin/activate.csh
 240
 241 Working Behind a Proxy
 242 ======================
 243
 244 If you're behind a proxy, you'll likely want to configure this before
 245 running any of the above. For example:
 246
 247   .. code:: bash
 248
 249     export http_proxy=proxy.mycompany.com:123
 250     export https_proxy=proxy.mycompany.com:123
 251
 252 .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/
 253 .. _virtualenv: https://virtualenv.readthedocs.org/en/latest/
 254 .. _vloop-vnf-ubuntu-14.04_20160823: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160823.qcow2
 255 .. _vloop-vnf-ubuntu-14.04_20160804: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160804.qcow2
 256 .. _vloop-vnf-ubuntu-14.04_20160303: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160303.qcow2
 257 .. _vloop-vnf-ubuntu-14.04_20151216: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20151216.qcow2
 258
 259 Hugepage Configuration
 260 ----------------------
 261
 262 Systems running vsperf with either dpdk and/or tests with guests must configure
 263 hugepage amounts to support running these configurations. It is recommended
 264 to configure 1GB hugepages as the pagesize.
 265
 266 The amount of hugepages needed depends on your configuration files in vsperf.
 267 Each guest image requires 2048 MB by default according to the default settings
 268 in the ``04_vnf.conf`` file.
 269
 270 .. code:: bash
 271
 272     GUEST_MEMORY = ['2048']
 273
 274 The dpdk startup parameters also require an amount of hugepages depending on
 275 your configuration in the ``02_vswitch.conf`` file.
 276
 277 .. code:: bash
 278
 279     DPDK_SOCKET_MEM = ['1024', '0']
 280
 281 **NOTE:** Option ``DPDK_SOCKET_MEM`` is used by all vSwitches with DPDK support.
 282 It means Open vSwitch, VPP and TestPMD.
 283
 284 VSPerf will verify hugepage amounts are free before executing test
 285 environments. In case of hugepage amounts not being free, test initialization
 286 will fail and testing will stop.
 287
 288 **NOTE:** In some instances on a test failure dpdk resources may not
 289 release hugepages used in dpdk configuration. It is recommended to configure a
 290 few extra hugepages to prevent a false detection by VSPerf that not enough free
 291 hugepages are available to execute the test environment. Normally dpdk would use
 292 previously allocated hugepages upon initialization.
 293
 294 Depending on your OS selection configuration of hugepages may vary. Please refer
 295 to your OS documentation to set hugepages correctly. It is recommended to set
 296 the required amount of hugepages to be allocated by default on reboots.
 297
 298 Information on hugepage requirements for dpdk can be found at
 299 http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
 300
 301 You can review your hugepage amounts by executing the following command
 302
 303 .. code:: bash
 304
 305     cat /proc/meminfo | grep Huge
 306
 307 If no hugepages are available vsperf will try to automatically allocate some.
 308 Allocation is controlled by ``HUGEPAGE_RAM_ALLOCATION`` configuration parameter in
 309 ``02_vswitch.conf`` file. Default is 2GB, resulting in either 2 1GB hugepages
 310 or 1024 2MB hugepages.