2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
6 http://www.apache.org/licenses/LICENSE-2.0
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
14 Convention for heading levels in Open vSwitch documentation:
16 ======= Heading 0 (reserved for the title in a document)
22 Avoid deeper levels because they do not render well.
24 =======================
25 Open vSwitch on Windows
26 =======================
28 .. _windows-build-reqs:
33 Open vSwitch on Linux uses autoconf and automake for generating Makefiles. It
34 will be useful to maintain the same build system while compiling on Windows
35 too. One approach is to compile Open vSwitch in a MinGW environment that
36 contains autoconf and automake utilities and then use Visual C++ as a compiler
39 The following explains the steps in some detail.
43 Install Mingw on a Windows machine by following the instructions on
44 `mingw.org <http://www.mingw.org/wiki/Getting_Started>`__.
46 This should install mingw at ``C:\Mingw`` and msys at ``C:\Mingw\msys``. Add
47 ``C:\MinGW\bin`` and ``C:\Mingw\msys\1.0\bin`` to PATH environment variable
50 You can either use the MinGW installer or the command line utility
51 ``mingw-get`` to install both the base packages and additional packages like
52 automake and autoconf(version 2.68).
54 Also make sure that ``/mingw`` mount point exists. If its not, please
55 add/create the following entry in ``/etc/fstab``::
61 Install the latest Python 2.x from python.org and verify that its path is
62 part of Windows' PATH environment variable.
66 You will need at least Visual Studio 2013 (update 4) to compile userspace
67 binaries. In addition to that, if you want to compile the kernel module you
68 will also need to install Windows Driver Kit (WDK) 8.1 Update.
70 It is important to get the Visual Studio related environment variables and to
71 have the $PATH inside the bash to point to the proper compiler and linker.
72 One easy way to achieve this for VS2013 is to get into the "VS2013 x86 Native
73 Tools Command Prompt" (in a default installation of Visual Studio 2013 this
74 can be found under the following location: ``C:\Program Files (x86)\Microsoft
75 Visual Studio 12.0\Common7\Tools\Shortcuts``) and through it enter into the
76 bash shell available from msys by typing ``bash --login``.
78 There is support for generating 64 bit binaries too. To compile under x64,
79 open the "VS2013 x64 Native Tools Command Prompt" (if your current running OS
80 is 64 bit) or "VS2013 x64 Cross Tools Command Prompt" (if your current
81 running OS is not 64 bit) instead of opening its x86 variant. This will
82 point the compiler and the linker to their 64 bit equivalent.
84 If after the above step, a ``which link`` inside MSYS's bash says,
85 ``/bin/link.exe``, rename ``/bin/link.exe`` to something else so that the
86 Visual studio's linker is used. You should also see a 'which sort' report
91 For pthread support, install the library, dll and includes of pthreads-win32
92 project from `sourceware
93 <ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release>`__ to a
94 directory (e.g.: ``C:/pthread``). You should add the pthread-win32's dll path
95 (e.g.: ``C:\pthread\dll\x86``) to the Windows' PATH environment variable.
99 To get SSL support for Open vSwitch on Windows, you will need to install
100 `OpenSSL for Windows <http://www.openssl.org/related/binaries.html>`__
102 Note down the directory where OpenSSL is installed (e.g.:
103 ``C:/OpenSSL-Win32``) for later use.
108 * Share network adaptors
110 We require that you don't disable the "Allow management operating system to
111 share this network adapter" under 'Virtual Switch Properties' > 'Connection
112 type: External network', in the HyperV virtual network switch configuration.
116 While there is some support for checksum/segmentation offloads in software,
117 this is still a work in progress. Till the support is complete we recommend
118 disabling TX/RX offloads for both the VM's as well as the HyperV.
123 This step is not needed if you have downloaded a released tarball. If
124 you pulled the sources directly from an Open vSwitch Git tree or got a
125 Git tree snapshot, then run boot.sh in the top source directory to build
126 the "configure" script::
130 .. _windows-configuring:
135 Configure the package by running the configure script. You should provide some
136 configure options to choose the right compiler, linker, libraries, Open vSwitch
137 component installation directories, etc. For example::
139 > ./configure CC=./build-aux/cccl LD="$(which link)" \
140 LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
141 --localstatedir="C:/openvswitch/var" \
142 --sysconfdir="C:/openvswitch/etc" \
143 --with-pthread="C:/pthread"
146 By default, the above enables compiler optimization for fast code. For
147 default compiler optimization, pass the ``--with-debug`` configure option.
149 To configure with SSL support, add the requisite additional options::
151 > ./configure CC=./build-aux/cccl LD="`which link`" \
152 LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
153 --localstatedir="C:/openvswitch/var"
154 --sysconfdir="C:/openvswitch/etc" \
155 --with-pthread="C:/pthread" \
156 --enable-ssl --with-openssl="C:/OpenSSL-Win32"
158 Finally, to the kernel module also::
160 > ./configure CC=./build-aux/cccl LD="`which link`" \
161 LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \
162 --localstatedir="C:/openvswitch/var" \
163 --sysconfdir="C:/openvswitch/etc" \
164 --with-pthread="C:/pthread" \
165 --enable-ssl --with-openssl="C:/OpenSSL-Win32" \
166 --with-vstudiotarget="<target type>"
168 Possible values for ``<target type>`` are: ``Debug`` and ``Release``
171 You can directly use the Visual Studio 2013 IDE to compile the kernel
172 datapath. Open the ovsext.sln file in the IDE and build the solution.
174 Refer to the `installation guide <INSTALL.rst>` for information on additional
175 configuration options.
177 .. _windows-building:
182 Once correctly configured, building Open vSwitch on Windows is similar to
183 building on Linux, FreeBSD, or NetBSD.
185 #. Run make for the ported executables in the top source directory, e.g.::
189 For faster compilation, you can pass the ``-j`` argument to make. For
190 example, to run 4 jobs simultaneously, run ``make -j4``.
194 MSYS 1.0.18 has a bug that causes parallel make to hang. You can overcome
195 this by downgrading to MSYS 1.0.17. A simple way to downgrade is to exit
196 all MinGW sessions and then run the below command from MSVC developers
199 > mingw-get upgrade msys-core-bin=1.0.17-1
201 #. To run all the unit tests in Open vSwitch, one at a time::
205 To run all the unit tests in Open vSwitch, up to 8 in parallel::
207 > make check TESTSUITEFLAGS="-j8"
209 #. To install all the compiled executables on the local machine, run::
215 This will install the Open vSwitch executables in ``C:/openvswitch``. You
216 can add ``C:\openvswitch\usr\bin`` and ``C:\openvswitch\usr\sbin`` to
217 Windows' PATH environment variable for easy access.
222 If you are building the kernel module, you will need to copy the below files to
223 the target Hyper-V machine.
225 - ``./datapath-windows/x64/Win8.1Debug/package/ovsext.inf``
226 - ``./datapath-windows/x64/Win8.1Debug/package/OVSExt.sys``
227 - ``./datapath-windows/x64/Win8.1Debug/package/ovsext.cat``
228 - ``./datapath-windows/misc/install.cmd``
229 - ``./datapath-windows/misc/uninstall.cmd``
232 The above path assumes that the kernel module has been built using Windows
233 DDK 8.1 in Debug mode. Change the path appropriately, if a different WDK
236 Now run ``./uninstall.cmd`` to remove the old extension. Once complete, run
237 ``./install.cmd`` to insert the new one. For this to work you will have to
238 turn on ``TESTSIGNING`` boot option or 'Disable Driver Signature
239 Enforcement' during boot. The following commands can be used::
241 > bcdedit /set LOADOPTIONS DISABLE_INTEGRITY_CHECKS
242 > bcdedit /set TESTSIGNING ON
243 > bcdedit /set nointegritychecks ON
246 You may have to restart the machine for the settings to take effect.
248 In the Virtual Switch Manager configuration you can enable the Open vSwitch
249 Extension on an existing switch or create a new switch. If you are using an
250 existing switch, make sure to enable the "Allow Management OS" option for VXLAN
251 to work (covered later).
253 The command to create a new switch named 'OVS-Extended-Switch' using a physical
254 NIC named 'Ethernet 1' is::
256 PS > New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
257 -NetAdapterName "Ethernet 1"
260 You can obtain the list of physical NICs on the host using 'Get-NetAdapter'
263 In the properties of any switch, you should should now see "Open vSwitch
264 Extension" under 'Extensions'. Click the check box to enable the extension.
265 An alternative way to do the same is to run the following command::
267 PS > Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch
270 If you enabled the extension using the command line, a delay of a few seconds
271 has been observed for the change to be reflected in the UI. This is not a
278 The following steps assume that you have installed the Open vSwitch utilities
279 in the local machine via 'make install'.
281 Before starting ovs-vswitchd itself, you need to start its configuration
282 database, ovsdb-server. Each machine on which Open vSwitch is installed should
283 run its own copy of ovsdb-server. Before ovsdb-server itself can be started,
284 configure a database that it can use::
286 > ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \
287 C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema
289 Configure ovsdb-server to use database created above and to listen on a Unix
292 > ovsdb-server -vfile:info --remote=punix:db.sock --log-file \
296 The logfile is created at ``C:/openvswitch/var/log/openvswitch/``
298 Initialize the database using ovs-vsctl. This is only necessary the first time
299 after you create the database with ovsdb-tool, though running it at any time is
302 > ovs-vsctl --no-wait init
305 If you would later like to terminate the started ovsdb-server, run::
307 > ovs-appctl -t ovsdb-server exit
309 Start the main Open vSwitch daemon, telling it to connect to the same Unix
312 > ovs-vswitchd -vfile:info --log-file --pidfile --detach
315 If you would like to terminate the started ovs-vswitchd, run::
320 The logfile is created at ``C:/openvswitch/var/log/openvswitch/``
325 At this point you can use ovs-vsctl to set up bridges and other Open vSwitch
331 Let's start by creating an integration bridge, ``br-int`` and a PIF bridge,
334 > ovs-vsctl add-br br-int
335 > ovs-vsctl add-br br-pif
338 There's a known bug that running the ovs-vsctl command does not terminate.
339 This is generally solved by having ovs-vswitchd running. If you face the
340 issue despite that, hit Ctrl-C to terminate ovs-vsctl and check the output to
341 see if your command succeeded.
343 Validate that ports are added by dumping from both ovs-dpctl and ovs-vsctl::
347 lookups: hit:0 missed:0 lost:0
349 port 2: br-pif (internal) <<< internal port on 'br-pif' bridge
350 port 1: br-int (internal) <<< internal port on 'br-int' bridge
353 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
364 There's a known bug that the ports added to OVSDB via ovs-vsctl don't get to
365 the kernel datapath immediately, ie. they don't show up in the output of
366 ``ovs-dpctl show`` even though they show up in output of ``ovs-vsctl show``.
367 In order to workaround this issue, restart ovs-vswitchd. (You can terminate
368 ovs-vswitchd by running ``ovs-appctl exit``.)
370 Add physicals NICs (PIF)
371 ~~~~~~~~~~~~~~~~~~~~~~~~
373 Now, let's add the physical NIC and the internal port to ``br-pif``. In OVS for
374 Hyper-V, we use the name of the adapter on top of which the Hyper-V virtual
375 switch was created, as a special name to refer to the physical NICs connected
376 to the Hyper-V switch, e.g. if we created the Hyper-V virtual switch on top of
377 the adapter named ``Ethernet0``, then in OVS we use that name (``Ethernet0``)
378 as a special name to refer to that adapter.
381 we assume that the Hyper-V switch on which OVS extension is enabled has a
382 single physical NIC connected to it.
384 An internal port is the virtual adapter created on the Hyper-V switch using the
385 ``AllowManagementOS`` setting. This has already been setup while creating the
386 switch using the instructions above. In OVS for Hyper-V, we use a the name of
387 that specific adapter as a special name to refer to that adapter. By default it
388 is created under the following rule ``vEthernet (<name of the switch>)``.
390 As a whole example, if we issue the following in a powershell console::
392 PS C:\package\binaries> Get-NetAdapter | select Name,MacAddress,InterfaceDescription
393 Name MacAddress InterfaceDescription
394 ---- ---------- --------------------
395 Ethernet1 00-0C-29-94-05-65 Intel(R) PRO/1000 MT Network Connection
396 vEthernet (external) 00-0C-29-94-05-5B Hyper-V Virtual Ethernet Adapter #2
397 Ethernet0 00-0C-29-94-05-5B Intel(R) PRO/1000 MT Network Connection #2
399 PS C:\package\binaries> Get-VMSwitch
400 Name SwitchType NetAdapterInterfaceDescription
401 ---- ---------- ------------------------------
402 external External Intel(R) PRO/1000 MT Network Connection #2
404 We can see that we have a switch(external) created upon adapter name
405 'Ethernet0' with an internal port under name ``vEthernet (external)``. Thus
406 resulting into the following ovs-vsctl commands::
408 > ovs-vsctl add-port br-pif Ethernet0
409 > ovs-vsctl add-port br-pif "vEthernet (external)"
411 Dumping the ports should show the additional ports that were just added::
415 lookups: hit:0 missed:0 lost:0
417 port 4: vEthernet (external) (internal) <<< 'AllowManagementOS'
420 port 2: br-pif (internal)
421 port 1: br-int (internal)
422 port 3: Ethernet0 <<< Physical NIC
425 a56ec7b5-5b1f-49ec-a795-79f6eb63228b
427 Port "vEthernet (external)"
428 Interface "vEthernet (external)"
433 Interface "Ethernet0"
439 Add virtual interfaces (VIFs)
440 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
442 Adding VIFs to openvswitch is a two step procedure. The first step is to
443 assign a 'OVS port name' which is a unique name across all VIFs on this
444 Hyper-V. The next step is to add the VIF to the ovsdb using its 'OVS port
447 First, assign a unique 'OVS port name' to the VIF. The VIF needs to have been
448 disconnected from the Hyper-V switch before assigning a 'OVS port name' to it.
449 In the example below, we assign a 'OVS port name' called ``ovs-port-a`` to a
450 VIF on a VM ``VM1``. By using index 0 for ``$vnic``, the first VIF of the VM
451 is being addressed. After assigning the name ``ovs-port-a``, the VIF is
452 connected back to the Hyper-V switch with name ``OVS-HV-Switch``, which is
453 assumed to be the Hyper-V switch with OVS extension enabled.::
455 PS> import-module .\datapath-windows\misc\OVS.psm1
456 PS> $vnic = Get-VMNetworkAdapter <Name of the VM>
457 PS> Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0]
458 PS> $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a
459 PS> Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \
460 -SwitchName OVS-Extended-Switch
462 Next, add the VIFs to ``br-int``::
464 > ovs-vsctl add-port br-int ovs-port-a
466 Dumping the ports should show the additional ports that were just added::
470 lookups: hit:0 missed:0 lost:0
472 port 4: vEthernet (external) (internal)
474 port 2: br-pif (internal)
475 port 1: br-int (internal
479 4cd86499-74df-48bd-a64d-8d115b12a9f2
481 Port "vEthernet (external)"
482 Interface "vEthernet (external)"
484 Interface "Ethernet0"
493 Interface "ovs-port-a"
495 Add patch ports and configure VLAN tagging
496 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498 The Windows Open vSwitch implementation support VLAN tagging in the switch.
499 Switch VLAN tagging along with patch ports between ``br-int`` and ``br-pif`` is
500 used to configure VLAN tagging functionality between two VMs on different
501 Hyper-Vs. To start, add a patch port from ``br-int`` to ``br-pif``::
503 > ovs-vsctl add-port br-int patch-to-pif
504 > ovs-vsctl set interface patch-to-pif type=patch \
505 options:peer=patch-to-int
507 Add a patch port from ``br-pif`` to ``br-int``::
509 > ovs-vsctl add-port br-pif patch-to-int
510 > ovs-vsctl set interface patch-to-int type=patch \
511 options:peer=patch-to-pif
513 Re-Add the VIF ports with the VLAN tag::
515 > ovs-vsctl add-port br-int ovs-port-a tag=900
516 > ovs-vsctl add-port br-int ovs-port-b tag=900
521 The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add
522 tunnels. For example, first add the tunnel port between 172.168.201.101 <->
525 > ovs-vsctl add-port br-int tun-1
526 > ovs-vsctl set Interface tun-1 type=<port-type>
527 > ovs-vsctl set Interface tun-1 options:local_ip=172.168.201.101
528 > ovs-vsctl set Interface tun-1 options:remote_ip=172.168.201.102
529 > ovs-vsctl set Interface tun-1 options:in_key=flow
530 > ovs-vsctl set Interface tun-1 options:out_key=flow
532 ...and the tunnel port between 172.168.201.101 <-> 172.168.201.105::
534 > ovs-vsctl add-port br-int tun-2
535 > ovs-vsctl set Interface tun-2 type=<port-type>
536 > ovs-vsctl set Interface tun-2 options:local_ip=172.168.201.102
537 > ovs-vsctl set Interface tun-2 options:remote_ip=172.168.201.105
538 > ovs-vsctl set Interface tun-2 options:in_key=flow
539 > ovs-vsctl set Interface tun-2 options:out_key=flow
541 Where ``<port-type>`` is one of: ``stt`` or ``vxlan``
544 Any patch ports created between br-int and br-pif MUST be be deleted prior to
550 Open vSwitch daemons come with support to run as a Windows service. The
551 instructions here assume that you have installed the Open vSwitch utilities and
552 daemons via ``make install``.
555 The commands shown here can be run from MSYS bash or Windows command prompt.
557 To start, create the database::
559 > ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \
560 "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema"
562 Create the ovsdb-server service and start it::
564 > sc create ovsdb-server \
565 binpath="C:/openvswitch/usr/sbin/ovsdb-server.exe \
566 C:/openvswitch/etc/openvswitch/conf.db \
567 -vfile:info --log-file --pidfile \
568 --remote=punix:db.sock --service --service-monitor"
569 > sc start ovsdb-server
572 One of the common issues with creating a Windows service is with mungled
573 paths. You can make sure that the correct path has been registered with the
574 Windows services manager by running::
578 Check that the service is healthy by running::
580 > sc query ovsdb-server
582 Initialize the database::
584 > ovs-vsctl --no-wait init
586 Create the ovs-vswitchd service and start it::
588 > sc create ovs-vswitchd \
589 binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe \
590 --pidfile -vfile:info --log-file --service --service-monitor"
591 > sc start ovs-vswitchd
593 Check that the service is healthy by running::
595 > sc query ovs-vswitchd
597 To stop and delete the services, run::
599 > sc stop ovs-vswitchd
600 > sc stop ovsdb-server
601 > sc delete ovs-vswitchd
602 > sc delete ovsdb-server
607 `AppVeyor <www.appveyor.com>`__ provides a free Windows autobuild service for
608 opensource projects. Open vSwitch has integration with AppVeyor for continuous
609 build. A developer can build test his changes for Windows by logging into
610 appveyor.com using a github account, creating a new project by linking it to
611 his development repository in github and triggering a new build.
616 * Investigate the working of sFlow on Windows and re-enable the unit tests.
618 * Investigate and add the feature to provide QoS.
620 * Sign the driver & create an MSI for installing the different OpenvSwitch
621 components on Windows.