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 (update 4) to compile userspace
  32 binaries.  In addition to that, if you want to compile the kernel module you
  33 will also need to 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 for VS2013 is to get into the "VS2013 x86 Native
  38 Tools Command Prompt" (in a default installation of Visual Studio 2013 this can
  39 be found under the following location:
  40 C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts)
  41 and through it enter into the bash shell available from msys by typing
  42 'bash --login'.
  43
  44 There is support for generating 64 bit binaries too.  To compile under x64,
  45 open the "VS2013 x64 Native Tools Command Prompt" (if your current running OS
  46 is 64 bit) or "VS2013 x64 Cross Tools Command Prompt" (if your current running
  47 OS is not 64 bit) instead of opening its x86 variant.  This will point the
  48 compiler and the linker to their 64 bit equivalent.
  49
  50 If after the above step, a 'which link' inside MSYS's bash says,
  51 "/bin/link.exe", rename /bin/link.exe to something else so that the
  52 Visual studio's linker is used. You should also see a 'which sort' report
  53 "/bin/sort.exe".
  54
  55 * For pthread support, install the library, dll and includes of pthreads-win32
  56 project from
  57 ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release to a
  58 directory (e.g.: C:/pthread). You should add the pthread-win32's dll
  59 path (e.g.: C:\pthread\dll\x86) to the Windows' PATH environment variable.
  60
  61 * Get the Open vSwitch sources from either cloning the repo using git
  62 or from a distribution tar ball.
  63
  64 * If you pulled the sources directly from an Open vSwitch Git tree,
  65   run boot.sh in the top source directory:
  66
  67     % ./boot.sh
  68
  69 * In the top source directory, configure the package by running the
  70   configure script.  You should provide some configure options to choose
  71   the right compiler, linker, libraries, Open vSwitch component installation
  72   directories, etc. For example,
  73
  74     % ./configure CC=./build-aux/cccl LD="`which link`" \
  75       LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
  76       --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \
  77        --with-pthread="C:/pthread"
  78
  79     By default, the above enables compiler optimization for fast code.
  80     For default compiler optimization, pass the "--with-debug" configure
  81     option.
  82
  83 * Run make for the ported executables in the top source directory, e.g.:
  84
  85     % make
  86
  87   For faster compilation, you can pass the '-j' argument to make.  For
  88   example, to run 4 jobs simultaneously, run 'make -j4'.
  89
  90   Note: MSYS 1.0.18 has a bug that causes parallel make to hang. You
  91   can overcome this by downgrading to MSYS 1.0.17.  A simple way to
  92   downgrade is to exit all MinGW sessions and then run the command
  93   'mingw-get upgrade msys-core-bin=1.0.17-1' from MSVC developers command
  94   prompt.
  95
  96 * To run all the unit tests in Open vSwitch, one at a time:
  97
  98     % make check
  99
 100   To run all the unit tests in Open vSwitch, up to 8 in parallel:
 101
 102     % make check TESTSUITEFLAGS="-j8"
 103
 104 * To install all the compiled executables on the local machine, run:
 105
 106     % make install
 107
 108   The above command will install the Open vSwitch executables in
 109   C:/openvswitch.  You can add 'C:\openvswitch\usr\bin' and
 110   'C:\openvswitch\usr\sbin' to Windows' PATH environment variable
 111   for easy access.
 112
 113 OpenSSL, Open vSwitch and Visual C++
 114 ------------------------------------
 115 To get SSL support for Open vSwitch on Windows, do the following:
 116
 117 * Install OpenSSL for Windows as suggested at
 118 http://www.openssl.org/related/binaries.html.
 119 The link as of this writing suggests to download it from
 120 http://slproweb.com/products/Win32OpenSSL.html
 121
 122 Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
 123
 124 * While configuring the package, specify the OpenSSL directory path.
 125 For example,
 126
 127     % ./configure CC=./build-aux/cccl LD="`which link`"  \
 128     LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
 129     --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \
 130     --with-pthread="C:/pthread" --enable-ssl --with-openssl="C:/OpenSSL-Win32"
 131
 132 * Run make for the ported executables.
 133
 134 Building the Kernel datapath module
 135 -----------------------------------
 136 * We directly use the Visual Studio 2013 IDE to compile the kernel datapath.
 137 You can open the extensions.sln file in the IDE and build the solution.
 138
 139 * The kernel datapath can be compiled from command line as well.  The top
 140 level 'make' will invoke building the kernel datapath, if the
 141 '--with-vstudiotarget' argument is specified while configuring the package.
 142 For example,
 143
 144     % ./configure CC=./build-aux/cccl LD="`which link`" \
 145     LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
 146     --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \
 147     --with-pthread="C:/pthread" --enable-ssl \
 148     --with-openssl="C:/OpenSSL-Win32" --with-vstudiotarget="<target type>"
 149
 150     Possible values for "<target type>" are:
 151     "Debug" and "Release"
 152
 153 Installing the Kernel module
 154 ----------------------------
 155 Once you have built the solution, you can copy the following files to the
 156 target Hyper-V machines.
 157
 158     ./datapath-windows/x64/Win8.1Debug/package/ovsext.inf
 159     ./datapath-windows/x64/Win8.1Debug/package/OVSExt.sys
 160     ./datapath-windows/x64/Win8.1Debug/package/ovsext.cat
 161     ./datapath-windows/misc/install.cmd
 162     ./datapath-windows/misc/uninstall.cmd
 163
 164 The above path assumes that the kernel module has been built using Windows
 165 DDK 8.1 in Debug mode. Change the path appropriately, if a different WDK
 166 has been used.
 167
 168 Steps to install the module
 169 ---------------------------
 170
 171 01> Run ./uninstall.cmd to remove the old extension.
 172
 173 02> Run ./install.cmd to insert the new one.  For this to work you will have to
 174 turn on TESTSIGNING boot option or 'Disable Driver Signature Enforcement'
 175 during boot.  The following commands can be used:
 176     % bcdedit /set LOADOPTIONS DISABLE_INTEGRITY_CHECKS
 177     % bcdedit /set TESTSIGNING ON
 178     % bcdedit /set nointegritychecks ON
 179
 180 Note: you may have to restart the machine for the settings to take effect.
 181
 182 03> In the Virtual Switch Manager configuration you can enable the Open vSwitch
 183 Extension on an existing switch or create a new switch.  If you are using an
 184 existing switch, make sure to enable the "Allow Management OS" option for VXLAN
 185 to work (covered later).
 186
 187 The command to create a new switch named 'OVS-Extended-Switch' using a physical
 188 NIC named 'Ethernet 1' is:
 189     % New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
 190                    -NetAdapterName "Ethernet 1"
 191
 192 Note: you can obtain the list of physical NICs on the host using
 193 'Get-NetAdapter' command.
 194
 195 04> In the properties of any switch, you should should now see "Open
 196 vSwitch Extension" under 'Extensions'.  Click the check box to enable the
 197 extension.  An alternative way to do the same is to run the following command:
 198     % Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch
 199
 200 Note: If you enabled the extension using the command line, a delay of a few
 201 seconds has been observed for the change to be reflected in the UI.  This is
 202 not a bug in Open vSwitch.
 203
 204 Steps to run the user processes & configure ports
 205 -------------------------------------------------
 206 The following steps assume that you have installed the Open vSwitch
 207 utilities in the local machine via 'make install'.
 208
 209 01> Create the database.
 210     % ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \
 211         C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema
 212
 213 02> Start the ovsdb-server and initialize the database.
 214     % ovsdb-server -vfile:info --remote=punix:db.sock --log-file --pidfile \
 215         --detach
 216     % ovs-vsctl --no-wait init
 217
 218     If you would like to terminate the started ovsdb-server, run:
 219     % ovs-appctl -t ovsdb-server exit
 220
 221     (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
 222
 223 03> Start ovs-vswitchd.
 224     % ovs-vswitchd -vfile:info --log-file --pidfile --detach
 225
 226     If you would like to terminate the started ovs-vswitchd, run:
 227     % ovs-appctl exit
 228
 229     (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
 230
 231 04> Create integration bridge & pif bridge
 232     % ovs-vsctl add-br br-int
 233     % ovs-vsctl add-br br-pif
 234
 235 NOTE: There's a known bug that running the ovs-vsctl command does not
 236 terminate.  This is generally solved by having ovs-vswitchd running.  If
 237 you face the issue despite that, hit Ctrl-C to terminate ovs-vsctl and
 238 check the output to see if your command succeeded.
 239
 240 NOTE: There's a known bug that the ports added to OVSDB via ovs-vsctl don't
 241 get to the kernel datapath immediately, ie. they don't show up in the output of
 242 "ovs-dpctl show" even though they show up in output of "ovs-vsctl show".
 243 In order to workaround this issue, restart ovs-vswitchd. (You can terminate
 244 ovs-vswitchd by running 'ovs-appctl exit'.)
 245
 246 05> Dump the ports in the kernel datapath
 247     % ovs-dpctl show
 248
 249 * Sample output is as follows:
 250
 251     % ovs-dpctl show
 252     system@ovs-system:
 253             lookups: hit:0 missed:0 lost:0
 254             flows: 0
 255             port 2: br-pif (internal)     <<< internal port on 'br-pif' bridge
 256             port 1: br-int (internal)     <<< internal port on 'br-int' bridge
 257
 258 06> Dump the ports in the OVSDB
 259     % ovs-vsctl show
 260
 261 * Sample output is as follows:
 262     % ovs-vsctl show
 263     a56ec7b5-5b1f-49ec-a795-79f6eb63228b
 264         Bridge br-pif
 265             Port br-pif
 266                 Interface br-pif
 267                     type: internal
 268         Bridge br-int
 269             Port br-int
 270                 Interface br-int
 271                     type: internal
 272
 273 07> Add the physical NIC and the internal port to br-pif.
 274
 275 In OVS for Hyper-V, we use the name of the adapter on top of which the Hyper-V
 276 virtual switch was created, as a special name to refer to the physical NICs
 277 connected to the Hyper-V switch. I.e. let us suppose we created the Hyper-V
 278 virtual switch on top of the adapter named 'Ethernet0'. In OVS for Hyper-V, we
 279 use that name('Ethernet0') as a special name to refer to that adapter.
 280
 281 Note: Currently, we assume that the Hyper-V switch on which OVS extension is
 282 enabled has a single physical NIC connected to it.
 283
 284 Internal port is the virtual adapter created on the Hyper-V switch using the
 285 'AllowManagementOS' setting.  This has already been setup while creating the
 286 switch using the instructions above.  In OVS for Hyper-V, we use a the name of
 287 that specific adapter as a special name to refer to that adapter. By default it
 288 is created under the following rule "vEthernet (<name of the switch>)".
 289
 290 As a whole example, if we issue the following in a powershell console:
 291 PS C:\package\binaries> Get-NetAdapter | select Name,MacAddress,InterfaceDescription
 292
 293 Name                   MacAddress         InterfaceDescription
 294 ----                   ----------         --------------------
 295 Ethernet1              00-0C-29-94-05-65  Intel(R) PRO/1000 MT Network Connection
 296 vEthernet (external)   00-0C-29-94-05-5B  Hyper-V Virtual Ethernet Adapter #2
 297 Ethernet0              00-0C-29-94-05-5B  Intel(R) PRO/1000 MT Network Connection #2
 298
 299 PS C:\package\binaries> Get-VMSwitch
 300
 301 Name     SwitchType NetAdapterInterfaceDescription
 302 ----     ---------- ------------------------------
 303 external External   Intel(R) PRO/1000 MT Network Connection #2
 304
 305
 306 We can see that we have a switch(external) created upon adapter name 'Ethernet0'
 307 with an internal port under name 'vEthernet (external)'. Thus resulting into the
 308 following ovs-vsctl commands
 309
 310     % ovs-vsctl add-port br-pif Ethernet0
 311     % ovs-vsctl add-port br-pif "vEthernet (external)"
 312
 313 * Dumping the ports should show the additional ports that were just added.
 314   Sample output shows up as follows:
 315
 316     % ovs-dpctl show
 317     system@ovs-system:
 318             lookups: hit:0 missed:0 lost:0
 319             flows: 0
 320             port 4: vEthernet (external) (internal) <<< 'AllowManagementOS'
 321                                                          adapter on
 322                                                          Hyper-V switch
 323             port 2: br-pif (internal)
 324             port 1: br-int (internal)
 325             port 3: Ethernet0                       <<< Physical NIC
 326
 327     % ovs-vsctl show
 328     a56ec7b5-5b1f-49ec-a795-79f6eb63228b
 329         Bridge br-pif
 330             Port "vEthernet (external)"
 331                 Interface "vEthernet (external)"
 332             Port br-pif
 333                 Interface br-pif
 334                     type: internal
 335             Port "Ethernet0"
 336                 Interface "Ethernet0"
 337         Bridge br-int
 338             Port br-int
 339                 Interface br-int
 340                     type: internal
 341
 342 08> Add the VIFs to br-int
 343
 344 Adding VIFs to openvswitch is a two step procedure.  The first step is to
 345 assign a 'OVS port name' which is a unique name across all VIFs on this
 346 Hyper-V.  The next step is to add the VIF to the ovsdb using its 'OVS port
 347 name' as key.
 348
 349 08a> Assign a unique 'OVS port name' to the VIF
 350
 351 Note that the VIF needs to have been disconnected from the Hyper-V switch
 352 before assigning a 'OVS port name' to it.  In the example below, we assign a
 353 'OVS port name' called 'ovs-port-a' to a VIF on a VM by name 'VM1'.  By using
 354 index 0 for '$vnic', the first VIF of the VM is being addressed.  After
 355 assigning the name 'ovs-port-a', the VIF is connected back to the Hyper-V
 356 switch with name 'OVS-HV-Switch', which is assumed to be the Hyper-V switch
 357 with OVS extension enabled.
 358
 359     Eg:
 360     % import-module .\datapath-windows\misc\OVS.psm1
 361     % $vnic = Get-VMNetworkAdapter <Name of the VM>
 362     % Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0]
 363     % $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a
 364     % Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \
 365                                -SwitchName OVS-Extended-Switch
 366
 367 08b> Add the VIFs to br-int in ovsdb
 368
 369     Eg:
 370     % ovs-vsctl add-port br-int ovs-port-a
 371
 372 09> Verify the status
 373     % ovs-dpctl show
 374     system@ovs-system:
 375             lookups: hit:0 missed:0 lost:0
 376             flows: 0
 377             port 4: vEthernet (external) (internal)
 378             port 5: ovs-port-a
 379             port 2: br-pif (internal)
 380             port 1: br-int (internal
 381             port 3: Ethernet0
 382
 383     % ovs-vsctl show
 384     4cd86499-74df-48bd-a64d-8d115b12a9f2
 385         Bridge br-pif
 386             Port "vEthernet (external)"
 387                 Interface "vEthernet (external)"
 388             Port "Ethernet0"
 389                 Interface "Ethernet0"
 390             Port br-pif
 391                 Interface br-pif
 392                     type: internal
 393         Bridge br-int
 394             Port br-int
 395                 Interface br-int
 396                     type: internal
 397             Port "ovs-port-a"
 398                 Interface "ovs-port-a"
 399
 400 Steps to configure patch ports and switch VLAN tagging
 401 ------------------------------------------------------
 402 The Windows Open vSwitch implementation support VLAN tagging in the switch.
 403 Switch VLAN tagging along with patch ports between 'br-int' and 'br-pif' is
 404 used to configure VLAN tagging functionality between two VMs on different
 405 Hyper-Vs.  The following examples demonstrate how it can be done:
 406
 407 01> Add a patch port from br-int to br-pif
 408     % ovs-vsctl add-port br-int patch-to-pif
 409     % ovs-vsctl set interface patch-to-pif type=patch \
 410                                  options:peer=patch-to-int
 411
 412 02> Add a patch port from br-pif to br-int
 413     % ovs-vsctl add-port br-pif patch-to-int
 414     % ovs-vsctl set interface patch-to-int type=patch \
 415                                  options:peer=patch-to-pif
 416
 417 03> Re-Add the VIF ports with the VLAN tag
 418     % ovs-vsctl add-port br-int ovs-port-a tag=900
 419     % ovs-vsctl add-port br-int ovs-port-b tag=900
 420
 421 Steps to add tunnels
 422 --------------------------
 423 The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add
 424 tunnels, the following steps serve as examples.
 425
 426 Note that, any patch ports created between br-int and br-pif MUST be beleted
 427 prior to adding tunnels.
 428
 429 01> Add the tunnel port between 172.168.201.101 <-> 172.168.201.102
 430     % ovs-vsctl add-port br-int tun-1
 431     % ovs-vsctl set Interface tun-1 type=port-type
 432     % ovs-vsctl set Interface tun-1 options:local_ip=172.168.201.101
 433     % ovs-vsctl set Interface tun-1 options:remote_ip=172.168.201.102
 434     % ovs-vsctl set Interface tun-1 options:in_key=flow
 435     % ovs-vsctl set Interface tun-1 options:out_key=flow
 436
 437 02> Add the tunnel port between 172.168.201.101 <-> 172.168.201.105
 438     % ovs-vsctl add-port br-int tun-2
 439     % ovs-vsctl set Interface tun-2 type=port-type
 440     % ovs-vsctl set Interface tun-2 options:local_ip=172.168.201.102
 441     % ovs-vsctl set Interface tun-2 options:remote_ip=172.168.201.105
 442     % ovs-vsctl set Interface tun-2 options:in_key=flow
 443     % ovs-vsctl set Interface tun-2 options:out_key=flow
 444
 445     Where port-type is the string stt or vxlan
 446
 447
 448 Requirements
 449 ------------
 450 * We require that you don't disable the "Allow management operating system to
 451 share this network adapter" under 'Virtual Switch Properties' > 'Connection
 452 type: External network', in the HyperV virtual network switch configuration.
 453
 454 * Checksum Offloads
 455     While there is some support for checksum/segmentation offloads in software,
 456 this is still a work in progress. Till the support is complete we recommend
 457 disabling TX/RX offloads for both the VM's as well as the HyperV.
 458
 459 Windows Services
 460 ----------------
 461 Open vSwitch daemons come with support to run as a Windows service. The
 462 instructions here assume that you have installed the Open vSwitch utilities
 463 and daemons via 'make install'. The commands shown here can be run from
 464 MSYS bash or Windows command prompt.
 465
 466 * Create the database.
 467
 468   % ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \
 469         "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema"
 470
 471 * Create the ovsdb-server service and start it.
 472
 473   % 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"
 474
 475   One of the common issues with creating a Windows service is with mungled
 476   paths. You can make sure that the correct path has been registered with
 477   the Windows services manager by running:
 478
 479   % sc qc ovsdb-server
 480
 481   Start the service.
 482
 483   % sc start ovsdb-server
 484
 485   Check that the service is healthy by running:
 486
 487   % sc query ovsdb-server
 488
 489 * Initialize the database.
 490
 491   % ovs-vsctl --no-wait init
 492
 493 * Create the ovs-vswitchd service and start it.
 494
 495   % sc create ovs-vswitchd binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe --pidfile -vfile:info --log-file  --service --service-monitor"
 496
 497   % sc start ovs-vswitchd
 498
 499   Check that the service is healthy by running:
 500
 501   % sc query ovs-vswitchd
 502
 503 * To stop and delete the services, run:
 504
 505   % sc stop ovs-vswitchd
 506   % sc stop ovsdb-server
 507   % sc delete ovs-vswitchd
 508   % sc delete ovsdb-server
 509
 510 Windows autobuild service
 511 -------------------------
 512 AppVeyor (appveyor.com) provides a free Windows autobuild service for
 513 opensource projects.  Open vSwitch has integration with AppVeyor for
 514 continuous build.  A developer can build test his changes for Windows by
 515 logging into appveyor.com using a github account, creating a new project
 516 by linking it to his development repository in github and triggering
 517 a new build.
 518
 519 TODO
 520 ----
 521
 522 * Investigate the working of sFlow on Windows and re-enable the unit tests.
 523
 524 * Investigate and add the feature to provide QOS.
 525
 526 * Sign the driver & create an MSI for installing the different OpenvSwitch
 527 components on windows.