diff options
Diffstat (limited to 'docs/testing/user/configguide/installation.rst')
| -rw-r--r-- | docs/testing/user/configguide/installation.rst | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/docs/testing/user/configguide/installation.rst b/docs/testing/user/configguide/installation.rst new file mode 100644 index 00000000..bda5a0bc --- /dev/null +++ b/docs/testing/user/configguide/installation.rst @@ -0,0 +1,304 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Intel Corporation, AT&T and others. + +.. _vsperf-installation: + +====================== +Installing vswitchperf +====================== + +Downloading vswitchperf +----------------------- + +The vswitchperf can be downloaded from its official git repository, which is +hosted by OPNFV. It is necessary to install a ``git`` at your DUT before downloading +vswitchperf. Installation of ``git`` is specific to the packaging system used by +Linux OS installed at DUT. + +Example of installation of GIT package and its dependencies: + +* in case of OS based on RedHat Linux: + + .. code:: bash + + sudo yum install git + + +* in case of Ubuntu or Debian: + + .. code:: bash + + sudo apt-get install git + +After the ``git`` is successfully installed at DUT, then vswitchperf can be downloaded +as follows: + +.. code:: bash + + git clone http://git.opnfv.org/vswitchperf + +The last command will create a directory ``vswitchperf`` with a local copy of vswitchperf +repository. + +Supported Operating Systems +--------------------------- + +* CentOS 7.3 +* Fedora 24 (kernel 4.8 requires DPDK 16.11 and newer) +* Fedora 25 (kernel 4.9 requires DPDK 16.11 and newer) +* openSUSE 42.2 +* RedHat 7.2 Enterprise Linux +* RedHat 7.3 Enterprise Linux +* Ubuntu 14.04 +* Ubuntu 16.04 +* Ubuntu 16.10 (kernel 4.8 requires DPDK 16.11 and newer) + +Supported vSwitches +------------------- + +The vSwitch must support Open Flow 1.3 or greater. + +* Open vSwitch +* Open vSwitch with DPDK support +* TestPMD application from DPDK (supports p2p and pvp scenarios) + +Supported Hypervisors +--------------------- + +* Qemu version 2.3 or greater (version 2.5.0 is recommended) + +Supported VNFs +-------------- + +In theory, it is possible to use any VNF image, which is compatible +with supported hypervisor. However such VNF must ensure, that appropriate +number of network interfaces is configured and that traffic is properly +forwarded among them. For new vswitchperf users it is recommended to start +with official vloop-vnf_ image, which is maintained by vswitchperf community. + +.. _vloop-vnf: + +vloop-vnf +========= + +The official VM image is called vloop-vnf and it is available for free download +from OPNFV artifactory. This image is based on Linux Ubuntu distribution and it +supports following applications for traffic forwarding: + +* DPDK testpmd +* Linux Bridge +* Custom l2fwd module + +The vloop-vnf can be downloaded to DUT, for example by ``wget``: + + .. code:: bash + + wget http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160823.qcow2 + +**NOTE:** In case that ``wget`` is not installed at your DUT, you could install it at RPM +based system by ``sudo yum install wget`` or at DEB based system by ``sudo apt-get install +wget``. + +Changelog of vloop-vnf: + + * `vloop-vnf-ubuntu-14.04_20160823`_ + + * ethtool installed + * only 1 NIC is configured by default to speed up boot with 1 NIC setup + * security updates applied + + * `vloop-vnf-ubuntu-14.04_20160804`_ + + * Linux kernel 4.4.0 installed + * libnuma-dev installed + * security updates applied + + * `vloop-vnf-ubuntu-14.04_20160303`_ + + * snmpd service is disabled by default to avoid error messages during VM boot + * security updates applied + + * `vloop-vnf-ubuntu-14.04_20151216`_ + + * version with development tools required for build of DPDK and l2fwd + +.. _vsperf-installation-script: + +Installation +------------ + +The test suite requires Python 3.3 or newer and relies on a number of other +system and python packages. These need to be installed for the test suite +to function. + +Installation of required packages, preparation of Python 3 virtual +environment and compilation of OVS, DPDK and QEMU is performed by +script **systems/build_base_machine.sh**. It should be executed under +user account, which will be used for vsperf execution. + +**NOTE:** Password-less sudo access must be configured for given +user account before script is executed. + +.. code:: bash + + $ cd systems + $ ./build_base_machine.sh + +**NOTE:** you don't need to go into any of the systems subdirectories, +simply run the top level **build_base_machine.sh**, your OS will be detected +automatically. + +Script **build_base_machine.sh** will install all the vsperf dependencies +in terms of system packages, Python 3.x and required Python modules. +In case of CentOS 7 or RHEL it will install Python 3.3 from an additional +repository provided by Software Collections (`a link`_). Installation script +will also use `virtualenv`_ to create a vsperf virtual environment, which is +isolated from the default Python environment. This environment will reside in a +directory called **vsperfenv** in $HOME. It will ensure, that system wide Python +installation is not modified or broken by VSPERF installation. The complete list +of Python packages installed inside virtualenv can be found at file +``requirements.txt``, which is located at vswitchperf repository. + +**NOTE:** For RHEL 7.3 Enterprise and CentOS 7.3 OVS Vanilla is not +built from upstream source due to kernel incompatibilities. Please see the +instructions in the vswitchperf_design document for details on configuring +OVS Vanilla for binary package usage. + +Using vswitchperf +----------------- + +You will need to activate the virtual environment every time you start a +new shell session. Its activation is specific to your OS: + +* CentOS 7 and RHEL + + .. code:: bash + + $ scl enable python33 bash + $ source $HOME/vsperfenv/bin/activate + +* Fedora and Ubuntu + + .. code:: bash + + $ source $HOME/vsperfenv/bin/activate + +After the virtual environment is configued, then VSPERF can be used. +For example: + + .. code:: bash + + (vsperfenv) $ cd vswitchperf + (vsperfenv) $ ./vsperf --help + +Gotcha +====== + +In case you will see following error during environment activation: + +.. code:: bash + + $ source $HOME/vsperfenv/bin/activate + Badly placed ()'s. + +then check what type of shell you are using: + +.. code:: bash + + $ echo $SHELL + /bin/tcsh + +See what scripts are available in $HOME/vsperfenv/bin + +.. code:: bash + + $ ls $HOME/vsperfenv/bin/ + activate activate.csh activate.fish activate_this.py + +source the appropriate script + +.. code:: bash + + $ source bin/activate.csh + +Working Behind a Proxy +====================== + +If you're behind a proxy, you'll likely want to configure this before +running any of the above. For example: + + .. code:: bash + + export http_proxy=proxy.mycompany.com:123 + export https_proxy=proxy.mycompany.com:123 + +.. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/ +.. _virtualenv: https://virtualenv.readthedocs.org/en/latest/ +.. _vloop-vnf-ubuntu-14.04_20160823: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160823.qcow2 +.. _vloop-vnf-ubuntu-14.04_20160804: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160804.qcow2 +.. _vloop-vnf-ubuntu-14.04_20160303: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20160303.qcow2 +.. _vloop-vnf-ubuntu-14.04_20151216: http://artifacts.opnfv.org/vswitchperf/vnf/vloop-vnf-ubuntu-14.04_20151216.qcow2 + +Hugepage Configuration +---------------------- + +Systems running vsperf with either dpdk and/or tests with guests must configure +hugepage amounts to support running these configurations. It is recommended +to configure 1GB hugepages as the pagesize. + +The amount of hugepages needed depends on your configuration files in vsperf. +Each guest image requires 2048 MB by default according to the default settings +in the ``04_vnf.conf`` file. + +.. code:: bash + + GUEST_MEMORY = ['2048'] + +The dpdk startup parameters also require an amount of hugepages depending on +your configuration in the ``02_vswitch.conf`` file. + +.. code:: bash + + VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,1024'] + VSWITCHD_DPDK_CONFIG = { + 'dpdk-init' : 'true', + 'dpdk-lcore-mask' : '0x4', + 'dpdk-socket-mem' : '1024,1024', + } + +**NOTE:** Option ``VSWITCHD_DPDK_ARGS`` is used for vswitchd, which supports ``--dpdk`` +parameter. In recent vswitchd versions, option ``VSWITCHD_DPDK_CONFIG`` is +used to configure vswitchd via ``ovs-vsctl`` calls. + +With the ``--socket-mem`` argument set to use 1 hugepage on the specified sockets as +seen above, the configuration will need 10 hugepages total to run all tests +within vsperf if the pagesize is set correctly to 1GB. + +VSPerf will verify hugepage amounts are free before executing test +environments. In case of hugepage amounts not being free, test initialization +will fail and testing will stop. + +**NOTE:** In some instances on a test failure dpdk resources may not +release hugepages used in dpdk configuration. It is recommended to configure a +few extra hugepages to prevent a false detection by VSPerf that not enough free +hugepages are available to execute the test environment. Normally dpdk would use +previously allocated hugepages upon initialization. + +Depending on your OS selection configuration of hugepages may vary. Please refer +to your OS documentation to set hugepages correctly. It is recommended to set +the required amount of hugepages to be allocated by default on reboots. + +Information on hugepage requirements for dpdk can be found at +http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html + +You can review your hugepage amounts by executing the following command + +.. code:: bash + + cat /proc/meminfo | grep Huge + +If no hugepages are available vsperf will try to automatically allocate some. +Allocation is controlled by ``HUGEPAGE_RAM_ALLOCATION`` configuration parameter in +``02_vswitch.conf`` file. Default is 2GB, resulting in either 2 1GB hugepages +or 1024 2MB hugepages. |