[ovs-dev] [PATCH] INSTALL.Windows: update documentation
Nithin Raju
nithin at vmware.com
Tue Apr 7 00:32:31 UTC 2015
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 <nithin at vmware.com>
---
INSTALL.Windows.md | 336 ++++++++++++++++++++++++++++++++++-------------------
1 file changed, 219 insertions(+), 117 deletions(-)
diff --git a/INSTALL.Windows.md b/INSTALL.Windows.md
index e84013a..3248364 100644
--- a/INSTALL.Windows.md
+++ b/INSTALL.Windows.md
@@ -136,128 +136,231 @@ 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 at 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 'Ethernet1' is:
+ % New-VMSwitch "OVS-Extended-Switch" -AllowManagementOS $true \
+ -NetAdapterName Ethernet1
+
+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-Enabled-Switch
+
+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 at 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.
+
+Currently, we assume that the Hyper-V switch on which OVS extension is enabled
+has a single physical NIC connected to it. All physical NICs have a special
+prefix 'external', and the first NIC has the name 'external.1'.
+
+Interal port is the virtual adapter created on the Hyper-V switch using the
+'AllowManagementOS' setting. It has a special name 'internal'.
+
+ % 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 at 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) <<< internal port on 'br-pif' bridge
+ port 1: br-int (internal) <<< internal port on 'br-int' bridge
+ 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-vsctl.exe show
+
+ Eg:
+ % 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.
@@ -269,7 +372,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
--
1.8.5.6
More information about the dev
mailing list