INSTALL.bridge

   1               Replacing a Linux Bridge with Open vSwitch
   2               ==========================================
   3
   4 This file documents how Open vSwitch may be used as a drop-in
   5 replacement for a Linux kernel bridge in an environment that includes
   6 elements that are tightly tied to the Linux bridge tools
   7 (e.g. "brctl") and architecture.  We do not recommend using the
   8 approach described here outside such an environment, since the other
   9 tools included with Open vSwitch are easier to use and more
  10 general-purpose than the Linux bridging tools.
  11
  12 Installation Procedure
  13 ----------------------
  14
  15 The procedure below explains how to use the Open vSwitch bridge
  16 compatibility support.  This procedure is written from the perspective
  17 of a system administrator manually loading and starting Open vSwitch
  18 in bridge compatibility mode, but of course in practice one would want
  19 to update system scripts to follow these steps.
  20
  21 1. Build and install the Open vSwitch kernel modules and userspace
  22    programs as described in INSTALL.Linux.
  23
  24    It is important to run "make install", because some Open vSwitch
  25    programs expect to find files in locations selected at installation
  26    time.
  27
  28 2. Load both the openvswitch and brcompat kernel modules (which were
  29    built in step 1), e.g.:
  30
  31       % insmod datapath/linux-2.6/openvswitch_mod.ko
  32       % insmod datapath/linux-2.6/brcompat_mod.ko
  33
  34    These kernel modules cannot be loaded if the Linux bridge module is
  35    already loaded.  Thus, you may need to remove any existing bridges
  36    and unload the bridge module with "rmmod bridge" before you can do
  37    this.  In addition, if you edit your system configuration files to
  38    load these modules at boot time, it should happen before any bridge
  39    configuration (e.g. before any calls to "brctl" or "ifup" of any
  40    bridge interfaces), to ensure that the Open vSwitch kernel modules
  41    are loaded before the Linux kernel bridge module.
  42
  43 3. Create an initial ovs-vswitchd.conf file.  This file may be empty
  44    when ovs-vswitchd, or you may add any valid configuration
  45    directives to it (as described in ovs-vswitchd.conf(5)), but it
  46    must exist.
  47
  48    To create an empty configuration file:
  49
  50       % touch /etc/ovs-vswitchd.conf
  51
  52 4. Start ovs-vswitchd and ovs-brcompatd, e.g.:
  53
  54       % ovs-vswitchd -P -D -vANY:console:EMER /etc/ovs-vswitchd.conf
  55       % ovs-brcompatd -P -D -vANY:console:EMER /etc/ovs-vswitchd.conf
  56
  57 5. Now you should be able to manage the Open vSwitch using brctl and
  58    related tools.  For example, you can create an Open vSwitch bridge,
  59    add interfaces to it, then print information about bridges with the
  60    commands:
  61
  62       % brctl addbr br0
  63       % brctl addif br0 eth0
  64       % brctl addif br0 eth1
  65       % brctl show
  66
  67    Each of these commands actually uses or modifies the Open vSwitch
  68    configuration file, then notifies the ovs-vswitchd daemon of the
  69    change.  For example, after executing the commands above starting
  70    from an empty configuration file, "cat /etc/ovs-vswitchd.conf"
  71    should show that the configuration file now contains the following:
  72
  73       bridge.br0.port=br0
  74       bridge.br0.port=eth0
  75       bridge.br0.port=eth1