IntegrationGuide.md

   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