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