]>
Commit | Line | Data |
---|---|---|
502c4714 JP |
1 | Integration Guide for Centralized Control |
2 | ========================================= | |
3 | ||
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 | |
11 | are drawn from it. | |
12 | ||
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). | |
18 | ||
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 | |
26 | and maintained. | |
27 | ||
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. | |
36 | ||
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'. | |
43 | ||
44 | The following diagram shows how integration scripts fit into the Open vSwitch | |
45 | architecture: | |
46 | ||
47 | +----------------------------------------+ | |
48 | | Controller Cluster + | |
49 | +----------------------------------------+ | |
50 | | | |
51 | | | |
52 | +----------------------------------------------------------+ | |
53 | | | | | |
54 | | +--------------+---------------+ | | |
55 | | | | | | |
56 | | +-------------------+ +------------------+ | | |
57 | | | ovsdb-server |-----------| ovs-vswitchd | | | |
58 | | +-------------------+ +------------------+ | | |
59 | | | | | | |
60 | | +---------------------+ | | | |
61 | | | Integration scripts | | | | |
62 | | | (ex: ovs-xapi-sync) | | | | |
63 | | +---------------------+ | | | |
64 | | | Userspace | | |
65 | |----------------------------------------------------------| | |
66 | | | Kernel | | |
67 | | | | | |
68 | | +---------------------+ | | |
69 | | | OVS Kernel Module | | | |
70 | | +---------------------+ | | |
71 | +----------------------------------------------------------+ | |
72 | ||
73 | ||
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. | |
79 | ||
80 | ||
81 | Open_vSwitch table | |
82 | ------------------ | |
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. | |
89 | ||
90 | Most of this configuration can be done with the ovs-ctl command at | |
91 | startup. For example: | |
92 | ||
93 | ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \ | |
94 | --system-id="${UUID}" "${other_options}" start | |
95 | ||
96 | Alternatively, the ovs-vsctl command may be used to set a particular | |
97 | value at runtime. For example: | |
98 | ||
99 | ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"' | |
100 | ||
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. | |
104 | ||
105 | ||
106 | Bridge table | |
107 | ------------ | |
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. | |
112 | ||
113 | For example, to set the identifier for bridge "br0", the following | |
114 | command can be used: | |
115 | ||
116 | ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"' | |
117 | ||
118 | The MAC address of the bridge may be manually configured by setting it | |
119 | with the "other_config:hwaddr" key. For example: | |
120 | ||
121 | ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab" | |
122 | ||
123 | ||
124 | Interface table | |
125 | --------------- | |
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: | |
129 | ||
130 | attached-mac | |
131 | ||
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 | |
138 | seen. | |
139 | ||
140 | iface-id | |
141 | ||
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 | |
149 | iface-id. | |
150 | ||
151 | iface-status | |
152 | ||
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. | |
157 | ||
158 | vm-id | |
159 | ||
160 | This field uniquely identifies the VM to which this interface | |
161 | belongs. A single VM may have multiple interfaces attached to | |
162 | it. | |
163 | ||
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: | |
167 | ||
168 | ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"' | |
169 |