1 How to Build the Kernel module & userspace daemons for Windows
2 ==============================================================
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
12 The following explains the steps in some detail.
14 * Install Mingw on a Windows machine by following the instructions at:
15 http://www.mingw.org/wiki/Getting_Started
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
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).
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'.
28 * Install the latest Python 2.x from python.org and verify that its path is
29 part of Windows' PATH environment variable.
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.
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
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.
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
55 * For pthread support, install the library, dll and includes of pthreads-win32
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.
61 * Get the Open vSwitch sources from either cloning the repo using git
62 or from a distribution tar ball.
64 * If you pulled the sources directly from an Open vSwitch Git tree,
65 run boot.sh in the top source directory:
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,
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"
79 By default, the above enables compiler optimization for fast code.
80 For default compiler optimization, pass the "--with-debug" configure
83 * Run make for the ported executables in the top source directory, e.g.:
87 For faster compilation, you can pass the '-j' argument to make. For
88 example, to run 4 jobs simultaneously, run 'make -j4'.
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
96 * To run all the unit tests in Open vSwitch, one at a time:
100 To run all the unit tests in Open vSwitch, up to 8 in parallel:
102 % make check TESTSUITEFLAGS="-j8"
104 * To install all the compiled executables on the local machine, run:
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
113 OpenSSL, Open vSwitch and Visual C++
114 ------------------------------------
115 To get SSL support for Open vSwitch on Windows, do the following:
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
122 Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
124 * While configuring the package, specify the OpenSSL directory path.
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"
132 * Run make for the ported executables.
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.
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.
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>"
150 Possible values for "<target type>" are:
151 "Debug" and "Release"
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.
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
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
168 Steps to install the module
169 ---------------------------
171 01> Run ./uninstall.cmd to remove the old extension.
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
180 Note: you may have to restart the machine for the settings to take effect.
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).
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"
192 Note: you can obtain the list of physical NICs on the host using
193 'Get-NetAdapter' command.
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
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.
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'.
209 01> Create the database.
210 % ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \
211 C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema
213 02> Start the ovsdb-server and initialize the database.
214 % ovsdb-server -vfile:info --remote=punix:db.sock --log-file --pidfile \
216 % ovs-vsctl --no-wait init
218 If you would like to terminate the started ovsdb-server, run:
219 % ovs-appctl -t ovsdb-server exit
221 (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
223 03> Start ovs-vswitchd.
224 % ovs-vswitchd -vfile:info --log-file --pidfile --detach
226 If you would like to terminate the started ovs-vswitchd, run:
229 (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
231 04> Create integration bridge & pif bridge
232 % ovs-vsctl add-br br-int
233 % ovs-vsctl add-br br-pif
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.
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'.)
246 05> Dump the ports in the kernel datapath
249 * Sample output is as follows:
253 lookups: hit:0 missed:0 lost: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
258 06> Dump the ports in the OVSDB
261 * Sample output is as follows:
263 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
273 07> Add the physical NIC and the internal port to br-pif.
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.
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.
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>)".
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
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
299 PS C:\package\binaries> Get-VMSwitch
301 Name SwitchType NetAdapterInterfaceDescription
302 ---- ---------- ------------------------------
303 external External Intel(R) PRO/1000 MT Network Connection #2
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
310 % ovs-vsctl add-port br-pif Ethernet0
311 % ovs-vsctl add-port br-pif "vEthernet (external)"
313 * Dumping the ports should show the additional ports that were just added.
314 Sample output shows up as follows:
318 lookups: hit:0 missed:0 lost:0
320 port 4: vEthernet (external) (internal) <<< 'AllowManagementOS'
323 port 2: br-pif (internal)
324 port 1: br-int (internal)
325 port 3: Ethernet0 <<< Physical NIC
328 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
330 Port "vEthernet (external)"
331 Interface "vEthernet (external)"
336 Interface "Ethernet0"
342 08> Add the VIFs to br-int
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
349 08a> Assign a unique 'OVS port name' to the VIF
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.
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
367 08b> Add the VIFs to br-int in ovsdb
370 % ovs-vsctl add-port br-int ovs-port-a
372 09> Verify the status
375 lookups: hit:0 missed:0 lost:0
377 port 4: vEthernet (external) (internal)
379 port 2: br-pif (internal)
380 port 1: br-int (internal
384 4cd86499-74df-48bd-a64d-8d115b12a9f2
386 Port "vEthernet (external)"
387 Interface "vEthernet (external)"
389 Interface "Ethernet0"
398 Interface "ovs-port-a"
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:
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
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
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
422 --------------------------
423 The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add
424 tunnels, the following steps serve as examples.
426 Note that, any patch ports created between br-int and br-pif MUST be beleted
427 prior to adding tunnels.
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
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
445 Where port-type is the string stt or vxlan
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.
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.
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.
466 * Create the database.
468 % ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \
469 "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema"
471 * Create the ovsdb-server service and start it.
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"
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:
483 % sc start ovsdb-server
485 Check that the service is healthy by running:
487 % sc query ovsdb-server
489 * Initialize the database.
491 % ovs-vsctl --no-wait init
493 * Create the ovs-vswitchd service and start it.
495 % sc create ovs-vswitchd binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe --pidfile -vfile:info --log-file --service --service-monitor"
497 % sc start ovs-vswitchd
499 Check that the service is healthy by running:
501 % sc query ovs-vswitchd
503 * To stop and delete the services, run:
505 % sc stop ovs-vswitchd
506 % sc stop ovsdb-server
507 % sc delete ovs-vswitchd
508 % sc delete ovsdb-server
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
522 * Investigate the working of sFlow on Windows and re-enable the unit tests.
524 * Investigate and add the feature to provide QOS.
526 * Sign the driver & create an MSI for installing the different OpenvSwitch
527 components on windows.