initial import

[ovs.git] / debian / openvswitch-switch.README.Debian

Debian network scripts integration
----------------------------------
This package lets a user to optionally configure Open vSwitch bridges
and ports from /etc/network/interfaces. Please refer to the interfaces(5)
manpage for more details regarding /etc/network/interfaces.

The stanzas that configure the OVS bridges should begin with "allow-ovs"
followed by name of the bridge. Here is an example.
allow-ovs br0

The stanzas that configure the OVS ports should begin with
"allow-${bridge-name}" followed by name of the port. Here is an example.
allow-br0 eth0

The following OVS specific "command" options are supported:

    - ovs_type: This can either be OVSBridge, OVSPort, OVSIntPort, OVSBond,
      OVSPatchPort or OVSTunnel depending on whether you configure a bridge,
      port, an internal port, a bond, a patch port or a tunnel. This is a
      required option.

    - ovs_ports: This option specifies all the ports that belong to a bridge.

    - ovs_bridge: This options specifies a bridge to which a port belongs.
      This is a required option for a port.

    - ovs_bonds: This option specifies the list of physical interfaces to be
      bonded together.

    - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies
      the patch's peer on the other bridge.

    - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
      For example, "gre", "vxlan", etc.

    - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
      used to specify the tunnel options like remote_ip, key, etc.

    - ovs_options: This option lets you add extra arguments to a ovs-vsctl
      command. See examples.

    - ovs_extra: This option lets you run additional ovs-vsctl commands,
      separated by "--" (double dash). Variables can be part of the "ovs_extra"
      option. You can provide all the standard environmental variables
      described in the interfaces(5) man page. You can also pass shell
      commands.

More implementation specific details can be seen in the examples.

Examples:
--------
ex 1: A standalone bridge.

allow-ovs br0
iface br0 inet static
    address 192.168.1.1
    netmask 255.255.255.0
    ovs_type OVSBridge

ex 2: A bridge with one port.

allow-ovs br0
iface br0 inet dhcp
    ovs_type OVSBridge
    ovs_ports eth0

allow-br0 eth0
iface eth0 inet manual
    ovs_bridge br0
    ovs_type OVSPort

ex 3: A bridge with multiple physical ports.

allow-ovs br0
iface br0 inet dhcp
    ovs_type OVSBridge
    ovs_ports eth0 eth1

allow-br0 eth0
iface eth0 inet manual
    ovs_bridge br0
    ovs_type OVSPort

allow-br0 eth1
iface eth1 inet manual
    ovs_bridge br0
    ovs_type OVSPort

ex 4: A bridge with an OVS internal port.

allow-ovs br1
iface br1 inet static
    address 192.168.1.1
    netmask 255.255.255.0
    ovs_type OVSBridge
    ovs_ports vlan100

allow-br1 vlan100
iface vlan100 inet manual
    ovs_bridge br1
    ovs_type OVSIntPort
    ovs_options tag=100
    ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)

ex 5: Bonding.

allow-ovs br2
iface br2 inet static
    address 192.170.1.1
    netmask 255.255.255.0
    ovs_type OVSBridge
    ovs_ports bond0

allow-br2 bond0
iface bond0 inet manual
    ovs_bridge br2
    ovs_type OVSBond
    ovs_bonds eth2 eth3
    ovs_options bond_mode=balance-tcp lacp=active

ex 6: Patch ports.

allow-ovs br0
iface br0 inet manual
    ovs_type OVSBridge
    ovs_ports patch0

allow-br0 patch0
iface patch0 inet manual
    ovs_bridge br0
    ovs_type OVSPatchPort
    ovs_patch_peer patch1

allow-ovs br1
iface br1 inet manual
    ovs_type OVSBridge
    ovs_ports patch1

allow-br1 patch1
iface patch1 inet manual
    ovs_bridge br1
    ovs_type OVSPatchPort
    ovs_patch_peer patch0

ex 7: Tunnel.

allow-ovs br1
iface br1 inet static
    address 192.168.1.1
    netmask 255.255.255.0
    ovs_type OVSBridge
    ovs_ports gre1

allow-br1 gre1
iface gre1 inet manual
    ovs_bridge br1
    ovs_type OVSTunnel
    ovs_tunnel_type gre
    ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1

ex 8: Create and destroy bridges.

ifup --allow=ovs $list_of_bridges
ifdown --allow=ovs $list_of_bridges

ex 9: Bond + Bridge + VLAN + MTU

allow-bond0 eth2
iface eth2 inet manual
    ovs_type OVSPort
    ovs_bonds bond0
    ovs_mtu 9000

# Interface eth3
#auto eth3
allow-bond0 eth3
iface eth3 inet manual
    ovs_type OVSPort
    ovs_bonds bond0
    ovs_mtu 9000

# Interface bond0
auto bond0
allow-br-ex bond0
iface bond0 inet manual
    ovs_bridge br-ex 
    ovs_type OVSBond
    ovs_bonds eth2 eth3
    ovs_options bond_mode=balance-tcp lacp=active other_config:lacp-time=fast
    ovs_mtu 9000
    up ifup eth2
    up ifup eth3
    up ovs-vsctl set Interface ${IFACE} mtu_request=${IF_OVS_MTU}

# Interface vlan81
auto vlan871
allow-br-ex vlan81
iface vlan81 inet static
    ovs_type OVSIntPort
    ovs_bridge br-ex
    ovs_options tag=81
    ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)-${IFACE}-vif
    ovs_mtu 9000
    address 192.168.100.2
    network 192.168.100.0
    netmask 255.255.255.0
    broadcast 192.168.100.255
    gateway 192.168.100.1

# Interface br-ex
auto br-ex
allow-ovs br-ex
iface br-ex inet manual
        ovs_type OVSBridge
        ovs_ports bond0 vlan81
        ovs_mtu 9000


Notes on dependencies:
---------------------

openvswitch-switch depends on $network, $named $remote_fs and $syslog to start.
This creates some startup dependency issues.

* Since openvswitch utilities are placed in /usr and /usr can be mounted
through NFS, openvswitch has to start after it.  But if a user uses openvswitch
for all his networking needs and hence to mount NFS, there will be a deadlock.
So, if /usr is mounted through NFS and openvswitch is used for all networking,
the administrator should figure out a way to mount NFS before starting OVS.
One way to do this is in initramfs.

* Since openvswitch starts after $network, $remote_fs and $syslog, any startup
script that depends on openvswitch but starts before it, needs to be changed
to depend on openvswitch-switch too.

* Ideally, an admin should not add openvswitch bridges in the 'auto'
section of the 'interfaces' file.  This is because, when ifupdown starts
working on bridges listed in 'auto', openvswitch has not yet started.

But, if the admin wants to go down this route and adds openvswitch bridges
in the 'auto' section, openvswitch-switch will forcefully be started when
ifupdown kicks in. In a case like this, the admin needs to make sure that /usr
has already been mounted and that a remote $syslog (if used) is ready to
receive openvswitch logs.

 -- Ben Pfaff <pfaffben@debian.org>, Fri, 23 Dec 2016 09:45:56 -0800