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.
  39
  40 If after the above step, a 'which link' inside MSYS's bash says,
  41 "/bin/link.exe", rename /bin/link.exe to something else so that the
  42 Visual studio's linker is used.
  43
  44 * For pthread support, install the library, dll and includes of pthreads-win32
  45 project from
  46 ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release to a
  47 directory (e.g.: C:/pthread).
  48
  49 * Get the Open vSwitch sources from either cloning the repo using git
  50 or from a distribution tar ball.
  51
  52 * If you pulled the sources directly from an Open vSwitch Git tree,
  53   run boot.sh in the top source directory:
  54
  55     % ./boot.sh
  56
  57 * In the top source directory, configure the package by running the
  58   configure script.  You should provide some configure options to choose
  59   the right compiler, linker, libraries, Open vSwitch component installation
  60   directories, etc. For example,
  61
  62     % ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
  63       --prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
  64       --sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread"
  65
  66     By default, the above enables compiler optimization for fast code.
  67     For default compiler optimization, pass the "--with-debug" configure
  68     option.
  69
  70 * Run make for the ported executables in the top source directory, e.g.:
  71
  72     % make
  73
  74 * To run all the unit tests:
  75
  76     % make check
  77
  78 OpenSSL, Open vSwitch and Visual C++
  79 ------------------------------------
  80 To get SSL support for Open vSwitch on Windows, do the following:
  81
  82 * Install OpenSSL for Windows as suggested at
  83 http://www.openssl.org/related/binaries.html.
  84 The link as of this writing suggests to download it from
  85 http://slproweb.com/products/Win32OpenSSL.html and the latest version is
  86 "Win32 OpenSSL v1.0.1j".
  87
  88 Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
  89
  90 * While configuring the package, specify the OpenSSL directory path.
  91 For example,
  92
  93     % ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
  94     --prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
  95     --sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread" \
  96     --enable-ssl --with-openssl="C:/OpenSSL-Win32"
  97
  98 * Run make for the ported executables.
  99
 100 Building the Kernel module
 101 --------------------------
 102 We directly use the Visual Studio 2013 IDE to compile the kernel module. You can
 103 open the extensions.sln file in the IDE and build the solution.
 104
 105 Installing the Kernel module
 106 ----------------------------
 107 Once you have built the solution, you can copy the following files to the
 108 target Hyper-V machines:
 109
 110     ./datapath-windows/x64/Win8.1Debug/package/ovsext.inf
 111     ./datapath-windows/x64/Win8.1Debug/package/OVSExt.sys
 112     ./datapath-windows/x64/Win8.1Debug/package/ovsext.cat
 113     ./datapath-windows/misc/install.cmd
 114     ./datapath-windows/misc/uninstall.cmd
 115
 116 Steps to install the module
 117 ---------------------------
 118
 119 01> Run ./uninstall.cmd to remove the old extension.
 120 02> Run ./install.cmd to insert the new one. For this to work you will have to
 121 turn on TESTSIGNING boot option or 'Disable Driver Signature Enforcement'
 122 during boot.
 123 03> In the Virtual Switch Manager configuration you should now see "VMWare OVS
 124 Extension" under 'Virtual Switch Extensions'. Click the check box to enable the
 125 extension.
 126
 127 Steps to run the user processes & configure VXLAN ports
 128 -------------------------------------------------------
 129
 130 01> Create the conf db file.
 131 ovsdb\ovsdb-tool.exe create conf.db .\vswitchd\vswitch.ovsschema
 132
 133 02> Run ovsdb-server
 134 ovsdb\ovsdb-server.exe -v --remote=ptcp:6632:127.0.0.1 conf.db
 135
 136 03> Create integration bridge & pif bridge
 137 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-br br-int
 138 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-br br-pif
 139
 140 04> Dump the ports
 141 utilities\ovs-dpctl.exe show
 142
 143 * Sample output shows up like this. Currently it is not possible to figure out
 144 * the mapping between VIF and VM from the output.
 145
 146 $ utilities\ovs-dpctl.exe show
 147 2014-06-27T01:55:32Z|00001|socket_util|ERR|4789:0.0.0.0:
 148 socket: Either the application has not called WSAStartup, or WSAStartup failed.
 149                                         <<< Ignore this error, it is harmless.
 150 system@ovs-system:
 151         lookups: hit:0 missed:0 lost:0
 152         flows: 0
 153         masks: hit:0 total:0 hit/pkt:0.00
 154         port 16777216: internal            <<< VTEP created by AllowManagementOS
 155                                                setting
 156         port 16777225: external.1          <<< Physical NIC
 157         port 16777288: vmNICEmu.1000048    <<< VIF #1
 158         port 16777289: vmNICSyn.1000049    <<< VIF #2
 159
 160
 161 05> Add the physical NIC and the internal port to br-pif
 162 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-pif <port name>
 163
 164 Eg:
 165 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-pif external.1
 166 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-pif internal
 167
 168 06> Add the VIFs to br-int
 169 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-int <port name>
 170
 171 Eg:
 172 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-int vmNICEmu.1000048
 173 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-int vmNICSyn.1000049
 174
 175 07> Verify the status
 176 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 show
 177
 178 Eg:
 179 $ utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 show
 180 4cd86499-74df-48bd-a64d-8d115b12a9f2
 181     Bridge br-pif
 182         Port internal
 183             Interface internal
 184         Port "external.1"
 185             Interface "external.1"
 186         Port br-pif
 187             Interface br-pif
 188                 type: internal
 189     Bridge br-int
 190         Port br-int
 191             Interface br-int
 192                 type: internal
 193         Port "vmNICEmu.1000048"
 194             Interface "vmNICEmu.1000048"
 195         Port "vmNICSyn.1000049"
 196             Interface "vmNICSyn.1000049"
 197
 198
 199 09> Run vswitchd
 200 vswitchd\ovs-vswitchd.exe -v tcp:127.0.0.1:6632
 201
 202 10> You can figure out the port name to MAC address mapping now. (optional)
 203 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 list interface
 204
 205 //********** VXLAN PORT CONFIGURATION (Supports Multiple ports) ************//
 206 (Remove all patch ports added to create VLAN networks.)
 207 11> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
 208 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-int vxlan-1
 209 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-1 type=vxlan
 210 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-1 options:local_ip=172.168.201.101
 211 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-1 options:remote_ip=172.168.201.102
 212 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-1 options:in_key=flow
 213 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-1 options:out_key=flow
 214
 215 12> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
 216 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 add-port br-int vxlan-2
 217 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-2 type=vxlan
 218 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-2 options:local_ip=172.168.201.102
 219 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-2 options:remote_ip=172.168.201.105
 220 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-2 options:in_key=flow
 221 utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6632 set Interface vxlan-2 options:out_key=flow
 222
 223
 224 //********** VLAN CONFIGURATION (Using patch ports) ************//
 225 (Remove all VXLAN ports from the configuration.)
 226 13> Add a patch port from br-int to br-pif
 227 utilities/ovs-vsctl.exe -- add-port br-int patch-to-pif
 228 utilities/ovs-vsctl.exe -- set interface patch-to-pif type=patch options:peer=patch-to-int
 229
 230 14> Add a patch port from br-pif to br-int
 231 utilities/ovs-vsctl.exe -- add-port br-pif patch-to-int
 232 utilities/ovs-vsctl.exe -- set interface patch-to-int type=patch options:peer=patch-to-pif
 233
 234 15> Re-Add the VIF ports with the VLAN tag
 235 utilities\ovs-vsctl.exe add-port br-int vmNICEmu.1000048 tag=900
 236 utilities\ovs-vsctl.exe add-port br-int vmNICSyn.1000049 tag=900
 237
 238
 239 Requirements
 240 ------------
 241
 242 * We require that you don't disable the "Allow management operating system to
 243 share this network adapter" under 'Virtual Switch Properties' > 'Connection
 244 type: External network', in the HyperV virtual network switch configuration.
 245
 246 * Checksum Offloads
 247     While there is some support for checksum/segmentation offloads in software,
 248 this is still a work in progress. Till the support is complete we recommend
 249 disabling TX/RX offloads for both the VM's as well as the HyperV.
 250
 251
 252 TODO
 253 ----
 254
 255 * Investigate the working of sFlow on Windows and re-enable the unit tests.
 256
 257 * Investigate and add the feature to provide QOS.
 258
 259 * Sign the driver & create an MSI for installing the different OpenvSwitch
 260 components on windows.