debian/openvswitch-switch.README.Debian

   1 README.Debian for openvswitch-switch
   2 ---------------------------------
   3
   4 To use the Linux kernel-based switch implementation, you will need an
   5 Open vSwitch kernel module.  There are multiple ways to obtain one.
   6 In order of increasing manual effort, these are:
   7
   8        * Use a Linux kernel 3.3 or later, which has an integrated Open
   9          vSwitch kernel module.
  10
  11          The upstream Linux kernel module lacks a few features that
  12          are in the third-party module.  For details, please see the
  13          FAQ, "What features are not available in the Open vSwitch
  14          kernel datapath that ships as part of the upstream Linux
  15          kernel?".
  16
  17        * Install the "openvswitch-datapath-dkms" Debian package that
  18          you built earlier.  This should automatically build and
  19          install the Open vSwitch kernel module for your running
  20          kernel.
  21
  22          This option requires that you have a compiler and toolchain
  23          installed on the machine where you run Open vSwitch, which
  24          may be unacceptable in some production server environments.
  25
  26        * Install the "openvswitch-datapath-source" Debian package, use
  27          "module-assistant" to build a Debian package of the Open
  28          vSwitch kernel module for your kernel, and then install that
  29          Debian package.
  30
  31          You can install the kernel module Debian packages that you
  32          build this way on the same machine where you built it or on
  33          another machine or machines, which means that you don't
  34          necessarily have to have any build infrastructure on the
  35          machines where you use the kernel module.
  36
  37          /usr/share/doc/openvswitch-datapath-source/README.Debian has
  38          details on the build process.
  39
  40        * Build and install the kernel module by hand.
  41
  42
  43 Debian network scripts (ifupdown) integration
  44 ------------------------------------------------
  45 This package lets a user to optionally configure Open vSwitch bridges
  46 and ports from /etc/network/interfaces. Please refer to the interfaces(5)
  47 manpage for more details regarding /etc/network/interfaces.
  48
  49 The stanzas that configure the OVS bridges should begin with "allow-ovs"
  50 followed by name of the bridge. Here is an example.
  51 allow-ovs br0
  52
  53 The stanzas that configure the OVS ports should begin with
  54 "allow-${bridge-name}" followed by name of the port. Here is an example.
  55 allow-br0 eth0
  56
  57 The following OVS specific "command" options are supported:
  58
  59     - ovs_type: This can either be OVSBridge, OVSPort, OVSIntPort, OVSBond,
  60       OVSPatchPort or OVSTunnel depending on whether you configure a bridge,
  61       port, an internal port, a bond, a patch port or a tunnel. This is a
  62       required option.
  63
  64     - ovs_ports: This option specifies all the ports that belong to a bridge.
  65
  66     - ovs_bridge: This options specifies a bridge to which a port belongs.
  67       This is a required option for a port.
  68
  69     - ovs_bonds: This option specifies the list of physical interfaces to be
  70       bonded together.
  71
  72     - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies
  73       the patch's peer on the other bridge.
  74
  75     - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
  76       For example, "gre", "vxlan", etc.
  77
  78     - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
  79       used to specify the tunnel options like remote_ip, key, etc.
  80
  81     - ovs_options: This option lets you add extra arguments to a ovs-vsctl
  82       command. See examples.
  83
  84     - ovs_extra: This option lets you run additional ovs-vsctl commands,
  85       separated by "--" (double dash). Variables can be part of the "ovs_extra"
  86       option. You can provide all the standard environmental variables
  87       described in the interfaces(5) man page. You can also pass shell
  88       commands.
  89
  90 More implementation specific details can be seen in the examples.
  91
  92 Examples:
  93 --------
  94 ex 1: A standalone bridge.
  95
  96 allow-ovs br0
  97 iface br0 inet static
  98     address 192.168.1.1
  99     netmask 255.255.255.0
 100     ovs_type OVSBridge
 101
 102 ex 2: A bridge with one port.
 103
 104 allow-ovs br0
 105 iface br0 inet dhcp
 106     ovs_type OVSBridge
 107     ovs_ports eth0
 108
 109 allow-br0 eth0
 110 iface eth0 inet manual
 111     ovs_bridge br0
 112     ovs_type OVSPort
 113
 114 ex 3: A bridge with multiple physical ports.
 115
 116 allow-ovs br0
 117 iface br0 inet dhcp
 118     ovs_type OVSBridge
 119     ovs_ports eth0 eth1
 120
 121 allow-br0 eth0
 122 iface eth0 inet manual
 123     ovs_bridge br0
 124     ovs_type OVSPort
 125
 126 allow-br0 eth1
 127 iface eth1 inet manual
 128     ovs_bridge br0
 129     ovs_type OVSPort
 130
 131 ex 4: A bridge with an OVS internal port.
 132
 133 allow-ovs br1
 134 iface br1 inet static
 135     address 192.168.1.1
 136     netmask 255.255.255.0
 137     ovs_type OVSBridge
 138     ovs_ports vlan100
 139
 140 allow-br1 vlan100
 141 iface vlan100 inet manual
 142     ovs_bridge br1
 143     ovs_type OVSIntPort
 144     ovs_options tag=100
 145     ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)
 146
 147 ex 5: Bonding.
 148
 149 allow-ovs br2
 150 iface br2 inet static
 151     address 192.170.1.1
 152     netmask 255.255.255.0
 153     ovs_type OVSBridge
 154     ovs_ports bond0
 155
 156 allow-br2 bond0
 157 iface bond0 inet manual
 158     ovs_bridge br2
 159     ovs_type OVSBond
 160     ovs_bonds eth2 eth3
 161     ovs_options bond_mode=balance-tcp lacp=active
 162
 163 ex 6: Patch ports.
 164
 165 allow-ovs br0
 166 iface br0 inet manual
 167     ovs_type OVSBridge
 168     ovs_ports patch0
 169
 170 allow-br0 patch0
 171 iface patch0 inet manual
 172     ovs_bridge br0
 173     ovs_type OVSPatchPort
 174     ovs_patch_peer patch1
 175
 176 allow-ovs br1
 177 iface br1 inet manual
 178     ovs_type OVSBridge
 179     ovs_ports patch1
 180
 181 allow-br1 patch1
 182 iface patch1 inet manual
 183     ovs_bridge br1
 184     ovs_type OVSPatchPort
 185     ovs_patch_peer patch0
 186
 187 ex 7: Tunnel.
 188
 189 allow-ovs br1
 190 iface br1 inet static
 191     address 192.168.1.1
 192     netmask 255.255.255.0
 193     ovs_type OVSBridge
 194     ovs_ports gre1
 195
 196 allow-br1 gre1
 197 iface gre1 inet manual
 198     ovs_bridge br1
 199     ovs_type OVSTunnel
 200     ovs_tunnel_type gre
 201     ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1
 202
 203 ex 8: Create and destroy bridges.
 204
 205 ifup --allow=ovs $list_of_bridges
 206 ifdown --allow=ovs $list_of_bridges
 207
 208 Open vSwitch integration with systemd-networkd
 209 -----------------------------------------------
 210
 211 There is no native integration of OVS with systemd-networkd. That is,
 212 you cannot create OVS bridges, ports and bonds by simply writing configuration
 213 files in /etc/systemd/network.  But, you can create OVS devices using ovs-vsctl
 214 and then write configuration files to provide them IP addresses.
 215
 216 As soon as a OVS device is visible, systemd-networkd will provide that device
 217 an IP address.  Since OVS database is persistent across reboots, the OVS
 218 devices will get re-created after a reboot as soon as OVS startup script is
 219 invoked. And systemd-networkd will immediately assign the configuration defined
 220 in /etc/systemd/network.
 221
 222 Example:
 223
 224 If you have a physical ethernet device "ens160" which has been configured with
 225 DHCP, your systemd-networkd's .network config file will look something like
 226 this:
 227
 228 ```
 229 [Match]
 230 Name=ens160
 231
 232 [Network]
 233 DHCP=ipv4
 234
 235 [DHCP]
 236 ClientIdentifier=mac
 237 ```
 238
 239 Please note how the DHCP ClientIdentifier above has been configured with the
 240 mac address.
 241
 242 To create a OVS bridge "br-ens160" and add "ens160" as a port of that
 243 bridge, you can change the .network configuration for "ens160" to look like:
 244
 245 ```
 246 [Match]
 247 Name=ens160
 248 ```
 249
 250 Now create a new .network configuration file for "br-ens160". Something like:
 251
 252 ```
 253 [Match]
 254 Name=br-ens160
 255
 256 [Network]
 257 DHCP=ipv4
 258
 259 [DHCP]
 260 ClientIdentifier=mac
 261 ```
 262
 263 Now, use ovs-vsctl to create br-ens160 and add ens160 as a port of it.  You
 264 will also have to flush the IP address of ens160 and restart systemd-networkd
 265 in the same line. It is important to let br-ens160 have the same mac address as
 266 ens160 to get the same IP address to br-ens160 from the DHCP server.  In the
 267 below command, "$mac_of_ens160" holds the mac address of ens160. For e.g:
 268
 269 ```
 270 mac_of_ens160='"00:0c:29:77:27:7a"'
 271 ovs-vsctl --may-exist add-br br-ens160 -- \
 272     --may-exist add-port br-ens160 ens160 -- \
 273     set interface br-ens160 mac="$mac_of_ens160"; ip addr flush dev ens160; \
 274     systemctl restart systemd-networkd
 275 ```
 276
 277 br-ens160 should now have the same DHCP IP. It should also have the correct
 278 DNS resolution servers configured.
 279
 280 Notes on dependencies:
 281 ---------------------
 282
 283 openvswitch-switch depends on $network, $named $remote_fs and $syslog to start.
 284 This creates some startup dependency issues.
 285
 286 * Since openvswitch utilities are placed in /usr and /usr can be mounted
 287 through NFS, openvswitch has to start after it.  But if a user uses openvswitch
 288 for all his networking needs and hence to mount NFS, there will be a deadlock.
 289 So, if /usr is mounted through NFS and openvswitch is used for all networking,
 290 the administrator should figure out a way to mount NFS before starting OVS.
 291 One way to do this is in initramfs.
 292
 293 * Since openvswitch starts after $network, $remote_fs and $syslog, any startup
 294 script that depends on openvswitch but starts before it, needs to be changed
 295 to depend on openvswitch-switch too.
 296
 297 * Ideally, an admin should not add openvswitch bridges in the 'auto'
 298 section of the 'interfaces' file (i.e., if "br0" is a OVS bridge, you should
 299 not have a line "auto br0"). This is because, when ifupdown starts
 300 working on bridges listed in 'auto', openvswitch has not yet started.
 301
 302 But, if the admin wants to go down this route and adds openvswitch bridges
 303 in the 'auto' section, openvswitch-switch will forcefully be started when
 304 ifupdown kicks in. In a case like this, the admin needs to make sure that /usr
 305 has already been mounted and that a remote $syslog (if used) is ready to
 306 receive openvswitch logs.
 307
 308 * With systemd, adding openvswitch bridges in the 'auto' section of the
 309 'interfaces' file can cause race conditions (i.e., if "br0" is a OVS bridge,
 310 you should not have a line "auto br0").  Debian systems have added a
 311 systemd ifup@.service file.  This file will call ifdown and ifup on interfaces
 312 in "auto" section automatically when the interfaces disappear and appear
 313 respectively.  This will cause race conditions if you delete and add the same
 314 bridges using tools like "ovs-vsctl" or "ovs-dpctl".  This is also a problem
 315 when you upgrade your openvswitch kernel module using commands like
 316 'force-reload-kmod'.