Document how to use Open vSwitch as a replacement for the Linux bridge.

INSTALL.bridge

@@ -0,0 +1,75 @@
+              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

README

@@ -65,6 +65,9 @@ What other documentation is available?
 
 To install Open vSwitch on a regular Linux machine, read INSTALL.Linux.
 
+To use Open vSwitch as a drop-in replacement for the Linux bridge,
+read INSTALL.bridge.
+
 To build RPMs for installing Open vSwitch on a Citrix XenServer host
 or resource pool, read INSTALL.XenServer.
 

vswitchd/ovs-brcompatd.8.in

@@ -46,4 +46,4 @@ loaded.
 .BR ovs\-appctl (8),
 .BR ovs\-vswitchd (8),
 .BR ovs\-vswitchd.conf (5),
-\fBINSTALL\fR in the Open vSwitch distribution.
+\fBINSTALL.bridge\fR in the Open vSwitch distribution.

vswitchd/ovs-vswitchd.8.in

@@ -56,7 +56,7 @@ to modify datapaths when \fBovs\-vswitchd\fR is running can interfere with
 its operation.  (\fBovs\-dpctl\fR may still be useful for diagnostics.)
 .PP
 An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR
-to be useful.  Please refer to the \fBINSTALL\fR file included in the
+to be useful.  Please refer to the \fBINSTALL.Linux\fR file included in the
 Open vSwitch distribution for instructions on how to build and load
 the Open vSwitch kernel module.
 .PP
@@ -84,4 +84,4 @@ Only Linux 2.6.\fIx\fR is currently supported.
 .BR ovs\-appctl (8),
 .BR ovs\-vswitchd.conf (5),
 .BR ovs\-brcompatd (8),
-\fBINSTALL\fR in the Open vSwitch distribution.
+\fBINSTALL.Linux\fR in the Open vSwitch distribution.