diff options
Diffstat (limited to 'docs/configguide/installation.rst')
| -rw-r--r-- | docs/configguide/installation.rst | 304 |
1 files changed, 0 insertions, 304 deletions
diff --git a/docs/configguide/installation.rst b/docs/configguide/installation.rst deleted file mode 100644 index bda5a0bc..00000000 --- a/docs/configguide/installation.rst +++ /dev/null @@ -1,304 +0,0 @@ -.. 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. |