diff options
36 files changed, 246 insertions, 230 deletions
diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 6f3df0770..3fade9492 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -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 \ diff --git a/INSTALL.Docker.rst b/Documentation/howto/docker.rst index 4d661720e..e23ca7575 100644 --- a/INSTALL.Docker.rst +++ b/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 diff --git a/Documentation/howto/index.rst b/Documentation/howto/index.rst index 1c4d9d2e3..81b2931d7 100644 --- a/Documentation/howto/index.rst +++ b/Documentation/howto/index.rst @@ -32,3 +32,9 @@ topics covered herein, refer to :doc:`/topics/index`. .. toctree:: :maxdepth: 2 + + kvm + selinux + libvirt + ssl + docker diff --git a/INSTALL.KVM.rst b/Documentation/howto/kvm.rst index 4a5b372e6..4b43af334 100644 --- a/INSTALL.KVM.rst +++ b/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 diff --git a/INSTALL.Libvirt.rst b/Documentation/howto/libvirt.rst index b32944cf8..0b303d54c 100644 --- a/INSTALL.Libvirt.rst +++ b/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 ----------- diff --git a/INSTALL.SELinux.rst b/Documentation/howto/selinux.rst index 8593d7f5a..ad556da58 100644 --- a/INSTALL.SELinux.rst +++ b/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. diff --git a/INSTALL.SSL.rst b/Documentation/howto/ssl.rst index 8edd25ec9..3085206fb 100644 --- a/INSTALL.SSL.rst +++ b/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, diff --git a/Documentation/index.rst b/Documentation/index.rst index a46407a06..be794f169 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -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 ----------- diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index 756f1678d..c32921e70 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -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 --------------------------- diff --git a/utilities/ovs-command-bashcomp.INSTALL.rst b/Documentation/intro/install/bash-completion.rst index 6df60c65c..6df60c65c 100644 --- a/utilities/ovs-command-bashcomp.INSTALL.rst +++ b/Documentation/intro/install/bash-completion.rst diff --git a/INSTALL.Debian.rst b/Documentation/intro/install/debian.rst index 6086b827b..648433144 100644 --- a/INSTALL.Debian.rst +++ b/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. diff --git a/INSTALL.DPDK-ADVANCED.rst b/Documentation/intro/install/dpdk-advanced.rst index 1c2437d89..44d1cd78c 100644 --- a/INSTALL.DPDK-ADVANCED.rst +++ b/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 @@ -345,8 +345,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:: @@ -367,7 +367,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: @@ -427,9 +427,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. @@ -672,7 +673,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:: @@ -935,5 +936,3 @@ Bug Reporting ------------- Report problems to bugs@openvswitch.org. - -.. _DPDK installation guide: INSTALL.DPDK.rst diff --git a/INSTALL.DPDK.rst b/Documentation/intro/install/dpdk.rst index 10ccfdf3b..7724c8a9f 100644 --- a/INSTALL.DPDK.rst +++ b/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.11 @@ -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 @@ threads and pin them to cores 1,2, run:: $ ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=0x6 -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_11.html -Bug Reporting -------------- +Reporting Bugs +-------------- -Please report problems to bugs@openvswitch.org. +Report problems to bugs@openvswitch.org. diff --git a/INSTALL.Fedora.rst b/Documentation/intro/install/fedora.rst index b9be0edfe..73635386a 100644 --- a/INSTALL.Fedora.rst +++ b/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 -------- diff --git a/INSTALL.rst b/Documentation/intro/install/general.rst index d934c1f51..631dc9be5 100644 --- a/INSTALL.rst +++ b/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. diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst index 35dc67cf5..2366388a2 100644 --- a/Documentation/intro/install/index.rst +++ b/Documentation/intro/install/index.rst @@ -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 diff --git a/INSTALL.NetBSD.rst b/Documentation/intro/install/netbsd.rst index e204c57d4..2b52eaf08 100644 --- a/INSTALL.NetBSD.rst +++ b/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`. diff --git a/INSTALL.RHEL.rst b/Documentation/intro/install/rhel.rst index 125c55de1..498fd8f25 100644 --- a/INSTALL.RHEL.rst +++ b/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 ----------------------------------- diff --git a/INSTALL.userspace.rst b/Documentation/intro/install/userspace.rst index 10223555b..036852759 100644 --- a/INSTALL.userspace.rst +++ b/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. diff --git a/INSTALL.Windows.rst b/Documentation/intro/install/windows.rst index 251cd10e3..eb55720ed 100644 --- a/INSTALL.Windows.rst +++ b/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: diff --git a/INSTALL.XenServer.rst b/Documentation/intro/install/xenserver.rst index 5f0fa4136..c0f5e3156 100644 --- a/INSTALL.XenServer.rst +++ b/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 diff --git a/Makefile.am b/Makefile.am index 0036fecff..df4214952 100644 --- a/Makefile.am +++ b/Makefile.am @@ -70,21 +70,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 \ diff --git a/PORTING.rst b/PORTING.rst index 33db41de7..bae8cd9cd 100644 --- a/PORTING.rst +++ b/PORTING.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 diff --git a/README.rst b/README.rst index 715f969e5..c8227f80b 100644 --- a/README.rst +++ b/README.rst @@ -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>`__. diff --git a/debian/openvswitch-common.docs b/debian/openvswitch-common.docs index c5612ddee..27f51626a 100644 --- a/debian/openvswitch-common.docs +++ b/debian/openvswitch-common.docs @@ -1,3 +1 @@ FAQ.rst -INSTALL.DPDK.rst -README-native-tunneling.rst diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in index d1f33af30..d70934a48 100644 --- a/rhel/openvswitch-fedora.spec.in +++ b/rhel/openvswitch-fedora.spec.in @@ -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 diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 846f8e0b9..261736803 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -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 diff --git a/tutorial/ovn-tutorial.rst b/tutorial/ovn-tutorial.rst index 8d9fc1a43..bb5f6201f 100644 --- a/tutorial/ovn-tutorial.rst +++ b/tutorial/ovn-tutorial.rst @@ -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 diff --git a/tutorial/tutorial.rst b/tutorial/tutorial.rst index fab635030..422bc0d61 100644 --- a/tutorial/tutorial.rst +++ b/tutorial/tutorial.rst @@ -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. diff --git a/utilities/automake.mk b/utilities/automake.mk index 014e477d1..2590dc0e6 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -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 \ diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8 index cd7c2674f..1fe0a3c94 100644 --- a/utilities/ovs-ctl.8 +++ b/utilities/ovs-ctl.8 @@ -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). diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 41288018c..19179060e 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -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). diff --git a/vswitchd/ovs-vswitchd.8.in b/vswitchd/ovs-vswitchd.8.in index c745dbc8b..fc19f3b32 100644 --- a/vswitchd/ovs-vswitchd.8.in +++ b/vswitchd/ovs-vswitchd.8.in @@ -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). diff --git a/vtep/README.ovs-vtep.rst b/vtep/README.ovs-vtep.rst index 75f03d0b7..668ee08f2 100644 --- a/vtep/README.ovs-vtep.rst +++ b/vtep/README.ovs-vtep.rst @@ -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: :: diff --git a/vtep/vtep-ctl.8.in b/vtep/vtep-ctl.8.in index e0f49a78d..190135665 100644 --- a/vtep/vtep-ctl.8.in +++ b/vtep/vtep-ctl.8.in @@ -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). |