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