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

diff --git a/INSTALL.bridge b/INSTALL.bridge
new file mode 100644 (file)
index 0000000..ec9e091
--- /dev/null
+++ b/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

diff --git a/README b/README
index 4f5882b2e8e9c9d7e3a846e2cfd9e5f01d87eca0..1fa27ba2bf24cf28c3564a83b220b0984567108a 100644 (file)
--- a/README
+++ b/README
@@ -65,6 +65,9 @@ What other documentation is available?
 
 To install Open vSwitch on a regular Linux machine, read INSTALL.Linux.
 
 
 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.
 
 To build RPMs for installing Open vSwitch on a Citrix XenServer host
 or resource pool, read INSTALL.XenServer.
 

diff --git a/vswitchd/ovs-brcompatd.8.in b/vswitchd/ovs-brcompatd.8.in
index ebd67028f3ca7ac1d8856eb157919f3bfe46b4e1..8df8498c3cde2a0b7a07bcb01611d670e438d66b 100644 (file)
--- a/vswitchd/ovs-brcompatd.8.in
+++ b/vswitchd/ovs-brcompatd.8.in
@@ -46,4 +46,4 @@ loaded.
 .BR ovs\-appctl (8),
 .BR ovs\-vswitchd (8),
 .BR ovs\-vswitchd.conf (5),
 .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.

diff --git a/vswitchd/ovs-vswitchd.8.in b/vswitchd/ovs-vswitchd.8.in
index 2585a20cbc664c87abe74a642046dc4b95a1eaf5..6941bdf5e51070afb831f4546764c8b6154f165c 100644 (file)
--- a/vswitchd/ovs-vswitchd.8.in
+++ b/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
 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
 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),
 .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.