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 recommend directly using the
   8 management tools provided with Open vSwitch rather than these
   9 compatibility hooks for environments that are not tightly tied to the
  10 Linux bridging tools; they are more efficient and better reflect the
  11 actual operation and status.
  12
  13
  14 Installation Procedure
  15 ----------------------
  16
  17 The procedure below explains how to use the Open vSwitch bridge
  18 compatibility support.  This procedure is written from the perspective
  19 of a system administrator manually loading and starting Open vSwitch
  20 in bridge compatibility mode, but of course in practice one would want
  21 to update system scripts to follow these steps.
  22
  23 1. Build and install the Open vSwitch kernel modules and userspace
  24    programs as described in INSTALL.Linux.
  25
  26    It is important to run "make install", because some Open vSwitch
  27    programs expect to find files in locations selected at installation
  28    time.
  29
  30 2. Load both the openvswitch and brcompat kernel modules (which were
  31    built in step 1), e.g.:
  32
  33       % insmod datapath/linux-2.6/openvswitch_mod.ko
  34       % insmod datapath/linux-2.6/brcompat_mod.ko
  35
  36    These kernel modules cannot be loaded if the Linux bridge module is
  37    already loaded.  Thus, you may need to remove any existing bridges
  38    and unload the bridge module with "rmmod bridge" before you can do
  39    this.  In addition, if you edit your system configuration files to
  40    load these modules at boot time, it should happen before any bridge
  41    configuration (e.g. before any calls to "brctl" or "ifup" of any
  42    bridge interfaces), to ensure that the Open vSwitch kernel modules
  43    are loaded before the Linux kernel bridge module.
  44
  45 3. Start ovsdb-server, ovs-vswitchd, and ovs-brcompatd, e.g.:
  46
  47       % ovsdb-server /etc/ovs-vswitchd.conf.db \
  48                 --remote=punix:/var/run/ovsdb-server
  49
  50       % ovs-vswitchd --pidfile --detach -vANY:console:EMER \
  51                 unix:/var/run/ovsdb-server
  52
  53       % ovs-brcompatd --pidfile --detach -vANY:console:EMER \
  54                 unix:/var/run/ovsdb-server
  55
  56 5. Now you should be able to manage the Open vSwitch using brctl and
  57    related tools.  For example, you can create an Open vSwitch bridge,
  58    add interfaces to it, then print information about bridges with the
  59    commands:
  60
  61       % brctl addbr br0
  62       % brctl addif br0 eth0
  63       % brctl addif br0 eth1
  64       % brctl show
  65
  66    Each of these commands actually uses or modifies the Open vSwitch
  67    configuration database, then notifies the ovs-vswitchd daemon of
  68    the change.  For example, after executing the commands above
  69    starting from an empty configuration file, "ovs-vsctl list-ports
  70    br0" should show that bridge br0 contains two ports, eth0 and eth1.