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 Installation Procedure
  14 ----------------------
  15
  16 The procedure below explains how to use the Open vSwitch bridge
  17 compatibility support.  This procedure is written from the perspective
  18 of a system administrator manually loading and starting Open vSwitch
  19 in bridge compatibility mode, but of course in practice one would want
  20 to update system scripts to follow these steps.  If you do edit your
  21 system configuration files to start Open vSwitch at boot time, make
  22 sure that it starts up before any bridge configuration (e.g. before
  23 any calls to "brctl" or "ifup" of any bridge interfaces), to ensure
  24 that the Open vSwitch kernel modules are loaded before the Linux
  25 kernel bridge module.
  26
  27 1. Build, install, and start up the Open vSwitch kernel modules and
  28    userspace programs as described in INSTALL.Linux.
  29
  30    It is important to run "make install", because some Open vSwitch
  31    programs expect to find files in locations selected at installation
  32    time.  The instructions below assume that files are installed in
  33    their default locations, under /usr/local.
  34
  35 2. Load the brcompat kernel module (which was built in step 1), e.g.:
  36
  37       % insmod datapath/linux-2.6/brcompat_mod.ko
  38
  39    (openvswitch_mod.ko should already have been loaded.)
  40
  41 3. Start ovs-brcompatd:
  42
  43       % ovs-brcompatd --pidfile --detach -vANY:console:EMER \
  44                 unix:/usr/local/var/run/openvswitch/db.sock
  45
  46    (ovsdb-server and ovs-vswitchd should already have been loaded.)
  47
  48 4. Now you should be able to manage the Open vSwitch using brctl and
  49    related tools.  For example, you can create an Open vSwitch bridge,
  50    add interfaces to it, then print information about bridges with the
  51    commands:
  52
  53       % brctl addbr br0
  54       % brctl addif br0 eth0
  55       % brctl addif br0 eth1
  56       % brctl show
  57
  58    Each of these commands actually uses or modifies the Open vSwitch
  59    configuration database, then notifies the ovs-vswitchd daemon of
  60    the change.  For example, after executing the commands above
  61    starting from an empty configuration file, "ovs-vsctl list-ports
  62    br0" should show that bridge br0 contains two ports, eth0 and eth1.