1
Integration Guide for Centralized Control
2
=========================================
4
This document describes how to integrate Open vSwitch onto a new
5
platform to expose the state of the switch and attached devices for
6
centralized control. (If you are looking to port the switching
7
components of Open vSwitch to a new platform, please see the PORTING
8
document.) The focus of this guide is on hypervisors, but many of the
9
interfaces are useful for hardware switches, as well. The XenServer
10
integration is the most mature implementation, so most of the examples
13
The externally visible interface to this integration is
14
platform-agnostic. We encourage anyone who integrates Open vSwitch to
15
use the same interface, because keeping a uniform interface means that
16
controllers require less customization for individual platforms (and
17
perhaps no customization at all).
19
Integration centers around the Open vSwitch database and mostly involves
20
the 'external_ids' columns in several of the tables. These columns are
21
not interpreted by Open vSwitch itself. Instead, they provide
22
information to a controller that permits it to associate a database
23
record with a more meaningful entity. In contrast, the 'other_config'
24
column is used to configure behavior of the switch. The main job of the
25
integrator, then, is to ensure that these values are correctly populated
28
An integrator sets the columns in the database by talking to the
29
ovsdb-server daemon. A few of the columns can be set during startup by
30
calling the ovs-ctl tool from inside the startup scripts. The
31
'xenserver/etc_init.d_openvswitch' script provides examples of its use,
32
and the ovs-ctl(8) manpage contains complete documentation. At runtime,
33
ovs-vsctl can be be used to set columns in the database. The script
34
'xenserver/etc_xensource_scripts_vif' contains examples of its use, and
35
ovs-vsctl(8) manpage contains complete documentation.
37
Python and C bindings to the database are provided if deeper integration
38
with a program are needed. The XenServer ovs-xapi-sync daemon
39
('xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync') provides an
40
example of using the Python bindings. More information on the python
41
bindings is available at 'python/ovs/db/idl.py'. Information on the C
42
bindings is available at 'lib/ovsdb-idl.h'.
44
The following diagram shows how integration scripts fit into the Open vSwitch
47
+----------------------------------------+
48
| Controller Cluster +
49
+----------------------------------------+
52
+----------------------------------------------------------+
54
| +--------------+---------------+ |
56
| +-------------------+ +------------------+ |
57
| | ovsdb-server |-----------| ovs-vswitchd | |
58
| +-------------------+ +------------------+ |
60
| +---------------------+ | |
61
| | Integration scripts | | |
62
| | (ex: ovs-xapi-sync) | | |
63
| +---------------------+ | |
65
|----------------------------------------------------------|
68
| +---------------------+ |
69
| | OVS Kernel Module | |
70
| +---------------------+ |
71
+----------------------------------------------------------+
74
A description of the most relevant fields for integration follows. By
75
setting these values, controllers are able to understand the network and
76
manage it more dynamically and precisely. For more details about the
77
database and each individual column, please refer to the
78
ovs-vswitchd.conf.db(5) manpage.
83
The Open_vSwitch table describes the switch as a whole. The
84
'system_type' and 'system_version' columns identify the platform to the
85
controller. The 'external_ids:system-id' key uniquely identifies the
86
physical host. In XenServer, the system-id will likely be the same as
87
the UUID returned by 'xe host-list'. This key allows controllers to
88
distinguish between multiple hypervisors.
90
Most of this configuration can be done with the ovs-ctl command at
93
ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
94
--system-id="${UUID}" "${other_options}" start
96
Alternatively, the ovs-vsctl command may be used to set a particular
97
value at runtime. For example:
99
ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
101
The 'other_config:enable-statistics' key may be set to "true" to have OVS
102
populate the database with statistics (e.g., number of CPUs, memory,
103
system load) for the controller's use.
108
The Bridge table describes individual bridges within an Open vSwitch
109
instance. The 'external-ids:bridge-id' key uniquely identifies a
110
particular bridge. In XenServer, this will likely be the same as the
111
UUID returned by 'xe network-list' for that particular bridge.
113
For example, to set the identifier for bridge "br0", the following
116
ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
118
The MAC address of the bridge may be manually configured by setting it
119
with the "other_config:hwaddr" key. For example:
121
ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
126
The Interface table describes an interface under the control of Open
127
vSwitch. The 'external_ids' column contains keys that are used to
128
provide additional information about the interface:
132
This field contains the MAC address of the device attached to
133
the interface. On a hypervisor, this is the MAC address of the
134
interface as seen inside a VM. It does not necessarily
135
correlate to the host-side MAC address. For example, on
136
XenServer, the MAC address on a VIF in the hypervisor is always
137
FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is
142
This field uniquely identifies the interface. In hypervisors,
143
this allows the controller to follow VM network interfaces as
144
VMs migrate. A well-chosen identifier should also allow an
145
administrator or a controller to associate the interface with
146
the corresponding object in the VM management system. For
147
example, the Open vSwitch integration with XenServer by default
148
uses the XenServer assigned UUID for a VIF record as the
153
In a hypervisor, there are situations where there are multiple
154
interface choices for a single virtual ethernet interface inside
155
a VM. Valid values are "active" and "inactive". A complete
156
description is available in the ovs-vswitchd.conf.db(5) manpage.
160
This field uniquely identifies the VM to which this interface
161
belongs. A single VM may have multiple interfaces attached to
164
As in the previous tables, the ovs-vsctl command may be used to
165
configure the values. For example, to set the 'iface-id' on eth0, the
166
following command can be used:
168
ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'
added
removed
IntegrationGuide.md
