/usr/src/openvswitch-2.0.1+git20140120/IntegrationGuide is in openvswitch-datapath-dkms 2.0.1+git20140120-0ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | 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:
+----------------------------------------+
| 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}"'
|