Replacing a Linux Bridge with Open vSwitch
              ==========================================

This file documents how Open vSwitch may be used as a drop-in
replacement for a Linux kernel bridge in an environment that includes
elements that are tightly tied to the Linux bridge tools
(e.g. "brctl") and architecture.  We do not recommend using the
approach described here outside such an environment, since the other
tools included with Open vSwitch are easier to use and more
general-purpose than the Linux bridging tools.

Installation Procedure
----------------------

The procedure below explains how to use the Open vSwitch bridge
compatibility support.  This procedure is written from the perspective
of a system administrator manually loading and starting Open vSwitch
in bridge compatibility mode, but of course in practice one would want
to update system scripts to follow these steps.

1. Build and install the Open vSwitch kernel modules and userspace
   programs as described in INSTALL.Linux.

   It is important to run "make install", because some Open vSwitch
   programs expect to find files in locations selected at installation
   time.

2. Load both the openvswitch and brcompat kernel modules (which were
   built in step 1), e.g.:

      % insmod datapath/linux-2.6/openvswitch_mod.ko
      % insmod datapath/linux-2.6/brcompat_mod.ko

   These kernel modules cannot be loaded if the Linux bridge module is
   already loaded.  Thus, you may need to remove any existing bridges
   and unload the bridge module with "rmmod bridge" before you can do
   this.  In addition, if you edit your system configuration files to
   load these modules at boot time, it should happen before any bridge
   configuration (e.g. before any calls to "brctl" or "ifup" of any
   bridge interfaces), to ensure that the Open vSwitch kernel modules
   are loaded before the Linux kernel bridge module.

3. Create an initial ovs-vswitchd.conf file.  This file may be empty
   when ovs-vswitchd, or you may add any valid configuration
   directives to it (as described in ovs-vswitchd.conf(5)), but it
   must exist.

   To create an empty configuration file:

      % touch /etc/ovs-vswitchd.conf

4. Start ovs-vswitchd and ovs-brcompatd, e.g.:

      % ovs-vswitchd -P -D -vANY:console:EMER /etc/ovs-vswitchd.conf
      % ovs-brcompatd -P -D -vANY:console:EMER /etc/ovs-vswitchd.conf

5. Now you should be able to manage the Open vSwitch using brctl and
   related tools.  For example, you can create an Open vSwitch bridge,
   add interfaces to it, then print information about bridges with the
   commands:

      % brctl addbr br0
      % brctl addif br0 eth0
      % brctl addif br0 eth1
      % brctl show

   Each of these commands actually uses or modifies the Open vSwitch
   configuration file, then notifies the ovs-vswitchd daemon of the
   change.  For example, after executing the commands above starting
   from an empty configuration file, "cat /etc/ovs-vswitchd.conf"
   should show that the configuration file now contains the following:

      bridge.br0.port=br0
      bridge.br0.port=eth0
      bridge.br0.port=eth1