--- /dev/null
+ 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. 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