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 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.
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
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
46 * For pthread support, install the library, dll and includes of pthreads-win32
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.
52 * Get the Open vSwitch sources from either cloning the repo using git
53 or from a distribution tar ball.
55 * If you pulled the sources directly from an Open vSwitch Git tree,
56 run boot.sh in the top source directory:
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,
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"
69 By default, the above enables compiler optimization for fast code.
70 For default compiler optimization, pass the "--with-debug" configure
73 * Run make for the ported executables in the top source directory, e.g.:
77 For faster compilation, you can pass the '-j' argument to make. For
78 example, to run 4 jobs simultaneously, run 'make -j4'.
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
86 * To run all the unit tests in Open vSwitch, one at a time:
90 To run all the unit tests in Open vSwitch, up to 8 in parallel:
92 % make check TESTSUITEFLAGS="-j8"
94 * To install all the compiled executables on the local machine, run:
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
103 OpenSSL, Open vSwitch and Visual C++
104 ------------------------------------
105 To get SSL support for Open vSwitch on Windows, do the following:
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
112 Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
114 * While configuring the package, specify the OpenSSL directory path.
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"
122 * Run make for the ported executables.
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.
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.
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>"
140 Possible values for "<WDK to use>" are:
141 "Win8.1 Debug", "Win8.1 Release", "Win8 Debug" and "Win8 Release".
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.
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
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
158 Steps to install the module
159 ---------------------------
161 01> Run ./uninstall.cmd to remove the old extension.
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'
167 03> In the Virtual Switch Manager configuration you can enable the Open vSwitch
168 Extension on an existing switch or create a new switch. If you are using an
169 existing switch, make sure to enable the "Allow Management OS" option for VXLAN
170 to work (covered later).
172 The command to create a new switch named 'OVS-Extended-Switch' using a physical
173 NIC named 'Ethernet 1' is:
174 % New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
175 -NetAdapterName "Ethernet 1"
177 Note: you can obtain the list of physical NICs on the host using
178 'Get-NetAdapter' command.
180 04> In the properties of any switch, you should should now see "Open
181 vSwitch Extension" under 'Extensions'. Click the check box to enable the
182 extension. An alternative way to do the same is to run the following command:
183 % Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch
185 Note: If you enabled the extension using the command line, a delay of a few
186 seconds has been observed for the change to be reflected in the UI. This is
187 not a bug in Open vSwitch.
189 Steps to run the user processes & configure ports
190 -------------------------------------------------
191 The following steps assume that you have installed the Open vSwitch
192 utilities in the local machine via 'make install'.
194 01> Create the database.
195 % ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \
196 C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema
198 02> Start the ovsdb-server and initialize the database.
199 % ovsdb-server -vfile:info --remote=punix:db.sock --log-file --pidfile \
201 % ovs-vsctl --no-wait init
203 If you would like to terminate the started ovsdb-server, run:
204 % ovs-appctl -t ovsdb-server exit
206 (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
208 03> Start ovs-vswitchd.
209 % ovs-vswitchd -vfile:info --log-file --pidfile --detach
211 If you would like to terminate the started ovs-vswitchd, run:
214 (Note that the logfile is created at C:/openvswitch/var/log/openvswitch/)
216 04> Create integration bridge & pif bridge
217 % ovs-vsctl add-br br-int
218 % ovs-vsctl add-br br-pif
220 NOTE: There's a known bug that running the ovs-vsctl command does not
221 terminate. This is generally solved by having ovs-vswitchd running. If
222 you face the issue despite that, hit Ctrl-C to terminate ovs-vsctl and
223 check the output to see if your command succeeded.
225 NOTE: There's a known bug that the ports added to OVSDB via ovs-vsctl don't
226 get to the kernel datapath immediately, ie. they don't show up in the output of
227 "ovs-dpctl show" even though they show up in output of "ovs-vsctl show".
228 In order to workaround this issue, restart ovs-vswitchd. (You can terminate
229 ovs-vswitchd by running 'ovs-appctl exit'.)
231 05> Dump the ports in the kernel datapath
234 * Sample output is as follows:
238 lookups: hit:0 missed:0 lost:0
240 port 2: br-pif (internal) <<< internal port on 'br-pif' bridge
241 port 1: br-int (internal) <<< internal port on 'br-int' bridge
243 06> Dump the ports in the OVSDB
246 * Sample output is as follows:
248 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
258 07> Add the physical NIC and the internal port to br-pif.
260 In OVS for Hyper-V, we use 'external' as a special name to refer to the
261 physical NICs connected to the Hyper-V switch. An index is added to this
262 special name to refer to the particular physical NIC. Eg. 'external.1' refers
263 to the first physical NIC on the Hyper-V switch.
265 Note: Currently, we assume that the Hyper-V switch on which OVS extension is
266 enabled has a single physical NIC connected to it.
268 Interal port is the virtual adapter created on the Hyper-V switch using the
269 'AllowManagementOS' setting. This has already been setup while creating the
270 switch using the instructions above. In OVS for Hyper-V, we use a 'internal'
271 as a special name to refer to that adapter.
273 % ovs-vsctl add-port br-pif external.1
274 % ovs-vsctl add-port br-pif internal
276 * Dumping the ports should show the additional ports that were just added.
277 Sample output shows up as follows:
281 lookups: hit:0 missed:0 lost:0
283 port 4: internal (internal) <<< 'AllowManagementOS' adapter on
285 port 2: br-pif (internal)
286 port 1: br-int (internal
287 port 3: external.1 <<< Physical NIC
290 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
299 Interface "external.1"
304 08> Add the VIFs to br-int
306 Adding VIFs to openvswitch is a two step procedure. The first step is to
307 assign a 'OVS port name' which is a unique name across all VIFs on this
308 Hyper-V. The next step is to add the VIF to the ovsdb using its 'OVS port
311 08a> Assign a unique 'OVS port name' to the VIF
313 Note that the VIF needs to have been disconnected from the Hyper-V switch
314 before assigning a 'OVS port name' to it. In the example below, we assign a
315 'OVS port name' called 'ovs-port-a' to a VIF on a VM by name 'VM1'. By using
316 index 0 for '$vnic', the first VIF of the VM is being addressed. After
317 assigning the name 'ovs-port-a', the VIF is connected back to the Hyper-V
318 switch with name 'OVS-HV-Switch', which is assumed to be the Hyper-V switch
319 with OVS extension enabled.
322 % import-module .\datapath-windows\misc\OVS.psm1
323 % $vnic = Get-VMNetworkAdapter <Name of the VM>
324 % Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0]
325 % $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a
326 % Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \
327 -SwitchName OVS-Extended-Switch
329 08b> Add the VIFs to br-int in ovsdb
332 % ovs-vsctl add-port br-int ovs-port-a
334 09> Verify the status
337 lookups: hit:0 missed:0 lost:0
339 port 4: internal (internal)
341 port 2: br-pif (internal)
342 port 1: br-int (internal
346 4cd86499-74df-48bd-a64d-8d115b12a9f2
351 Interface "external.1"
360 Interface "ovs-port-a"
362 Steps to configure patch ports and switch VLAN tagging
363 ------------------------------------------------------
364 The Windows Open vSwitch implementation support VLAN tagging in the switch.
365 Switch VLAN tagging along with patch ports between 'br-int' and 'br-pif' is
366 used to configure VLAN tagging functionality between two VMs on different
367 Hyper-Vs. The following examples demonstrate how it can be done:
369 01> Add a patch port from br-int to br-pif
370 % ovs-vsctl add-port br-int patch-to-pif
371 % ovs-vsctl set interface patch-to-pif type=patch \
372 options:peer=patch-to-int
374 02> Add a patch port from br-pif to br-int
375 % ovs-vsctl add-port br-pif patch-to-int
376 % ovs-vsctl set interface patch-to-int type=patch \
377 options:peer=patch-to-pif
379 03> Re-Add the VIF ports with the VLAN tag
380 % ovs-vsctl add-port br-int ovs-port-a tag=900
381 % ovs-vsctl add-port br-int ovs-port-b tag=900
383 Steps to add VXLAN tunnels
384 --------------------------
385 The Windows Open vSwitch implementation support VXLAN tunnels. To add VXLAN
386 tunnels, the following steps serve as examples.
388 Note that, any patch ports created between br-int and br-pif MUST be beleted
389 prior to adding VXLAN tunnels.
391 01> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
392 % ovs-vsctl add-port br-int vxlan-1
393 % ovs-vsctl set Interface vxlan-1 type=vxlan
394 % ovs-vsctl set Interface vxlan-1 options:local_ip=172.168.201.101
395 % ovs-vsctl set Interface vxlan-1 options:remote_ip=172.168.201.102
396 % ovs-vsctl set Interface vxlan-1 options:in_key=flow
397 % ovs-vsctl set Interface vxlan-1 options:out_key=flow
399 02> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
400 % ovs-vsctl add-port br-int vxlan-2
401 % ovs-vsctl set Interface vxlan-2 type=vxlan
402 % ovs-vsctl set Interface vxlan-2 options:local_ip=172.168.201.102
403 % ovs-vsctl set Interface vxlan-2 options:remote_ip=172.168.201.105
404 % ovs-vsctl set Interface vxlan-2 options:in_key=flow
405 % ovs-vsctl set Interface vxlan-2 options:out_key=flow
410 * We require that you don't disable the "Allow management operating system to
411 share this network adapter" under 'Virtual Switch Properties' > 'Connection
412 type: External network', in the HyperV virtual network switch configuration.
415 While there is some support for checksum/segmentation offloads in software,
416 this is still a work in progress. Till the support is complete we recommend
417 disabling TX/RX offloads for both the VM's as well as the HyperV.
421 Open vSwitch daemons come with support to run as a Windows service. The
422 instructions here assume that you have installed the Open vSwitch utilities
423 and daemons via 'make install'. The commands shown here can be run from
424 MSYS bash or Windows command prompt.
426 * Create the database.
428 % ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \
429 "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema"
431 * Create the ovsdb-server service and start it.
433 % 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"
435 One of the common issues with creating a Windows service is with mungled
436 paths. You can make sure that the correct path has been registered with
437 the Windows services manager by running:
443 % sc start ovsdb-server
445 Check that the service is healthy by running:
447 % sc query ovsdb-server
449 * Initialize the database.
451 % ovs-vsctl --no-wait init
453 * Create the ovs-vswitchd service and start it.
455 % sc create ovs-vswitchd binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe --pidfile -vfile:info --log-file --service --service-monitor"
457 % sc start ovs-vswitchd
459 Check that the service is healthy by running:
461 % sc query ovs-vswitchd
463 * To stop and delete the services, run:
465 % sc stop ovs-vswitchd
466 % sc stop ovsdb-server
467 % sc delete ovs-vswitchd
468 % sc delete ovsdb-server
470 Windows autobuild service
471 -------------------------
472 AppVeyor (appveyor.com) provides a free Windows autobuild service for
473 opensource projects. Open vSwitch has integration with AppVeyor for
474 continuous build. A developer can build test his changes for Windows by
475 logging into appveyor.com using a github account, creating a new project
476 by linking it to his development repository in github and triggering
482 * Investigate the working of sFlow on Windows and re-enable the unit tests.
484 * Investigate and add the feature to provide QOS.
486 * Sign the driver & create an MSI for installing the different OpenvSwitch
487 components on windows.