doc: Convert INSTALL.Windows to rST

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 <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

4 files changed, 623 insertions, 529 deletions

diff --git a/INSTALL.Windows.md b/INSTALL.Windows.md
deleted file mode 100644
index 59f393633..000000000
--- 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 000000000..3cec9e747
--- /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 4dddd3f8a..bf546b11a 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 2bee56560..75f966641 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 \