From: Numan Siddique <[email protected]> This patch deletes the non ovn related files and updates the Documentation/intro/install/general.rst and other related file for OVN installation.
Signed-off-by: Numan Siddique <[email protected]> --- Documentation/automake.mk | 6 - Documentation/index.rst | 11 +- Documentation/intro/index.rst | 2 - .../intro/install/bash-completion.rst | 106 --- Documentation/intro/install/debian.rst | 104 +-- Documentation/intro/install/distributions.rst | 38 +- Documentation/intro/install/fedora.rst | 83 +- Documentation/intro/install/general.rst | 395 +++------ Documentation/intro/install/index.rst | 4 - Documentation/intro/install/netbsd.rst | 58 -- Documentation/intro/install/userspace.rst | 106 --- Documentation/intro/install/windows.rst | 776 +----------------- Documentation/intro/install/xenserver.rst | 229 ------ Documentation/intro/what-is-ovs.rst | 41 - Documentation/intro/why-ovs.rst | 131 --- 15 files changed, 145 insertions(+), 1945 deletions(-) delete mode 100644 Documentation/intro/install/bash-completion.rst delete mode 100644 Documentation/intro/install/netbsd.rst delete mode 100644 Documentation/intro/install/userspace.rst delete mode 100644 Documentation/intro/install/xenserver.rst delete mode 100644 Documentation/intro/what-is-ovs.rst delete mode 100644 Documentation/intro/why-ovs.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index c3b0949bd..f7e1d2628 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -6,21 +6,15 @@ DOC_SOURCE = \ Documentation/index.rst \ Documentation/contents.rst \ Documentation/intro/index.rst \ - Documentation/intro/what-is-ovs.rst \ - Documentation/intro/why-ovs.rst \ Documentation/intro/install/index.rst \ - Documentation/intro/install/bash-completion.rst \ Documentation/intro/install/debian.rst \ Documentation/intro/install/documentation.rst \ Documentation/intro/install/distributions.rst \ Documentation/intro/install/fedora.rst \ Documentation/intro/install/general.rst \ - Documentation/intro/install/netbsd.rst \ Documentation/intro/install/ovn-upgrades.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/tutorials/ovn-openstack.rst \ Documentation/tutorials/ovn-sandbox.rst \ diff --git a/Documentation/index.rst b/Documentation/index.rst index 192ed7631..9e5664ec0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -47,17 +47,10 @@ The Open vSwitch documentation is organised into multiple sections: First Steps ----------- -Getting started with Open vSwitch (OVS) or Open Virtual Network (OVN) for Open -vSwitch? Start here. - -- **Overview:** :doc:`intro/what-is-ovs` | - :doc:`intro/why-ovs` +Getting started with 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/windows` - **Tutorials:** :doc:`tutorials/ovn-sandbox` | :doc:`tutorials/ovn-openstack` | diff --git a/Documentation/intro/index.rst b/Documentation/intro/index.rst index 0ad7ad1dc..7d42813cd 100644 --- a/Documentation/intro/index.rst +++ b/Documentation/intro/index.rst @@ -32,6 +32,4 @@ How to get started with Open vSwitch. .. toctree:: :maxdepth: 2 - what-is-ovs - why-ovs install/index diff --git a/Documentation/intro/install/bash-completion.rst b/Documentation/intro/install/bash-completion.rst deleted file mode 100644 index 4018be05b..000000000 --- a/Documentation/intro/install/bash-completion.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -==================================== -Bash command-line completion scripts -==================================== - -There are two completion scripts available: ``ovs-appctl-bashcomp.bash`` and -``ovs-vsctl-bashcomp.bash``. - -ovs-appctl-bashcomp -------------------- - -``ovs-appctl-bashcomp.bash`` adds bash command-line completion support for -``ovs-appctl``, ``ovs-dpctl``, ``ovs-ofctl`` and ``ovsdb-tool`` commands. - -Features -~~~~~~~~ - -- Display available completion or complete on unfinished user input (long - option, subcommand, and argument). - -- Subcommand hints - -- Convert between keywords like ``bridge``, ``port``, ``interface``, or ``dp`` - and the available record in ovsdb. - -Limitations -~~~~~~~~~~~ - -- Only supports a small set of important keywords (``dp``, ``datapath``, - ``bridge``, ``switch``, ``port``, ``interface``, ``iface``). - -- Does not support parsing of nested options. For example:: - - $ ovsdb-tool create [db [schema]] - -- Does not support expansion on repeated argument. For example:: - - $ ovs-dpctl show [dp...]). - -- Only supports matching on long options, and only in the format ``--option - [arg]``. Do not use ``--option=[arg]``. - -ovs-vsctl-bashcomp -------------------- - -``ovs-vsctl-bashcomp.bash`` adds Bash command-line completion support for -``ovs-vsctl`` command. - -Features -~~~~~~~~ - -- Display available completion and complete on user input for global/local - options, command, and argument. - -- Query database and expand keywords like ``table``, ``record``, ``column``, or - ``key``, to available completions. - -- Deal with argument relations like 'one and more', 'zero or one'. - -- Complete multiple ``ovs-vsctl`` commands cascaded via ``--``. - -Limitations -~~~~~~~~~~~ - -Completion of very long ``ovs-vsctl`` commands can take up to several seconds. - -Usage ------ - -The bashcomp scripts should be placed at ``/etc/bash_completion.d/`` to be -available for all bash sessions. Running ``make install`` will place the -scripts to ``$(sysconfdir)/bash_completion.d/``, thus, the user should specify -``--sysconfdir=/etc`` at configuration. If OVS is installed from packages, the -scripts will automatically be placed inside ``/etc/bash_completion.d/``. - -If you just want to run the scripts in one bash, you can remove them from -``/etc/bash_completion.d/`` and run the scripts via ``. -ovs-appctl-bashcomp.bash`` or ``. ovs-vsctl-bashcomp.bash``. - -Tests ------ - -Unit tests are added in ``tests/completion.at`` and integrated into autotest -framework. To run the tests, just run ``make check``. diff --git a/Documentation/intro/install/debian.rst b/Documentation/intro/install/debian.rst index 4024dc07a..e0605ed50 100644 --- a/Documentation/intro/install/debian.rst +++ b/Documentation/intro/install/debian.rst @@ -22,106 +22,8 @@ Avoid deeper levels because they do not render well. ================================= -Debian Packaging for Open vSwitch +Debian Packaging for OVN ================================= -This document describes how to build Debian packages for Open vSwitch. To -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 - distributions. - -Before You Begin ----------------- - -Before you begin, consider whether you really need to build packages yourself. -Debian "wheezy" and "sid", as well as recent versions of Ubuntu, contain -pre-built Debian packages for Open vSwitch. It is easier to install these than -to build your own. To use packages from your distribution, skip ahead to -"Installing .deb Packages", below. - -Building Open vSwitch Debian packages -------------------------------------- - -You may build from an Open vSwitch distribution tarball or from an Open vSwitch -Git tree with these instructions. - -You do not need to be the superuser to build the Debian packages. - -1. Install the "build-essential" and "fakeroot" packages. For example:: - - $ apt-get install build-essential fakeroot - -2. Obtain and unpack an Open vSwitch source distribution and ``cd`` into its - top level directory. - -3. Install the build dependencies listed under "Build-Depends:" near the top of - ``debian/control``. You can install these any way you like, e.g. with - ``apt-get install``. - -Check your work by running ``dpkg-checkbuilddeps`` in the top level of your OVS -directory. If you've installed all the dependencies properly, -``dpkg-checkbuilddeps`` will exit without printing anything. If you forgot to -install some dependencies, it will tell you which ones. - -4. Build the package:: - - $ fakeroot debian/rules binary - - This will do a serial build that runs the unit tests. This will take - approximately 8 to 10 minutes. If you prefer, you can run a faster parallel - build:: - - $ DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary - - If you are in a big hurry, you can even skip the unit tests:: - - $ DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary - -.. note:: - - There are a few pitfalls in the Debian packaging building system so that, - occasionally, you may find that in a tree that you have using for a while, - the build command above exits immediately without actually building anything. - To fix the problem, run:: - - $ fakeroot debian/rules clean - - or start over from a fresh copy of the source tree. - -5. The generated .deb files will be in the parent directory of the Open vSwitch - source distribution. - -Installing .deb Packages ------------------------- - -These instructions apply to installing from Debian packages that you built -yourself, as described in the previous section. In this case, use a command -such as ``dpkg -i`` to install the .deb files that you build. You will have to -manually install any missing dependencies. - -You can also use these instruction to install from packages provided by Debian -or a Debian derivative distribution such as Ubuntu. In this case, use a -program such as ``apt-get`` or ``aptitude`` to download and install the -provided packages. These programs will also automatically download and install -any missing dependencies. - -.. important:: - You must be superuser to install Debian packages. - -1. Start by installing an Open vSwitch kernel module. See - ``debian/openvswitch-switch.README.Debian`` for the available options. - -2. Install the ``openvswitch-switch`` and ``openvswitch-common`` packages. - These packages include the core userspace components of the switch. - -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. - -Reporting Bugs --------------- - -Report problems to [email protected]. +OVN packages needs to be split from OVS. This section will be +updated once it is done. diff --git a/Documentation/intro/install/distributions.rst b/Documentation/intro/install/distributions.rst index 5987178ea..29e52fd56 100644 --- a/Documentation/intro/install/distributions.rst +++ b/Documentation/intro/install/distributions.rst @@ -25,48 +25,28 @@ Distributions packaging Open vSwitch ==================================== -This document lists various popular distributions packaging Open vSwitch. -Open vSwitch is packaged by various distributions for multiple platforms and -architectures. +This document lists various popular distributions packaging OVN. .. note:: The packaged version available with distributions may not be latest - Open vSwitch release. + OVN release. Debian ------- You can use ``apt-get`` or ``aptitude`` to install the .deb packages and must -be superuser. - -1. Debian has ``openvswitch-switch`` and ``openvswitch-common`` .deb packages -that includes the core userspace components of the switch. - -2. For kernel datapath, ``openvswitch-datapath-dkms`` can be installed to -automatically build and install Open vSwitch kernel module for your running -kernel. - -3. For DPDK datapath, Open vSwitch with DPDK support is bundled in the package -``openvswitch-switch-dpdk``. +be superuser. Debian has ``ovn-common``, ``ovn-host``, ``ovn-central`` and +``ovn-vtep`` .deb packages. Fedora ------ -Fedora provides ``openvswitch``, ``openvswitch-devel``, ``openvswitch-test`` -and ``openvswitch-debuginfo`` rpm packages. You can install ``openvswitch`` -package in minimum installation. Use ``yum`` or ``dnf`` to install the rpm -packages and must be superuser. - -Red Hat -------- - -RHEL distributes ``openvswitch`` rpm package that supports kernel datapath. -DPDK accelerated Open vSwitch can be installed using ``openvswitch-dpdk`` -package. +Fedora provides ``ovn``, ``ovn-host``, ``ovn-central`` +and ``ovn-vtep`` rpm packages. Use ``yum`` or ``dnf`` to install +the rpm packages and must be superuser. OpenSuSE -------- -OpenSUSE provides ``openvswitch``, ``openvswitch-switch`` rpm packages. Also -``openvswitch-dpdk`` and ``openvswitch-dpdk-switch`` can be installed for -Open vSwitch using DPDK accelerated datapath. +OpenSUSE provides ``openvswitch-ovn-common``, ```openvswitch-ovn-host``, +```openvswitch-ovn-central`` and ```openvswitch-ovn-vtep`` rpm packages. diff --git a/Documentation/intro/install/fedora.rst b/Documentation/intro/install/fedora.rst index 4e1a99766..c8ea6ec01 100644 --- a/Documentation/intro/install/fedora.rst +++ b/Documentation/intro/install/fedora.rst @@ -22,16 +22,17 @@ Avoid deeper levels because they do not render well. =========================================== -Fedora, RHEL 7.x Packaging for Open vSwitch +Fedora, RHEL 7.x Packaging for OVN =========================================== -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 +This document provides instructions for building and installing OVN +RPM packages on a Fedora Linux host. Instructions for the installation of OVN +Fedora Linux host without using RPM packages can be found in the :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. +These instructions have been tested with Fedora 29 and 30, and are also +applicable for RHEL 7.x and its derivatives, including CentOS 7.x and +Scientific Linux 7.x. Build Requirements ------------------ @@ -41,7 +42,7 @@ Newer distributions use ``dnf`` but if it's not available, then use ``yum`` instructions. The command below will install RPM tools and generic build dependencies. -And (optionally) include these packages: libcap-ng libcap-ng-devel dpdk-devel. +And (optionally) include these packages: libcap-ng libcap-ng-devel. DNF: :: @@ -53,14 +54,14 @@ YUM: $ yum install @'Development Tools' rpm-build yum-utils -Then it is necessary to install Open vSwitch specific build dependencies. +Then it is necessary to install OVN specific build dependencies. The dependencies are listed in the SPEC file, but first it is necessary to replace the VERSION tag to be a valid SPEC. The command below will create a temporary SPEC file:: - $ sed -e 's/@VERSION@/0.0.1/' rhel/openvswitch-fedora.spec.in \ - > /tmp/ovs.spec + $ sed -e 's/@VERSION@/0.0.1/' rhel/ovn-fedora.spec.in \ + > /tmp/ovn.spec And to install specific dependencies, use the corresponding tool below. For some of the dependencies on RHEL you may need to add two additional @@ -71,13 +72,13 @@ repositories to help yum-builddep, e.g.:: DNF:: - $ dnf builddep /tmp/ovs.spec + $ dnf builddep /tmp/ovn.spec YUM:: - $ yum-builddep /tmp/ovs.spec + $ yum-builddep /tmp/ovn.spec -Once that is completed, remove the file ``/tmp/ovs.spec``. +Once that is completed, remove the file ``/tmp/ovn.spec``. Bootstraping ------------ @@ -92,25 +93,20 @@ Refer to :ref:`general-configuring`. Building -------- -User Space RPMs +OVN RPMs ~~~~~~~~~~~~~~~ -To build Open vSwitch user-space RPMs, execute the following from the directory +To build OVN RPMs, execute the following from the directory in which `./configure` was executed: :: $ make rpm-fedora -This will create the RPMs `openvswitch`, `python-openvswitch`, -`openvswitch-test`, `openvswitch-devel` and `openvswitch-debuginfo`. +This will create the RPMs `ovn`, `ovn-central`, `ovn-host`, `ovn-vtep`, +`ovn-docker`, ``ovn-debuginfo``, ``ovn-central-debuginfo``, +``ovn-host-debuginfo`` and ```ovn-vtep-debuginfo```. -To enable DPDK support in the openvswitch package, the ``--with dpdk`` option -can be added: - -:: - - $ make rpm-fedora RPMBUILD_OPT="--with dpdk --without check" You can also have the above commands automatically run the Open vSwitch unit tests. This can take several minutes. @@ -119,34 +115,6 @@ tests. This can take several minutes. $ make rpm-fedora RPMBUILD_OPT="--with check" -To build OVN RPMs, execute the following from the directory in which -`./configure` was executed: - -:: - - $ make rpm-fedora-ovn - -This will create the RPMs `ovn`, `ovn-common`, `ovn-central`, `ovn-host`, -`ovn-docker` and `ovn-vtep`. - - -Kernel OVS Tree Datapath RPM -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To build the Open vSwitch kernel module for the currently running kernel -version, run: - -:: - - $ make rpm-fedora-kmod - -To build the Open vSwitch kernel module for another kernel version, the desired -kernel version can be specified via the `kversion` macro. For example: - -:: - - $ make rpm-fedora-kmod \ - RPMBUILD_OPT='-D "kversion 4.3.4-300.fc23.x86_64"' Installing ---------- @@ -154,19 +122,6 @@ Installing RPM packages can be installed by using the command ``rpm -i``. Package installation requires superuser privileges. -The `openvswitch-kmod` RPM should be installed first if the Linux OVS tree -datapath module is to be used. The `openvswitch-kmod` RPM should not be -installed if only the in-tree Linux datapath or user-space datapath is needed. -Refer to the :doc:`/faq/index` for more information about the various Open -vSwitch datapath options. - -In most cases only the `openvswitch` RPM will need to be installed. The -`python-openvswitch`, `openvswitch-test`, `openvswitch-devel`, and -`openvswitch-debuginfo` RPMs are optional unless required for a specific -purpose. - -The `ovn-*` packages are only needed when using OVN. - Refer to the `RHEL README`__ for additional usage and configuration information. diff --git a/Documentation/intro/install/general.rst b/Documentation/intro/install/general.rst index bca4decb9..99d8fec04 100644 --- a/Documentation/intro/install/general.rst +++ b/Documentation/intro/install/general.rst @@ -22,47 +22,36 @@ Avoid deeper levels because they do not render well. ========================================= -Open vSwitch on Linux, FreeBSD and NetBSD +OVN on Linux, FreeBSD and NetBSD ========================================= -This document describes how to build and install Open vSwitch on a generic +This document describes how to build and install OVN on a generic Linux, FreeBSD, or NetBSD host. For specifics around installation on a specific platform, refer to one of the other installation guides listed in :doc:`index`. -Obtaining Open vSwitch Sources +Obtaining OVN Sources ------------------------------ -The canonical location for Open vSwitch source code is its Git -repository, which you can clone into a directory named "ovs" with:: +The canonical location for OVN source code is its Git +repository, which you can clone into a directory named "ovn" with:: - $ git clone https://github.com/openvswitch/ovs.git + $ git clone https://github.com/ovn-org/ovn.git Cloning the repository leaves the "master" branch initially checked -out. This is the right branch for general development. If, on the -other hand, if you want to build a particular released version, you -can check it out by running a command such as the following from the -"ovs" directory:: +out. This is the right branch for general development. - $ git checkout v2.7.0 +As of now there are no official OVN releases. -The repository also has a branch for each release series. For -example, to obtain the latest fixes in the Open vSwitch 2.7.x release -series, which might include bug fixes that have not yet been in any -released version, you can check it out from the "ovs" directory with:: - - $ git checkout origin/branch-2.7 - -If you do not want to use Git, you can also obtain tarballs for Open -vSwitch release versions via http://openvswitch.org/download/, or -download a ZIP file for any snapshot from the web interface at -https://github.com/openvswitch/ovs. +Although building OVN, also builds OVS, it is recommended to clone +and build OVS from its own repo. Please see the Open vSwitch +documentation to build and install OVS. .. _general-build-reqs: Build Requirements ------------------ -To compile the userspace programs in the Open vSwitch distribution, you will +To compile the userspace programs in the OVN distribution, you will need the following software: - GNU make @@ -76,66 +65,26 @@ need the following software: - 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``). +- While OVN may be compatible with other compilers, optimal support for atomic + operations may be missing, making OVN very slow + (see ``ovs/lib/ovs-atomic.h``). - libssl, from OpenSSL, is optional but recommended if you plan to connect the - Open vSwitch to an OpenFlow controller. libssl is required to establish - confidentiality and authenticity in the connections from an Open vSwitch to - an OpenFlow controller. If libssl is installed, then Open vSwitch will - automatically build with support for it. - -- libcap-ng, written by Steve Grubb, is optional but recommended. It is - required to run OVS daemons as a non-root user with dropped root privileges. - If libcap-ng is installed, then Open vSwitch will automatically build with - support for it. + OVN services to the OVN DB ovsdb-servers securely. If libssl is installed, + then OVN will automatically build with support for it. - Python 2.7. You must also have the Python ``six`` library version 1.4.0 or later. - Unbound library, from http://www.unbound.net, is optional but recommended if - you want to enable ovs-vswitchd and other utilities to use DNS names when - specifying OpenFlow and OVSDB remotes. If unbound library is already - installed, then Open vSwitch will automatically build with support for it. + you want to enable ovn-northd, ovn-controller and other utilities to use + DNS names when specifying OVSDB remotes. If unbound library is already + installed, then OVN will automatically build with support for it. The environment variable OVS_RESOLV_CONF can be used to specify DNS server configuration file (the default file on Linux is /etc/resolv.conf). -On Linux, you may choose to compile the kernel module that comes with the Open -vSwitch distribution or to use the kernel module built into the Linux kernel -(version 3.3 or later). See the :doc:`/faq/index` 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. Refer to :doc:`userspace` for details. - -To compile the kernel module on Linux, you must also install the -following: - -- A supported Linux kernel version. - - For optional support of ingress policing, you must enable kernel - configuration options ``NET_CLS_BASIC``, ``NET_SCH_INGRESS``, and - ``NET_ACT_POLICE``, either built-in or as modules. ``NET_CLS_POLICE`` is - obsolete and not needed.) - - On kernels before 3.11, the ``ip_gre`` module, for GRE tunnels over IP - (``NET_IPGRE``), must not be loaded or compiled in. - - To configure HTB or HFSC quality of service with Open vSwitch, you must - enable the respective configuration options. - - To use Open vSwitch support for TAP devices, you must enable ``CONFIG_TUN``. - -- To build a kernel module, you need the same version of GCC that was used to - build that kernel. - -- A kernel build directory corresponding to the Linux kernel image the module - is to run on. Under Debian and Ubuntu, for example, each linux-image package - containing a kernel binary has a corresponding linux-headers package with - the required build infrastructure. - If you are working from a Git tree or snapshot (instead of from a distribution -tarball), or if you modify the Open vSwitch build system or the database +tarball), or if you modify the OVN build system or the database schema, you will also need the following software: - Autoconf version 2.63 or later. @@ -144,28 +93,12 @@ schema, you will also need the following software: - libtool version 2.4 or later. (Older versions might work too.) -The datapath tests for userspace and Linux datapaths also rely upon: - -- pyftpdlib. Version 1.2.0 is known to work. Earlier versions should - also work. - -- GNU wget. Version 1.16 is known to work. Earlier versions should also - work. - -- netcat. Several common implementations are known to work. - -- curl. Version 7.47.0 is known to work. Earlier versions should also work. - -- tftpy. Version 0.6.2 is known to work. Earlier versions should also work. - -- netstat. Available from various distro specific packages - -The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in formats +The OVN manpages will include an E-R diagram, in formats other than plain text, only if you have the following: - dot from graphviz (http://www.graphviz.org/). -If you are going to extensively modify Open vSwitch, consider installing the +If you are going to extensively modify OVN, consider installing the following to obtain better warnings: - "sparse" version 0.5.1 or later @@ -180,29 +113,18 @@ following to obtain better warnings: come from the "hacking" flake8 plugin. If it's not installed, the warnings just won't occur until it's run on a system with "hacking" installed. -You may find the ovs-dev script found in ``utilities/ovs-dev.py`` useful. +You may find the ovs-dev script found in ``ovs/utilities/ovs-dev.py`` useful. .. _general-install-reqs: Installation Requirements ------------------------- -The machine you build Open vSwitch on may not be the one you run it on. To -simply install and run Open vSwitch you require the following software: +The machine you build OVN on may not be the one you run it on. +To simply install and run OVN you require the following software: - Shared libraries compatible with those used for the build. -- On Linux, if you want to use the kernel-based datapath (which is the most - common use case), then a kernel with a compatible kernel module. This - can be a kernel module built with Open vSwitch (e.g. in the previous - step), or the kernel module that accompanies Linux 3.3 and later. Open - vSwitch features and performance can vary based on the module and the - kernel. - -- For optional support of ingress policing on Linux, the "tc" program - from iproute2 (part of all major distributions and available at - https://wiki.linuxfoundation.org/networking/iproute2). - - Python 2.7. You must also have the Python six library version 1.4.0 or later. @@ -231,9 +153,9 @@ invoke configure without any arguments. For example:: $ ./configure -By default all files are installed under ``/usr/local``. Open vSwitch also -expects to find its database in ``/usr/local/etc/openvswitch`` by default. If -you want to install all files into, e.g., ``/usr`` and ``/var`` instead of +By default all files are installed under ``/usr/local``. OVN and Open vSwitch +also expects to find its database in ``/usr/local/etc/openvswitch`` by default. +If you want to install all files into, e.g., ``/usr`` and ``/var`` instead of ``/usr/local`` and ``/usr/local/var`` and expect to use ``/etc/openvswitch`` as the default database directory, add options as shown here:: @@ -241,9 +163,9 @@ the default database directory, add options as shown here:: .. note:: - Open vSwitch installed with packages like .rpm (e.g. via ``yum install`` or - ``rpm -ivh``) and .deb (e.g. via ``apt-get install`` or ``dpkg -i``) use the - above configure options. + Open vSwitch and OVN installed with packages like .rpm (e.g. via + ``yum install`` or ``rpm -ivh``) and .deb (e.g. via + ``apt-get install`` or ``dpkg -i``) use the above configure options. By default, static libraries are built and linked against. If you want to use shared libraries instead:: @@ -313,14 +235,7 @@ example, to build for a running instance of Linux:: then ``configure`` will fail with an error message. Refer to the :doc:`/faq/index` for advice in that case. -If you wish to build the kernel module for an architecture other than the -architecture of the machine used for the build, you may specify the kernel -architecture string using the KARCH variable when invoking the configure -script. For example, to build for MIPS with Linux:: - - $ ./configure --with-linux=/path/to/linux KARCH=mips - -If you plan to do much Open vSwitch development, you might want to add +If you plan to do much OVN development, you might want to add ``--enable-Werror``, which adds the ``-Werror`` option to the compiler command line, turning warnings into errors. That makes it impossible to miss warnings generated by the build. For example:: @@ -345,9 +260,8 @@ option:: $ ./configure --help You can also run configure from a separate build directory. This is helpful if -you want to build Open vSwitch in more than one way from a single source -directory, e.g. to try out both GCC and Clang builds, or to build kernel -modules for more than one Linux version. For example:: +you want to build OVN in more than one way from a single source +directory, e.g. to try out both GCC and Clang builds. For example:: $ mkdir _gcc && (cd _gcc && ./configure CC=gcc) $ mkdir _clang && (cd _clang && ./configure CC=clang) @@ -390,210 +304,121 @@ Building $ make install -5. If you built kernel modules, you may install them, e.g.:: - - $ make modules_install - - It is possible that you already had a Open vSwitch kernel module installed - on your machine that came from upstream Linux (in a different directory). To - make sure that you load the Open vSwitch kernel module you built from this - repository, you should create a ``depmod.d`` file that prefers your newly - installed kernel modules over the kernel modules from upstream Linux. The - following snippet of code achieves the same:: - - $ config_file="/etc/depmod.d/openvswitch.conf" - $ for module in datapath/linux/*.ko; do - modname="$(basename ${module})" - echo "override ${modname%.ko} * extra" >> "$config_file" - echo "override ${modname%.ko} * weak-updates" >> "$config_file" - done - $ depmod -a - - Finally, load the kernel modules that you need. e.g.:: - - $ /sbin/modprobe openvswitch - - To verify that the modules have been loaded, run ``/sbin/lsmod`` and check - that openvswitch is listed:: - - $ /sbin/lsmod | grep openvswitch - - .. note:: - If the ``modprobe`` operation fails, look at the last few kernel log - messages (e.g. with ``dmesg | tail``). Generally, issues like this occur - when Open vSwitch is built for a kernel different from the one into which - you are trying to load it. Run ``modinfo`` on ``openvswitch.ko`` and on a - module built for the running kernel, e.g.:: - - $ /sbin/modinfo openvswitch.ko - $ /sbin/modinfo /lib/modules/$(uname -r)/kernel/net/bridge/bridge.ko - - Compare the "vermagic" lines output by the two commands. If they differ, - then Open vSwitch was built for the wrong kernel. - - If you decide to report a bug or ask a question related to module loading, - include the output from the ``dmesg`` and ``modinfo`` commands mentioned - above. - .. _general-starting: Starting -------- -On Unix-alike systems, such as BSDs and Linux, starting the Open vSwitch -suite of daemons is a simple process. Open vSwitch includes a shell script, -and helpers, called ovs-ctl which automates much of the tasks for starting -and stopping ovsdb-server, and ovs-vswitchd. After installation, the daemons -can be started by using the ovs-ctl utility. This will take care to setup -initial conditions, and start the daemons in the correct order. The ovs-ctl -utility is located in '$(pkgdatadir)/scripts', and defaults to +Before starting the OVN, start the Open vSwitch daemons. Refer to the +Open vSwitch documentation for more details on how to start OVS. + +On Unix-alike systems, such as BSDs and Linux, starting the OVN +suite of daemons is a simple process. OVN includes a shell script, +called ovn-ctl which automates much of the tasks for starting +and stopping ovn-northd, ovn-controller and ovsdb-servers. After installation, +the daemons can be started by using the ovn-ctl utility. This will take care +to setup initial conditions, and start the daemons in the correct order. +The ovn-ctl utility is located in '$(pkgdatadir)/scripts', and defaults to '/usr/local/share/openvswitch/scripts'. An example after install might be:: $ export PATH=$PATH:/usr/local/share/openvswitch/scripts - $ ovs-ctl start + $ ovn-ctl start_northd + $ ovn-ctl start_controller -Additionally, the ovs-ctl script allows starting / stopping the daemons -individually using specific options. To start just the ovsdb-server:: +Starting OVN Central services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ export PATH=$PATH:/usr/local/share/openvswitch/scripts - $ ovs-ctl --no-ovs-vswitchd start - -Likewise, to start just the ovs-vswitchd:: +OVN central services includes ovn-northd, Northbound and +Southbound ovsdb-server. $ export PATH=$PATH:/usr/local/share/openvswitch/scripts - $ ovs-ctl --no-ovsdb-server start + $ ovn-ctl start_northd -Refer to ovs-ctl(8) for more information on ovs-ctl. +Refer to ovn-ctl(8) for more information and the supported options. -In addition to using the automated script to start Open vSwitch, you may -wish to manually start the various daemons. Before starting ovs-vswitchd -itself, you need to start its configuration database, ovsdb-server. Each -machine on which Open vSwitch is installed should run its own copy of -ovsdb-server. Before ovsdb-server itself can be started, configure a -database that it can use:: +You may wish to manually start the OVN central daemons. +Before starting ovn-northd you need to start OVN Northbound and Southbound +ovsdb-servers. Before ovsdb-servers can be started, +configure the Northbound and Southbound databases:: $ mkdir -p /usr/local/etc/openvswitch - $ ovsdb-tool create /usr/local/etc/openvswitch/conf.db \ - vswitchd/vswitch.ovsschema - -Configure ovsdb-server to use database created above, to listen on a Unix -domain socket, to connect to any managers specified in the database itself, and -to use the SSL configuration in the database:: - - $ mkdir -p /usr/local/var/run/openvswitch - $ ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \ - --remote=db:Open_vSwitch,Open_vSwitch,manager_options \ - --private-key=db:Open_vSwitch,SSL,private_key \ - --certificate=db:Open_vSwitch,SSL,certificate \ - --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \ + $ ovsdb-tool create /usr/local/etc/openvswitch/ovnnb_db.db \ + ovn-nb.ovsschema + $ ovsdb-tool create /usr/local/etc/openvswitch/ovnsb_db.db \ + ovn-sb.ovsschema + +Configure ovsdb-servers to use databases created above, to listen on a Unix +domain socket and to use the SSL configuration in the database:: + + $ mkdir -p /usr/local/var/run/openvswitch + $ ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/ovnnb_db.sock \ + --remote=db:OVN_Northbound,NB_Global,connections \ + --private-key=db:OVN_Northbound,SSL,private_key \ + --certificate=db:OVN_Northbound,SSL,certificate \ + --bootstrap-ca-cert=db:OVN_Northbound,SSL,ca_cert \ + --pidfile --detach --log-file + $ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/ovnsb_db.sock \ + --remote=db:OVN_Southbound,SB_Global,connections \ + --private-key=db:OVN_Southbound,SSL,private_key \ + --certificate=db:OVN_Southbound,SSL,certificate \ + --bootstrap-ca-cert=db:OVN_Southbound,SSL,ca_cert \ --pidfile --detach --log-file .. note:: - If you built Open vSwitch without SSL support, then omit ``--private-key``, + If you built OVN without SSL support, then omit ``--private-key``, ``--certificate``, and ``--bootstrap-ca-cert``.) -Initialize the database using ovs-vsctl. This is only necessary the first time -after you create the database with ovsdb-tool, though running it at any time is -harmless:: +Initialize the databases using ovn-nbctl and ovn-sbctl. This is only necessary +the first time after you create the databases with ovsdb-tool, though running +it at any time is harmless:: - $ ovs-vsctl --no-wait init + $ ovn-nbctl --no-wait init + $ ovn-sbctl --no-wait init -Start the main Open vSwitch daemon, telling it to connect to the same Unix +Start the ovn-northd, telling it to connect to the OVN db servers same Unix domain socket:: - $ ovs-vswitchd --pidfile --detach --log-file - -Validating ----------- - -At this point you can use ovs-vsctl to set up bridges and other Open vSwitch -features. For example, to create a bridge named ``br0`` and add ports ``eth0`` -and ``vif1.0`` to it:: + $ ovn-northd --pidfile --detach --log-file - $ ovs-vsctl add-br br0 - $ ovs-vsctl add-port br0 eth0 - $ ovs-vsctl add-port br0 vif1.0 +Starting OVN host service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Refer to ovs-vsctl(8) for more details. You may also wish to refer to -:doc:`/topics/testing` for information on more generic testing of OVS. +On each chassis, ovn-controller service should be started. +ovn-controller assumes it gets configuration information from the +Open_vSwitch table of the local OVS instance. Refer to the +ovn-controller(8) for the configuration keys. -Upgrading ---------- +Below are the required keys to be configured on each chassis. -When you upgrade Open vSwitch from one version to another you should also -upgrade the database schema: +1. external_ids:system-id -.. note:: - The following manual steps may also be accomplished by using ovs-ctl to - stop and start the daemons after upgrade. The ovs-ctl script will - automatically upgrade the schema. +2. external_ids:ovn-remote -1. Stop the Open vSwitch daemons, e.g.:: +3. external_ids:ovn-encap-type - $ kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid` +4. external_ids:ovn-encap-ip -2. Install the new Open vSwitch release by using the same configure options as - was used for installing the previous version. If you do not use the same - configure options, you can end up with two different versions of Open - vSwitch executables installed in different locations. +You may wish to manually start the ovn-controller service on each +chassis. -3. Upgrade the database, in one of the following two ways: +Start the ovn-controller, telling it to connect to the local ovsdb-server Unix +domain socket:: - - If there is no important data in your database, then you may delete the - database file and recreate it with ovsdb-tool, following the instructions - under "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD". + $ ovn-controller --pidfile --detach --log-file - - If you want to preserve the contents of your database, back it up first, - then use ``ovsdb-tool convert`` to upgrade it, e.g.:: +Validating +---------- - $ ovsdb-tool convert /usr/local/etc/openvswitch/conf.db \ - vswitchd/vswitch.ovsschema +At this point you can use ovn-nbctl on the central node to set up logical +switches and ports and other OVN logical entities. For example, to create a +logical switch ``sw0`` and add logical port ``sw0-p1`` :: -4. Start the Open vSwitch daemons as described under `Starting`_ above. + $ ovn-nbctl ls-add sw0 + $ ovn-nbctl lsp-add sw0 sw0-p1 + $ ovn-nbctl show -Hot Upgrading -------------- +Refer to ovn-nbctl(8) and ovn-sbctl (8) for more details. -Upgrading Open vSwitch from one version to the next version with minimum -disruption of traffic going through the system that is using that Open vSwitch -needs some considerations: - -1. If the upgrade only involves upgrading the userspace utilities and daemons - of Open vSwitch, make sure that the new userspace version is compatible with - the previously loaded kernel module. - -2. An upgrade of userspace daemons means that they have to be restarted. - Restarting the daemons means that the OpenFlow flows in the ovs-vswitchd - daemon will be lost. One way to restore the flows is to let the controller - re-populate it. Another way is to save the previous flows using a utility - like ovs-ofctl and then re-add them after the restart. Restoring the old - flows is accurate only if the new Open vSwitch interfaces retain the old - 'ofport' values. - -3. When the new userspace daemons get restarted, they automatically flush the - old flows setup in the kernel. This can be expensive if there are hundreds - of new flows that are entering the kernel but userspace daemons are busy - setting up new userspace flows from either the controller or an utility like - ovs-ofctl. Open vSwitch database provides an option to solve this problem - through the ``other_config:flow-restore-wait`` column of the - ``Open_vSwitch`` table. Refer to the ovs-vswitchd.conf.db(5) manpage for - details. - -4. If the upgrade also involves upgrading the kernel module, the old kernel - module needs to be unloaded and the new kernel module should be loaded. This - means that the kernel network devices belonging to Open vSwitch is recreated - and the kernel flows are lost. The downtime of the traffic can be reduced if - the userspace daemons are restarted immediately and the userspace flows are - restored as soon as possible. - -The ovs-ctl utility's ``restart`` function only restarts the userspace daemons, -makes sure that the 'ofport' values remain consistent across restarts, restores -userspace flows using the ovs-ofctl utility and also uses the -``other_config:flow-restore-wait`` column to keep the traffic downtime to the -minimum. The ovs-ctl utility's ``force-reload-kmod`` function does all of the -above, but also replaces the old kernel module with the new one. Open vSwitch -startup scripts for Debian, XenServer and RHEL use ovs-ctl's functions and it -is recommended that these functions be used for other software platforms too. Reporting Bugs -------------- diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst index 1f941f988..92c347235 100644 --- a/Documentation/intro/install/index.rst +++ b/Documentation/intro/install/index.rst @@ -40,10 +40,7 @@ Installation from Source :maxdepth: 2 general - netbsd windows - xenserver - userspace Installation from Packages -------------------------- @@ -74,5 +71,4 @@ Others .. toctree:: :maxdepth: 2 - bash-completion documentation diff --git a/Documentation/intro/install/netbsd.rst b/Documentation/intro/install/netbsd.rst deleted file mode 100644 index 994f6b7d9..000000000 --- a/Documentation/intro/install/netbsd.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -====================== -Open vSwitch on NetBSD -====================== - -On NetBSD, you might want to install requirements from pkgsrc. In that case, -you need at least the following packages. - -- automake -- libtool-base -- gmake -- python27 -- py27-six -- py27-xml - -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:: - - $ PKG_PATH=http://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/amd64/7.0.2/All/ - $ export PKG_PATH - $ pkg_add automake libtool-base gmake python27 py27-six py27-xml \ - pkg_alternatives - -.. note:: - You might get some warnings about minor version mismatch. These can be safely - ignored. - -NetBSD's ``/usr/bin/make`` is not GNU make. GNU make is installed as -``/usr/pkg/bin/gmake`` by the above mentioned ``gmake`` package. - -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. Or install OVS by -``gmake`` and ``gmake install``. diff --git a/Documentation/intro/install/userspace.rst b/Documentation/intro/install/userspace.rst deleted file mode 100644 index d18632d6c..000000000 --- a/Documentation/intro/install/userspace.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -=================================== -Open vSwitch without Kernel Support -=================================== - -Open vSwitch can operate, at a cost in performance, entirely in userspace, -without assistance from a kernel module. This file explains how to install -Open vSwitch in such a mode. - -This version of Open vSwitch should be built manually with ``configure`` and -``make``. Debian packaging for Open vSwitch is also included, but it has not -been recently tested, and so Debian packages are not a recommended way to use -this version of Open vSwitch. - -.. warning:: - The userspace-only mode of Open vSwitch without DPDK is considered - experimental. It has not been thoroughly tested. - -Building and Installing ------------------------ - -The requirements and procedure for building, installing, and configuring Open -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 -are not sure, check for a directory named ``/sys/class/misc/tun``. If it does -not exist, then attempt to load the module with ``modprobe tun``. - -The tun device must also exist as ``/dev/net/tun``. If it does not exist, then -create ``/dev/net`` (if necessary) with ``mkdir /dev/net``, then create -``/dev/net/tun`` with ``mknod /dev/net/tun c 10 200``. - -On FreeBSD and NetBSD, the userspace switch additionally requires the kernel -tap(4) driver to be available, either built into the kernel or loaded as a -module. - -Using the Userspace Datapath with ovs-vswitchd ----------------------------------------------- - -To use ovs-vswitchd in userspace mode, create a bridge with -``datapath_type=netdev`` in the configuration database. For example:: - - $ ovs-vsctl add-br br0 - $ ovs-vsctl set bridge br0 datapath_type=netdev - $ ovs-vsctl add-port br0 eth0 - $ ovs-vsctl add-port br0 eth1 - $ ovs-vsctl add-port br0 eth2 - -ovs-vswitchd will create a TAP device as the bridge's local interface, named -the same as the bridge, as well as for each configured internal interface. - -Currently, on FreeBSD, the functionality required for in-band control support -is not implemented. To avoid related errors, you can disable the in-band -support with the following command:: - - $ ovs-vsctl set bridge br0 other_config:disable-in-band=true - -Firewall Rules --------------- - -On Linux, when a physical interface is in use by the userspace datapath, -packets received on the interface still also pass into the kernel TCP/IP stack. -This can cause surprising and incorrect behavior. You can use "iptables" to -avoid this behavior, by using it to drop received packets. For example, to -drop packets received on eth0:: - - $ iptables -A INPUT -i eth0 -j DROP - $ iptables -A FORWARD -i eth0 -j DROP - -Other Settings --------------- - -On NetBSD, depending on your network topology and applications, the following -configuration might help. See sysctl(7).:: - - $ sysctl -w net.inet.ip.checkinterface=1 - -Reporting Bugs --------------- - -Report problems to [email protected]. diff --git a/Documentation/intro/install/windows.rst b/Documentation/intro/install/windows.rst index f696d2c9b..25b4eaa88 100644 --- a/Documentation/intro/install/windows.rst +++ b/Documentation/intro/install/windows.rst @@ -22,781 +22,9 @@ Avoid deeper levels because they do not render well. ======================= -Open vSwitch on Windows +OVN on Windows ======================= -.. _windows-build-reqs: - -Build Requirements ------------------- - -Open vSwitch on Linux uses autoconf and automake for generating Makefiles. It -will be useful to maintain the same build system while compiling on Windows -too. One approach is to compile Open vSwitch in a MinGW environment that -contains autoconf and automake utilities and then use Visual C++ as a compiler -and linker. - -The following explains the steps in some detail. - -- Mingw - - Install Mingw on a Windows machine by following the instructions on - `mingw.org <http://www.mingw.org/wiki/Getting_Started>`__. - - This should install mingw at ``C:\Mingw`` and msys at ``C:\Mingw\msys``. Add - ``C:\MinGW\bin`` and ``C:\Mingw\msys\1.0\bin`` to PATH environment variable - of Windows. - - You can either use the MinGW installer or the command line utility - ``mingw-get`` to install both the base packages and additional packages like - automake and autoconf(version 2.68). - - Also make sure that ``/mingw`` mount point exists. If its not, please - add/create the following entry in ``/etc/fstab``:: - - 'C:/MinGW /mingw'. - -- Python - - Install the latest Python 2.x from python.org and verify that its path is - part of Windows' PATH environment variable. - We require that you have Python six and pypiwin32 libraries installed. - The libraries can be installed via pip command: - - :: - - $ pip install six - $ pip install pypiwin32 - -- Visual Studio - - You will need at least Visual Studio 2013 (update 4) to compile userspace - binaries. In addition to that, if you want to compile the kernel module you - will also need to install Windows Driver Kit (WDK) 8.1 Update. - - It is important to get the Visual Studio related environment variables and to - have the $PATH inside the bash to point to the proper compiler and linker. - One easy way to achieve this for VS2013 is to get into the "VS2013 x86 Native - Tools Command Prompt" (in a default installation of Visual Studio 2013 this - can be found under the following location: ``C:\Program Files (x86)\Microsoft - Visual Studio 12.0\Common7\Tools\Shortcuts``) and through it enter into the - bash shell available from msys by typing ``bash --login``. - - There is support for generating 64 bit binaries too. To compile under x64, - open the "VS2013 x64 Native Tools Command Prompt" (if your current running OS - is 64 bit) or "VS2013 x64 Cross Tools Command Prompt" (if your current - running OS is not 64 bit) instead of opening its x86 variant. This will - point the compiler and the linker to their 64 bit equivalent. - - If after the above step, a ``which link`` inside MSYS's bash says, - ``/bin/link.exe``, rename ``/bin/link.exe`` to something else so that the - Visual studio's linker is used. You should also see a 'which sort' report - ``/bin/sort.exe``. - -- pthreads-win32 - - For pthread support, install the library, dll and includes of pthreads-win32 - project from `sourceware - <ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release>`__ to a - directory (e.g.: ``C:/pthread``). You should add the pthread-win32's dll path - (e.g.: ``C:\pthread\dll\x86``) to the Windows' PATH environment variable. - -- OpenSSL - - To get SSL support for Open vSwitch on Windows, you will need to install - `OpenSSL for Windows <https://wiki.openssl.org/index.php/Binaries>`__ - - Note down the directory where OpenSSL is installed (e.g.: - ``C:/OpenSSL-Win32``) for later use. - -.. note:: - - Commands prefixed by ``$`` must be run in the Bash shell provided by MinGW. - Open vSwitch commands, such as ``ovs-dpctl`` are shown running under the DOS - shell (``cmd.exe``), as indicated by the ``>`` prefix, but will also run - under Bash. The remainder, prefixed by ``>``, are PowerShell commands and - must be run in PowerShell. - -Install Requirements --------------------- - -* Share network adaptors - - We require that you don't disable the "Allow management operating system to - share this network adapter" under 'Virtual Switch Properties' > 'Connection - type: External network', in the Hyper-V virtual network switch configuration. - -* Checksum Offloads - - While there is some support for checksum/segmentation offloads in software, - this is still a work in progress. Till the support is complete we recommend - disabling TX/RX offloads for both the VM's as well as the Hyper-V. - -Bootstrapping -------------- - -This step is not needed if you have downloaded a released tarball. If -you pulled the sources directly from an Open vSwitch Git tree or got a -Git tree snapshot, then run boot.sh in the top source directory to build -the "configure" script: - -:: - - $ ./boot.sh - -.. _windows-configuring: - -Configuring ------------ - -Configure the package by running the configure script. You should provide some -configure options to choose the right compiler, linker, libraries, Open vSwitch -component installation directories, etc. For example: - -:: - - $ ./configure CC=./build-aux/cccl LD="$(which link)" \ - LIBS="-lws2_32 -lShlwapi -liphlpapi -lwbemuuid -lole32 -loleaut32" \ - --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" \ - --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" - -.. note:: - - By default, the above enables compiler optimization for fast code. For - default compiler optimization, pass the ``--with-debug`` configure option. - -To configure with SSL support, add the requisite additional options: - -:: - - $ ./configure CC=./build-aux/cccl LD="`which link`" \ - LIBS="-lws2_32 -lShlwapi -liphlpapi -lwbemuuid -lole32 -loleaut32" \ - --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" - --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" \ - --enable-ssl --with-openssl="C:/OpenSSL-Win32" - -Finally, to the kernel module also: - -:: - - $ ./configure CC=./build-aux/cccl LD="`which link`" \ - LIBS="-lws2_32 -lShlwapi -liphlpapi -lwbemuuid -lole32 -loleaut32" \ - --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" \ - --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" \ - --enable-ssl --with-openssl="C:/OpenSSL-Win32" \ - --with-vstudiotarget="<target type>" \ - --with-vstudiotargetver="<target versions>" - -Possible values for ``<target type>`` are: ``Debug`` and ``Release`` -Possible values for ``<target versions>`` is a comma separated list -of target versions to compile among: ``Win8,Win8.1,Win10`` - -.. note:: - - 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 :doc:`general` for information on additional configuration options. - -.. _windows-building: - -Building --------- - -Once correctly configured, building Open vSwitch on Windows is similar to -building on Linux, FreeBSD, or NetBSD. - -#. Run make for the ported executables in the top source directory, e.g.: - - :: - - $ make - - For faster compilation, you can pass the ``-j`` argument to make. For - example, to run 4 jobs simultaneously, run ``make -j4``. - - .. note:: - - MSYS 1.0.18 has a bug that causes parallel make to hang. You can overcome - this by downgrading to MSYS 1.0.17. A simple way to downgrade is to exit - all MinGW sessions and then run the below command from MSVC developers - command prompt.: - - :: - - > mingw-get upgrade msys-core-bin=1.0.17-1 - -#. To run all the unit tests in Open vSwitch, one at a time: - - :: - - $ make check - - To run all the unit tests in Open vSwitch, up to 8 in parallel: - - :: - - $ make check TESTSUITEFLAGS="-j8" - -#. To install all the compiled executables on the local machine, run: - - :: - - $ make install - - .. note:: - - This will install the Open vSwitch executables in ``C:/openvswitch``. You - can add ``C:\openvswitch\usr\bin`` and ``C:\openvswitch\usr\sbin`` to - Windows' PATH environment variable for easy access. - -The Kernel Module -~~~~~~~~~~~~~~~~~ - -If you are building the kernel module, you will need to copy the below files to -the target Hyper-V machine. - -- ``./datapath-windows/x64/Win8.1Debug/package/ovsext.inf`` -- ``./datapath-windows/x64/Win8.1Debug/package/OVSExt.sys`` -- ``./datapath-windows/x64/Win8.1Debug/package/ovsext.cat`` -- ``./datapath-windows/misc/install.cmd`` -- ``./datapath-windows/misc/uninstall.cmd`` - -.. note:: - - The above path assumes that the kernel module has been built using Windows - DDK 8.1 in Debug mode. Change the path appropriately, if a different WDK has - been used. - -Now run ``./uninstall.cmd`` to remove the old extension. Once complete, run -``./install.cmd`` to insert the new one. For this to work you will have to -turn on ``TESTSIGNING`` boot option or 'Disable Driver Signature -Enforcement' during boot. The following commands can be used: - -:: - - > bcdedit /set LOADOPTIONS DISABLE_INTEGRITY_CHECKS - > bcdedit /set TESTSIGNING ON - > bcdedit /set nointegritychecks ON - -.. note:: - - You may have to restart the machine for the settings to take effect. - -In the Virtual Switch Manager configuration you can enable the Open vSwitch -Extension on an existing switch or create a new switch. If you are using an -existing switch, make sure to enable the "Allow Management OS" option for VXLAN -to work (covered later). - -The command to create a new switch named 'OVS-Extended-Switch' using a physical -NIC named 'Ethernet 1' is: - -:: - - PS > New-VMSwitch "OVS-Extended-Switch" -NetAdapterName "Ethernet 1" - -.. note:: - - You can obtain the list of physical NICs on the host using 'Get-NetAdapter' - command. - -In the properties of any switch, you should should now see "Open vSwitch -Extension" under 'Extensions'. Click the check box to enable the extension. -An alternative way to do the same is to run the following command: - -:: - - PS > Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch - -.. note:: - - If you enabled the extension using the command line, a delay of a few - seconds has been observed for the change to be reflected in the UI. This is - not a bug in Open vSwitch. - -Starting --------- - -.. important:: - - The following steps assume that you have installed the Open vSwitch - utilities in the local machine via 'make install'. - -Before starting ovs-vswitchd itself, you need to start its configuration -database, ovsdb-server. Each machine on which Open vSwitch is installed should -run its own copy of ovsdb-server. Before ovsdb-server itself can be started, -configure a database that it can use: - -:: - - > ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \ - C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema - -Configure ovsdb-server to use database created above and to listen on a Unix -domain socket: - -:: - - > ovsdb-server -vfile:info --remote=punix:db.sock --log-file \ - --pidfile --detach - -.. note:: - - The logfile is created at ``C:/openvswitch/var/log/openvswitch/`` - -Initialize the database using ovs-vsctl. This is only necessary the first time -after you create the database with ovsdb-tool, though running it at any time is -harmless: - -:: - - > ovs-vsctl --no-wait init - -.. tip:: - - If you would later like to terminate the started ovsdb-server, run: - - :: - - > ovs-appctl -t ovsdb-server exit - -Start the main Open vSwitch daemon, telling it to connect to the same Unix -domain socket: - -:: - - > ovs-vswitchd -vfile:info --log-file --pidfile --detach - -.. tip:: - - If you would like to terminate the started ovs-vswitchd, run: - - :: - - > ovs-appctl exit - -.. note:: - - The logfile is created at ``C:/openvswitch/var/log/openvswitch/`` - -Validating ----------- - -At this point you can use ovs-vsctl to set up bridges and other Open vSwitch -features. - -Add bridges -~~~~~~~~~~~ - -Let's start by creating an integration bridge, ``br-int`` and a PIF bridge, -``br-pif``: - -:: - - > ovs-vsctl add-br br-int - > ovs-vsctl add-br br-pif - -.. note:: - - There's a known bug that running the ovs-vsctl command does not terminate. - This is generally solved by having ovs-vswitchd running. If you face the - issue despite that, hit Ctrl-C to terminate ovs-vsctl and check the output - to see if your command succeeded. - -Validate that ports are added by dumping from both ovs-dpctl and ovs-vsctl: - -:: - - > ovs-dpctl show - system@ovs-system: - lookups: hit:0 missed:0 lost:0 - flows: 0 - port 2: br-pif (internal) <<< internal port on 'br-pif' bridge - port 1: br-int (internal) <<< internal port on 'br-int' bridge - - > ovs-vsctl show - a56ec7b5-5b1f-49ec-a795-79f6eb63228b - Bridge br-pif - Port br-pif - Interface br-pif - type: internal - Bridge br-int - Port br-int - Interface br-int - type: internal - -.. note:: - - There's a known bug that the ports added to OVSDB via ovs-vsctl don't get to - the kernel datapath immediately, ie. they don't show up in the output of - ``ovs-dpctl show`` even though they show up in output of ``ovs-vsctl show``. - In order to workaround this issue, restart ovs-vswitchd. (You can terminate - ovs-vswitchd by running ``ovs-appctl exit``.) - -Add physicals NICs (PIF) -~~~~~~~~~~~~~~~~~~~~~~~~ - -Now, let's add the physical NIC and the internal port to ``br-pif``. In OVS for -Hyper-V, we use the name of the adapter on top of which the Hyper-V virtual -switch was created, as a special name to refer to the physical NICs connected -to the Hyper-V switch, e.g. if we created the Hyper-V virtual switch on top of -the adapter named ``Ethernet0``, then in OVS we use that name (``Ethernet0``) -as a special name to refer to that adapter. - -.. note:: - - We assume that the OVS extension is enabled Hyper-V switch. - -Internal ports are the virtual adapters created on the Hyper-V switch using the -``ovs-vsctl add-br <bridge>`` command. By default they are created under the -following rule "<name of bridge>" and the adapters are disabled. One needs to -enable them and set the corresponding values to it to make them IP-able. - -As a whole example, if we issue the following in a powershell console: - -:: - - PS > Get-NetAdapter | select Name,InterfaceDescription - Name InterfaceDescription - ---- -------------------- - Ethernet1 Intel(R) PRO/1000 MT Network Connection - br-pif Hyper-V Virtual Ethernet Adapter #2 - Ethernet0 Intel(R) PRO/1000 MT Network Connection #2 - br-int Hyper-V Virtual Ethernet Adapter #3 - - PS > Get-VMSwitch - Name SwitchType NetAdapterInterfaceDescription - ---- ---------- ------------------------------ - external External Intel(R) PRO/1000 MT Network Connection #2 - -We can see that we have a switch(external) created upon adapter name -'Ethernet0' with the internal ports under name 'br-pif' and 'br-int'. Thus -resulting into the following ovs-vsctl commands: - -:: - - > ovs-vsctl add-port br-pif Ethernet0 - -Dumping the ports should show the additional ports that were just added: - -:: - - > ovs-dpctl show - system@ovs-system: - lookups: hit:0 missed:0 lost:0 - flows: 0 - port 2: br-pif (internal) <<< internal port - adapter on - Hyper-V switch - port 1: br-int (internal) <<< internal port - adapter on - Hyper-V switch - port 3: Ethernet0 <<< Physical NIC - - > ovs-vsctl show - a56ec7b5-5b1f-49ec-a795-79f6eb63228b - Bridge br-pif - Port br-pif - Interface br-pif - type: internal - Port "Ethernet0" - Interface "Ethernet0" - Bridge br-int - Port br-int - Interface br-int - type: internal - -Add virtual interfaces (VIFs) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Adding VIFs to Open vSwitch is a two step procedure. The first step is to -assign a 'OVS port name' which is a unique name across all VIFs on this -Hyper-V. The next step is to add the VIF to the ovsdb using its 'OVS port -name' as key. - -First, assign a unique 'OVS port name' to the VIF. The VIF needs to have been -disconnected from the Hyper-V switch before assigning a 'OVS port name' to it. -In the example below, we assign a 'OVS port name' called ``ovs-port-a`` to a -VIF on a VM ``VM1``. By using index 0 for ``$vnic``, the first VIF of the VM -is being addressed. After assigning the name ``ovs-port-a``, the VIF is -connected back to the Hyper-V switch with name ``OVS-HV-Switch``, which is -assumed to be the Hyper-V switch with OVS extension enabled.: - -:: - - PS > import-module .\datapath-windows\misc\OVS.psm1 - PS > $vnic = Get-VMNetworkAdapter <Name of the VM> - PS > Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] - PS > $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a - PS > Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \ - -SwitchName OVS-Extended-Switch - -Next, add the VIFs to ``br-int``: - -:: - - > ovs-vsctl add-port br-int ovs-port-a - -Dumping the ports should show the additional ports that were just added: - -:: - - > ovs-dpctl show - system@ovs-system: - lookups: hit:0 missed:0 lost:0 - flows: 0 - port 4: ovs-port-a - port 2: br-pif (internal) - port 1: br-int (internal - port 3: Ethernet0 - - > ovs-vsctl show - 4cd86499-74df-48bd-a64d-8d115b12a9f2 - Bridge br-pif - Port "vEthernet (external)" - Interface "vEthernet (external)" - Port "Ethernet0" - Interface "Ethernet0" - Port br-pif - Interface br-pif - type: internal - Bridge br-int - Port br-int - Interface br-int - type: internal - Port "ovs-port-a" - Interface "ovs-port-a" - -Add multiple NICs to be managed by OVS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To leverage support of multiple NICs into OVS, we will be using the MSFT -cmdlets for forwarding team extension. More documentation about them can be -found at technet_. - -.. _technet: https://technet.microsoft.com/en-us/library/jj553812%28v=wps.630%29.aspx - -For example, to set up a switch team combined from ``Ethernet0 2`` and -``Ethernet1 2`` named ``external``: - -:: - - PS > Get-NetAdapter - Name InterfaceDescription - ---- -------------------- - br-int Hyper-V Virtual Ethernet Adapter #3 - br-pif Hyper-V Virtual Ethernet Adapter #2 - Ethernet3 2 Intel(R) 82574L Gigabit Network Co...#3 - Ethernet2 2 Intel(R) 82574L Gigabit Network Co...#4 - Ethernet1 2 Intel(R) 82574L Gigabit Network Co...#2 - Ethernet0 2 Intel(R) 82574L Gigabit Network Conn... - - PS > New-NetSwitchTeam -Name external -TeamMembers "Ethernet0 2","Ethernet1 2" - - PS > Get-NetSwitchTeam - Name : external - Members : {Ethernet1 2, Ethernet0 2} - -This will result in a new adapter bound to the host called ``external``: - -:: - - PS > Get-NetAdapter - Name InterfaceDescription - ---- -------------------- - br-test Hyper-V Virtual Ethernet Adapter #4 - br-pif Hyper-V Virtual Ethernet Adapter #2 - external Microsoft Network Adapter Multiplexo... - Ethernet3 2 Intel(R) 82574L Gigabit Network Co...#3 - Ethernet2 2 Intel(R) 82574L Gigabit Network Co...#4 - Ethernet1 2 Intel(R) 82574L Gigabit Network Co...#2 - Ethernet0 2 Intel(R) 82574L Gigabit Network Conn... - -Next we will set up the Hyper-V VMSwitch on the new adapter ``external``: - -:: - - PS > New-VMSwitch -Name external -NetAdapterName external \ - -AllowManagementOS $false - -Under OVS the adapters under the team ``external``, ``Ethernet0 2`` and -``Ethernet1 2``, can be added either under a bond device or separately. - -The following example shows how the bridges look with the NICs being -separated: - -:: - - > ovs-vsctl show - 6cd9481b-c249-4ee3-8692-97b399dd29d8 - Bridge br-test - Port br-test - Interface br-test - type: internal - Port "Ethernet1 2" - Interface "Ethernet1 2" - Bridge br-pif - Port "Ethernet0 2" - Interface "Ethernet0 2" - Port br-pif - Interface br-pif - type: internal - -Add patch ports and configure VLAN tagging -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Windows Open vSwitch implementation support VLAN tagging in the switch. -Switch VLAN tagging along with patch ports between ``br-int`` and ``br-pif`` is -used to configure VLAN tagging functionality between two VMs on different -Hyper-Vs. To start, add a patch port from ``br-int`` to ``br-pif``: - -:: - - > ovs-vsctl add-port br-int patch-to-pif - > ovs-vsctl set interface patch-to-pif type=patch \ - options:peer=patch-to-int - -Add a patch port from ``br-pif`` to ``br-int``: - -:: - - > ovs-vsctl add-port br-pif patch-to-int - > ovs-vsctl set interface patch-to-int type=patch \ - options:peer=patch-to-pif - -Re-Add the VIF ports with the VLAN tag: - -:: - - > ovs-vsctl add-port br-int ovs-port-a tag=900 - > ovs-vsctl add-port br-int ovs-port-b tag=900 - -Add tunnels -~~~~~~~~~~~ - -The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add -tunnels. For example, first add the tunnel port between 172.168.201.101 <-> -172.168.201.102: - -:: - - > ovs-vsctl add-port br-int tun-1 - > ovs-vsctl set Interface tun-1 type=<port-type> - > ovs-vsctl set Interface tun-1 options:local_ip=172.168.201.101 - > ovs-vsctl set Interface tun-1 options:remote_ip=172.168.201.102 - > ovs-vsctl set Interface tun-1 options:in_key=flow - > ovs-vsctl set Interface tun-1 options:out_key=flow - -...and the tunnel port between 172.168.201.101 <-> 172.168.201.105: - -:: - - > ovs-vsctl add-port br-int tun-2 - > ovs-vsctl set Interface tun-2 type=<port-type> - > ovs-vsctl set Interface tun-2 options:local_ip=172.168.201.102 - > ovs-vsctl set Interface tun-2 options:remote_ip=172.168.201.105 - > ovs-vsctl set Interface tun-2 options:in_key=flow - > ovs-vsctl set Interface tun-2 options:out_key=flow - -Where ``<port-type>`` is one of: ``stt`` or ``vxlan`` - -.. note:: - - Any patch ports created between br-int and br-pif MUST be be deleted prior - to adding tunnels. - -Windows Services ----------------- - -Open vSwitch daemons come with support to run as a Windows service. The -instructions here assume that you have installed the Open vSwitch utilities and -daemons via ``make install``. - -To start, create the database: - -:: - - > ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \ - "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema" - -Create the ovsdb-server service and start it: - -:: - - > sc create ovsdb-server \ - binpath="C:/openvswitch/usr/sbin/ovsdb-server.exe \ - C:/openvswitch/etc/openvswitch/conf.db \ - -vfile:info --log-file --pidfile \ - --remote=punix:db.sock --service --service-monitor" - > sc start ovsdb-server - -.. tip:: - - One of the common issues with creating a Windows service is with mungled - paths. You can make sure that the correct path has been registered with the - Windows services manager by running: - - :: - - > sc qc ovsdb-server - -Check that the service is healthy by running: - -:: - - > sc query ovsdb-server - -Initialize the database: - -:: - - > ovs-vsctl --no-wait init - -Create the ovs-vswitchd service and start it: - -:: - - > sc create ovs-vswitchd \ - binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe \ - --pidfile -vfile:info --log-file --service --service-monitor" - > sc start ovs-vswitchd - -Check that the service is healthy by running: - -:: - - > sc query ovs-vswitchd - -To stop and delete the services, run: - -:: - - > sc stop ovs-vswitchd - > sc stop ovsdb-server - > sc delete ovs-vswitchd - > sc delete ovsdb-server - -Windows CI Service ------------------- - -`AppVeyor <www.appveyor.com>`__ provides a free Windows autobuild service for -open source projects. Open vSwitch has integration with AppVeyor for continuous -build. A developer can build test his changes for Windows by logging into -appveyor.com using a github account, creating a new project by linking it to -his development repository in github and triggering a new build. - TODO ---- - -* Investigate the working of sFlow on Windows and re-enable the unit tests. - -* Investigate and add the feature to provide QoS. - -* Sign the driver & create an MSI for installing the different Open vSwitch - components on Windows. +* This document needs to be updated. diff --git a/Documentation/intro/install/xenserver.rst b/Documentation/intro/install/xenserver.rst deleted file mode 100644 index c0f5e3156..000000000 --- a/Documentation/intro/install/xenserver.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -================================ -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, 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 -or earlier requires installing Python 2.7. - -Building --------- - -You may build from an Open vSwitch distribution tarball or from an Open vSwitch -Git tree. The recommended build environment to build RPMs for Citrix XenServer -is the DDK VM available from Citrix. - -1. If you are building from an Open vSwitch Git tree, then you will need to - first create a distribution tarball by running:: - - $ ./boot.sh - $ ./configure - $ make dist - - 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 :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. - -3. In the DDK VM, unpack the distribution tarball into a temporary directory - and "cd" into the root of the distribution tarball. - -4. To build Open vSwitch userspace, run:: - - $ rpmbuild -bb xenserver/openvswitch-xen.spec - - This produces three RPMs in ``/usr/src/redhat/RPMS/i386``: - - - ``openvswitch`` - - ``openvswitch-modules-xen`` - - ``openvswitch-debuginfo`` - - The above command automatically runs the Open vSwitch unit tests. To - disable the unit tests, run:: - - $ rpmbuild -bb --without check xenserver/openvswitch-xen.spec - -Build Parameters ----------------- - -``openvswitch-xen.spec`` needs to know a number of pieces of information about -the XenServer kernel. Usually, it can figure these out for itself, but if it -does not do it correctly then you can specify them yourself as parameters to -the build. Thus, the final ``rpmbuild`` step above can be elaborated as:: - - $ VERSION=<Open vSwitch version> - $ KERNEL_NAME=<Xen Kernel name> - $ KERNEL_VERSION=<Xen Kernel version> - $ KERNEL_FLAVOR=<Xen Kernel flavor(suffix)> - $ rpmbuild \ - -D "openvswitch_version $VERSION" \ - -D "kernel_name $KERNEL_NAME" \ - -D "kernel_version $KERNEL_VERSION" \ - -D "kernel_flavor $KERNEL_FLAVOR" \ - -bb xenserver/openvswitch-xen.spec - -where: - -``<openvswitch version>`` - is the version number that appears in the name of the Open vSwitch tarball, - e.g. 0.90.0. - -``<Xen Kernel name>`` - is the name of the XenServer kernel package, e.g. ``kernel-xen`` or - ``kernel-NAME-xen``, without the ``kernel-`` prefix. - -``<Xen Kernel version>`` - is the output of:: - - $ rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>, - - e.g. ``2.6.32.12-0.7.1.xs5.6.100.323.170596``, where - ``<kernel-devel-package>`` is the name of the ``-devel`` package - corresponding to ``<Xen Kernel name>``. - -``<Xen Kernel flavor (suffix)>`` - is either ``xen`` or ``kdump``, where ``xen`` flavor is the main running - kernel flavor and the ``kdump`` flavor is the crashdump kernel flavor. - Commonly, one would specify ``xen`` here. - -For XenServer 6.5 or above, the kernel version naming no longer contains -KERNEL_FLAVOR. In fact, only providing the ``uname -r`` output is enough. So, -the final ``rpmbuild`` step changes to:: - - $ KERNEL_UNAME=<`uname -r` output> - $ rpmbuild \ - -D "kenel_uname $KERNEL_UNAME" \ - -bb xenserver/openvswitch-xen.spec - -Installing Open vSwitch for XenServer -------------------------------------- - -To install Open vSwitch on a XenServer host, or to upgrade to a newer version, -copy the ``openvswitch`` and ``openvswitch-modules-xen`` RPMs to that host with -``scp``, then install them with ``rpm -U``, e.g.:: - - $ scp openvswitch-$VERSION-1.i386.rpm \ - openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \ - root@<host>: - # Enter <host>'s root password. - $ ssh root@<host> - # Enter <host>'s root password again. - $ rpm -U openvswitch-$VERSION-1.i386.rpm \ - openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm - -To uninstall Open vSwitch from a XenServer host, remove the packages:: - - $ ssh root@<host> - # Enter <host>'s root password again. - $ rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION - -After installing or uninstalling Open vSwitch, the XenServer should be rebooted -as soon as possible. - -Open vSwitch Boot Sequence on XenServer ---------------------------------------- - -When Open vSwitch is installed on XenServer, its startup script -``/etc/init.d/openvswitch`` runs early in boot. It does roughly the following: - -* Loads the OVS kernel module, openvswitch. - -* Starts ovsdb-server, the OVS configuration database. - -* XenServer expects there to be no bridges configured at startup, but the OVS - configuration database likely still has bridges configured from before - reboot. To match XenServer expectations, the startup script deletes all - configured bridges from the database. - -* Starts ovs-vswitchd, the OVS switching daemon. - -At this point in the boot process, then, there are no Open vSwitch bridges, -even though all of the Open vSwitch daemons are running. Later on in boot, -``/etc/init.d/management-interface`` (part of XenServer, not Open vSwitch) -creates the bridge for the XAPI management interface by invoking -``/opt/xensource/libexec/interface-reconfigure``. Normally this program -consults XAPI's database to obtain information about how to configure the -bridge, but XAPI is not running yet(\*) so it instead consults -``/var/xapi/network.dbcache``, which is a cached copy of the most recent -network configuration. - -(\*) Even if XAPI were running, if this XenServer node is a pool slave then the - query would have to consult the master, which requires network access, - which begs the question of how to configure the management interface. - -XAPI starts later on in the boot process. XAPI can then create other bridges -on demand using ``/opt/xensource/libexec/interface-reconfigure``. Now that -XAPI is running, that program consults XAPI directly instead of reading the -cache. - -As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin script -``/etc/xapi.d/openvswitch-cfg-update`` passing the ``update`` command. The -plugin script does roughly the following: - -* Calls ``/opt/xensource/libexec/interface-reconfigure`` with the ``rewrite`` - command, to ensure that the network cache is up-to-date. - -* Queries the Open vSwitch manager setting (named ``vswitch_controller``) from - the XAPI database for the XenServer pool. - -* If XAPI and OVS are configured for different managers, or if OVS is - configured for a manager but XAPI is not, runs ``ovs-vsctl emer-reset`` to - bring the Open vSwitch configuration to a known state. One effect of - emer-reset is to deconfigure any manager from the OVS database. - -* If XAPI is configured for a manager, configures the OVS manager to match with - ``ovs-vsctl set-manager``. - -Notes ------ - -* The Open vSwitch boot sequence only configures an OVS configuration database - manager. There is no way to directly configure an OpenFlow controller on - XenServer and, as a consequence of the step above that deletes all of the - bridges at boot time, controller configuration only persists until XenServer - reboot. The configuration database manager can, however, configure - controllers for bridges. See the BUGS section of ovs-testcontroller(8) for - more information on this topic. - -* The Open vSwitch startup script automatically adds a firewall rule to allow - GRE traffic. This rule is needed for the XenServer feature called "Cross-Host - Internal Networks" (CHIN) that uses GRE. If a user configures tunnels other - than GRE (ex: Geneve, VXLAN, LISP), they will have to either manually add a - iptables firewall rule to allow the tunnel traffic or add it through a - startup script (Please refer to the "enable-protocol" command in the - ovs-ctl(8) manpage). - -Reporting Bugs --------------- - -Please report problems to [email protected]. diff --git a/Documentation/intro/what-is-ovs.rst b/Documentation/intro/what-is-ovs.rst deleted file mode 100644 index bf7071f7a..000000000 --- a/Documentation/intro/what-is-ovs.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. - Copyright (c) 2016, Stephen Finucane <[email protected]> - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -===================== -What Is Open vSwitch? -===================== - -.. image:: ../_static/overview.png - :align: center - -Overview --------- - -.. NOTE(stephenfin): The below line numbers may need to be updated if the - README is modified - -.. include:: ../../README.rst - :start-line: 13 - :end-line: 71 diff --git a/Documentation/intro/why-ovs.rst b/Documentation/intro/why-ovs.rst deleted file mode 100644 index e73066a76..000000000 --- a/Documentation/intro/why-ovs.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels in Open vSwitch documentation: - - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - - Avoid deeper levels because they do not render well. - -================= -Why Open vSwitch? -================= - -Hypervisors need the ability to bridge traffic between VMs and with the outside -world. On Linux-based hypervisors, this used to mean using the built-in L2 -switch (the Linux bridge), which is fast and reliable. So, it is reasonable to -ask why Open vSwitch is used. - -The answer is that Open vSwitch is targeted at multi-server virtualization -deployments, a landscape for which the previous stack is not well suited. These -environments are often characterized by highly dynamic end-points, the -maintenance of logical abstractions, and (sometimes) integration with or -offloading to special purpose switching hardware. - -The following characteristics and design considerations help Open vSwitch cope -with the above requirements. - -The mobility of state ---------------------- - -All network state associated with a network entity (say a virtual machine) -should be easily identifiable and migratable between different hosts. This may -include traditional "soft state" (such as an entry in an L2 learning table), L3 -forwarding state, policy routing state, ACLs, QoS policy, monitoring -configuration (e.g. NetFlow, IPFIX, sFlow), etc. - -Open vSwitch has support for both configuring and migrating both slow -(configuration) and fast network state between instances. For example, if a VM -migrates between end-hosts, it is possible to not only migrate associated -configuration (SPAN rules, ACLs, QoS) but any live network state (including, -for example, existing state which may be difficult to reconstruct). Further, -Open vSwitch state is typed and backed by a real data-model allowing for the -development of structured automation systems. - -Responding to network dynamics ------------------------------- - -Virtual environments are often characterized by high-rates of change. VMs -coming and going, VMs moving backwards and forwards in time, changes to the -logical network environments, and so forth. - -Open vSwitch supports a number of features that allow a network control system -to respond and adapt as the environment changes. This includes simple -accounting and visibility support such as NetFlow, IPFIX, and sFlow. But -perhaps more useful, Open vSwitch supports a network state database (OVSDB) -that supports remote triggers. Therefore, a piece of orchestration software can -"watch" various aspects of the network and respond if/when they change. This is -used heavily today, for example, to respond to and track VM migrations. - -Open vSwitch also supports OpenFlow as a method of exporting remote access to -control traffic. There are a number of uses for this including global network -discovery through inspection of discovery or link-state traffic (e.g. LLDP, -CDP, OSPF, etc.). - -Maintenance of logical tags ----------------------------- - -Distributed virtual switches (such as VMware vDS and Cisco's Nexus 1000V) often -maintain logical context within the network through appending or manipulating -tags in network packets. This can be used to uniquely identify a VM (in a -manner resistant to hardware spoofing), or to hold some other context that is -only relevant in the logical domain. Much of the problem of building a -distributed virtual switch is to efficiently and correctly manage these tags. - -Open vSwitch includes multiple methods for specifying and maintaining tagging -rules, all of which are accessible to a remote process for orchestration. -Further, in many cases these tagging rules are stored in an optimized form so -they don't have to be coupled with a heavyweight network device. This allows, -for example, thousands of tagging or address remapping rules to be configured, -changed, and migrated. - -In a similar vein, Open vSwitch supports a GRE implementation that can handle -thousands of simultaneous GRE tunnels and supports remote configuration for -tunnel creation, configuration, and tear-down. This, for example, can be used -to connect private VM networks in different data centers. - -Hardware integration --------------------- - -Open vSwitch's forwarding path (the in-kernel datapath) is designed to be -amenable to "offloading" packet processing to hardware chipsets, whether housed -in a classic hardware switch chassis or in an end-host NIC. This allows for the -Open vSwitch control path to be able to both control a pure software -implementation or a hardware switch. - -There are many ongoing efforts to port Open vSwitch to hardware chipsets. These -include multiple merchant silicon chipsets (Broadcom and Marvell), as well as a -number of vendor-specific platforms. The "Porting" section in the documentation -discusses how one would go about making such a port. - -The advantage of hardware integration is not only performance within -virtualized environments. If physical switches also expose the Open vSwitch -control abstractions, both bare-metal and virtualized hosting environments can -be managed using the same mechanism for automated network control. - -Summary -------- - -In many ways, Open vSwitch targets a different point in the design space than -previous hypervisor networking stacks, focusing on the need for automated and -dynamic network control in large-scale Linux-based virtualization environments. - -The goal with Open vSwitch is to keep the in-kernel code as small as possible -(as is necessary for performance) and to re-use existing subsystems when -applicable (for example Open vSwitch uses the existing QoS stack). As of Linux -3.3, Open vSwitch is included as a part of the kernel and packaging for the -userspace utilities are available on most popular distributions. -- 2.21.0 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
