Skip to content

Commit

Permalink
INSTALL.Windows: update documentation
Browse files Browse the repository at this point in the history 
The documentation to run the executables has fallen behind quite
a bit. In this patch, we make a few updates. There's more to come.

The patch assumes the user has not run 'make install' or does not
have access to an installer.

Signed-off-by: Nithin Raju <[email protected]>
Signed-off-by: Gurucharan Shetty <[email protected]>
  • Loading branch information
@nithinrajub @shettyg
nithinrajub authored and shettyg committed Apr 9, 2015
1 parent dcd0321 commit 0a46bca
Showing 1 changed file with 239 additions and 117 deletions.
356 changes: 239 additions & 117 deletions INSTALL.Windows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,128 +136,251 @@ Steps to install the module
---------------------------

01> Run ./uninstall.cmd to remove the old extension.
02> Run ./install.cmd to insert the new one. For this to work you will have to

02> Run ./install.cmd to insert the new one. For this to work you will have to
turn on TESTSIGNING boot option or 'Disable Driver Signature Enforcement'
during boot.
03> In the Virtual Switch Manager configuration you should now see "VMWare OVS
Extension" under 'Virtual Switch Extensions'. Click the check box to enable the
extension.

Steps to run the user processes & configure VXLAN ports
-------------------------------------------------------

01> Create the conf db file.
ovsdb\ovsdb-tool.exe create conf.db .\vswitchd\vswitch.ovsschema

02> Run ovsdb-server
ovsdb\ovsdb-server.exe -v --remote=ptcp:6640:127.0.0.1 conf.db

03> Create integration bridge & pif bridge
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-br br-int
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-br br-pif

04> Dump the ports
utilities\ovs-dpctl.exe show

* Sample output shows up like this. Currently it is not possible to figure out
* the mapping between VIF and VM from the output.

$ utilities\ovs-dpctl.exe show
2014-06-27T01:55:32Z|00001|socket_util|ERR|4789:0.0.0.0:
socket: Either the application has not called WSAStartup, or WSAStartup failed.
<<< Ignore this error, it is harmless.
system@ovs-system:
lookups: hit:0 missed:0 lost:0
flows: 0
masks: hit:0 total:0 hit/pkt:0.00
port 16777216: internal <<< VTEP created by AllowManagementOS
setting
port 16777225: external.1 <<< Physical NIC
port 16777288: vmNICEmu.1000048 <<< VIF #1
port 16777289: vmNICSyn.1000049 <<< VIF #2


05> Add the physical NIC and the internal port to br-pif
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif <port name>

Eg:
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif external.1
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-pif internal

06> Add the VIFs to br-int
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int <port name>

Eg:
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vmNICEmu.1000048
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vmNICSyn.1000049

07> Verify the status
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 show

Eg:
$ utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 show
4cd86499-74df-48bd-a64d-8d115b12a9f2
Bridge br-pif
Port internal
Interface internal
Port "external.1"
Interface "external.1"
Port br-pif
Interface br-pif
type: internal
Bridge br-int
Port br-int
Interface br-int
type: internal
Port "vmNICEmu.1000048"
Interface "vmNICEmu.1000048"
Port "vmNICSyn.1000049"
Interface "vmNICSyn.1000049"


09> Run vswitchd
vswitchd\ovs-vswitchd.exe -v tcp:127.0.0.1:6640

10> You can figure out the port name to MAC address mapping now. (optional)
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 list interface

//********** VXLAN PORT CONFIGURATION (Supports Multiple ports) ************//
(Remove all patch ports added to create VLAN networks.)
11> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vxlan-1
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 type=vxlan
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:local_ip=172.168.201.101
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:remote_ip=172.168.201.102
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:in_key=flow
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-1 options:out_key=flow

12> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 add-port br-int vxlan-2
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 type=vxlan
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:local_ip=172.168.201.102
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:remote_ip=172.168.201.105
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:in_key=flow
utilities\ovs-vsctl.exe --db=tcp:127.0.0.1:6640 set Interface vxlan-2 options:out_key=flow


//********** VLAN CONFIGURATION (Using patch ports) ************//
(Remove all VXLAN ports from the configuration.)
13> Add a patch port from br-int to br-pif
utilities/ovs-vsctl.exe -- add-port br-int patch-to-pif
utilities/ovs-vsctl.exe -- set interface patch-to-pif type=patch options:peer=patch-to-int

14> Add a patch port from br-pif to br-int
utilities/ovs-vsctl.exe -- add-port br-pif patch-to-int
utilities/ovs-vsctl.exe -- set interface patch-to-int type=patch options:peer=patch-to-pif

15> Re-Add the VIF ports with the VLAN tag
utilities\ovs-vsctl.exe add-port br-int vmNICEmu.1000048 tag=900
utilities\ovs-vsctl.exe add-port br-int vmNICSyn.1000049 tag=900

03> In the Virtual Switch Manager configuration you can enable the Open vSwitch
Extension on an existing switch or create a new switch. If you are using an
existing switch, make sure to enable the "Allow Management OS" option for VXLAN
to work (covered later).

