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 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 or
  60       OVSTunnel depending on whether you configure a bridge, port, an internal
  61       port, a bond or a tunnel. This is a required option.
  62
  63     - ovs_ports: This option specifies all the ports that belong to a bridge.
  64
  65     - ovs_bridge: This options specifies a bridge to which a port belongs.
  66       This is a required option for a port.
  67
  68     - ovs_bonds: This option specifies the list of physical interfaces to be
  69       bonded together.
  70
  71     - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
  72       For example, "gre", "vxlan", etc.
  73
  74     - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
  75       used to specify the tunnel options like remote_ip, key, etc.
  76
  77     - ovs_options: This option lets you add extra arguments to a ovs-vsctl
  78       command. See examples.
  79
  80     - ovs_extra: This option lets you run additional ovs-vsctl commands,
  81       separated by "--" (double dash). Variables can be part of the "ovs_extra"
  82       option. You can provide all the standard environmental variables
  83       described in the interfaces(5) man page. You can also pass shell
  84       commands.
  85
  86 More implementation specific details can be seen in the examples.
  87
  88 Examples:
  89 --------
  90 ex 1: A standalone bridge.
  91
  92 allow-ovs br0
  93 iface br0 inet static
  94     address 192.168.1.1
  95     netmask 255.255.255.0
  96     ovs_type OVSBridge
  97
  98 ex 2: A bridge with one port.
  99
 100 allow-ovs br0
 101 iface br0 inet dhcp
 102     ovs_type OVSBridge
 103     ovs_ports eth0
 104
 105 allow-br0 eth0
 106 iface eth0 inet manual
 107     ovs_bridge br0
 108     ovs_type OVSPort
 109
 110 ex 3: A bridge with multiple physical ports.
 111
 112 allow-ovs br0
 113 iface br0 inet dhcp
 114     ovs_type OVSBridge
 115     ovs_ports eth0 eth1
 116
 117 allow-br0 eth0
 118 iface eth0 inet manual
 119     ovs_bridge br0
 120     ovs_type OVSPort
 121
 122 allow-br0 eth1
 123 iface eth1 inet manual
 124     ovs_bridge br0
 125     ovs_type OVSPort
 126
 127 ex 4: A bridge with an OVS internal port.
 128
 129 allow-ovs br1
 130 iface br1 inet static
 131     address 192.168.1.1
 132     netmask 255.255.255.0
 133     ovs_type OVSBridge
 134     ovs_ports vlan100
 135
 136 allow-br1 vlan100
 137 iface vlan100 inet manual
 138     ovs_bridge br1
 139     ovs_type OVSIntPort
 140     ovs_options tag=100
 141     ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)
 142
 143 ex 5: Bonding.
 144
 145 allow-ovs br2
 146 iface br2 inet static
 147     address 192.170.1.1
 148     netmask 255.255.255.0
 149     ovs_type OVSBridge
 150     ovs_ports bond0
 151
 152 allow-br2 bond0
 153 iface bond0 inet manual
 154     ovs_bridge br2
 155     ovs_type OVSBond
 156     ovs_bonds eth2 eth3
 157     ovs_options bond_mode=balance-tcp lacp=active
 158
 159 ex 6: Tunnel.
 160
 161 allow-ovs br1
 162 iface br1 inet static
 163     address 192.168.1.1
 164     netmask 255.255.255.0
 165     ovs_type OVSBridge
 166     ovs_ports gre1
 167
 168 allow-br1 gre1
 169 iface gre1 inet manual
 170     ovs_bridge br1
 171     ovs_type OVSTunnel
 172     ovs_tunnel_type gre
 173     ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1
 174
 175 ex 7: Create and destroy bridges.
 176
 177 ifup --allow=ovs $list_of_bridges
 178 ifdown --allow=ovs $list_of_bridges