@@ -9,9 +9,25 @@ EXTRA_DIST += \
Documentation/contents.rst \
Documentation/intro/index.rst \
Documentation/intro/install/index.rst \
+ Documentation/intro/install/bash-completion.rst \
+ Documentation/intro/install/debian.rst \
+ Documentation/intro/install/dpdk-advanced.rst \
+ Documentation/intro/install/dpdk.rst \
+ Documentation/intro/install/fedora.rst \
+ Documentation/intro/install/general.rst \
+ Documentation/intro/install/netbsd.rst \
+ Documentation/intro/install/rhel.rst \
+ Documentation/intro/install/userspace.rst \
+ Documentation/intro/install/windows.rst \
+ Documentation/intro/install/xenserver.rst \
Documentation/tutorials/index.rst \
Documentation/topics/index.rst \
Documentation/howto/index.rst \
+ Documentation/howto/docker.rst \
+ Documentation/howto/kvm.rst \
+ Documentation/howto/libvirt.rst \
+ Documentation/howto/selinux.rst \
+ Documentation/howto/ssl.rst \
Documentation/ref/index.rst \
Documentation/faq/index.rst \
Documentation/internals/index.rst
similarity index 96%
rename from INSTALL.Docker.rst
rename to Documentation/howto/docker.rst
@@ -37,8 +37,7 @@ or later.
.. note::
You must build and install Open vSwitch before proceeding with the below
- guide. Refer to the `installation guide <INSTALL.rst>`__ for more
- information.
+ guide. Refer to :doc:`/intro/install/index` for more information.
Setup
-----
@@ -162,10 +161,10 @@ The "overlay" mode
Open vSwitch Python modules are installed. If you installed Open vSwitch
Python modules via the Debian package of ``python-openvswitch`` or via pip
by running ``pip install ovs``, you do not need to specify the PATH. If
- you installed it by following the instructions in the `installation guide
- <INSTALL.rst>`__, then you should specify the PATH. In this case, the PATH
- depends on the options passed to ``./configure``. It is usually either
- ``/usr/share/openvswitch/python`` or
+ you installed it by following the instructions in
+ :doc:`/intro/install/general`, then you should specify the PATH. In this
+ case, the PATH depends on the options passed to ``./configure``. It is
+ usually either ``/usr/share/openvswitch/python`` or
``/usr/local/share/openvswitch/python``
Docker has inbuilt primitives that closely match OVN's logical switches and
@@ -290,7 +289,7 @@ The "underlay" mode
Depending on your VM, you can make the above step persistent across reboots.
For example, if your VM is Debian/Ubuntu-based, read
`openvswitch-switch.README.Debian` found in `debian` folder. If your VM is
- RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.rst>`__.
+ RHEL-based, refer to :doc:`/intro/install/rhel`.
3. Start the Open vSwitch network driver
@@ -32,3 +32,9 @@ topics covered herein, refer to :doc:`/topics/index`.
.. toctree::
:maxdepth: 2
+
+ kvm
+ selinux
+ libvirt
+ ssl
+ docker
similarity index 86%
rename from INSTALL.KVM.rst
rename to Documentation/howto/kvm.rst
@@ -21,17 +21,16 @@
Avoid deeper levels because they do not render well.
-================================
-How to Use Open vSwitch with KVM
-================================
+=====================
+Open vSwitch with KVM
+=====================
This document describes how to use Open vSwitch with the Kernel-based Virtual
Machine (KVM).
.. note::
- This document assumes that you have read and followed the `installation guide
- <INSTALL.rst>`__ to get Open vSwitch setup on your Linux system.
+ This document assumes that you have Open vSwitch set up on a Linux system.
Setup
-----
@@ -64,9 +63,9 @@ Create the following two files and store them in known locations. For example::
/sbin/ifconfig $1 0.0.0.0 down
ovs-vsctl del-port ${switch} $1
-The basic usage of Open vSwitch is described at the end of the `installation
-guide <INSTALL.rst>`__. If you haven't already, create a bridge named ``br0``
-with the following command::
+The basic usage of Open vSwitch is described at the end of
+:doc:`/intro/install/general`. If you haven't already, create a bridge named
+``br0`` with the following command::
$ ovs-vsctl add-br br0
similarity index 87%
rename from INSTALL.Libvirt.rst
rename to Documentation/howto/libvirt.rst
@@ -26,12 +26,11 @@ Open vSwitch with Libvirt
=========================
This document describes how to use Open vSwitch with Libvirt 0.9.11 or later.
-This document assumes that you followed the `general installation guide
-<INSTALL.rst>`__ or installed Open vSwitch from distribution packaging such as
-a .deb or .rpm. The Open vSwitch support is included by default in Libvirt
-0.9.11. Consult www.libvirt.org for instructions on how to build the latest
-Libvirt, if your Linux distribution by default comes with an older Libvirt
-release.
+This document assumes that you followed :doc:`/intro/install/general` or
+installed Open vSwitch from distribution packaging such as a .deb or .rpm. The
+Open vSwitch support is included by default in Libvirt 0.9.11. Consult
+www.libvirt.org for instructions on how to build the latest Libvirt, if your
+Linux distribution by default comes with an older Libvirt release.
Limitations
-----------
similarity index 97%
rename from INSTALL.SELinux.rst
rename to Documentation/howto/selinux.rst
@@ -74,8 +74,8 @@ anticipated the feature set that your SELinux implementation supports.
Installation
------------
-Refer to the `Fedora installation guide <INSTALL.Fedora.rst>`__ for
-instructions on how to build all Open vSwitch rpm packages.
+Refer to :doc:`/intro/install/fedora` for instructions on how to build all Open
+vSwitch rpm packages.
Once the package is built, install it on your Linux distribution::
@@ -159,8 +159,8 @@ vSwitch developer mailing list:
Implications of this are that you should use only those SELinux policy
features that are supported by the lowest SELinux version out there.
Typically this means that you should test your SELinux policy changes on the
- oldest RHEL or CentOS version that this OVS version supports. Check
- INSTALL.Fedora.rst file to find out this.
+ oldest RHEL or CentOS version that this OVS version supports. Refer to
+ :doc:`/intro/install/fedora` to find out this.
3. The SELinux policy is enforced only when state transition to
``openvswitch_t`` domain happens.
similarity index 98%
rename from INSTALL.SSL.rst
rename to Documentation/howto/ssl.rst
@@ -31,8 +31,8 @@ OpenSSL. SSL support ensures integrity and confidentiality of the OpenFlow
connections, increasing network security.
This document describes how to configure an Open vSwitch to connect to an
-OpenFlow controller over SSL. Refer to the `general installation guide
-<INSTALL.rst>`__ for instructions on building Open vSwitch with SSL support.
+OpenFlow controller over SSL. Refer to :doc:`/intro/install/general`. for
+instructions on building Open vSwitch with SSL support.
Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by RFC 2246,
which is very similar to SSL version 3.0. TLSv1 was released in January 1999,
@@ -45,7 +45,17 @@ The Open vSwitch documentation is organised into multiple sections:
First Steps
-----------
-**TODO**
+Getting started with Open vSwitch (OVS) or Open Virtual Network (OVN) for Open
+vSwitch? Start here.
+
+- **Install:** :doc:`intro/install/general` |
+ :doc:`intro/install/userspace` |
+ :doc:`intro/install/netbsd` |
+ :doc:`intro/install/windows` |
+ :doc:`intro/install/xenserver` |
+ :doc:`intro/install/dpdk`
+
+- **Tutorials:** **TODO**
Deeper Dive
-----------
@@ -29,8 +29,8 @@ Open vSwitch Documentation Style
This file describes the documentation style used in all documentation found in
Open vSwitch. Documentation includes any documents found in ``Documentation``
-along with any ``README``, ``INSTALL``, or generally ``rst`` suffixed documents
-found in the project tree.
+along with any ``README``, ``MAINTAINERS``, or generally ``rst`` suffixed
+documents found in the project tree.
reStructuredText vs. Sphinx
---------------------------
similarity index 100%
rename from utilities/ovs-command-bashcomp.INSTALL.rst
rename to Documentation/intro/install/bash-completion.rst
similarity index 94%
rename from INSTALL.Debian.rst
rename to Documentation/intro/install/debian.rst
@@ -21,13 +21,13 @@
Avoid deeper levels because they do not render well.
-=========================================
-Building Debian Packages for Open vSwitch
-=========================================
+=================================
+Debian Packaging for Open vSwitch
+=================================
This document describes how to build Debian packages for Open vSwitch. To
-install Open vSwitch on Debian without building Debian packages, see the
-`installation guide <INSTALL.rst>`__ instead.
+install Open vSwitch on Debian without building Debian packages, refer to
+:doc:`general` instead.
.. note::
These instructions should also work on Ubuntu and other Debian derivative
@@ -117,7 +117,7 @@ Open vSwitch ``.deb`` packages not mentioned above are rarely useful. Refer to
their individual package descriptions to find out whether any of them are
useful to you.
-Bug Reporting
--------------
+Reporting Bugs
+--------------
-Please report problems to bugs@openvswitch.org.
+Report problems to bugs@openvswitch.org.
similarity index 98%
rename from INSTALL.DPDK-ADVANCED.rst
rename to Documentation/intro/install/dpdk-advanced.rst
@@ -40,8 +40,8 @@ Open vSwitch against the shared DPDK library.
Minor performance loss is seen with OVS when using shared DPDK library as
compared to static library.
-To build Open vSwitch using DPDK as a shared library, first refer to the `DPDK
-installation guide`_ for download instructions for DPDK and OVS.
+To build Open vSwitch using DPDK as a shared library, first refer to
+:doc:`/intro/install/dpdk` for download instructions for DPDK and OVS.
Once DPDK and OVS have been downloaded, you must configure the DPDK library
accordingly. Simply set ``CONFIG_RTE_BUILD_SHARED_LIB=y`` in
@@ -53,7 +53,7 @@ built as usual. For example::
$ make install T=$DPDK_TARGET DESTDIR=install
Once DPDK is built, export the DPDK shared library location and setup OVS as
-detailed in the `DPDK installation guide`_::
+detailed in :doc:`/intro/install/dpdk`::
$ export LD_LIBRARY_PATH=$DPDK_DIR/x86_64-native-linuxapp-gcc/lib
@@ -344,8 +344,8 @@ OVS Testcases
PHY-VM-PHY (vHost Loopback)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `DPDK installation guide`_ details steps for PHY-VM-PHY loopback testcase
-and packet forwarding using DPDK testpmd application in the Guest VM. For users
+:doc:`/intro/install/dpdk` details steps for PHY-VM-PHY loopback testcase and
+packet forwarding using DPDK testpmd application in the Guest VM. For users
wishing to do packet forwarding using kernel stack below, you need to run the
below commands on the guest::
@@ -366,7 +366,7 @@ PHY-VM-PHY (IVSHMEM)
~~~~~~~~~~~~~~~~~~~~
IVSHMEM can also be validated using the PHY-VM-PHY configuration. To begin,
-follow the steps described in the `DPDK installation guide`_ to create and
+follow the steps described in the :doc:`/intro/install/dpdk` to create and
initialize the database, start ovs-vswitchd and add ``dpdk``-type devices to
bridge ``br0``. Once complete, follow the below steps:
@@ -426,9 +426,10 @@ PHY-VM-PHY (vHost Multiqueue)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
vHost Multique functionality can also be validated using the PHY-VM-PHY
-configuration. To begin, follow the steps described in the `DPDK installation
-guide`_ to create and initialize the database, start ovs-vswitchd and add
-``dpdk``-type devices to bridge ``br0``. Once complete, follow the below steps:
+configuration. To begin, follow the steps described in
+:doc:`/intro/install/dpdk` to create and initialize the database, start
+ovs-vswitchd and add ``dpdk``-type devices to bridge ``br0``. Once complete,
+follow the below steps:
1. Configure PMD and RXQs.
@@ -671,7 +672,7 @@ itself.
2. Instantiate the VM
- - Copy the XML configuration described in the `DPDK installation guide`_.
+ - Copy the XML configuration described in :doc:`/intro/install/dpdk`
- Start the VM::
@@ -934,5 +935,3 @@ Bug Reporting
-------------
Report problems to bugs@openvswitch.org.
-
-.. _DPDK installation guide: INSTALL.DPDK.rst
similarity index 92%
rename from INSTALL.DPDK.rst
rename to Documentation/intro/install/dpdk.rst
@@ -35,8 +35,8 @@ userspace.
Build requirements
------------------
-In addition to the requirements described in the `installation guide
-<INSTALL.rst>`__, building Open vSwitch with DPDK will require the following:
+In addition to the requirements described in :doc:`general`, building Open
+vSwitch with DPDK will require the following:
- DPDK 16.07
@@ -53,9 +53,10 @@ In addition to the requirements described in the `installation guide
present, it will be necessary to upgrade your kernel or build a custom kernel
with these flags enabled.
+.. TODO(stephenfin): drag the below information in from dpdk-advanced
+
Detailed system requirements can be found at `DPDK requirements`_, while more
-detailed install information can be found in the `advanced installation guide
-<INSTALL.DPDK-ADVANCED.rst>`__.
+detailed install information can be found in :doc:`dpdk-advanced`.
.. _DPDK supported NIC: http://dpdk.org/doc/nics
.. _DPDK requirements: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
@@ -100,28 +101,25 @@ has to be configured with DPDK support (``--with-dpdk``).
.. _OVS sources: http://openvswitch.org/releases/
-1. Ensure the standard OVS requirements, described in the `installation guide
- <INSTALL.rst>`__, are installed.
+1. Ensure the standard OVS requirements, described in
+ :ref:`general-build-reqs`, are installed
-2. Bootstrap, if required, as described in the `installation guide
- <INSTALL.rst>`__.
+2. Bootstrap, if required, as described in :ref:`general-bootstrapping`
3. Configure the package using the ``--with-dpdk`` flag::
$ ./configure --with-dpdk=$DPDK_BUILD
where ``DPDK_BUILD`` is the path to the built DPDK library. This can be
- skipped if DPDK library is installed in its default location.
+ skipped if DPDK library is installed in its default location
.. note::
While ``--with-dpdk`` is required, you can pass any other configuration
- option described in the `installation guide <INSTALL.rst>`__.
+ option described in :ref:`general-configuring`.
-4. Build and install OVS, as described in the `installation guide
- <INSTALL.rst>`__.
+4. Build and install OVS, as described in :ref:`general-building`
-Additional information can be found in the `installation guide
-<INSTALL.rst>`__.
+Additional information can be found in :doc:`general`.
Setup
-----
@@ -182,12 +180,11 @@ to the VFIO driver::
Setup OVS
~~~~~~~~~
-Open vSwitch should be started as described in the `installation guide
-<INSTALL.rst>`__ with the exception of ovs-vswitchd, which requires some
-special configuration to enable DPDK functionality. DPDK configuration
-arguments can be passed to ovs-vswitchd via the ``other_config`` column of the
-``Open_vSwitch`` table. At a minimum, the ``dpdk-init`` option must be set to
-``true``. For example::
+Open vSwitch should be started as described in :doc:`general` with the
+exception of ovs-vswitchd, which requires some special configuration to enable
+DPDK functionality. DPDK configuration arguments can be passed to ovs-vswitchd
+via the ``other_config`` column of the ``Open_vSwitch`` table. At a minimum,
+the ``dpdk-init`` option must be set to ``true``. For example::
$ export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
$ ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
@@ -228,8 +225,7 @@ them to cores 1,2, run::
$ ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=6
-For details on using ivshmem with DPDK, refer to `the advanced installation
-guide <INSTALL.DPDK-ADVANCED.rst>`__.
+For details on using ivshmem with DPDK, refer to :doc:`dpdk-advanced`.
Refer to ovs-vswitchd.conf.db(5) for additional information on configuration
options.
@@ -338,7 +334,7 @@ DPDK 'testpmd' application can be run in the Guest VM for high speed packet
forwarding between vhostuser ports. DPDK and testpmd application has to be
compiled on the guest VM. Below are the steps for setting up the testpmd
application in the VM. More information on the vhostuser ports can be found in
-the `advanced install guide <INSTALL.DPDK-ADVANCED.rst>`__.
+:doc:`dpdk-advanced`.
.. note::
Support for DPDK in the guest requires QEMU >= 2.2.0.
@@ -573,13 +569,13 @@ When you finish testing, bind the vNICs back to kernel::
$ $DPDK_DIR/tools/dpdk-devbind.py --status
.. note::
- More information on the dpdkvhostuser ports can be found in the `advanced
- installation guide <INSTALL.DPDK-ADVANCED.rst>`__.
+ More information on the dpdkvhostuser ports can be found in
+ :doc:`dpdk-advanced`.
PHY-VM-PHY (IVSHMEM loopback)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Refer to the `advanced installation guide <INSTALL.DPDK-ADVANCED.rst>`__.
+Refer to the :doc:`dpdk-advanced`.
Limitations
------------
@@ -598,7 +594,7 @@ Limitations
.. _DPDK release notes: http://dpdk.org/doc/guides/rel_notes/release_16.07.html
-Bug Reporting
--------------
+Reporting Bugs
+--------------
-Please report problems to bugs@openvswitch.org.
+Report problems to bugs@openvswitch.org.
similarity index 90%
rename from INSTALL.Fedora.rst
rename to Documentation/intro/install/fedora.rst
@@ -21,14 +21,14 @@
Avoid deeper levels because they do not render well.
-============================
-Open vSwitch on Fedora Linux
-============================
+===========================================
+Fedora, RHEL 7.x Packaging for Open vSwitch
+===========================================
This document provides instructions for building and installing Open vSwitch
RPM packages on a Fedora Linux host. Instructions for the installation of Open
vSwitch on a Fedora Linux host without using RPM packages can be found in the
-`general installation guide <INSTALL.rst>`__.
+:doc:`general`.
These instructions have been tested with Fedora 23, and are also applicable for
RHEL 7.x and its derivatives, including CentOS 7.x and Scientific Linux 7.x.
@@ -37,8 +37,7 @@ Build Requirements
------------------
To build packages for a Fedora Linux host, you will need the packages described
-in the `general installation guide <INSTALL.rst>`__. Specific packages (by
-package name) include:
+in the :doc:`general`. Specific packages (by package name) include:
- rpm-build
- autoconf automake libtool
@@ -56,14 +55,12 @@ And (optionally):
Bootstraping
------------
-Refer to the *Bootstrapping* section of the `general installation guide
-<INSTALL.rst>`__.
+Refer to :ref:`general-bootstrapping`.
Configuring
-----------
-Refer to the *Configuring* section of the `general installation guide
-<INSTALL.rst>`__.
+Refer to :ref:`general-configuring`.
Building
--------
similarity index 97%
rename from INSTALL.rst
rename to Documentation/intro/install/general.rst
@@ -27,15 +27,7 @@ Open vSwitch on Linux, FreeBSD and NetBSD
This document describes how to build and install Open vSwitch on a generic
Linux, FreeBSD, or NetBSD host. For specifics around installation on a specific
-platform, refer to one of these installation guides:
-
-- `Debian <INSTALL.Debian.rst>`__
-- `Fedora <INSTALL.Fedora.rst>`__
-- `RHEL <INSTALL.RHEL.rst>`__
-- `XenServer <INSTALL.XenServer.rst>`__
-- `NetBSD <INSTALL.NetBSD.rst>`__
-- `Windows <INSTALL.Windows.rst>`__
-- `DPDK <INSTALL.DPDK.rst>`__
+platform, refer to one of the other installation guides listed in :doc:`index`.
.. _general-build-reqs:
@@ -55,8 +47,8 @@ need the following software:
thread-safety checks. For Ubuntu, there are nightly built packages
available on clang's website.
- - MSVC 2013. See the `Windows installation guide <INSTALL.Windows>`__
- for additional Windows build instructions.
+ - MSVC 2013. Refer to :doc:`windows` for additional Windows build
+ instructions.
While OVS may be compatible with other compilers, optimal support for atomic
operations may be missing, making OVS very slow (see ``lib/ovs-atomic.h``).
@@ -79,14 +71,13 @@ vSwitch distribution or to use the kernel module built into the Linux kernel
(version 3.3 or later). See the `FAQ <FAQ.rst>`__ question "What features
are not available in the Open vSwitch kernel datapath that ships as part of the
upstream Linux kernel?" for more information on this trade-off. You may also
-use the userspace-only implementation, at some cost in features and performance
-(see the `userspace installation guide <INSTALL.userspace.rst>`__ for details).
+use the userspace-only implementation, at some cost in features and
+performance. Refer to :doc:`userspace` for details.
To compile the kernel module on Linux, you must also install the
following:
-- A supported Linux kernel version. Refer to the `README <README.rst>`__
- for a list of supported versions.
+- A supported Linux kernel version.
For optional support of ingress policing, you must enable kernel
configuration options ``NET_CLS_BASIC``, ``NET_SCH_INGRESS``, and
@@ -865,7 +856,7 @@ You should invoke scan-view to view analysis results. The last line of output
from ``clang-analyze`` will list the command (containing results directory)
that you should invoke to view the results on a browser.
-Bug Reporting
--------------
+Reporting Bugs
+--------------
-Please report problems to bugs@openvswitch.org.
+Report problems to bugs@openvswitch.org.
@@ -30,5 +30,38 @@ Installing Open vSwitch
A collection of guides detailing how to install Open vSwitch in a variety of
different environments and using different configurations.
+Installation from Source
+------------------------
+
+.. TODO(stephenfin): The DPDK-ADVANCED doc is mostly usage material. The
+ install related instructions should be moved to the main doc, while the
+ rest should be moved to howto and topic docs
+
+.. TODO(stephenfin): Based on the title alone, the NetBSD doc should probably
+ be merged into the general install doc
+
+.. toctree::
+ :maxdepth: 2
+
+ general
+ netbsd
+ windows
+ xenserver
+ userspace
+ dpdk
+ dpdk-advanced
+ bash-completion
+
+Installation from Packages
+--------------------------
+
+Open vSwitch is packaged on a variety of distributions. The tooling required to
+build these packages is included in the Open vSwitch tree. The instructions are
+provided below.
+
.. toctree::
:maxdepth: 2
+
+ debian
+ fedora
+ rhel
similarity index 89%
rename from INSTALL.NetBSD.rst
rename to Documentation/intro/install/netbsd.rst
@@ -36,8 +36,8 @@ you need at least the following packages.
- py27-xml
- pkg_alternatives
-Some components have additional requirements. Refer to the `general
-installation guide <INSTALL.rst>`__.
+Some components have additional requirements. Refer to :doc:`general` for more
+information.
Assuming you are running NetBSD/amd64 6.1.2, you can download and install
pre-built binary packages as the following::
@@ -58,5 +58,4 @@ As all executables installed with pkgsrc are placed in ``/usr/pkg/bin/``
directory, it might be a good idea to add it to your PATH.
Open vSwitch on NetBSD is currently "userspace switch" implementation in the
-sense described in the `userspace installation guide <INSTALL.userspace.rst>`__
-and `porting guide <PORTING.rst>`__.
+sense described in :doc:`userspace` and the `porting guide`.
similarity index 87%
rename from INSTALL.RHEL.rst
rename to Documentation/intro/install/rhel.rst
@@ -22,18 +22,20 @@
Avoid deeper levels because they do not render well.
========================================
-Open vSwitch on Red Hat Enterprise Linux
+RHEL 5.6, 6.x Packaging for Open vSwitch
========================================
This document describes how to build and install Open vSwitch on a Red Hat
Enterprise Linux (RHEL) host. If you want to install Open vSwitch on a generic
-Linux host, see the `general installation guide <INSTALL.rst>`__ instead.
+Linux host, refer to :doc:`general` instead.
We have tested these instructions with RHEL 5.6 and RHEL 6.0.
For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow the
-instructions in the `Fedora installation guide <INSTALL.Fedora.rst>`__. The
-Fedora spec files are used for RHEL 7.x.
+instructions in the :doc:`fedora`. The Fedora spec files are used for RHEL
+7.x.
+
+.. _rhel-prerequisites:
Prerequisites
-------------
@@ -69,21 +71,23 @@ Build Requirements
------------------
To compile the RPMs, you will need to install the packages described in the
-`general installation guide <INSTALL.rst>`__ along with some additional
-packages. These can be installed with the below command::
+:doc:`general` along with some additional packages. These can be installed with
+the below command::
$ yum install gcc make python-devel openssl-devel kernel-devel graphviz \
kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
libtool
+.. _rhel-bootstrapping:
+
Bootstrapping and Configuring
-----------------------------
-If you are building from a distribution tarball, skip to *Building*. If not,
-you must be building from an Open vSwitch Git tree. Determine what version of
-Autoconf is installed (e.g. run ``autoconf --version``). If it is not at least
-version 2.63, then you must upgrade or use another machine to build the
-packages.
+If you are building from a distribution tarball, skip to :ref:`rhel-building`.
+If not, you must be building from an Open vSwitch Git tree. Determine what
+version of Autoconf is installed (e.g. run ``autoconf --version``). If it is
+not at least version 2.63, then you must upgrade or use another machine to
+build the packages.
Assuming all requirements have been met, build the tarball by running::
@@ -91,10 +95,10 @@ Assuming all requirements have been met, build the tarball by running::
$ ./configure
$ make dist
-You must run this on a machine that has the tools listed in the `general
-installation guide <INSTALL.rst>`__ as prerequisites for building from a Git
-tree. Afterward, proceed with the rest of the instructions using the
-distribution tarball.
+You must run this on a machine that has the tools listed in
+:ref:`general-build-reqs` as prerequisites for building from a Git tree.
+Afterward, proceed with the rest of the instructions using the distribution
+tarball.
Now you have a distribution tarball, named something like
``openvswitch-x.y.z.tar.gz``. Copy this file into the RPM sources directory,
@@ -135,6 +139,8 @@ where ``<target>`` is the name of an existing directory under
contain some extra parts. Once you have done this, verify the fix with the
same procedure you used above to check for the problem.
+.. _rhel-building:
+
Building
--------
@@ -187,6 +193,8 @@ This produces an "kmod-openvswitch" RPM for each kernel variant, in this
example: "kmod-openvswitch", "kmod-openvswitch-debug", and
"kmod-openvswitch-kdump".
+.. _rhel-script-integrations:
+
Red Hat Network Scripts Integration
-----------------------------------
similarity index 92%
rename from INSTALL.userspace.rst
rename to Documentation/intro/install/userspace.rst
@@ -22,7 +22,7 @@
Avoid deeper levels because they do not render well.
===================================
-Open vSwitch Without Kernel Support
+Open vSwitch without Kernel Support
===================================
Open vSwitch can operate, at a cost in performance, entirely in userspace,
@@ -42,9 +42,9 @@ Building and Installing
-----------------------
The requirements and procedure for building, installing, and configuring Open
-vSwitch are the same as those given in the `installation guide
-<INSTALL.rst>`__. You may omit configuring, building, and installing the
-kernel module, and the related requirements.
+vSwitch are the same as those given in :doc:`general`. You may omit
+configuring, building, and installing the kernel module, and the related
+requirements.
On Linux, the userspace switch additionally requires the kernel TUN/TAP driver
to be available, either built into the kernel or loaded as a module. If you
@@ -100,7 +100,7 @@ configuration might help. See sysctl(7).::
$ sysctl -w net.inet.ip.checkinterface=1
-Bug Reporting
--------------
+Reporting Bugs
+--------------
-Please report problems to bugs@openvswitch.org.
+Report problems to bugs@openvswitch.org.
similarity index 99%
rename from INSTALL.Windows.rst
rename to Documentation/intro/install/windows.rst
@@ -171,8 +171,7 @@ Possible values for ``<target type>`` are: ``Debug`` and ``Release``
You can directly use the Visual Studio 2013 IDE to compile the kernel
datapath. Open the ovsext.sln file in the IDE and build the solution.
-Refer to the `installation guide <INSTALL.rst>` for information on additional
-configuration options.
+Refer to :doc:`general` for information on additional configuration options.
.. _windows-building:
similarity index 96%
rename from INSTALL.XenServer.rst
rename to Documentation/intro/install/xenserver.rst
@@ -21,13 +21,13 @@
Avoid deeper levels because they do not render well.
-===============================================
-How to Install Open vSwitch on Citrix XenServer
-===============================================
+================================
+Open vSwitch on Citrix XenServer
+================================
This document describes how to build and install Open vSwitch on a Citrix
XenServer host. If you want to install Open vSwitch on a generic Linux or BSD
-host, see the `installation guide <INSTALL.rst>`__ instead.
+host, refer to :doc:`general` instead.
Open vSwitch should work with XenServer 5.6.100 and later. However, Open
vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5
@@ -49,8 +49,8 @@ is the DDK VM available from Citrix.
You cannot run this in the DDK VM, because it lacks tools that are necessary
to bootstrap the Open vSwitch distribution. Instead, you must run this on a
- machine that has the tools listed in the installation guide <INSTALL.rst>`__
- as prerequisites for building from a Git tree.
+ machine that has the tools listed in :ref:`general-install-reqs` as
+ prerequisites for building from a Git tree.
2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside
the DDK VM.
@@ -486,7 +486,7 @@ Q: How do I configure a DPDK port as an access port?
Finally, it is required that DPDK port names begin with ``dpdk``.
- See `INSTALL.DPDK <INSTALL.DPDK.rst>`__ for more information on enabling
+ Refer to the `DPDK installation guide`_ for more information on enabling
and using DPDK with Open vSwitch.
Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all
@@ -794,7 +794,8 @@ very high.
on the Port table in ovs-vswitchd.conf.db(5) for all the details.
Configuration for DPDK-enabled interfaces is slightly less
- straightforward: see `INSTALL.DPDK <INSTALL.DPDK.rst>`__.
+ straightforward. Refer to the `DPDK installation guide`_ for more
+ information.
- Perhaps you don't actually need eth0 and eth1 to be on the same bridge.
For example, if you simply want to be able to connect each of them to
@@ -862,8 +863,8 @@ port in the datapath?
Linux GRE module is already loaded and blocking OVS (to confirm, check
dmesg for errors regarding GRE registration). To fix this, unload all GRE
modules that appear in lsmod as well as the OVS kernel module. You can then
- reload the OVS module following the directions in the `installation guide
- <INSTALL.rst>`__, which will ensure that dependencies are satisfied.
+ reload the OVS module following the directions in the `general installation
+ guide`_, which will ensure that dependencies are satisfied.
Q: Open vSwitch does not seem to obey my packet filter rules.
@@ -2048,8 +2049,7 @@ Q: How do I implement a new OpenFlow message?
``lib/ofp-msgs.h``, following the existing pattern. Then recompile and fix
all of the new warnings, implementing new functionality for the new message
as needed. (If you configure with ``--enable-Werror``, as described in the
- `installation guide <INSTALL.rst>`__, then it is impossible to miss any
- warnings.)
+ `general installation guide`_, then it is impossible to miss any warnings.)
If you need to add an OpenFlow vendor extension message for a vendor that
doesn't yet have any extension messages, then you will also need to edit
@@ -2065,8 +2065,8 @@ Q: How do I add support for a new field or header?
``lib/nx-match.c`` to output your new field in OXM matches. Then recompile
and fix all of the new warnings, implementing new functionality for the new
field or header as needed. (If you configure with ``--enable-Werror``, as
- described in the `installation guide <INSTALL.rst>`__, then it is impossible
- to miss any warnings.)
+ described in the `general installation guide`_, then it is impossible to
+ miss any warnings.)
If you want kernel datapath support for your new field, you also need to
modify the kernel module for the operating systems you are interested in.
@@ -2085,9 +2085,12 @@ Q: How do I add support for a new OpenFlow action?
``lib/ofp-actions.c``, following the existing pattern. Then recompile and
fix all of the new warnings, implementing new functionality for the new
action as needed. (If you configure with ``--enable-Werror``, as described
- in the `installation guide <INSTALL.rst>`__, then it is impossible to miss
- any warnings.)
+ in the `general installation guide`_, then it is impossible to miss any
+ warnings.)
If you need to add an OpenFlow vendor extension action for a vendor that
doesn't yet have any extension actions, then you will also need to edit
``build-aux/extract-ofp-actions``.
+
+.. _general installation guide: Documentation/intro/install/general.rst
+.. _DPDK installation guide: Documentation/intro/install/dpdk.rst
@@ -69,21 +69,6 @@ docs = \
CONTRIBUTING.rst \
DESIGN.rst \
FAQ.rst \
- INSTALL.rst \
- INSTALL.Debian.rst \
- INSTALL.Docker.rst \
- INSTALL.DPDK-ADVANCED.rst \
- INSTALL.DPDK.rst \
- INSTALL.Fedora.rst \
- INSTALL.KVM.rst \
- INSTALL.Libvirt.rst \
- INSTALL.NetBSD.rst \
- INSTALL.RHEL.rst \
- INSTALL.SELinux.rst \
- INSTALL.SSL.rst \
- INSTALL.XenServer.rst \
- INSTALL.userspace.rst \
- INSTALL.Windows.rst \
IntegrationGuide.rst \
MAINTAINERS.rst \
OPENFLOW.rst \
@@ -141,13 +141,15 @@ Porting Strategies
After a netdev provider has been implemented for a system's network devices,
you may choose among three basic porting strategies.
+.. TODO(stephenfin): Update the link to the installation guide when this is
+ moved
+
The lowest-effort strategy is to use the "userspace switch" implementation
built into Open vSwitch. This ought to work, without writing any more code, as
long as the netdev provider that you implemented supports receiving packets.
It yields poor performance, however, because every packet passes through the
-ovs-vswitchd process. See the `userspace installation guide
-<INSTALL.userspace.rst>` for instructions on how to configure a userspace
-switch.
+ovs-vswitchd process. See the `userspace installation guide` for instructions
+on how to configure a userspace switch.
If the userspace switch is not the right choice for your port, then you will
have to write more code. You may implement either an "ofproto provider" or a
@@ -73,36 +73,16 @@ Open vSwitch also provides some tools:
What other documentation is available?
--------------------------------------
-To install Open vSwitch on a regular Linux or FreeBSD host, please read the
-`installation guide <INSTALL.rst>`__. For specifics around installation on a
-specific platform, please see one of the below installation guides:
-
-- `Debian <INSTALL.Debian.rst>`__
-- `Fedora <INSTALL.Fedora.rst>`__
-- `RHEL <INSTALL.RHEL.rst>`__
-- `XenServer <INSTALL.XenServer.rst>`__
-- `Windows <INSTALL.Windows.rst>`__
-
-To use Open vSwitch...
-
-- ...with Docker on Linux, see `here <INSTALL.Docker.rst>`__.
-
-- ...with KVM on Linux, see `here <INSTALL.rst>`__ and `here
- <INSTALL.KVM.rst>`__.
+.. TODO(stephenfin): Update with a link to the hosting site of the docs, once
+ we know where that is
-- ...with Libvirt, see `here <INSTALL.Libvirt.rst>`__.
-
-- ...without using a kernel module, see `here <INSTALL.userspace.rst>`__.
-
-- ...with DPDK, see `here <INSTALL.DPDK.rst>`__.
-
-- ...with SELinux, see `here <INSTALL.SELinux.rst>`__.
+To install Open vSwitch on a regular Linux or FreeBSD host, please read the
+`installation guide <Documentation/intro/install/general.rst>`__. For specifics
+around installation on a specific platform, refer to one of the `other
+installation guides <Documentation/intro/install/index.rst>`__
For answers to common questions, refer to the `FAQ <FAQ.rst>`__.
-To learn how to set up SSL support for Open vSwitch, see `here
-<INSTALL.SSL.rst>`__.
-
To learn about some advanced features of the Open vSwitch software switch, read
the `tutorial <tutorial/tutorial.rst>`__.
@@ -1,3 +1 @@
FAQ.rst
-INSTALL.DPDK.rst
-README-native-tunneling.rst
@@ -481,8 +481,8 @@ fi
%{_mandir}/man8/ovs-vswitchd.8*
%{_mandir}/man8/ovs-parse-backtrace.8*
%{_mandir}/man8/ovs-testcontroller.8*
-%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst
-%doc FAQ.rst NEWS INSTALL.DPDK.rst rhel/README.RHEL.rst
+%doc COPYING DESIGN.rst NOTICE README.rst WHY-OVS.rst
+%doc FAQ.rst NEWS rhel/README.RHEL.rst
/var/lib/openvswitch
/var/log/openvswitch
%ghost %attr(755,root,root) %{_rundir}/openvswitch
@@ -248,8 +248,8 @@ exit 0
/usr/share/openvswitch/scripts/sysconfig.template
/usr/share/openvswitch/vswitch.ovsschema
/usr/share/openvswitch/vtep.ovsschema
-%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS
-%doc INSTALL.DPDK.rst rhel/README.RHEL.rst README-native-tunneling.rst
+%doc COPYING DESIGN.rst NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS
+%doc rhel/README.RHEL.rst README-native-tunneling.rst
/var/lib/openvswitch
/var/log/openvswitch
@@ -873,11 +873,12 @@ of what the resulting OpenFlow flows look like.
Container Ports
---------------
+.. TODO(stephenfin): Update Docker link when this is moved.
+
OVN supports containers running directly on the hypervisors and running
containers inside VMs. This example shows how OVN supports network
virtualization to containers when run inside VMs. Details about how to use
-docker containers in OVS can be found in the `Docker installlation guide
-<../INSTALL.Docker.rst>`__.
+docker containers in OVS can be found in the `Docker installlation guide`.
To support container traffic created inside a VM and to distinguish network
traffic coming from different container vifs, for each container a logical port
@@ -54,6 +54,8 @@ hardware or even supervisor privilege on your system. Instead, we will use a
script called ``ovs-sandbox``, which accompanies the tutorial, that constructs
a software simulated network environment based on Open vSwitch.
+.. TODO(stephenfin): Update installation guide link when this is moved.
+
You can use ``ovs-sandbox`` three ways:
* If you have already installed Open vSwitch on your system, then you should be
@@ -61,9 +63,9 @@ You can use ``ovs-sandbox`` three ways:
* If you have not installed Open vSwitch (and you do not want to install it),
then you can build Open vSwitch according to the instructions in the
- `installation guide <INSTALL.rst>`__, without installing it. Then run
- ``./ovs-sandbox -b DIRECTORY`` from this directory, substituting the Open
- vSwitch build directory for ``DIRECTORY``.
+ `installation guide`, without installing it. Then run ``./ovs-sandbox -b
+ DIRECTORY`` from this directory, substituting the Open vSwitch build
+ directory for ``DIRECTORY``.
* As a slight variant on the latter, you can run ``make sandbox`` from an Open
vSwitch build directory.
@@ -37,11 +37,9 @@ noinst_SCRIPTS += utilities/ovs-sim
utilities/ovs-lib: $(top_builddir)/config.status
-docs += utilities/ovs-command-bashcomp.INSTALL.rst
EXTRA_DIST += \
utilities/ovs-appctl-bashcomp.bash \
utilities/ovs-check-dead-ifs.in \
- utilities/ovs-command-bashcomp.INSTALL.rst \
utilities/ovs-ctl.in \
utilities/ovs-dev.py \
utilities/ovs-docker \
@@ -502,5 +502,4 @@ distribution are good examples of how to use \fBovs\-ctl\fR.
.
.SH "SEE ALSO"
.
-\fBREADME.rst\fR, \fBINSTALL.Linux.rst\fR, \fBovsdb\-server\fR(8),
-\fBovs\-vswitchd\fR(8).
+\fBREADME.rst\fR, \fBovsdb\-server\fR(8), \fBovs\-vswitchd\fR(8).
@@ -399,9 +399,9 @@ Sets the configured failure mode.
These commands manipulate the \fBmanager_options\fR column in the
\fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table. When
\fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for
-OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup
-scripts provided with Open vSwitch), this allows the administrator to use
-\fBovs\-vsctl\fR to configure database connections.
+OVSDB connections (as described in the startup scripts provided with
+Open vSwitch), this allows the administrator to use \fBovs\-vsctl\fR to
+configure database connections.
.
.IP "\fBget\-manager\fR"
Prints the configured manager(s).
@@ -67,9 +67,8 @@ to modify datapaths when \fBovs\-vswitchd\fR is running can interfere with
its operation. (\fBovs\-dpctl\fR may still be useful for diagnostics.)
.PP
An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR
-to be useful. Please refer to the \fBINSTALL.Linux\fR file included in the
-Open vSwitch distribution for instructions on how to build and load
-the Open vSwitch kernel module.
+to be useful. Refer to the documentation for instructions on how to build and
+load the Open vSwitch kernel module.
.PP
.SH OPTIONS
.IP "\fB\-\-mlockall\fR"
@@ -85,7 +84,7 @@ unavailable or unsuccessful.
.
.SS "DPDK Options"
For details on initializing the \fBovs\-vswitchd\fR DPDK datapath,
-refer to INSTALL.DPDK.rst or \fBovs\-vswitchd.conf.db\fR(5) for
+refer to the documentation or \fBovs\-vswitchd.conf.db\fR(5) for
details.
.SS "Daemon Options"
.ds DD \
@@ -348,5 +347,4 @@ time linear in the number of flows.
.
.SH "SEE ALSO"
.BR ovs\-appctl (8),
-.BR ovsdb\-server (1),
-\fBINSTALL.Linux\fR in the Open vSwitch distribution.
+.BR ovsdb\-server (1).
@@ -36,13 +36,12 @@ The VTEP emulator is a Python script that invokes calls to tools like vtep-ctl
and ovs-vsctl. It is only useful when Open vSwitch daemons like ovsdb-server
and ovs-vswitchd are running and installed. To do this, either:
-- Follow the instructions in the `installation guide <..INSTALL.rst>`__ (don't
+- Follow the instructions in ``Documentation/intro/install/general`` (don't
start any daemons yet).
-- Follow the instructions in `Debian installation guide
- <../INSTALL.Debian.rst>`__ and then install the ``openvswitch-vtep`` package
- (if operating on a debian based machine). This will automatically start the
- daemons.
+- Follow the instructions in ``Documentation/intro/install/debian`` and then
+ install the ``openvswitch-vtep`` package (if operating on a debian based
+ machine). This will automatically start the daemons.
Design
------
@@ -152,9 +151,9 @@ using the debian packages as mentioned in step 2 of the "Requirements" section.
$ vtep-ctl add-ps br0
$ vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1
-6. Start the VTEP emulator. If you installed the components following the
- `installation guide <../INSTALL.rst>`__ file, run the following from the
- same directory as this README:
+6. Start the VTEP emulator. If you installed the components following
+ ``Documentation/intro/install/general``, run the following from the same
+ directory as this README:
::
@@ -325,9 +325,9 @@ List the remote MAC bindings for \fIlswitch\fR, one per line.
These commands manipulate the \fBmanagers\fR column in the \fBGlobal\fR
table and rows in the \fBManagers\fR table. When \fBovsdb\-server\fR is
configured to use the \fBmanagers\fR column for OVSDB connections (as
-described in \fBINSTALL.Linux\fR and in the startup scripts provided
-with Open vSwitch), this allows the administrator to use \fBvtep\-ctl\fR
-to configure database connections.
+described in the startup scripts provided with Open vSwitch), this
+allows the administrator to use \fBvtep\-ctl\fR to configure database
+connections.
.
.IP "\fBget\-manager\fR"
Prints the configured manager(s).
This is a dumb move of all 'INSTALL*' docs, with very little refactoring (mostly updating links and making the titles a little more consistent. Additional refactoring will be done in subsequent changes. Signed-off-by: Stephen Finucane <stephen@that.guru> --- Documentation/automake.mk | 16 +++++++ .../howto/docker.rst | 13 +++--- Documentation/howto/index.rst | 6 +++ INSTALL.KVM.rst => Documentation/howto/kvm.rst | 15 +++--- .../howto/libvirt.rst | 11 ++--- .../howto/selinux.rst | 8 ++-- INSTALL.SSL.rst => Documentation/howto/ssl.rst | 4 +- Documentation/index.rst | 12 ++++- .../internals/contributing/documentation-style.rst | 4 +- .../intro/install/bash-completion.rst | 0 .../intro/install/debian.rst | 16 +++---- .../intro/install/dpdk-advanced.rst | 23 +++++---- .../intro/install/dpdk.rst | 54 ++++++++++------------ .../intro/install/fedora.rst | 17 +++---- .../intro/install/general.rst | 27 ++++------- Documentation/intro/install/index.rst | 33 +++++++++++++ .../intro/install/netbsd.rst | 7 ++- .../intro/install/rhel.rst | 38 +++++++++------ .../intro/install/userspace.rst | 14 +++--- .../intro/install/windows.rst | 3 +- .../intro/install/xenserver.rst | 12 ++--- FAQ.rst | 23 +++++---- Makefile.am | 15 ------ PORTING.rst | 8 ++-- README.rst | 32 +++---------- debian/openvswitch-common.docs | 2 - rhel/openvswitch-fedora.spec.in | 4 +- rhel/openvswitch.spec.in | 4 +- tutorial/ovn-tutorial.rst | 5 +- tutorial/tutorial.rst | 8 ++-- utilities/automake.mk | 2 - utilities/ovs-ctl.8 | 3 +- utilities/ovs-vsctl.8.in | 6 +-- vswitchd/ovs-vswitchd.8.in | 10 ++-- vtep/README.ovs-vtep.rst | 15 +++--- vtep/vtep-ctl.8.in | 6 +-- 36 files changed, 246 insertions(+), 230 deletions(-) rename INSTALL.Docker.rst => Documentation/howto/docker.rst (96%) rename INSTALL.KVM.rst => Documentation/howto/kvm.rst (86%) rename INSTALL.Libvirt.rst => Documentation/howto/libvirt.rst (87%) rename INSTALL.SELinux.rst => Documentation/howto/selinux.rst (97%) rename INSTALL.SSL.rst => Documentation/howto/ssl.rst (98%) rename utilities/ovs-command-bashcomp.INSTALL.rst => Documentation/intro/install/bash-completion.rst (100%) rename INSTALL.Debian.rst => Documentation/intro/install/debian.rst (94%) rename INSTALL.DPDK-ADVANCED.rst => Documentation/intro/install/dpdk-advanced.rst (98%) rename INSTALL.DPDK.rst => Documentation/intro/install/dpdk.rst (92%) rename INSTALL.Fedora.rst => Documentation/intro/install/fedora.rst (90%) rename INSTALL.rst => Documentation/intro/install/general.rst (97%) rename INSTALL.NetBSD.rst => Documentation/intro/install/netbsd.rst (89%) rename INSTALL.RHEL.rst => Documentation/intro/install/rhel.rst (87%) rename INSTALL.userspace.rst => Documentation/intro/install/userspace.rst (92%) rename INSTALL.Windows.rst => Documentation/intro/install/windows.rst (99%) rename INSTALL.XenServer.rst => Documentation/intro/install/xenserver.rst (96%)