This has been extensively reworked such that the format of the document matches that of INSTALL.rst. The sum of the content remains the same, however.
Signed-off-by: Stephen Finucane <step...@that.guru> --- INSTALL.Windows.md | 527 -------------------------------------------- INSTALL.Windows.rst | 621 ++++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL.rst | 2 +- Makefile.am | 2 +- 4 files changed, 623 insertions(+), 529 deletions(-) delete mode 100644 INSTALL.Windows.md create mode 100644 INSTALL.Windows.rst diff --git a/INSTALL.Windows.md b/INSTALL.Windows.md deleted file mode 100644 index 59f3936..0000000 --- a/INSTALL.Windows.md +++ /dev/null @@ -1,527 +0,0 @@ -How to Build the Kernel module & userspace daemons for Windows -============================================================== - -Autoconf, Automake and Visual C++: ---------------------------------- -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. - -* Install Mingw on a Windows machine by following the instructions at: -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'. - -* Install the latest Python 2.x from python.org and verify that its path is -part of Windows' PATH environment variable. - -* 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". - -* For pthread support, install the library, dll and includes of pthreads-win32 -project from -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. - -* Get the Open vSwitch sources from either cloning the repo using git -or from a distribution tar ball. - -* If you pulled the sources directly from an Open vSwitch Git tree, - run boot.sh in the top source directory: - - % ./boot.sh - -* In the top source directory, 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 -liphlpapi" --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" - - By default, the above enables compiler optimization for fast code. - For default compiler optimization, pass the "--with-debug" configure - option. - -* 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 command - 'mingw-get upgrade msys-core-bin=1.0.17-1' from MSVC developers command - prompt. - -* 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 - - The above command 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. - -OpenSSL, Open vSwitch and Visual C++ ------------------------------------- -To get SSL support for Open vSwitch on Windows, do the following: - -* Install OpenSSL for Windows as suggested at -http://www.openssl.org/related/binaries.html. -The link as of this writing suggests to download it from -http://slproweb.com/products/Win32OpenSSL.html - -Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32). - -* While configuring the package, specify the OpenSSL directory path. -For example, - - % ./configure CC=./build-aux/cccl LD="`which link`" \ - LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" --enable-ssl --with-openssl="C:/OpenSSL-Win32" - -* Run make for the ported executables. - -Building the Kernel datapath module ------------------------------------ -* We directly use the Visual Studio 2013 IDE to compile the kernel datapath. -You can open the ovsext.sln file in the IDE and build the solution. - -* The kernel datapath can be compiled from command line as well. The top -level 'make' will invoke building the kernel datapath, if the -'--with-vstudiotarget' argument is specified while configuring the package. -For example, - - % ./configure CC=./build-aux/cccl LD="`which link`" \ - LIBS="-lws2_32 -liphlpapi" --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>" - - Possible values for "<target type>" are: - "Debug" and "Release" - -Installing the Kernel module ----------------------------- -Once you have built the solution, you can copy the following files to the -target Hyper-V machines. - - ./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 - -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. - -Steps to install the module ---------------------------- - -01> Run ./uninstall.cmd to remove the old extension. - -02> 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. - -03> 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: - % New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \ - -NetAdapterName "Ethernet 1" - -Note: you can obtain the list of physical NICs on the host using -'Get-NetAdapter' command. - -04> 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: - % 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. - -Steps to run the user processes & configure ports -------------------------------------------------- -The following steps assume that you have installed the Open vSwitch -utilities in the local machine via 'make install'. - -01> Create the database. - % ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \ - C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema - -02> Start the ovsdb-server and initialize the database. - % ovsdb-server -vfile:info --remote=punix:db.sock --log-file --pidfile \ - --detach - % ovs-vsctl --no-wait init - - If you would like to terminate the started ovsdb-server, run: - % ovs-appctl -t ovsdb-server exit - - (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/) - -03> Start ovs-vswitchd. - % ovs-vswitchd -vfile:info --log-file --pidfile --detach - - If you would like to terminate the started ovs-vswitchd, run: - % ovs-appctl exit - - (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/) - -04> Create integration bridge & pif bridge - % 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. - -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'.) - -05> Dump the ports in the kernel datapath - % ovs-dpctl show - -* Sample output is as follows: - - % 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 - -06> Dump the ports in the OVSDB - % ovs-vsctl show - -* Sample output is as follows: - % 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 - -07> 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. I.e. let us suppose we created the Hyper-V -virtual switch on top of the adapter named 'Ethernet0'. In OVS for Hyper-V, we -use that name('Ethernet0') as a special name to refer to that adapter. - -Note: Currently, we assume that the Hyper-V switch on which OVS extension is -enabled has a single physical NIC connected to it. - -Internal port is the virtual adapter created on the Hyper-V switch using the -'AllowManagementOS' setting. This has already been setup while creating the -switch using the instructions above. In OVS for Hyper-V, we use a the name of -that specific adapter as a special name to refer to that adapter. By default it -is created under the following rule "vEthernet (<name of the switch>)". - -As a whole example, if we issue the following in a powershell console: -PS C:\package\binaries> Get-NetAdapter | select Name,MacAddress,InterfaceDescription - -Name MacAddress InterfaceDescription ----- ---------- -------------------- -Ethernet1 00-0C-29-94-05-65 Intel(R) PRO/1000 MT Network Connection -vEthernet (external) 00-0C-29-94-05-5B Hyper-V Virtual Ethernet Adapter #2 -Ethernet0 00-0C-29-94-05-5B Intel(R) PRO/1000 MT Network Connection #2 - -PS C:\package\binaries> 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 an internal port under name 'vEthernet (external)'. Thus resulting into the -following ovs-vsctl commands - - % ovs-vsctl add-port br-pif Ethernet0 - % ovs-vsctl add-port br-pif "vEthernet (external)" - -* Dumping the ports should show the additional ports that were just added. - Sample output shows up as follows: - - % ovs-dpctl show - system@ovs-system: - lookups: hit:0 missed:0 lost:0 - flows: 0 - port 4: vEthernet (external) (internal) <<< 'AllowManagementOS' - adapter on - Hyper-V switch - port 2: br-pif (internal) - port 1: br-int (internal) - port 3: Ethernet0 <<< Physical NIC - - % ovs-vsctl show - a56ec7b5-5b1f-49ec-a795-79f6eb63228b - Bridge br-pif - Port "vEthernet (external)" - Interface "vEthernet (external)" - Port br-pif - Interface br-pif - type: internal - Port "Ethernet0" - Interface "Ethernet0" - Bridge br-int - Port br-int - Interface br-int - type: internal - -08> Add the VIFs to br-int - -Adding VIFs to openvswitch 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. - -08a> Assign a unique 'OVS port name' to the VIF - -Note that 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 by name '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. - - Eg: - % import-module .\datapath-windows\misc\OVS.psm1 - % $vnic = Get-VMNetworkAdapter <Name of the VM> - % Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] - % $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a - % Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \ - -SwitchName OVS-Extended-Switch - -08b> Add the VIFs to br-int in ovsdb - - Eg: - % ovs-vsctl add-port br-int ovs-port-a - -09> Verify the status - % ovs-dpctl show - system@ovs-system: - lookups: hit:0 missed:0 lost:0 - flows: 0 - port 4: vEthernet (external) (internal) - port 5: 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" - -Steps to configure patch ports and switch 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. The following examples demonstrate how it can be done: - -01> 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 - -02> 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 - -03> 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 - -Steps to add tunnels --------------------------- -The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add -tunnels, the following steps serve as examples. - -Note that, any patch ports created between br-int and br-pif MUST be beleted -prior to adding tunnels. - -01> 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 - -02> Add 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 the string stt or vxlan - - -Requirements ------------- -* 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 HyperV 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 HyperV. - -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'. The commands shown here can be run from -MSYS bash or Windows command prompt. - -* 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" - - 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 - - Start the service. - - % sc start 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 autobuild service -------------------------- -AppVeyor (appveyor.com) provides a free Windows autobuild service for -opensource 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 OpenvSwitch -components on windows. diff --git a/INSTALL.Windows.rst b/INSTALL.Windows.rst new file mode 100644 index 0000000..44f721e --- /dev/null +++ b/INSTALL.Windows.rst @@ -0,0 +1,621 @@ +.. + 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 + + Install the latest Python 2.x from python.org and verify that its path is + part of Windows' PATH environment variable. + +- 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. + +- OpenSSQL + + To get SSL support for Open vSwitch on Windows, you will need to install + `OpenSSL for Windows <http://www.openssl.org/related/binaries.html>`__ + + Note down the directory where OpenSSL is installed (e.g.: + ``C:/OpenSSL-Win32``) for later use. + +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 HyperV 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 HyperV. + +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 -liphlpapi" --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 -liphlpapi" --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 -liphlpapi" --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>" + +Possible values for ``<target type>`` are: ``Debug`` and ``Release`` + +.. 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 the `installation guide <INSTALL.rst>` 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" -AllowManagementOS $true \ + -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 Hyper-V switch on which OVS extension is enabled has a + single physical NIC connected to it. + +An internal port is the virtual adapter created on the Hyper-V switch using the +``AllowManagementOS`` setting. This has already been setup while creating the +switch using the instructions above. In OVS for Hyper-V, we use a the name of +that specific adapter as a special name to refer to that adapter. By default it +is created under the following rule ``vEthernet (<name of the switch>)``. + +As a whole example, if we issue the following in a powershell console::: + + PS C:\package\binaries> Get-NetAdapter | select Name,MacAddress,InterfaceDescription + Name MacAddress InterfaceDescription + ---- ---------- -------------------- + Ethernet1 00-0C-29-94-05-65 Intel(R) PRO/1000 MT Network Connection + vEthernet (external) 00-0C-29-94-05-5B Hyper-V Virtual Ethernet Adapter #2 + Ethernet0 00-0C-29-94-05-5B Intel(R) PRO/1000 MT Network Connection #2 + + PS C:\package\binaries> 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 an internal port under name ``vEthernet (external)``. Thus +resulting into the following ovs-vsctl commands::: + + $ ovs-vsctl add-port br-pif Ethernet0 + $ ovs-vsctl add-port br-pif "vEthernet (external)" + +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: vEthernet (external) (internal) <<< 'AllowManagementOS' + adapter on + Hyper-V switch + port 2: br-pif (internal) + port 1: br-int (internal) + port 3: Ethernet0 <<< Physical NIC + + $ ovs-vsctl show + a56ec7b5-5b1f-49ec-a795-79f6eb63228b + Bridge br-pif + Port "vEthernet (external)" + Interface "vEthernet (external)" + 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 openvswitch 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: vEthernet (external) (internal) + port 5: 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 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``. + +.. note:: + The commands shown here can be run from MSYS bash or Windows command prompt. + +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 +opensource 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 OpenvSwitch + components on Windows. diff --git a/INSTALL.rst b/INSTALL.rst index 612b36d..963be09 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -34,7 +34,7 @@ platform, refer to one of these installation guides: - `RHEL <INSTALL.RHEL.md>`__ - `XenServer <INSTALL.XenServer.md>`__ - `NetBSD <INSTALL.NetBSD.md>`__ -- `Windows <INSTALL.Windows.md>`__ +- `Windows <INSTALL.Windows.rst>`__ - `DPDK <INSTALL.DPDK.rst>`__ .. _general-build-reqs: diff --git a/Makefile.am b/Makefile.am index 2bee565..75f9666 100644 --- a/Makefile.am +++ b/Makefile.am @@ -84,7 +84,7 @@ docs = \ INSTALL.SSL.md \ INSTALL.XenServer.md \ INSTALL.userspace.md \ - INSTALL.Windows.md \ + INSTALL.Windows.rst \ IntegrationGuide.md \ MAINTAINERS.md \ OPENFLOW-1.1+.md \ -- 2.7.4 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
