From d377243b8557ae8e6c1d374d76b6ee29fd61ceb4 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Wed, 18 Nov 2009 12:57:18 -0800 Subject: [PATCH] Document userspace switch. --- INSTALL.Linux | 7 +++++-- INSTALL.userspace | 51 +++++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 1 + README | 15 +++++++++++--- 4 files changed, 69 insertions(+), 5 deletions(-) create mode 100644 INSTALL.userspace diff --git a/INSTALL.Linux b/INSTALL.Linux index 891fd2307..7090ce672 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 000000000..a0c6a266c --- /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 60fd21efc..add0e72a9 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 2bdbfdcf9..7871c763c 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 -- 2.43.0