summaryrefslogtreecommitdiffstats
path: root/docs/configguide/installation.rst
diff options
context:
space:
mode:
authorTrevor Cooper <trevor.cooper@intel.com>2017-03-21 13:25:49 -0700
committerTrevor Cooper <trevor.cooper@intel.com>2017-03-21 13:25:49 -0700
commit32a5263216d79ad34041dca55357278f092bb931 (patch)
treee3bf10ba8190ad93d2b114c1903cc43e2dfbf6b6 /docs/configguide/installation.rst
parent59668b1aa68da507335ef351619d9f50019df762 (diff)
Moved doc files to testing document structure testing/user ... testing/developer and modified doc index to match dir structure
Change-Id: I4b1a535808a48773505fa7874c61707cd349fced Signed-off-by: Trevor Cooper <trevor.cooper@intel.com>
Diffstat (limited to 'docs/configguide/installation.rst')
-rw-r--r--docs/configguide/installation.rst310
1 files changed, 0 insertions, 310 deletions
diff --git a/docs/configguide/installation.rst b/docs/configguide/installation.rst
deleted file mode 100644
index 1965a8f5..00000000
--- a/docs/configguide/installation.rst
+++ /dev/null
@@ -1,310 +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.
-
-.. _vpp-installation:
-
-VPP installation
-================
-
-Currently vswitchperf installation scripts do not support automatic build
-of VPP. In order to execute tests with VPP, it is required to install it
-manually. Please refer to the official documentation of `fd.io`_ project to
-install VPP from `packages`_ or from the `sources`_.
-
-See details about :ref:`vpp-test`.
-
-.. _fd.io: https://fd.io/
-.. _packages: https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages
-.. _sources: https://wiki.fd.io/view/VPP/Build,_install,_and_test_images
-
-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
-
- DPDK_SOCKET_MEM = ['1024', '0']
-
-**NOTE:** Option ``DPDK_SOCKET_MEM`` is used by all vSwitches with DPDK support.
-It means Open vSwitch, VPP and TestPMD.
-
-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.