From: Ben Pfaff <blp@nicira.com>
Date: Wed, 18 Nov 2009 20:57:18 +0000 (-0800)
Subject: Document userspace switch.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d377243b8557ae8e6c1d374d76b6ee29fd61ceb4;p=openvswitch

Document userspace switch.
---

diff --git a/INSTALL.Linux b/INSTALL.Linux
index 891fd230..7090ce67 100644
--- a/INSTALL.Linux
+++ b/INSTALL.Linux
@@ -27,8 +27,11 @@ you will need the following software:
       connections from an Open vSwitch to an OpenFlow controller.  To
       enable, configure with --enable-ssl=yes.
 
-To compile the kernel module (which is required for operation), you
-must also install the following:
+To compile the kernel module, you must also install the following.  If
+you cannot build or install the kernel module, you may use the
+userspace-only implementation, at a cost in performance.  The
+userspace implementation may also lack some features.  Refer to
+INSTALL.userspace for more information.
 
     - A supported Linux kernel version.  Please refer to README for a
       list of supported versions.
diff --git a/INSTALL.userspace b/INSTALL.userspace
new file mode 100644
index 00000000..a0c6a266
--- /dev/null
+++ b/INSTALL.userspace
@@ -0,0 +1,51 @@
+              Using Open vSwitch without kernel support
+              =========================================
+
+Open vSwitch can operate, at a cost in performance, entirely in
+userspace, without assistance from a kernel module.  This file
+explains how to install Open vSwitch in such a mode.
+
+The userspace-only mode of Open vSwitch is considered experimental.
+It has not been thoroughly tested.
+
+This version of Open vSwitch should be built manually with "configure"
+and "make".  Debian packaging for Open vSwitch is also included, but
+it has not been recently tested, and so Debian packages are not a
+recommended way to use this version of Open vSwitch.
+
+Building and Installing
+-----------------------
+
+The requirements and procedure for building, installing, and
+configuring Open vSwitch are the same as those given in INSTALL.Linux.
+You may omit configuring, building, and installing the kernel module,
+and the related requirements.
+
+On Linux, the userspace switch additionally requires the kernel
+TUN/TAP driver to be available, either built into the kernel or loaded
+as a module.  If you are not sure, check for a directory named
+/sys/class/misc/tun.  If it does not exist, then attempt to load the
+module with "modprobe tun".
+
+The tun device must also exist as /dev/net/tun.  If it does not exist,
+then create /dev/net (if necessary) with "mkdir /dev/net", then create
+/dev/net/tun with "mknod /dev/net/tun c 10 200".
+
+Using the Userspace Datapath
+----------------------------
+
+To use ovs-vswitchd in userspace mode, give the bridge a name that
+begins with "netdev:" in the configuration file.  For example:
+
+    bridge.netdev:br0.port=eth0
+    bridge.netdev:br0.port=eth1
+    bridge.netdev:br0.port=eth2
+
+ovs-vswitchd will create a TAP device as the bridge's local interface,
+named the same as the bridge minus the "netdev:" prefix, as well as
+for each configured internal interface.
+
+Bug Reporting
+-------------
+
+Please report problems to bugs@openvswitch.org.
diff --git a/Makefile.am b/Makefile.am
index 60fd21ef..add0e72a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -28,6 +28,7 @@ CLEANFILES =
 DISTCLEANFILES =
 EXTRA_DIST = INSTALL.bridge \
 	INSTALL.Linux \
+	INSTALL.userspace \
 	INSTALL.OpenFlow \
 	INSTALL.SSL \
 	INSTALL.XenServer 
diff --git a/README b/README
index 2bdbfdcf..7871c763 100644
--- a/README
+++ b/README
@@ -28,9 +28,15 @@ vSwitch supports the following features:
     * Support for OpenFlow
     * Compatibility layer for the Linux bridging code
 
-Open vSwitch supports Linux 2.6.15 and up, with testing focused on
-2.6.18 with Centos and Xen patches and version 2.6.26 from kernel.org.
-Open vSwitch also has special support for Citrix XenServer hosts.
+The included Linux kernel module supports Linux 2.6.15 and up, with
+testing focused on 2.6.18 with Centos and Xen patches and version
+2.6.26 from kernel.org.  Open vSwitch also has special support for
+Citrix XenServer hosts.
+
+Open vSwitch can also operate, at a cost in performance, entirely in
+userspace, without assistance from a kernel module.  This userspace
+implementation should be easier to port than the kernel-based switch.
+It is considered experimental.
 
 What's here?
 ------------
@@ -85,6 +91,9 @@ read INSTALL.bridge.
 To build RPMs for installing Open vSwitch on a Citrix XenServer host
 or resource pool, read INSTALL.XenServer.
 
+To install Open vSwitch without using a kernel module, read
+INSTALL.userspace.
+
 To learn set up SSL support for Open vSwitch, read INSTALL.SSL.
 
 Each Open vSwitch userspace program is accompanied by a manpage.  Many