Windows support was deprecated in 3.7, it's time to remove it. Documentation is the next self-contained part.
The next part is the windows-datapath and it's hard to carve out only the datapath-related bits from the docs, so it's easier to remove them all together now. Signed-off-by: Ilya Maximets <[email protected]> --- Documentation/automake.mk | 3 - Documentation/index.rst | 1 - .../contributing/coding-style-windows.rst | 183 --- .../internals/contributing/coding-style.rst | 3 +- .../internals/contributing/index.rst | 1 - Documentation/intro/install/general.rst | 3 - Documentation/intro/install/index.rst | 1 - Documentation/intro/install/windows.rst | 1080 ----------------- Documentation/topics/index.rst | 1 - Documentation/topics/windows.rst | 509 -------- 10 files changed, 1 insertion(+), 1784 deletions(-) delete mode 100644 Documentation/internals/contributing/coding-style-windows.rst delete mode 100644 Documentation/intro/install/windows.rst delete mode 100644 Documentation/topics/windows.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index ea9459b55..23b66a5ee 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -20,7 +20,6 @@ DOC_SOURCE = \ Documentation/intro/install/netbsd.rst \ Documentation/intro/install/rhel.rst \ Documentation/intro/install/userspace.rst \ - Documentation/intro/install/windows.rst \ Documentation/tutorials/index.rst \ Documentation/tutorials/faucet.rst \ Documentation/tutorials/ovs-advanced.rst \ @@ -61,7 +60,6 @@ DOC_SOURCE = \ Documentation/topics/userspace-checksum-offloading.rst \ Documentation/topics/userspace-tso.rst \ Documentation/topics/userspace-tx-steering.rst \ - Documentation/topics/windows.rst \ Documentation/howto/index.rst \ Documentation/howto/dpdk.rst \ Documentation/howto/ipsec.rst \ @@ -111,7 +109,6 @@ DOC_SOURCE = \ Documentation/internals/contributing/backporting-patches.rst \ Documentation/internals/contributing/inclusive-language.rst \ Documentation/internals/contributing/coding-style.rst \ - Documentation/internals/contributing/coding-style-windows.rst \ Documentation/internals/contributing/documentation-style.rst \ Documentation/internals/contributing/libopenvswitch-abi.rst \ Documentation/internals/contributing/submitting-patches.rst \ diff --git a/Documentation/index.rst b/Documentation/index.rst index 704138473..9f1f9c7f3 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -45,7 +45,6 @@ Contributing - :doc:`internals/contributing/backporting-patches` - :doc:`internals/contributing/inclusive-language` - :doc:`internals/contributing/coding-style` - - :doc:`internals/contributing/coding-style-windows` Maintaining ----------- diff --git a/Documentation/internals/contributing/coding-style-windows.rst b/Documentation/internals/contributing/coding-style-windows.rst deleted file mode 100644 index d0868f7b3..000000000 --- a/Documentation/internals/contributing/coding-style-windows.rst +++ /dev/null @@ -1,183 +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. - -============================= -Windows Datapath Coding Style -============================= - -The :doc:`coding style <coding-style>` guide gives the flexibility for each -platform to use its own coding style for the kernel datapath. This file -describes the specific coding style used in most of the C files in the Windows -kernel datapath of the Open vSwitch distribution. - -Most of the coding conventions applicable for the Open vSwitch distribution are -applicable to the Windows kernel datapath as well. There are some exceptions -and new guidelines owing to the commonly followed practices in Windows -kernel/driver code. They are noted as follows: - -Basics ------- - -- Limit lines to 79 characters. - - Many times, this is not possible due to long names of functions and it is - fine to go beyond the characters limit. One common example is when calling - into NDIS functions. - -Types ------ - -Use data types defined by Windows for most of the code. This is a common -practice in Windows driver code, and it makes integrating with the data -structures and functions defined by Windows easier. Example: ``DWORD`` and -``BOOLEAN``. - -Use caution in portions of the code that interface with the OVS userspace. OVS -userspace does not use Windows specific data types, and when copying data back -and forth between kernel and userspace, care should be exercised. - -Naming ------- - -It is common practice to use camel casing for naming variables, functions and -files in Windows. For types, especially structures, unions and enums, using -all upper case letters with words separated by '_' is common. These practices -can be used for OVS Windows datapath. However, use the following guidelines: - -- Use lower case to begin the name of a variable. - -- Do not use '_' to begin the name of the variable. '_' is to be used to begin - the parameters of a pre-processor macro. - -- Use upper case to begin the name of a function, enum, file name etc. - -- Static functions whose scope is limited to the file they are defined in can - be prefixed with '_'. This is not mandatory though. - -- For types, use all upper case for all letters with words separated by '_'. If - camel casing is preferred, use upper case for the first letter. - -- It is a common practice to define a pointer type by prefixing the letter 'P' - to a data type. The same practice can be followed here as well. - -For example:: - - static __inline BOOLEAN - OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx, - POVS_FLOW_KEY flowKey) - { - POVS_VPORT_ENTRY tunnelVport = NULL; - - if (!flowKey->ipKey.nwFrag && - flowKey->ipKey.nwProto == IPPROTO_UDP && - flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) { - tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN); - ovsActionStats.rxVxlan++; - } else { - return FALSE; - } - - if (tunnelVport) { - ASSERT(ovsFwdCtx->tunnelRxNic == NULL); - ovsFwdCtx->tunnelRxNic = tunnelVport; - return TRUE; - } - - return FALSE; - } - -For declaring variables of pointer type, use of the pointer data type prefixed -with 'P' is preferred over using '*'. This is not mandatory though, and is only -prescribed since it is a common practice in Windows. - -Example, #1 is preferred over #2 though #2 is also equally correct: - -1. ``PNET_BUFFER_LIST curNbl;`` -2. ``NET_BUFFER_LIST *curNbl;`` - -Comments --------- - -Comments should be written as full sentences that start with a capital letter -and end with a period. Putting two spaces between sentences is not necessary. - -``//`` can be used for comments as long as the comment is a single line -comment. For block comments, use ``/* */`` comments - -Functions ---------- - -Put the return type, function name, and the braces that surround the function's -code on separate lines, all starting in column 0. - -Before each function definition, write a comment that describes the function's -purpose, including each parameter, the return value, and side effects. -References to argument names should be given in single-quotes, e.g. 'arg'. The -comment should not include the function name, nor need it follow any formal -structure. The comment does not need to describe how a function does its work, -unless this information is needed to use the function correctly (this is often -better done with comments *inside* the function). - -Mention any side effects that the function has that are not obvious based on -the name of the function or based on the workflow it is called from. - -In the interest of keeping comments describing functions similar in structure, -use the following template. - -:: - - /* - *---------------------------------------------------------------------------- - * Any description of the function, arguments, return types, assumptions and - * side effects. - *---------------------------------------------------------------------------- - */ - -Source Files ------------- - -Each source file should state its license in a comment at the very top, -followed by a comment explaining the purpose of the code that is in that file. -The comment should explain how the code in the file relates to code in other -files. The goal is to allow a programmer to quickly figure out where a given -module fits into the larger system. - -The first non-comment line in a .c source file should be:: - - #include <precomp.h> - -``#include`` directives should appear in the following order: - -1. ``#include <precomp.h>`` - -2. The module's own headers, if any. Including this before any other header - (besides ``<precomp.h>``) ensures that the module's header file is - self-contained (see *Header Files*) below. - -3. Standard C library headers and other system headers, preferably in - alphabetical order. (Occasionally one encounters a set of system headers - that must be included in a particular order, in which case that order must - take precedence.) - -4. Open vSwitch headers, in alphabetical order. Use ``""``, not ``<>``, to - specify Open vSwitch header names. diff --git a/Documentation/internals/contributing/coding-style.rst b/Documentation/internals/contributing/coding-style.rst index eef984e87..034fd4cef 100644 --- a/Documentation/internals/contributing/coding-style.rst +++ b/Documentation/internals/contributing/coding-style.rst @@ -27,8 +27,7 @@ Coding Style This file describes the coding style used in most C files in the Open vSwitch distribution. However, Linux kernel code datapath directory follows the Linux -kernel's established coding conventions. For the Windows kernel datapath code, -use the coding style described in :doc:`coding-style-windows`. +kernel's established coding conventions. The following GNU indent options approximate this style. diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst index 91304e60b..f60609650 100644 --- a/Documentation/internals/contributing/index.rst +++ b/Documentation/internals/contributing/index.rst @@ -33,7 +33,6 @@ The below guides provide information on contributing to Open vSwitch itself. submitting-patches backporting-patches coding-style - coding-style-windows documentation-style inclusive-language libopenvswitch-abi diff --git a/Documentation/intro/install/general.rst b/Documentation/intro/install/general.rst index 8d46c2a75..b41a25225 100644 --- a/Documentation/intro/install/general.rst +++ b/Documentation/intro/install/general.rst @@ -73,9 +73,6 @@ need the following software: - Clang 3.4 or later. - - 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``). diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst index 885a65d6e..d5af6b470 100644 --- a/Documentation/intro/install/index.rst +++ b/Documentation/intro/install/index.rst @@ -41,7 +41,6 @@ Installation from Source general netbsd - windows userspace dpdk afxdp diff --git a/Documentation/intro/install/windows.rst b/Documentation/intro/install/windows.rst deleted file mode 100644 index 165d807bf..000000000 --- a/Documentation/intro/install/windows.rst +++ /dev/null @@ -1,1080 +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 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 3.7 or later. - - Install the latest Python 3.x from python.org and verify that its path is - part of Windows' PATH environment variable. - We require that you have pypiwin32 library installed. - The library can be installed via pip command: - - :: - - $ 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 or later. - To be able to build the kernel module you need - `WiX Toolset <https://wixtoolset.org/>`__ . - - We recommend using the latest Visual Studio version together with the latest - WDK installed. - - 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``. - -- PThreads4W - - For pthread support, install the library, dll and includes of PThreads4W - project from `sourceware - <https://sourceforge.net/projects/pthreads4w/>`__ to a directory - (e.g.: ``C:/pthread``). You should add the PThreads4W's dll path - (e.g.: ``C:\pthread\bin``) 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-Win64``) 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-Win64" - -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-Win64" \ - --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 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 -~~~~~~~~~~~ - -#. IPv4 tunnel, e.g.: - - The Windows Open vSwitch implementation supports VXLAN and Geneve 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: ``geneve`` or ``vxlan`` - - .. note:: - - Any patch ports created between br-int and br-pif MUST be deleted prior - to adding tunnels. - -#. IPv6 tunnel, e.g.: - - To add IPV6 Geneve tunnels. For example, add the tunnel port between - 5000::2 <-> 5000::9. - - :: - - > ovs-vsctl add-port br-int tun-3 -- set interface tun-3 type=Geneve \ - options:csum=true options:key=flow options:local_ip="5000::2"\ - options:remote_ip=flow - - add the tunnel port between 5000::2 <-> 5000::9 - - > ovs-ofctl add-flow br-int "table=0,priority=100,ipv6,ipv6_src=6000::2 \ - actions=load:0x9->NXM_NX_TUN_IPV6_DST[0..63], \ - load:0x5000000000000000->NXM_NX_TUN_IPV6_DST[64..127], output:tun-3" - - add the specified flow from 6000::2 go via IPV6 Geneve tunnel - - .. note:: - - Till the checksum offload support is complete we recommend - disabling TX/RX offloads for IPV6 on Windows VM. - -Add conntrack for ipv6 -~~~~~~~~~~~~~~~~~~~~~~ - -The Windows Open vSwitch implementation support conntrack ipv6. To use the -conntrack ipv6. Using the following commands. Take tcp6(replace Protocol to -icmp6, udp6 to other protocol) for example. - -:: - - normal scenario - Vif38(20::1, ofport:2)->Vif40(20:2, ofport:3) - Vif38Name="podvif38" - Vif40Name="podvif40" - Vif38Port=2 - Vif38Address="20::1" - Vif40Port=3 - Vif40Address="20::2" - Vif40MacAddressCli="00-15-5D-F0-01-0C" - Vif38MacAddressCli="00-15-5D-F0-01-0b" - Protocol="tcp6" - > netsh int ipv6 set neighbors $Vif38Name $Vif40Address \ - Vif40MacAddressCli - > netsh int ipv6 set neighbors $Vif40Name $Vif38Address \ - $Vif38MacAddressCli - > ovs-ofctl del-flows --strict br-int "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0,priority=1,ip6, \ - ipv6_dst=$Vif40Address,$Protocol,actions=ct(table=1)" - > ovs-ofctl add-flow br-int "table=0,priority=1,ip6, \ - ipv6_dst=$Vif38Address,$Protocol,actions=ct(table=1)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ip6,ct_state=+new+trk, \ - $Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=2,ip6, \ - ct_state=-new+rpl+trk,$Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ip6, \ - ct_state=+trk+est-new,$Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6, \ - ipv6_dst=$Vif38Address,$Protocol,actions=output:$Vif38Port" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6, \ - ipv6_dst=$Vif40Address,$Protocol,actions=output:$Vif40Port" - - -:: - - nat scenario - Vif38(20::1, ofport:2) -> nat address(20::9) -> Vif42(21::3, ofport:4) - Due to not construct flow to return neighbor mac address, - we set the neighbor mac address manually. - Vif38Name="podvif38" - Vif42Name="podvif42" - Vif38Ip="20::1" - Vif38Port=2 - Vif42Port=4 - NatAddress="20::9" - NatMacAddress="aa:bb:cc:dd:ee:ff" - NatMacAddressForCli="aa-bb-cc-dd-ee-ff" - Vif42Ip="21::3" - Vif38MacAddress="00:15:5D:F0:01:0B" - Vif38MacAddressCli="00-15-5D-F0-01-0B" - Vif42MacAddress="00:15:5D:F0:01:0D" - Protocol="tcp6" - > netsh int ipv6 set neighbors $Vif38Name $NatAddress \ - $NatMacAddressForCli - > netsh int ipv6 set neighbors $Vif42Name $Vif38Ip \ - $Vif38MacAddressCli - > ovs-ofctl del-flows --strict br-int "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0, priority=2,ipv6, \ - dl_dst=$NatMacAddress,ct_state=-trk,$Protocol \ - actions=ct(table=1,zone=456,nat)" - > ovs-ofctl add-flow br-int "table=0, priority=1,ipv6,ct_state=-trk, \ - ip6,$Protocol actions=ct(nat, zone=456,table=1)" - > ovs-ofctl add-flow br-int "table=1, ipv6,in_port=$Vif38Port, \ - ipv6_dst=$NatAddress,$Protocol,ct_state=+trk+new, \ - actions=ct(commit,nat(dst=$Vif42Ip),zone=456, \ - exec(set_field:1->ct_mark)),mod_dl_src=$NatMacAddress, \ - mod_dl_dst=$Vif42MacAddress,output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=1, ipv6,ct_state=+dnat,$Protocol, \ - action=resubmit(,2)" - > ovs-ofctl add-flow br-int "table=1, ipv6,ct_state=+trk+snat, \ - $Protocol, action=resubmit(,2)" - > ovs-ofctl add-flow br-int "table=2, ipv6,in_port=$Vif38Port, \ - ipv6_dst=$Vif42Ip,$Protocol, actions=mod_dl_src=$NatMacAddress, \ - mod_dl_dst=$Vif42MacAddress,output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=2, ipv6,in_port=$Vif42Port, \ - ct_state=-new+est,ct_mark=1,ct_zone=456,$Protocol, \ - actions=mod_dl_src=$NatMacAddress,mod_dl_dst=$Vif38MacAddress, \ - output:$Vif38Port" - -Ftp is a specific protocol, it contains an related flow, we need to match is -related state. - -:: - - normal scenario - Vif38(20::1, ofport:2)->Vif40(20:2, ofport:3) - Vif38Name="podvif70" - Vif40Name="Ethernet1" - Vif38Port=2 - Vif38Address="20::88" - Vif40Port=3 - Vif40Address="20::45" - Vif40MacAddressCli="00-50-56-98-9d-97" - Vif38MacAddressCli="00-15-5D-F0-01-0B" - Protocol="tcp6" - > netsh int ipv6 set neighbors $Vif38Name $Vif40Address $Vif40MacAddressCli - > netsh int ipv6 set neighbors $Vif42Name $Vif38Ip $Vif38MacAddressCli - > ovs-ofctl del-flows br-int --strict "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0,priority=1,$Protocol - actions=ct(table=1)" - > ovs-ofctl add-flow br-int "table=1,priority=1,tp_dst=21, $Protocol,\ - actions=ct(commit,table=2,alg=ftp)" - > ovs-ofctl add-flow br-int "table=1,priority=1,tp_src=21, $Protocol,\ - actions=ct(commit,table=2,alg=ftp)" - > ovs-ofctl add-flow br-int "table=1,priority=1, ct_state=+new+trk+rel,\ - $Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=1, \ - ct_state=-new+trk+est+rel,$Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6,\ - ipv6_dst=$Vif38Address,$Protocol,actions=output:$Vif38Port" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6,\ - ipv6_dst=$Vif40Address,$Protocol,actions=output:$Vif40Port" - - -:: - - nat scenario - Vif38(20::1, ofport:2) -> nat address(20::9) -> Vif42(21::3, ofport:4) - Due to not construct flow to return neighbor mac address, we set the - neighbor mac address manually - Vif38Name="podvif70" - Vif42Name="Ethernet1" - Vif38Ip="20::88" - Vif38Port=2 - Vif42Port=3 - NatAddress="20::9" - NatMacAddress="aa:bb:cc:dd:ee:ff" - NatMacAddressForCli="aa-bb-cc-dd-ee-ff" - Vif42Ip="21::3" - Vif38MacAddress="00:15:5D:F0:01:14" - Vif38MacAddressCli="00-15-5D-F0-01-14" - Vif42MacAddress="00:50:56:98:9d:97" - Protocol="tcp6" - netsh int ipv6 set neighbors $Vif38Name $NatAddress $NatMacAddressForCli - netsh int ipv6 set neighbors $Vif42Name $Vif38Ip $Vif38MacAddressCli - > ovs-ofctl del-flows br-int --strict "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0,priority=2,ipv6,ipv6_dst=$NatAddress,\ - ct_state=-trk,$Protocol actions=ct(table=1,zone=456)" - > ovs-ofctl add-flow br-int "table=0,priority=1,ipv6,ipv6_dst=$Vif38Ip,\ - ct_state=-trk,ip6,$Protocol actions=ct(zone=456,table=1)" - > ovs-ofctl add-flow br-int "table=1,priority=2,ipv6,in_port=$Vif38Port,\ - ipv6_dst=$NatAddress,ct_state=+trk-rel,tp_dst=21,$Protocol \ - actions=ct(commit,alg=ftp,nat(dst=$Vif42Ip),zone=456, \ - exec(set_field:1->ct_mark)),mod_dl_src=$NatMacAddress,\ - mod_dl_dst=$Vif42MacAddress,output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=1,priority=1,ipv6,ct_state=+trk-rel,\ - ipv6_dst=$Vif38Ip,$Protocol,action=ct(nat,alg=ftp,zone=456,table=2)" - > ovs-ofctl add-flow br-int "table=1,ipv6,ct_state=+trk+rel,\ - ipv6_dst=$NatAddress,$Protocol,\ - action=ct(table=2,commit,nat(dst=$Vif42Ip),\ - zone=456, exec(set_field:1->ct_mark))" - > ovs-ofctl add-flow br-int "table=1,ipv6,ct_state=+trk+rel,$Protocol,\ - ipv6_dst=$Vif38Ip, action=ct(nat,zone=456,table=2)" - > ovs-ofctl add-flow br-int "table=2,ipv6,ipv6_dst=$Vif42Ip,$Protocol,\ - actions=mod_dl_src=$NatMacAddress, mod_dl_dst=$Vif42MacAddress,\ - output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=2,ipv6,ipv6_dst=$Vif38Ip,\ - ct_state=-new+est,ct_mark=1,ct_zone=456,$Protocol,\ - actions=mod_dl_src=$NatMacAddress,mod_dl_dst=$Vif38MacAddress,\ - output:$Vif38Port" - > ovs-ofctl add-flow br-int "table=2,ipv6,ipv6_dst=$Vif38Ip,\ - ct_state=+new,ct_mark=1,ct_zone=456,$Protocol,\ - actions=mod_dl_src=$NatMacAddress,\ - mod_dl_dst=$Vif38MacAddress, output:$Vif38Port" - -Tftp same with ftp, it also contains a related connection, we could use -following follow test the tftp connection. - -:: - - normal scenario - Vif38Name="podvif70" - Vif40Name="Ethernet1" - Vif38Port=2 - Vif38Address="20::88" - Vif40Port=3 - Vif40Address="20::45" - Vif40MacAddressCli="00-50-56-98-9d-97" - Vif38MacAddressCli="00-15-5D-F0-01-14" - Protocol="udp6" - netsh int ipv6 set neighbors $Vif38Name $Vif40Address $Vif40MacAddressCli - netsh int ipv6 set neighbors $Vif40Name $Vif38Address $Vif38MacAddressCli - > ovs-ofctl del-flows br-int --strict "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0,priority=1,$Protocol, - ipv6_src=$Vif38Address actions=ct(table=1)" - > ovs-ofctl add-flow br-int "table=0,priority=1,$Protocol, - ipv6_src=$Vif40Address actions=ct(table=1)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ct_state=+new+trk-est, - tp_dst=69,$Protocol,udp6 actions=ct(commit,alg=tftp,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ct_state=-new+trk+est-rel,\ - udp6 $Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ct_state=-new+trk+est+rel,\ - $Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=1,priority=1,ct_state=+new+trk+rel,\ - $Protocol,actions=ct(commit,table=2)" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6,\ - ipv6_dst=$Vif38Address,$Protocol,actions=output:$Vif38Port" - > ovs-ofctl add-flow br-int "table=2,priority=1,ip6,\ - ipv6_dst=$Vif40Address,$Protocol,actions=output:$Vif40Port" - -:: - - nat scenario - Vif38Name="podvif70" - Vif42Name="Ethernet1" - Vif38Ip="20::88" - Vif38Port=2 - Vif42Port=3 - NatAddress="20::9" - NatMacAddress="aa:bb:cc:dd:ee:ff" - NatMacAddressForCli="aa-bb-cc-dd-ee-ff" - Vif42Ip="21::3" - Vif38MacAddress="00:15:5D:F0:01:14" - Vif38MacAddressCli="00-15-5D-F0-01-14" - Vif42MacAddress="00:50:56:98:9d:97" - Protocol="ip6" - netsh int ipv6 set neighbors $Vif38Name $NatAddress $NatMacAddressForCli - netsh int ipv6 set neighbors $Vif42Name $Vif38Ip $Vif38MacAddressCli - > ovs-ofctl del-flows br-int --strict "table=0,priority=0" - > ovs-ofctl add-flow br-int "table=0,priority=2,ipv6,\ - dl_dst=$NatMacAddress,ct_state=-trk,$Protocol \ - actions=ct(table=1,zone=456)" - > ovs-ofctl add-flow br-int "table=0,priority=1,ipv6,ct_state=-trk,ip6,\ - $Protocol actions=ct(table=1,zone=456)" - > ovs-ofctl add-flow br-int "table=1,in_port=$Vif38Port,\ - ipv6_dst=$NatAddress,ct_state=+trk+new-rel,$Protocol,udp6\ - actions=ct(commit,alg=tftp,nat(dst=$Vif42Ip),zone=456,\ - exec(set_field:1->ct_mark)),mod_dl_src=$NatMacAddress,\ - mod_dl_dst=$Vif42MacAddress,output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=1,ipv6,in_port=$Vif42Port,\ - ipv6_dst=$Vif38Ip,ct_state=+trk+rel-rpl,$Protocol\ - actions=ct(commit,nat(src=$NatAddress),zone=456,\ - exec(set_field:1->ct_mark)),mod_dl_src=$NatMacAddress,\ - mod_dl_dst=$Vif38MacAddress,output:$Vif38Port" - > ovs-ofctl add-flow br-int "table=1,ipv6,ct_state=+trk+rel+est+rpl,\ - $Protocol,action=ct(nat,table=2,zone=456)" - > ovs-ofctl add-flow br-int "table=2,ipv6,in_port=$Vif38Port,\ - ct_state=+rel+dnat,ipv6_dst=$Vif42Ip,$Protocol,\ - actions=mod_dl_src=$NatMacAddress,mod_dl_dst=$Vif42MacAddress,\ - output:$Vif42Port" - > ovs-ofctl add-flow br-int "table=2,ipv6,in_port=$Vif42Port,\ - ct_state=-new+est,$Protocol,actions=mod_dl_src=$NatMacAddress,\ - mod_dl_dst=$Vif38MacAddress,output:$Vif38Port" - - -.. note:: - - Till the checksum offload support is complete we recommend - disabling TX/RX offloads for IPV6 on Windows VM. - -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 - -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. diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst index 9ddb145dd..4db5fdff1 100644 --- a/Documentation/topics/index.rst +++ b/Documentation/topics/index.rst @@ -47,7 +47,6 @@ OVS ovsdb-relay ovsdb-replication dpdk/index - windows language-bindings record-replay testing diff --git a/Documentation/topics/windows.rst b/Documentation/topics/windows.rst deleted file mode 100644 index 1f1b513e4..000000000 --- a/Documentation/topics/windows.rst +++ /dev/null @@ -1,509 +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. - -===================== -OVS-on-Hyper-V Design -===================== - -This document provides details of the effort to develop Open vSwitch on -Microsoft Hyper-V. This document should give enough information to understand -the overall design. - -.. note:: - The userspace portion of the OVS has been ported to Hyper-V in a separate - effort, and committed to the openvswitch repo. This document will mostly - emphasize on the kernel driver, though we touch upon some of the aspects of - userspace as well. - -Background Info ---------------- - -Microsoft's hypervisor solution - Hyper-V [1]_ implements a virtual switch -that is extensible and provides opportunities for other vendors to implement -functional extensions [2]_. The extensions need to be implemented as NDIS -drivers that bind within the extensible switch driver stack provided. The -extensions can broadly provide the functionality of monitoring, modifying and -forwarding packets to destination ports on the Hyper-V extensible switch. -Correspondingly, the extensions can be categorized into the following types and -provide the functionality noted: - -* Capturing extensions: monitoring packets - -* Filtering extensions: monitoring, modifying packets - -* Forwarding extensions: monitoring, modifying, forwarding packets - -As can be expected, the kernel portion (datapath) of OVS on Hyper-V solution -will be implemented as a forwarding extension. - -In Hyper-V, the virtual machine is called the Child Partition. Each VIF or -physical NIC on the Hyper-V extensible switch is attached via a port. Each port -is both on the ingress path or the egress path of the switch. The ingress path -is used for packets being sent out of a port, and egress is used for packet -being received on a port. By design, NDIS provides a layered interface. In this -layered interface, higher level layers call into lower level layers, in the -ingress path. In the egress path, it is the other way round. In addition, there -is a object identifier (OID) interface for control operations Eg. addition of a -port. The workflow for the calls is similar in nature to the packets, where -higher level layers call into the lower level layers. A good representational -diagram of this architecture is in [3]_. - -Windows Filtering Platform (WFP) [4]_ is a platform implemented on Hyper-V that -provides APIs and services for filtering packets. WFP has been utilized to -filter on some of the packets that OVS is not equipped to handle directly. More -details in later sections. - -IP Helper [5]_ is a set of API available on Hyper-V to retrieve information -related to the network configuration information on the host machine. IP Helper -has been used to retrieve some of the configuration information that OVS needs. - -Design ------- - -:: - - Various blocks of the OVS Windows implementation - - +-------------------------------+ - | | - | CHILD PARTITION | - | | - +------+ +--------------+ | +-----------+ +------------+ | - | | | | | | | | | | - | ovs- | | OVS- | | | Virtual | | Virtual | | - | *ctl | | USERSPACE | | | Machine #1| | Machine #2 | | - | | | DAEMON | | | | | | | - +------+-++---+---------+ | +--+------+-+ +----+------++ | +--------+ - | dpif- | | netdev- | | |VIF #1| |VIF #2| | |Physical| - | netlink | | windows | | +------+ +------+ | | NIC | - +---------+ +---------+ | || /\ | +--------+ - User /\ /\ | || *#1* *#4* || | /\ - =========||=========||============+------||-------------------||--+ || - Kernel || || \/ || ||=====/ - \/ \/ +-----+ +-----+ *#5* - +-------------------------------+ | | | | - | +----------------------+ | | | | | - | | OVS Pseudo Device | | | | | | - | +----------------------+ | | | | | - | | Netlink Impl. | | | | | | - | ----------------- | | I | | | - | +------------+ | | N | | E | - | | Flowtable | +------------+ | | G | | G | - | +------------+ | Packet | |*#2*| R | | R | - | +--------+ | Processing | |<=> | E | | E | - | | WFP | | | | | S | | S | - | | Driver | +------------+ | | S | | S | - | +--------+ | | | | | - | | | | | | - | OVS FORWARDING EXTENSION | | | | | - +-------------------------------+ +-----+-----------------+-----+ - |HYPER-V Extensible Switch *#3| - +-----------------------------+ - NDIS STACK - -This diagram shows the various blocks involved in the OVS Windows -implementation, along with some of the components available in the NDIS stack, -and also the virtual machines. The workflow of a packet being transmitted from -a VIF out and into another VIF and to a physical NIC is also shown. Later on in -this section, we will discuss the flow of a packet at a high level. - -The figure gives a general idea of where the OVS userspace and the kernel -components fit in, and how they interface with each other. - -The kernel portion (datapath) of OVS on Hyper-V solution has be implemented as -a forwarding extension roughly implementing the following -sub-modules/functionality. Details of each of these sub-components in the -kernel are contained in later sections: - -* Interfacing with the NDIS stack - -* Netlink message parser - -* Netlink sockets - -* Switch/Datapath management - -* Interfacing with userspace portion of the OVS solution to implement the - necessary functionality that userspace needs - -* Port management - -* Flowtable/Actions/packet forwarding - -* Tunneling - -* Event notifications - -The datapath for the OVS on Linux is a kernel module, and cannot be directly -ported since there are significant differences in architecture even though the -end functionality provided would be similar. Some examples of the differences -are: - -* Interfacing with the NDIS stack to hook into the NDIS callbacks for - functionality such as receiving and sending packets, packet completions, OIDs - used for events such as a new port appearing on the virtual switch. - -* Interface between the userspace and the kernel module. - -* Event notifications are significantly different. - -* The communication interface between DPIF and the kernel module need not be - implemented in the way OVS on Linux does. That said, it would be advantageous - to have a similar interface to the kernel module for reasons of readability - and maintainability. - -* Any licensing issues of using Linux kernel code directly. - -Due to these differences, it was a straightforward decision to develop the -datapath for OVS on Hyper-V from scratch rather than porting the one on Linux. -A re-development focused on the following goals: - -* Adhere to the existing requirements of userspace portion of OVS (such as - ovs-vswitchd), to minimize changes in the userspace workflow. - -* Fit well into the typical workflow of a Hyper-V extensible switch forwarding - extension. - -The userspace portion of the OVS solution is mostly POSIX code, and not very -Linux specific. Majority of the userspace code does not interface directly with -the kernel datapath and was ported independently of the kernel datapath effort. - -As explained in the OVS porting design document [6]_, DPIF is the portion of -userspace that interfaces with the kernel portion of the OVS. The interface -that each DPIF provider has to implement is defined in ``dpif-provider.h``. -Though each platform is allowed to have its own implementation of the -DPIF provider, it was found, via community feedback, that it is desired to -share code whenever possible. Thus, the DPIF provider for OVS on Hyper-V shares -code with the DPIF provider on Linux. This interface is implemented in -``dpif-netlink.c``. - -We'll elaborate more on kernel-userspace interface in a dedicated section -below. Here it suffices to say that the DPIF provider implementation for -Windows is netlink-based and shares code with the Linux one. - -Kernel Module (Datapath) ------------------------- - -Interfacing with the NDIS Stack -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For each virtual switch on Hyper-V, the OVS extensible switch extension can be -enabled/disabled. We support enabling the OVS extension on only one switch. -This is consistent with using a single datapath in the kernel on Linux. All the -physical adapters are connected as external adapters to the extensible switch. - -When the OVS switch extension registers itself as a filter driver, it also -registers callbacks for the switch/port management and datapath functions. In -other words, when a switch is created on the Hyper-V root partition (host), the -extension gets an activate callback upon which it can initialize the data -structures necessary for OVS to function. Similarly, there are callbacks for -when a port gets added to the Hyper-V switch, and an External Network adapter -or a VM Network adapter is connected/disconnected to the port. There are also -callbacks for when a VIF (NIC of a child partition) send out a packet, or a -packet is received on an external NIC. - -As shown in the figures, an extensible switch extension gets to see a packet -sent by the VM (VIF) twice - once on the ingress path and once on the egress -path. Forwarding decisions are to be made on the ingress path. Correspondingly, -we will be hooking onto the following interfaces: - -* Ingress send indication: intercept packets for performing flow based - forwarding.This includes straight forwarding to output ports. Any packet - modifications needed to be performed are done here either inline or by - creating a new packet. A forwarding action is performed as the flow actions - dictate. - -* Ingress completion indication: cleanup and free packets that we generated on - the ingress send path, pass-through for packets that we did not generate. - -* Egress receive indication: pass-through. - -* Egress completion indication: pass-through. - -Interfacing with OVS Userspace -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We have implemented a pseudo device interface for letting OVS userspace talk to -the OVS kernel module. This is equivalent to the typical character device -interface on POSIX platforms where we can register custom functions for read, -write and ioctl functionality. The pseudo device supports a whole bunch of -ioctls that netdev and DPIF on OVS userspace make use of. - -Netlink Message Parser -~~~~~~~~~~~~~~~~~~~~~~ - -The communication between OVS userspace and OVS kernel datapath is in the form -of Netlink messages [1]_, [7]_. More details about this are provided below. In -the kernel, a full fledged netlink message parser has been implemented along -the lines of the netlink message parser in OVS userspace. In fact, a lot of the -code is ported code. - -On the lines of ``struct ofpbuf`` in OVS userspace, a managed buffer has been -implemented in the kernel datapath to make it easier to parse and construct -netlink messages. - -Netlink Sockets -~~~~~~~~~~~~~~~ - -On Linux, OVS userspace utilizes netlink sockets to pass back and forth netlink -messages. Since much of userspace code including DPIF provider in -dpif-netlink.c (formerly dpif-linux.c) has been reused, pseudo-netlink sockets -have been implemented in OVS userspace. As it is known, Windows lacks native -netlink socket support, and also the socket family is not extensible either. -Hence it is not possible to provide a native implementation of netlink socket. -We emulate netlink sockets in lib/netlink-socket.c and support all of the nl_* -APIs to higher levels. The implementation opens a handle to the pseudo device -for each netlink socket. Some more details on this topic are provided in the -userspace section on netlink sockets. - -Typical netlink semantics of read message, write message, dump, and transaction -have been implemented so that higher level layers are not affected by the -netlink implementation not being native. - -Switch/Datapath Management -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As explained above, we hook onto the management callback functions in the NDIS -interface for when to initialize the OVS data structures, flow tables etc. Some -of this code is also driven by OVS userspace code which sends down ioctls for -operations like creating a tunnel port etc. - -Port Management -~~~~~~~~~~~~~~~ - -As explained above, we hook onto the management callback functions in the NDIS -interface to know when a port is added/connected to the Hyper-V switch. We use -these callbacks to initialize the port related data structures in OVS. Also, -some of the ports are tunnel ports that don't exist on the Hyper-V switch and -get added from OVS userspace. - -In order to identify a Hyper-V port, we use the value of 'FriendlyName' field -in each Hyper-V port. We call this the "OVS-port-name". The idea is that OVS -userspace sets 'OVS-port-name' in each Hyper-V port to the same value as the -'name' field of the 'Interface' table in OVSDB. When OVS userspace calls into -the kernel datapath to add a port, we match the name of the port with the -'OVS-port-name' of a Hyper-V port. - -We maintain separate hash tables, and separate counters for ports that have -been added from the Hyper-V switch, and for ports that have been added from OVS -userspace. - -Flowtable/Actions/Packet Forwarding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The flowtable and flow actions based packet forwarding is the core of the OVS -datapath functionality. For each packet on the ingress path, we consult the -flowtable and execute the corresponding actions. The actions can be limited to -simple forwarding to a particular destination port(s), or more commonly -involves modifying the packet to insert a tunnel context or a VLAN ID, and -thereafter forwarding to the external port to send the packet to a destination -host. - -Tunneling -~~~~~~~~~ - -We make use of the Internal Port on a Hyper-V switch for implementing -tunneling. The Internal Port is a virtual adapter that is exposed on the Hyper- -V host, and connected to the Hyper-V switch. Basically, it is an interface -between the host and the virtual switch. The Internal Port acts as the Tunnel -end point for the host (aka VTEP), and holds the VTEP IP address. - -Tunneling ports are not actual ports on the Hyper-V switch. These are virtual -ports that OVS maintains and while executing actions, if the outport is a -tunnel port, we short circuit by performing the encapsulation action based on -the tunnel context. The encapsulated packet gets forwarded to the external -port, and appears to the outside world as though it was set from the VTEP. - -Similarly, when a tunneled packet enters the OVS from the external port bound -to the internal port (VTEP), and if yes, we short circuit the path, and -directly forward the inner packet to the destination port (mostly a VIF, but -dictated by the flow). We leverage the Windows Filtering Platform (WFP) -framework to be able to receive tunneled packets that cannot be decapsulated by -OVS right away. Currently, fragmented IP packets fall into that category, and -we leverage the code in the host IP stack to reassemble the packet, and -performing decapsulation on the reassembled packet. - -We'll also be using the IP helper library to provide us IP address and other -information corresponding to the Internal port. - -Event Notifications -~~~~~~~~~~~~~~~~~~~ - -The pseudo device interface described above is also used for providing event -notifications back to OVS userspace. A shared memory/overlapped IO model is -used. - -Userspace Components -~~~~~~~~~~~~~~~~~~~~ - -The userspace portion of the OVS solution is mostly POSIX code, and not very -Linux specific. Majority of the userspace code does not interface directly with -the kernel datapath and was ported independently of the kernel datapath effort. - -In this section, we cover the userspace components that interface with the -kernel datapath. - -As explained earlier, OVS on Hyper-V shares the DPIF provider implementation -with Linux. The DPIF provider on Linux uses netlink sockets and netlink -messages. Netlink sockets and messages are extensively used on Linux to -exchange information between userspace and kernel. In order to satisfy these -dependencies, netlink socket (pseudo and non-native) and netlink messages are -implemented on Hyper-V. - -The following are the major advantages of sharing DPIF provider code: - -1. Maintenance is simpler: - - Any change made to the interface defined in dpif-provider.h need not be - propagated to multiple implementations. Also, developers familiar with the - Linux implementation of the DPIF provider can easily ramp on the Hyper-V - implementation as well. - -2. Netlink messages provides inherent advantages: - - Netlink messages are known for their extensibility. Each message is - versioned, so the provided data structures offer a mechanism to perform - version checking and forward/backward compatibility with the kernel module. - -Netlink Sockets -~~~~~~~~~~~~~~~ - -As explained in other sections, an emulation of netlink sockets has been -implemented in ``lib/netlink-socket.c`` for Windows. The implementation creates -a handle to the OVS pseudo device, and emulates netlink socket semantics of -receive message, send message, dump, and transact. Most of the ``nl_*`` -functions are supported. - -The fact that the implementation is non-native manifests in various ways. One -example is that PID for the netlink socket is not automatically assigned in -userspace when a handle is created to the OVS pseudo device. There's an extra -command (defined in ``OvsDpInterfaceExt.h``) that is used to grab the PID -generated in the kernel. - -DPIF Provider -~~~~~~~~~~~~~ - -As has been mentioned in earlier sections, the netlink socket and netlink -message based DPIF provider on Linux has been ported to Windows. - -Most of the code is common. Some divergence is in the code to receive packets. -The Linux implementation uses epoll() [8]_ which is not natively supported on -Windows. - -netdev-windows -~~~~~~~~~~~~~~ - -We have a Windows implementation of the interface defined in -``lib/netdev-provider.h``. The implementation provides functionality to get -extended information about an interface. It is limited in functionality -compared to the Linux implementation of the netdev provider and cannot be used -to add any interfaces in the kernel such as a tap interface or to send/receive -packets. The netdev-windows implementation uses the datapath interface -extensions defined in ``datapath-windows/include/OvsDpInterfaceExt.h``. - -Powershell Extensions to Set ``OVS-port-name`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As explained in the section on "Port management", each Hyper-V port has a -'FriendlyName' field, which we call as the "OVS-port-name" field. We have -implemented powershell command extensions to be able to set the "OVS-port-name" -of a Hyper-V port. - -Kernel-Userspace Interface --------------------------- - -openvswitch.h and OvsDpInterfaceExt.h -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since the DPIF provider is shared with Linux, the kernel datapath provides the -same interface as the Linux datapath. The interface is defined in -``datapath/linux/compat/include/linux/openvswitch.h``. Derivatives of this -interface file are created during OVS userspace compilation. The derivative for -the kernel datapath on Hyper-V is provided in -``datapath-windows/include/OvsDpInterface.h``. - -That said, there are Windows specific extensions that are defined in the -interface file ``datapath-windows/include/OvsDpInterfaceExt.h``. - -Flow of a Packet ----------------- - -Figure 2 shows the numbered steps in which a packets gets sent out of a VIF and -is forwarded to another VIF or a physical NIC. As mentioned earlier, each VIF -is attached to the switch via a port, and each port is both on the ingress and -egress path of the switch, and depending on whether a packet is being -transmitted or received, one of the paths gets used. In the figure, each step n -is annotated as ``#n`` - -The steps are as follows: - -1. When a packet is sent out of a VIF or an physical NIC or an internal port, - the packet is part of the ingress path. - -2. The OVS kernel driver gets to intercept this packet. - - a. OVS looks up the flows in the flowtable for this packet, and executes the - corresponding action. - - b. If there is not action, the packet is sent up to OVS userspace to examine - the packet and figure out the actions. - - c. Userspace executes the packet by specifying the actions, and might also - insert a flow for such a packet in the future. - - d. The destination ports are added to the packet and sent down to the Hyper- - V switch. - -3. The Hyper-V forwards the packet to the destination ports specified in the - packet, and sends it out on the egress path. - -4. The packet gets forwarded to the destination VIF. - -5. It might also get forwarded to a physical NIC as well, if the physical NIC - has been added as a destination port by OVS. - -Build/Deployment ----------------- - -The userspace components added as part of OVS Windows implementation have been -integrated with autoconf, and can be built using the steps mentioned in the -BUILD.Windows file. Additional targets need to be specified to make. - -The OVS kernel code is part of a Visual Studio 2013 solution, and is compiled -from the IDE. There are plans in the future to move this to a compilation mode -such that we can compile it without an IDE as well. - -Once compiled, we have an install script that can be used to load the kernel -driver. - -References ----------- - -.. [1] Hyper-V Extensible Switch https://msdn.microsoft.com/windows/hardware/drivers/network/hyper-v-extensible-switch -.. [2] Hyper-V Extensible Switch Extensions https://msdn.microsoft.com/windows/hardware/drivers/network/hyper-v-extensible-switch-extensions -.. [3] Hyper-V Extensible Switch Components https://msdn.microsoft.com/windows/hardware/drivers/network/hyper-v-extensible-switch-components -.. [4] Windows Filtering Platform https://msdn.microsoft.com/en-us/library/windows/desktop/aa366510(v=vs.85).aspx -.. [5] IP Helper https://msdn.microsoft.com/windows/hardware/drivers/network/ip-helper -.. [6] How to Port Open vSwitch to New Software or Hardware :doc:`porting` -.. [7] Netlink https://en.wikipedia.org/wiki/Netlink -.. [8] epoll https://en.wikipedia.org/wiki/Epoll -- 2.53.0 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
