From 2e549f6216db3e11e7e97f41b402e2be440aa528 Mon Sep 17 00:00:00 2001 From: Martin Klozik Date: Wed, 18 Jan 2017 16:01:29 +0000 Subject: docs: Installation doc updated Documentation was updated as follows: * description of vsperf downloading was added * VNF section was updated * additions to installation and virtualnev related parts * file permissions of all documentaton files was unified on 644 * README.md was updated with links to doc files and online docs * 3rd_party/readme was renamed and updated to follow markdown syntax JIRA: VSPERF-441 Change-Id: I648c6a8f0bb283bbc0875fd6fecd2539ca0c9056 Signed-off-by: Martin Klozik Reviewed-by: Al Morton Reviewed-by: Christian Trautman Reviewed-by: Bill Michalowski Reviewed-by: Antonio Fischetti Reviewed-by: Sridhar Rao Reviewed-by: Martin Goldammer --- 3rd_party/README.md | 4 + 3rd_party/readme.txt | 1 - README.md | 9 +- conf/03_traffic.conf | 9 +- docs/configguide/installation.rst | 176 ++++++++++++++------- docs/design/index.rst | 0 docs/design/vswitchperf_design.rst | 9 +- docs/index.rst | 4 +- docs/msc/factory_and_loader.msc | 0 docs/msc/traffic_controller.msc | 0 docs/msc/vsperf.msc | 0 .../draft-ietf-bmwg-vswitch-opnfv-01.xml | 0 .../draft-vsperf-bmwg-vswitch-opnfv-00.xml | 0 .../draft-vsperf-bmwg-vswitch-opnfv-01.xml | 0 .../draft-vsperf-bmwg-vswitch-opnfv-02.xml | 0 docs/requirements/vm2vm_alternative_benchmark.png | Bin docs/requirements/vm2vm_benchmark.png | Bin docs/requirements/vm2vm_hypervisor_benchmark.png | Bin .../vm2vm_virtual_interface_benchmark.png | Bin docs/userguide/integration.rst | 0 docs/userguide/testusage.rst | 0 docs/userguide/yardstick.rst | 0 22 files changed, 144 insertions(+), 68 deletions(-) create mode 100644 3rd_party/README.md delete mode 100644 3rd_party/readme.txt mode change 100755 => 100644 docs/configguide/installation.rst mode change 100755 => 100644 docs/design/index.rst mode change 100755 => 100644 docs/design/vswitchperf_design.rst mode change 100755 => 100644 docs/index.rst mode change 100755 => 100644 docs/msc/factory_and_loader.msc mode change 100755 => 100644 docs/msc/traffic_controller.msc mode change 100755 => 100644 docs/msc/vsperf.msc mode change 100755 => 100644 docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml mode change 100755 => 100644 docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-00.xml mode change 100755 => 100644 docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-01.xml mode change 100755 => 100644 docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-02.xml mode change 100755 => 100644 docs/requirements/vm2vm_alternative_benchmark.png mode change 100755 => 100644 docs/requirements/vm2vm_benchmark.png mode change 100755 => 100644 docs/requirements/vm2vm_hypervisor_benchmark.png mode change 100755 => 100644 docs/requirements/vm2vm_virtual_interface_benchmark.png mode change 100755 => 100644 docs/userguide/integration.rst mode change 100755 => 100644 docs/userguide/testusage.rst mode change 100755 => 100644 docs/userguide/yardstick.rst diff --git a/3rd_party/README.md b/3rd_party/README.md new file mode 100644 index 00000000..a73a4d33 --- /dev/null +++ b/3rd_party/README.md @@ -0,0 +1,4 @@ +3rd\_party +========== + +Here are located files and scripts, which are not released under Apache 2.0 license. diff --git a/3rd_party/readme.txt b/3rd_party/readme.txt deleted file mode 100644 index fc308dc8..00000000 --- a/3rd_party/readme.txt +++ /dev/null @@ -1 +0,0 @@ -Here are located files and scripts, which are not released under Apache 2.0 license. diff --git a/README.md b/README.md index c9cdd6dc..82c334d3 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # VSPERF - vSwitch Performance Tests -Documentation for this project including the [quickstart guide] is contained -under the ./docs directory. +Documentation for this project including the [installation userguide] is contained +under the **./docs** directory or available [online]. +Additional information about VSPERF project are available at [project wiki]. --- -[quickstart guide]: docs/quickstart.md +[installation userguide]: docs/configguide/installation.rst +[online]: http://artifacts.opnfv.org/vswitchperf/docs/index.html +[project wiki]: https://wiki.opnfv.org/display/vsperf/VSperf+Home diff --git a/conf/03_traffic.conf b/conf/03_traffic.conf index 4931e977..ccc98e3b 100644 --- a/conf/03_traffic.conf +++ b/conf/03_traffic.conf @@ -53,10 +53,11 @@ LOG_FILE_TRAFFIC_GEN = 'traffic-gen.log' # of selected transport protocol # Default value: "L4". # 'pre_installed_flows' -# - Pre-installed flows is an extension of the multistream" -# feature. If multistream is disabled, then pre-installed -# flows will be ignored. It defines if stream specific flows -# will be inserted into OVS or not. +# - Pre-installed flows is an extension of the "multistream" +# feature. If enabled, it will implicitly insert a flow +# for each stream. If multistream is disabled, then +# pre-installed flows will be ignored. +# Note: It is supported only for p2p deployment scenario. # Data type: str # Supported values: # "Yes" - flows will be inserted into OVS diff --git a/docs/configguide/installation.rst b/docs/configguide/installation.rst old mode 100755 new mode 100644 index 476919af..ed414a8b --- a/docs/configguide/installation.rst +++ b/docs/configguide/installation.rst @@ -6,6 +6,39 @@ 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 --------------------------- @@ -21,72 +54,94 @@ Supported Operating Systems Supported vSwitches ------------------- + The vSwitch must support Open Flow 1.3 or greater. -* OVS (built from source). -* OVS with DPDK (built from source). +* Open vSwitch +* Open vSwitch with DPDK support +* TestPMD application from DPDK (supports p2p and pvp scenarios) Supported Hypervisors --------------------- -* Qemu version 2.3 or greater. +* Qemu version 2.3 or greater (version 2.5.0 is recommended) -Available VNFs +Supported VNFs -------------- -A simple VNF that forwards traffic through a VM, using: + +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 official VM image is called vloop-vnf and it is available for free -download at OPNFV website. +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 -vloop-vnf changelog: -==================== +**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``. -* `vloop-vnf-ubuntu-14.04_20160823`_ +Changelog of vloop-vnf: - * 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_20160823`_ -* `vloop-vnf-ubuntu-14.04_20160804`_ + * ethtool installed + * only 1 NIC is configured by default to speed up boot with 1 NIC setup + * security updates applied - * Linux kernel 4.4.0 installed - * libnuma-dev installed - * security updates applied + * `vloop-vnf-ubuntu-14.04_20160804`_ -* `vloop-vnf-ubuntu-14.04_20160303`_ + * Linux kernel 4.4.0 installed + * libnuma-dev installed + * security updates applied - * snmpd service is disabled by default to avoid error messages during VM boot - * security updates applied + * `vloop-vnf-ubuntu-14.04_20160303`_ -* `vloop-vnf-ubuntu-14.04_20151216`_ + * snmpd service is disabled by default to avoid error messages during VM boot + * security updates applied - * version with development tools required for build of DPDK and l2fwd + * `vloop-vnf-ubuntu-14.04_20151216`_ -Other Requirements ------------------- -The test suite requires Python 3.3 and relies on a number of other -packages. These need to be installed for the test suite to function. + * version with development tools required for build of DPDK and l2fwd + +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. -**Please Note**: Password-less sudo access must be configured for given +**NOTE:** Password-less sudo access must be configured for given user account before script is executed. -Execution of installation script: - .. code:: bash $ cd systems $ ./build_base_machine.sh -**Please Note**: you don't need to go into any of the systems subdirectories, +**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. @@ -96,52 +151,65 @@ 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. +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. -**Please Note**: For RHEL 7.3 Enterprise and CentOS 7.3 OVS Vanilla is not +**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 -================= +* CentOS 7 and RHEL -.. code:: bash + .. code:: bash - $ scl enable python33 bash - $ cd $HOME/vsperfenv - $ source bin/activate + $ scl enable python33 bash + $ source $HOME/vsperfenv/bin/activate -Fedora and Ubuntu -================= +* Fedora and Ubuntu -.. code:: bash + .. code:: bash - $ cd $HOME/vsperfenv - $ source bin/activate + $ 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 bin/activate + $ source $HOME/vsperfenv/bin/activate Badly placed ()'s. -Check what type of shell you are using +then check what type of shell you are using: .. code:: bash - echo $shell + $ echo $SHELL /bin/tcsh See what scripts are available in $HOME/vsperfenv/bin .. code:: bash - $ ls bin/ + $ ls $HOME/vsperfenv/bin/ activate activate.csh activate.fish activate_this.py source the appropriate script @@ -195,11 +263,11 @@ your configuration in the ``02_vswitch.conf`` file. '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 will be -used to configure vswitchd via ovs-vsctl calls. +**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 +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. @@ -207,7 +275,7 @@ 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. -**Please Note**: In some instances on a test failure dpdk resources may not +**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 @@ -227,6 +295,6 @@ You can review your hugepage amounts by executing the following command 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 +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. diff --git a/docs/design/index.rst b/docs/design/index.rst old mode 100755 new mode 100644 diff --git a/docs/design/vswitchperf_design.rst b/docs/design/vswitchperf_design.rst old mode 100755 new mode 100644 index 96b97631..bf82f9b8 --- a/docs/design/vswitchperf_design.rst +++ b/docs/design/vswitchperf_design.rst @@ -314,10 +314,11 @@ Detailed description of ``TRAFFIC`` dictionary items follows: of selected transport protocol Default value: "L4". 'pre_installed_flows' - - Pre-installed flows is an extension of the multistream" - feature. If multistream is disabled, then pre-installed - flows will be ignored. It defines if stream specific flows - will be inserted into OVS or not. + - Pre-installed flows is an extension of the "multistream" + feature. If enabled, it will implicitly insert a flow + for each stream. If multistream is disabled, then + pre-installed flows will be ignored. + Note: It is supported only for p2p deployment scenario. Data type: str Supported values: "Yes" - flows will be inserted into OVS diff --git a/docs/index.rst b/docs/index.rst old mode 100755 new mode 100644 index 37e0c43f..bce2aa61 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,8 @@ Performance and Test group and its associated projects, as part of OPNFV Platform and VNF level testing and validation. * Project Wiki: https://wiki.opnfv.org/characterize_vswitch_performance_for_telco_nfv_use_cases -* Project Repository: https://gerrit.opnfv.org/gerrit/#/q/vswitchperf +* Project Repository: https://git.opnfv.org/vswitchperf +* Project Artifacts: https://artifacts.opnfv.org/vswitchperf.html * Continuous Integration https://build.opnfv.org/ci/view/vswitchperf/ .. toctree:: @@ -34,4 +35,3 @@ Platform and VNF level testing and validation. Indices ======= * :ref:`search` - diff --git a/docs/msc/factory_and_loader.msc b/docs/msc/factory_and_loader.msc old mode 100755 new mode 100644 diff --git a/docs/msc/traffic_controller.msc b/docs/msc/traffic_controller.msc old mode 100755 new mode 100644 diff --git a/docs/msc/vsperf.msc b/docs/msc/vsperf.msc old mode 100755 new mode 100644 diff --git a/docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml b/docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml old mode 100755 new mode 100644 diff --git a/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-00.xml b/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-00.xml old mode 100755 new mode 100644 diff --git a/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-01.xml b/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-01.xml old mode 100755 new mode 100644 diff --git a/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-02.xml b/docs/requirements/ietf_draft/draft-vsperf-bmwg-vswitch-opnfv-02.xml old mode 100755 new mode 100644 diff --git a/docs/requirements/vm2vm_alternative_benchmark.png b/docs/requirements/vm2vm_alternative_benchmark.png old mode 100755 new mode 100644 diff --git a/docs/requirements/vm2vm_benchmark.png b/docs/requirements/vm2vm_benchmark.png old mode 100755 new mode 100644 diff --git a/docs/requirements/vm2vm_hypervisor_benchmark.png b/docs/requirements/vm2vm_hypervisor_benchmark.png old mode 100755 new mode 100644 diff --git a/docs/requirements/vm2vm_virtual_interface_benchmark.png b/docs/requirements/vm2vm_virtual_interface_benchmark.png old mode 100755 new mode 100644 diff --git a/docs/userguide/integration.rst b/docs/userguide/integration.rst old mode 100755 new mode 100644 diff --git a/docs/userguide/testusage.rst b/docs/userguide/testusage.rst old mode 100755 new mode 100644 diff --git a/docs/userguide/yardstick.rst b/docs/userguide/yardstick.rst old mode 100755 new mode 100644 -- cgit 1.2.3-korg