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 02> Run ./install.cmd to insert the new one. For this to work you will have to
 140 turn on TESTSIGNING boot option or 'Disable Driver Signature Enforcement'
 141 during boot.
 142 03> In the Virtual Switch Manager configuration you should now see "VMWare OVS
 143 Extension" under 'Virtual Switch Extensions'. Click the check box to enable the
 144 extension.
 145
 146 Steps to run the user processes & configure VXLAN ports
 147 -------------------------------------------------------
 148
 149 01> Create the conf db file.
 150 ovsdb\ovsdb-tool.exe create conf.db .\vswitchd\vswitch.ovsschema
 151
 152 02> Run ovsdb-server
 153 ovsdb\ovsdb-server.exe -v --remote=ptcp:6640:127.0.0.1 conf.db
 154
 155 03> Create integration bridge & pif bridge
 156 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-br br-int
 157 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-br br-pif
 158
 159 04> Dump the ports
 160 utilities\ovs-dpctl.exe show
 161
 162 * Sample output shows up like this. Currently it is not possible to figure out
 163 * the mapping between VIF and VM from the output.
 164
 165 $ utilities\ovs-dpctl.exe show
 166 2014-06-27T01:55:32Z|00001|socket_util|ERR|4789:0.0.0.0:
 167 socket: Either the application has not called WSAStartup, or WSAStartup failed.
 168                                         <<< Ignore this error, it is harmless.
 169 system@ovs-system:
 170         lookups: hit:0 missed:0 lost:0
 171         flows: 0
 172         masks: hit:0 total:0 hit/pkt:0.00
 173         port 16777216: internal            <<< VTEP created by AllowManagementOS
 174                                                setting
 175         port 16777225: external.1          <<< Physical NIC
 176         port 16777288: vmNICEmu.1000048    <<< VIF #1
 177         port 16777289: vmNICSyn.1000049    <<< VIF #2
 178
 179
 180 05> Add the physical NIC and the internal port to br-pif
 181 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif <port name>
 182
 183 Eg:
 184 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif external.1
 185 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif internal
 186
 187 06> Add the VIFs to br-int
 188 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int <port name>
 189
 190 Eg:
 191 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vmNICEmu.1000048
 192 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vmNICSyn.1000049
 193
 194 07> Verify the status
 195 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 show
 196
 197 Eg:
 198 $ utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 show
 199 4cd86499-74df-48bd-a64d-8d115b12a9f2
 200     Bridge br-pif
 201         Port internal
 202             Interface internal
 203         Port "external.1"
 204             Interface "external.1"
 205         Port br-pif
 206             Interface br-pif
 207                 type: internal
 208     Bridge br-int
 209         Port br-int
 210             Interface br-int
 211                 type: internal
 212         Port "vmNICEmu.1000048"
 213             Interface "vmNICEmu.1000048"
 214         Port "vmNICSyn.1000049"
 215             Interface "vmNICSyn.1000049"
 216
 217
 218 09> Run vswitchd
 219 vswitchd\ovs-vswitchd.exe -v tcp:127.0.0.1:6640
 220
 221 10> You can figure out the port name to MAC address mapping now. (optional)
 222 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 list interface
 223
 224 //********** VXLAN PORT CONFIGURATION (Supports Multiple ports) ************//
 225 (Remove all patch ports added to create VLAN networks.)
 226 11> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
 227 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vxlan-1
 228 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 type=vxlan
 229 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:local_ip=172.168.201.101
 230 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:remote_ip=172.168.201.102
 231 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:in_key=flow
 232 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:out_key=flow
 233
 234 12> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
 235 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vxlan-2
 236 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 type=vxlan
 237 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:local_ip=172.168.201.102
 238 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:remote_ip=172.168.201.105
 239 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:in_key=flow
 240 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:out_key=flow
 241
 242
 243 //********** VLAN CONFIGURATION (Using patch ports) ************//
 244 (Remove all VXLAN ports from the configuration.)
 245 13> Add a patch port from br-int to br-pif
 246 utilities/ovs-vsctl.exe -- add-port br-int patch-to-pif
 247 utilities/ovs-vsctl.exe -- set interface patch-to-pif type=patch options:peer=patch-to-int
 248
 249 14> Add a patch port from br-pif to br-int
 250 utilities/ovs-vsctl.exe -- add-port br-pif patch-to-int
 251 utilities/ovs-vsctl.exe -- set interface patch-to-int type=patch options:peer=patch-to-pif
 252
 253 15> Re-Add the VIF ports with the VLAN tag
 254 utilities\ovs-vsctl.exe add-port br-int vmNICEmu.1000048 tag=900
 255 utilities\ovs-vsctl.exe add-port br-int vmNICSyn.1000049 tag=900
 256
 257
 258 Requirements
 259 ------------
 260
 261 * We require that you don't disable the "Allow management operating system to
 262 share this network adapter" under 'Virtual Switch Properties' > 'Connection
 263 type: External network', in the HyperV virtual network switch configuration.
 264
 265 * Checksum Offloads
 266     While there is some support for checksum/segmentation offloads in software,
 267 this is still a work in progress. Till the support is complete we recommend
 268 disabling TX/RX offloads for both the VM's as well as the HyperV.
 269
 270 Windows autobuild service
 271 -------------------------
 272
 273 AppVeyor (appveyor.com) provides a free Windows autobuild service for
 274 opensource projects.  Open vSwitch has integration with AppVeyor for
 275 continuous build.  A developer can build test his changes for Windows by
 276 logging into appveyor.com using a github account, creating a new project
 277 by linking it to his development repository in github and triggering
 278 a new build.
 279
 280 TODO
 281 ----
 282
 283 * Investigate the working of sFlow on Windows and re-enable the unit tests.
 284
 285 * Investigate and add the feature to provide QOS.
 286
 287 * Sign the driver & create an MSI for installing the different OpenvSwitch
 288 components on windows.