1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Convention for heading levels in Open vSwitch documentation:
======= Heading 0 (reserved for the title in a document)
------- Heading 1
~~~~~~~ Heading 2
+++++++ Heading 3
''''''' Heading 4
Avoid deeper levels because they do not render well.
=========================================
Integration Guide for Centralized Control
=========================================
This document describes how to integrate Open vSwitch onto a new platform to
expose the state of the switch and attached devices for centralized control.
(If you are looking to port the switching components of Open vSwitch to a new
platform, please see the PORTING document.) The focus of this guide is on
hypervisors, but many of the interfaces are useful for hardware switches, as
well. The XenServer integration is the most mature implementation, so most of
the examples are drawn from it.
The externally visible interface to this integration is platform-agnostic. We
encourage anyone who integrates Open vSwitch to use the same interface, because
keeping a uniform interface means that controllers require less customization
for individual platforms (and perhaps no customization at all).
Integration centers around the Open vSwitch database and mostly involves the
``external_ids`` columns in several of the tables. These columns are not
interpreted by Open vSwitch itself. Instead, they provide information to a
controller that permits it to associate a database record with a more
meaningful entity. In contrast, the ``other_config`` column is used to
configure behavior of the switch. The main job of the integrator, then, is to
ensure that these values are correctly populated and maintained.
An integrator sets the columns in the database by talking to the ovsdb-server
daemon. A few of the columns can be set during startup by calling the ovs-ctl
tool from inside the startup scripts. The ``xenserver/etc_init.d_openvswitch``
script provides examples of its use, and the ovs-ctl(8) manpage contains
complete documentation. At runtime, ovs-vsctl can be be used to set columns in
the database. The script ``xenserver/etc_xensource_scripts_vif`` contains
examples of its use, and ovs-vsctl(8) manpage contains complete documentation.
Python and C bindings to the database are provided if deeper integration with a
program are needed. The XenServer ovs-xapi-sync daemon
(``xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync``) provides an example
of using the Python bindings. More information on the python bindings is
available at ``python/ovs/db/idl.py``. Information on the C bindings is
available at ``lib/ovsdb-idl.h``.
The following diagram shows how integration scripts fit into the Open vSwitch
architecture:
::
Diagram
+----------------------------------------+
| Controller Cluster +
+----------------------------------------+
|
|
+----------------------------------------------------------+
| | |
| +--------------+---------------+ |
| | | |
| +-------------------+ +------------------+ |
| | ovsdb-server |-----------| ovs-vswitchd | |
| +-------------------+ +------------------+ |
| | | |
| +---------------------+ | |
| | Integration scripts | | |
| | (ex: ovs-xapi-sync) | | |
| +---------------------+ | |
| | Userspace |
|----------------------------------------------------------|
| | Kernel |
| | |
| +---------------------+ |
| | OVS Kernel Module | |
| +---------------------+ |
+----------------------------------------------------------+
A description of the most relevant fields for integration follows. By setting
these values, controllers are able to understand the network and manage it more
dynamically and precisely. For more details about the database and each
individual column, please refer to the ovs-vswitchd.conf.db(5) manpage.
``Open_vSwitch`` table
----------------------
The ``Open_vSwitch`` table describes the switch as a whole. The
``system_type`` and ``system_version`` columns identify the platform to the
controller. The ``external_ids:system-id`` key uniquely identifies the
physical host. In XenServer, the system-id will likely be the same as the UUID
returned by ``xe host-list``. This key allows controllers to distinguish
between multiple hypervisors.
Most of this configuration can be done with the ovs-ctl command at startup.
For example:
::
$ ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
--system-id="${UUID}" "${other_options}" start
Alternatively, the ovs-vsctl command may be used to set a particular value at
runtime. For example:
::
$ ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
The ``other_config:enable-statistics`` key may be set to ``true`` to have OVS
populate the database with statistics (e.g., number of CPUs, memory, system
load) for the controller's use.
Bridge table
------------
The Bridge table describes individual bridges within an Open vSwitch instance.
The ``external-ids:bridge-id`` key uniquely identifies a particular bridge. In
XenServer, this will likely be the same as the UUID returned by ``xe
network-list`` for that particular bridge.
For example, to set the identifier for bridge "br0", the following command can
be used:
::
$ ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
The MAC address of the bridge may be manually configured by setting it with the
``other_config:hwaddr`` key. For example:
::
$ ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
Interface table
---------------
The Interface table describes an interface under the control of Open vSwitch.
The ``external_ids`` column contains keys that are used to provide additional
information about the interface:
attached-mac
This field contains the MAC address of the device attached to the interface.
On a hypervisor, this is the MAC address of the interface as seen inside a
VM. It does not necessarily correlate to the host-side MAC address. For
example, on XenServer, the MAC address on a VIF in the hypervisor is always
FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is seen.
iface-id
This field uniquely identifies the interface. In hypervisors, this allows
the controller to follow VM network interfaces as VMs migrate. A well-chosen
identifier should also allow an administrator or a controller to associate
the interface with the corresponding object in the VM management system. For
example, the Open vSwitch integration with XenServer by default uses the
XenServer assigned UUID for a VIF record as the iface-id.
iface-status
In a hypervisor, there are situations where there are multiple interface
choices for a single virtual ethernet interface inside a VM. Valid values
are "active" and "inactive". A complete description is available in the
ovs-vswitchd.conf.db(5) manpage.
vm-id
This field uniquely identifies the VM to which this interface belongs. A
single VM may have multiple interfaces attached to it.
As in the previous tables, the ovs-vsctl command may be used to configure the
values. For example, to set the ``iface-id`` on eth0, the following command
can be used:
::
$ ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'
|
