INSTALL.Windows.md

   1 How to Build the Kernel module & userspace daemons for Windows
   2 ==============================================================
   3
   4 Autoconf, Automake and Visual C++:
   5 ---------------------------------
   6 Open vSwitch on Linux uses autoconf and automake for generating Makefiles.
   7 It will be useful to maintain the same build system while compiling on Windows
   8 too.  One approach is to compile Open vSwitch in a MinGW environment that
   9 contains autoconf and automake utilities and then use Visual C++ as a compiler
  10 and linker.
  11
  12 The following explains the steps in some detail.
  13
  14 * Install Mingw on a Windows machine by following the instructions at:
  15 http://www.mingw.org/wiki/Getting_Started
  16
  17 This should install mingw at C:\Mingw and msys at C:\Mingw\msys.
  18 Add "C:\MinGW\bin" and "C:\Mingw\msys\1.0\bin" to PATH environment variable
  19 of Windows.
  20
  21 You can either use the MinGW installer or the command line utility 'mingw-get'
  22 to install both the base packages and additional packages like automake and
  23 autoconf(version 2.68).
  24
  25 Also make sure that /mingw mount point exists. If its not, please add/create
  26 the following entry in /etc/fstab - 'C:/MinGW /mingw'.
  27
  28 * Install the latest Python 2.x from python.org and verify that its path is
  29 part of Windows' PATH environment variable.
  30
  31 * You will need at least Visual Studio 2013 to compile userspace binaries. In
  32 addition to that, if you want to compile the kernel module you will also need to
  33 install Windows Driver Kit (WDK) 8.1 Update.
  34
  35 It is important to get the Visual Studio related environment variables and to
  36 have the $PATH inside the bash to point to the proper compiler and linker. One
  37 easy way to achieve this is to get into the "Developer Command prompt for visual
  38 studio" and through it enter into the bash shell available from msys by typing
  39 'bash --login'.
  40
  41 If after the above step, a 'which link' inside MSYS's bash says,
  42 "/bin/link.exe", rename /bin/link.exe to something else so that the
  43 Visual studio's linker is used. You should also see a 'which sort' report
  44 "/bin/sort.exe".
  45
  46 * For pthread support, install the library, dll and includes of pthreads-win32
  47 project from
  48 ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release to a
  49 directory (e.g.: C:/pthread).
  50
  51 * Get the Open vSwitch sources from either cloning the repo using git
  52 or from a distribution tar ball.
  53
  54 * If you pulled the sources directly from an Open vSwitch Git tree,
  55   run boot.sh in the top source directory:
  56
  57     % ./boot.sh
  58
  59 * In the top source directory, configure the package by running the
  60   configure script.  You should provide some configure options to choose
  61   the right compiler, linker, libraries, Open vSwitch component installation
  62   directories, etc. For example,
  63
  64     % ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
  65       --prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
  66       --sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread"
  67
  68     By default, the above enables compiler optimization for fast code.
  69     For default compiler optimization, pass the "--with-debug" configure
  70     option.
  71
  72 * Run make for the ported executables in the top source directory, e.g.:
  73
  74     % make
  75
  76 * To run all the unit tests:
  77
  78     % make check
  79
  80 OpenSSL, Open vSwitch and Visual C++
  81 ------------------------------------
  82 To get SSL support for Open vSwitch on Windows, do the following:
  83
  84 * Install OpenSSL for Windows as suggested at
  85 http://www.openssl.org/related/binaries.html.
  86 The link as of this writing suggests to download it from
  87 http://slproweb.com/products/Win32OpenSSL.html
  88
  89 Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
  90
  91 * While configuring the package, specify the OpenSSL directory path.
  92 For example,
  93
  94     % ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
  95     --prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
  96     --sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread" \
  97     --enable-ssl --with-openssl="C:/OpenSSL-Win32"
  98
  99 * Run make for the ported executables.
 100
 101 Building the Kernel datapath module
 102 -----------------------------------
 103 * We directly use the Visual Studio 2013 IDE to compile the kernel datapath.
 104 You can open the extensions.sln file in the IDE and build the solution.
 105
 106 * The kernel datapath can be compiled from command line as well.  The top
 107 level 'make' will invoke building the kernel datapath, if the
 108 '--with-vstudioddk' argument is specified while configuring the package.
 109 For example,
 110
 111     % ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
 112     --prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
 113     --sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread" \
 114     --enable-ssl --with-openssl="C:/OpenSSL-Win32" \
 115     --with-vstudioddk="<WDK to use>"
 116
 117     Possible values for "<WDK to use>" are:
 118     "Win8.1 Debug", "Win8.1 Release", "Win8 Debug" and "Win8 Release".
 119
 120 Installing the Kernel module
 121 ----------------------------
 122 Once you have built the solution, you can copy the following files to the
 123 target Hyper-V machines.
 124
 125     ./datapath-windows/x64/Win8.1Debug/package/ovsext.inf
 126     ./datapath-windows/x64/Win8.1Debug/package/OVSExt.sys
 127     ./datapath-windows/x64/Win8.1Debug/package/ovsext.cat
 128     ./datapath-windows/misc/install.cmd
 129     ./datapath-windows/misc/uninstall.cmd
 130
 131 The above path assumes that the kernel module has been built using Windows
 132 DDK 8.1 in Debug mode. Change the path appropriately, if a different WDK
 133 has been used.
 134
 135 Steps to install the module
 136 ---------------------------
 137
 138 01> Run ./uninstall.cmd to remove the old extension.
 139
 140 02> Run ./install.cmd to insert the new one.  For this to work you will have to
 141 turn on TESTSIGNING boot option or 'Disable Driver Signature Enforcement'
 142 during boot.
 143
 144 03> In the Virtual Switch Manager configuration you can enable the Open vSwitch
 145 Extension on an existing switch or create a new switch.  If you are using an
 146 existing switch, make sure to enable the "Allow Management OS" option for VXLAN
 147 to work (covered later).
 148
 149 The command to create a new switch named 'OVS-Extended-Switch' using a physical
 150 NIC named 'Ethernet 1' is:
 151     % New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
 152                    -NetAdapterName "Ethernet 1"
 153
 154 Note: you can obtain the list of physical NICs on the host using
 155 'Get-NetAdapter' command.
 156
 157 04> In the properties of any switch, you should should now see "Open
 158 vSwitch Extension" under 'Extensions'.  Click the check box to enable the
 159 extension.  An alternative way to do the same is to run the following command:
 160     % Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch
 161
 162 Note: If you enabled the extension using the command line, a delay of a few
 163 seconds has been observed for the change to be reflected in the UI.  This is
 164 not a bug in Open vSwitch.
 165
 166 Steps to run the user processes & configure ports
 167 -------------------------------------------------
 168 NOTE: The userspace executables built in Open vSwitch for Hyper-V links
 169 statically with the pthread library mentioned above.  However, the pthread
 170 library has been found to have a dependency on a DLL file called
 171 "pthreadVC2.dll" which is part of the pthread package and typically resides in
 172 "C:\pthread\dll\x86".  In order to resolve the dependency, add the location of
 173 the DLL file to Windows environment variable %Path%.  An alternative is to copy
 174 the DLL file into each of the directories where the OVS executables are
 175 located.  Without having this DLL dependency resolved, the OVS executables will
 176 not run.  They exit without showing any error/output.
 177
 178 01> Create the OVSDB file
 179     % ovsdb\ovsdb-tool.exe create conf.db .\vswitchd\vswitch.ovsschema
 180
 181 02> Start ovsdb-server [IN A NEW CONSOLE]
 182     % ovsdb\ovsdb-server.exe -v --remote=punix:db.sock conf.db
 183
 184 03> Start ovs-vswitchd [IN A NEW CONSOLE]
 185     % vswitchd\ovs-vswitchd.exe -v
 186
 187 04> Create integration bridge & pif bridge
 188     % utilities\ovs-vsctl.exe add-br br-int
 189     % utilities\ovs-vsctl.exe add-br br-pif
 190
 191 NOTE: There's a known bug that running the ovs-vsctl.exe command does not
 192 terminate.  This is generally solved by having ovs-vswitchd.exe running.  If
 193 you face the issue despite that, hit Ctrl-C to terminate ovs-vsctl.exe and
 194 check the output to see if your command succeeded.
 195
 196 NOTE: There's a known bug that the ports added to OVSDB via ovs-vsctl.exe don't
 197 get to the kernel datapath immediately, ie. they don't whow up in the output of
 198 "ovs-dpctl.exe show" even though they show up in output of "ovs-vsctl.exe
 199 show".  In order to workaround this issue, restart ovs-vswitchd.exe.
 200
 201 05> Dump the ports in the kernel datapath
 202 .\    % utilities\ovs-dpctl.exe show
 203
 204 * Sample output is as follows:
 205
 206     % utilities\ovs-dpctl.exe show
 207     system@ovs-system:
 208             lookups: hit:0 missed:0 lost:0
 209             flows: 0
 210             port 2: br-pif (internal)     <<< internal port on 'br-pif' bridge
 211             port 1: br-int (internal)     <<< internal port on 'br-int' bridge
 212
 213 06> Dump the ports in the OVSDB
 214     % utilities\ovs-vsctl.exe show
 215
 216 * Sample output is as follows:
 217     % .\ovs-vsctl.exe show
 218     a56ec7b5-5b1f-49ec-a795-79f6eb63228b
 219         Bridge br-pif
 220             Port br-pif
 221                 Interface br-pif
 222                     type: internal
 223         Bridge br-int
 224             Port br-int
 225                 Interface br-int
 226                     type: internal
 227
 228 07> Add the physical NIC and the internal port to br-pif.
 229
 230 In OVS for Hyper-V, we use 'external' as a special name to refer to the
 231 physical NICs connected to the Hyper-V switch.  An index is added to this
 232 special name to refer to the particular physical NIC. Eg. 'external.1' refers
 233 to the first physical NIC on the Hyper-V switch.
 234
 235 Note: Currently, we assume that the Hyper-V switch on which OVS extension is
 236 enabled has a single physical NIC connected to it.
 237
 238 Interal port is the virtual adapter created on the Hyper-V switch using the
 239 'AllowManagementOS' setting.  This has already been setup while creating the
 240 switch using the instructions above.  In OVS for Hyper-V, we use a 'internal'
 241 as a special name to refer to that adapter.
 242
 243     % utilities\ovs-vsctl.exe add-port br-pif external.1
 244     % utilities\ovs-vsctl.exe add-port br-pif internal
 245
 246 * Dumping the ports should show the additional ports that were just added.
 247   Sample output shows up as follows:
 248
 249     % utilities\ovs-dpctl.exe show
 250     system@ovs-system:
 251             lookups: hit:0 missed:0 lost:0
 252             flows: 0
 253             port 4: internal (internal)   <<< 'AllowManagementOS' adapter on
 254                                               Hyper-V switch
 255             port 2: br-pif (internal)
 256             port 1: br-int (internal
 257             port 3: external.1            <<< Physical NIC
 258
 259     % .\ovs-vsctl.exe show
 260     a56ec7b5-5b1f-49ec-a795-79f6eb63228b
 261         Bridge br-pif
 262             Port internal
 263                 Interface internal
 264             Port br-pif
 265                 Interface br-pif
 266                     type: internal
 267         Bridge br-int
 268             Port "external.1"
 269                 Interface "external.1"
 270             Port br-int
 271                 Interface br-int
 272                     type: internal
 273
 274 08> Add the VIFs to br-int
 275
 276 Adding VIFs to openvswitch is a two step procedure.  The first step is to
 277 assign a 'OVS port name' which is a unique name across all VIFs on this
 278 Hyper-V.  The next step is to add the VIF to the ovsdb using its 'OVS port
 279 name' as key.
 280
 281 08a> Assign a unique 'OVS port name' to the VIF
 282
 283 Note that the VIF needs to have been disconnected from the Hyper-V switch
 284 before assigning a 'OVS port name' to it.  In the example below, we assign a
 285 'OVS port name' called 'ovs-port-a' to a VIF on a VM by name 'VM1'.  By using
 286 index 0 for '$vnic', the first VIF of the VM is being addressed.  After
 287 assigning the name 'ovs-port-a', the VIF is connected back to the Hyper-V
 288 switch with name 'OVS-HV-Switch', which is assumed to be the Hyper-V switch
 289 with OVS extension enabled.
 290
 291     Eg:
 292     % import-module .\datapath-windows\misc\OVS.psm1
 293     % $vnic = Get-VMNetworkAdapter <Name of the VM>
 294     % Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0]
 295     % $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a
 296     % Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \
 297                                -SwitchName OVS-Extended-Switch
 298
 299 08b> Add the VIFs to br-int in ovsdb
 300
 301     Eg:
 302     % utilities\ovs-vsctl.exe add-port br-int ovs-port-a
 303
 304 09> Verify the status
 305     % utilities\ovs-dpctl.exe show
 306     system@ovs-system:
 307             lookups: hit:0 missed:0 lost:0
 308             flows: 0
 309             port 4: internal (internal)
 310             port 5: ovs-port-a
 311             port 2: br-pif (internal)
 312             port 1: br-int (internal
 313             port 3: external.1
 314
 315     % utilities\ovs-vsctl.exe show
 316     4cd86499-74df-48bd-a64d-8d115b12a9f2
 317         Bridge br-pif
 318             Port internal
 319                 Interface internal
 320             Port "external.1"
 321                 Interface "external.1"
 322             Port br-pif
 323                 Interface br-pif
 324                     type: internal
 325         Bridge br-int
 326             Port br-int
 327                 Interface br-int
 328                     type: internal
 329             Port "ovs-port-a"
 330                 Interface "ovs-port-a"
 331
 332 Steps to configure patch ports and switch VLAN tagging
 333 ------------------------------------------------------
 334 The Windows Open vSwitch implementation support VLAN tagging in the switch.
 335 Switch VLAN tagging along with patch ports between 'br-int' and 'br-pif' is
 336 used to configure VLAN tagging functionality between two VMs on different
 337 Hyper-Vs.  The following examples demonstrate how it can be done:
 338
 339 01> Add a patch port from br-int to br-pif
 340     % utilities/ovs-vsctl.exe -- add-port br-int patch-to-pif
 341     % utilities/ovs-vsctl.exe -- set interface patch-to-pif type=patch \
 342                                  options:peer=patch-to-int
 343
 344 02> Add a patch port from br-pif to br-int
 345     % utilities/ovs-vsctl.exe -- add-port br-pif patch-to-int
 346     % utilities/ovs-vsctl.exe -- set interface patch-to-int type=patch \
 347                                  options:peer=patch-to-pif
 348
 349 03> Re-Add the VIF ports with the VLAN tag
 350     % utilities\ovs-vsctl.exe add-port br-int ovs-port-a tag=900
 351     % utilities\ovs-vsctl.exe add-port br-int ovs-port-b tag=900
 352
 353 Steps to add VXLAN tunnels
 354 --------------------------
 355 The Windows Open vSwitch implementation support VXLAN tunnels.  To add VXLAN
 356 tunnels, the following steps serve as examples.
 357
 358 Note that, any patch ports created between br-int and br-pif MUST be beleted
 359 prior to adding VXLAN tunnels.
 360
 361 01> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
 362     % utilities\ovs-vsctl.exe add-port br-int vxlan-1
 363     % utilities\ovs-vsctl.exe set Interface vxlan-1 type=vxlan
 364     % utilities\ovs-vsctl.exe set Interface vxlan-1 \
 365                                   options:local_ip=172.168.201.101
 366     % utilities\ovs-vsctl.exe set Interface vxlan-1 \
 367                                   options:remote_ip=172.168.201.102
 368     % utilities\ovs-vsctl.exe set Interface vxlan-1 options:in_key=flow
 369     % utilities\ovs-vsctl.exe set Interface vxlan-1 options:out_key=flow
 370
 371 02> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
 372     % utilities\ovs-vsctl.exe add-port br-int vxlan-2
 373     % utilities\ovs-vsctl.exe set Interface vxlan-2 type=vxlan
 374     % utilities\ovs-vsctl.exe set Interface vxlan-2 \
 375                                   options:local_ip=172.168.201.102
 376     % utilities\ovs-vsctl.exe set Interface vxlan-2 \
 377                                   options:remote_ip=172.168.201.105
 378     % utilities\ovs-vsctl.exe set Interface vxlan-2 options:in_key=flow
 379     % utilities\ovs-vsctl.exe set Interface vxlan-2 options:out_key=flow
 380
 381
 382 Requirements
 383 ------------
 384 * We require that you don't disable the "Allow management operating system to
 385 share this network adapter" under 'Virtual Switch Properties' > 'Connection
 386 type: External network', in the HyperV virtual network switch configuration.
 387
 388 * Checksum Offloads
 389     While there is some support for checksum/segmentation offloads in software,
 390 this is still a work in progress. Till the support is complete we recommend
 391 disabling TX/RX offloads for both the VM's as well as the HyperV.
 392
 393 Windows autobuild service
 394 -------------------------
 395 AppVeyor (appveyor.com) provides a free Windows autobuild service for
 396 opensource projects.  Open vSwitch has integration with AppVeyor for
 397 continuous build.  A developer can build test his changes for Windows by
 398 logging into appveyor.com using a github account, creating a new project
 399 by linking it to his development repository in github and triggering
 400 a new build.
 401
 402 TODO
 403 ----
 404
 405 * Investigate the working of sFlow on Windows and re-enable the unit tests.
 406
 407 * Investigate and add the feature to provide QOS.
 408
 409 * Sign the driver & create an MSI for installing the different OpenvSwitch
 410 components on windows.