The command to create a new switch named 'OVS-Extended-Switch' using a physical
NIC named 'Ethernet 1' is:
% New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
-NetAdapterName "Ethernet 1"

Note: you can obtain the list of physical NICs on the host using
'Get-NetAdapter' command.

04> In the properties of any switch, you should should now see "Open
vSwitch Extension" under 'Extensions'. Click the check box to enable the
extension. An alternative way to do the same is to run the following command:
% Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch

Note: If you enabled the extension using the command line, a delay of a few
seconds has been observed for the change to be reflected in the UI. This is
not a bug in Open vSwitch.

Steps to run the user processes & configure ports
-------------------------------------------------
NOTE: The userspace executables built in Open vSwitch for Hyper-V links
statically with the pthread library mentioned above. However, the pthread
library has been found to have a dependency on a DLL file called
"pthreadVC2.dll" which is part of the pthread package and typically resides in
"C:\pthread\dll\x86". In order to resolve the dependency, add the location of
the DLL file to Windows environment variable %Path%. An alternative is to copy
the DLL file into each of the directories where the OVS executables are
located. Without having this DLL dependency resolved, the OVS executables will
not run. They exit without showing any error/output.

01> Create the OVSDB file
% ovsdb\ovsdb-tool.exe create conf.db .\vswitchd\vswitch.ovsschema

02> Start ovsdb-server [IN A NEW CONSOLE]
% ovsdb\ovsdb-server.exe -v --remote=punix:db.sock conf.db

03> Start ovs-vswitchd [IN A NEW CONSOLE]
% vswitchd\ovs-vswitchd.exe -v

04> Create integration bridge & pif bridge
% utilities\ovs-vsctl.exe add-br br-int
% utilities\ovs-vsctl.exe add-br br-pif

NOTE: There's a known bug that running the ovs-vsctl.exe command does not
terminate. This is generally solved by having ovs-vswitchd.exe running. If
you face the issue despite that, hit Ctrl-C to terminate ovs-vsctl.exe and
check the output to see if your command succeeded.

NOTE: There's a known bug that the ports added to OVSDB via ovs-vsctl.exe don't
get to the kernel datapath immediately, ie. they don't whow up in the output of
"ovs-dpctl.exe show" even though they show up in output of "ovs-vsctl.exe
show". In order to workaround this issue, restart ovs-vswitchd.exe.

05> Dump the ports in the kernel datapath
.\ % utilities\ovs-dpctl.exe show

* Sample output is as follows:

% utilities\ovs-dpctl.exe show
system@ovs-system:
lookups: hit:0 missed:0 lost:0
flows: 0
port 2: br-pif (internal) <<< internal port on 'br-pif' bridge
port 1: br-int (internal) <<< internal port on 'br-int' bridge

06> Dump the ports in the OVSDB
% utilities\ovs-vsctl.exe show

* Sample output is as follows:
% .\ovs-vsctl.exe show
a56ec7b5-5b1f-49ec-a795-79f6eb63228b
Bridge br-pif
Port br-pif
Interface br-pif
type: internal
Bridge br-int
Port br-int
Interface br-int
type: internal

07> Add the physical NIC and the internal port to br-pif.

In OVS for Hyper-V, we use 'external' as a special name to refer to the
physical NICs connected to the Hyper-V switch. An index is added to this
special name to refer to the particular physical NIC. Eg. 'external.1' refers
to the first physical NIC on the Hyper-V switch.

Note: Currently, we assume that the Hyper-V switch on which OVS extension is
enabled has a single physical NIC connected to it.

Interal port is the virtual adapter created on the Hyper-V switch using the
'AllowManagementOS' setting. This has already been setup while creating the
switch using the instructions above. In OVS for Hyper-V, we use a 'internal'
as a special name to refer to that adapter.

% utilities\ovs-vsctl.exe add-port br-pif external.1
% utilities\ovs-vsctl.exe add-port br-pif internal

* Dumping the ports should show the additional ports that were just added.
Sample output shows up as follows:

% utilities\ovs-dpctl.exe show
system@ovs-system:
lookups: hit:0 missed:0 lost:0
flows: 0
port 4: internal (internal) <<< 'AllowManagementOS' adapter on
Hyper-V switch
port 2: br-pif (internal)
port 1: br-int (internal
port 3: external.1 <<< Physical NIC

% .\ovs-vsctl.exe show
a56ec7b5-5b1f-49ec-a795-79f6eb63228b
Bridge br-pif
Port internal
Interface internal
Port br-pif
Interface br-pif
type: internal
Bridge br-int
Port "external.1"
Interface "external.1"
Port br-int
Interface br-int
type: internal

08> Add the VIFs to br-int

Adding VIFs to openvswitch is a two step procedure. The first step is to
assign a 'OVS port name' which is a unique name across all VIFs on this
Hyper-V. The next step is to add the VIF to the ovsdb using its 'OVS port
name' as key.

08a> Assign a unique 'OVS port name' to the VIF

Note that the VIF needs to have been disconnected from the Hyper-V switch
before assigning a 'OVS port name' to it. In the example below, we assign a
'OVS port name' called 'ovs-port-a' to a VIF on a VM by name 'VM1'. By using
index 0 for '$vnic', the first VIF of the VM is being addressed. After
assigning the name 'ovs-port-a', the VIF is connected back to the Hyper-V
switch with name 'OVS-HV-Switch', which is assumed to be the Hyper-V switch
with OVS extension enabled.

Eg:
% import-module .\datapath-windows\misc\OVS.psm1
% $vnic = Get-VMNetworkAdapter <Name of the VM>
% Disconnect-VMNetworkAdapter -VMNetworkAdapter $vnic[0]
% $vnic[0] | Set-VMNetworkAdapterOVSPort -OVSPortName ovs-port-a
% Connect-VMNetworkAdapter -VMNetworkAdapter $vnic[0] \
-SwitchName OVS-Extended-Switch

08b> Add the VIFs to br-int in ovsdb

Eg:
% utilities\ovs-vsctl.exe add-port br-int ovs-port-a

09> Verify the status
% utilities\ovs-dpctl.exe show
system@ovs-system:
lookups: hit:0 missed:0 lost:0
flows: 0
port 4: internal (internal)
port 5: ovs-port-a
port 2: br-pif (internal)
port 1: br-int (internal
port 3: external.1

% utilities\ovs-vsctl.exe show
4cd86499-74df-48bd-a64d-8d115b12a9f2
Bridge br-pif
Port internal
Interface internal
Port "external.1"
Interface "external.1"
Port br-pif
Interface br-pif
type: internal
Bridge br-int
Port br-int
Interface br-int
type: internal
Port "ovs-port-a"
Interface "ovs-port-a"

Steps to configure patch ports and switch VLAN tagging
------------------------------------------------------
The Windows Open vSwitch implementation support VLAN tagging in the switch.
Switch VLAN tagging along with patch ports between 'br-int' and 'br-pif' is
used to configure VLAN tagging functionality between two VMs on different
Hyper-Vs. The following examples demonstrate how it can be done:

01> Add a patch port from br-int to br-pif
% utilities/ovs-vsctl.exe -- add-port br-int patch-to-pif
% utilities/ovs-vsctl.exe -- set interface patch-to-pif type=patch \
options:peer=patch-to-int

02> Add a patch port from br-pif to br-int
% utilities/ovs-vsctl.exe -- add-port br-pif patch-to-int
% utilities/ovs-vsctl.exe -- set interface patch-to-int type=patch \
options:peer=patch-to-pif

03> Re-Add the VIF ports with the VLAN tag
% utilities\ovs-vsctl.exe add-port br-int ovs-port-a tag=900
% utilities\ovs-vsctl.exe add-port br-int ovs-port-b tag=900

Steps to add VXLAN tunnels
--------------------------
The Windows Open vSwitch implementation support VXLAN tunnels. To add VXLAN
tunnels, the following steps serve as examples.

Note that, any patch ports created between br-int and br-pif MUST be beleted
prior to adding VXLAN tunnels.

01> Add the vxlan port between 172.168.201.101 <-> 172.168.201.102
% utilities\ovs-vsctl.exe add-port br-int vxlan-1
% utilities\ovs-vsctl.exe set Interface vxlan-1 type=vxlan
% utilities\ovs-vsctl.exe set Interface vxlan-1 \
options:local_ip=172.168.201.101
% utilities\ovs-vsctl.exe set Interface vxlan-1 \
options:remote_ip=172.168.201.102
% utilities\ovs-vsctl.exe set Interface vxlan-1 options:in_key=flow
% utilities\ovs-vsctl.exe set Interface vxlan-1 options:out_key=flow

02> Add the vxlan port between 172.168.201.101 <-> 172.168.201.105
% utilities\ovs-vsctl.exe add-port br-int vxlan-2
% utilities\ovs-vsctl.exe set Interface vxlan-2 type=vxlan
% utilities\ovs-vsctl.exe set Interface vxlan-2 \
options:local_ip=172.168.201.102
% utilities\ovs-vsctl.exe set Interface vxlan-2 \
options:remote_ip=172.168.201.105
% utilities\ovs-vsctl.exe set Interface vxlan-2 options:in_key=flow
% utilities\ovs-vsctl.exe set Interface vxlan-2 options:out_key=flow


Requirements
------------

* We require that you don't disable the "Allow management operating system to
share this network adapter" under 'Virtual Switch Properties' > 'Connection
type: External network', in the HyperV virtual network switch configuration.
Expand All @@ -269,7 +392,6 @@ disabling TX/RX offloads for both the VM's as well as the HyperV.

Windows autobuild service
-------------------------

AppVeyor (appveyor.com) provides a free Windows autobuild service for
opensource projects. Open vSwitch has integration with AppVeyor for
continuous build. A developer can build test his changes for Windows by
Expand Down

0 comments on commit 0a46bca

Please sign in to comment.