@@ -879,7 +879,7 @@ Bug Reporting:
Please report problems to bugs@openvswitch.org.
-[INSTALL.userspace.md]:INSTALL.userspace.md
+[INSTALL.userspace.rst]:INSTALL.userspace.rst
[INSTALL.rst]:INSTALL.rst
[DPDK Linux GSG]: http://www.dpdk.org/doc/guides/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-igb-uioor-vfio-modules
[DPDK Docs]: http://dpdk.org/doc
@@ -31,8 +31,8 @@ As all executables installed with pkgsrc are placed in `/usr/pkg/bin/`
directory, it might be a good idea to add it to your PATH.
Open vSwitch on NetBSD is currently "userspace switch" implementation
-in the sense described in [INSTALL.userspace.md] and [PORTING.md].
+in the sense described in [INSTALL.userspace.rst] and [PORTING.md].
[INSTALL.rst]:INSTALL.rst
-[INSTALL.userspace.md]:INSTALL.userspace.md
+[INSTALL.userspace.rst]:INSTALL.userspace.rst
[PORTING.md]:PORTING.md
@@ -80,8 +80,7 @@ vSwitch distribution or to use the kernel module built into the Linux kernel
are not available in the Open vSwitch kernel datapath that ships as part of the
upstream Linux kernel?" for more information on this trade-off. You may also
use the userspace-only implementation, at some cost in features and performance
-(see the `userspace installation guide <INSTALL.userspace.md>`__ for
-details).
+(see the `userspace installation guide <INSTALL.userspace.md>`__ for details).
To compile the kernel module on Linux, you must also install the
following:
deleted file mode 100644
@@ -1,86 +0,0 @@
-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.rst].
-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`.
-
-On FreeBSD and NetBSD, the userspace switch additionally requires the
-kernel tap(4) driver to be available, either built into the kernel or
-loaded as a module.
-
-Using the Userspace Datapath with ovs-vswitchd
-----------------------------------------------
-
-To use ovs-vswitchd in userspace mode, create a bridge with datapath_type
-"netdev" in the configuration database. For example:
-
- ovs-vsctl add-br br0
- ovs-vsctl set bridge br0 datapath_type=netdev
- ovs-vsctl add-port br0 eth0
- ovs-vsctl add-port br0 eth1
- ovs-vsctl add-port br0 eth2
-
-ovs-vswitchd will create a TAP device as the bridge's local interface,
-named the same as the bridge, as well as for each configured internal
-interface.
-
-Currently, on FreeBSD, the functionality required for in-band control
-support is not implemented. To avoid related errors, you can disable
-the in-band support with the following command.
-
- ovs-vsctl set bridge br0 other_config:disable-in-band=true
-
-Firewall Rules
---------------
-
-On Linux, when a physical interface is in use by the userspace
-datapath, packets received on the interface still also pass into the
-kernel TCP/IP stack. This can cause surprising and incorrect
-behavior. You can use "iptables" to avoid this behavior, by using it
-to drop received packets. For example, to drop packets received on
-eth0:
-
- iptables -A INPUT -i eth0 -j DROP
- iptables -A FORWARD -i eth0 -j DROP
-
-Other settings
---------------
-
-On NetBSD, depending on your network topology and applications, the
-following configuration might help. See sysctl(7).
-
- sysctl -w net.inet.ip.checkinterface=1
-
-Bug Reporting
--------------
-
-Please report problems to bugs@openvswitch.org.
-
-[INSTALL.rst]:INSTALL.rst
new file mode 100644
@@ -0,0 +1,101 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ ======= Heading 0 (reserved for the title in a document)
+ ------- Heading 1
+ ~~~~~~~ Heading 2
+ +++++++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+===================================
+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.
+
+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.
+
+.. warning::
+ The userspace-only mode of Open vSwitch is considered experimental. It has
+ not been thoroughly tested.
+
+Building and Installing
+-----------------------
+
+The requirements and procedure for building, installing, and configuring Open
+vSwitch are the same as those given in the `installation guide
+<INSTALL.rst>`__. 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``.
+
+On FreeBSD and NetBSD, the userspace switch additionally requires the kernel
+tap(4) driver to be available, either built into the kernel or loaded as a
+module.
+
+Using the Userspace Datapath with ovs-vswitchd
+----------------------------------------------
+
+To use ovs-vswitchd in userspace mode, create a bridge with
+``datapath_type=netdev`` in the configuration database. For example:::
+
+ $ ovs-vsctl add-br br0
+ $ ovs-vsctl set bridge br0 datapath_type=netdev
+ $ ovs-vsctl add-port br0 eth0
+ $ ovs-vsctl add-port br0 eth1
+ $ ovs-vsctl add-port br0 eth2
+
+ovs-vswitchd will create a TAP device as the bridge's local interface, named
+the same as the bridge, as well as for each configured internal interface.
+
+Currently, on FreeBSD, the functionality required for in-band control support
+is not implemented. To avoid related errors, you can disable the in-band
+support with the following command:::
+
+ $ ovs-vsctl set bridge br0 other_config:disable-in-band=true
+
+Firewall Rules
+--------------
+
+On Linux, when a physical interface is in use by the userspace datapath,
+packets received on the interface still also pass into the kernel TCP/IP stack.
+This can cause surprising and incorrect behavior. You can use "iptables" to
+avoid this behavior, by using it to drop received packets. For example, to
+drop packets received on eth0:::
+
+ $ iptables -A INPUT -i eth0 -j DROP
+ $ iptables -A FORWARD -i eth0 -j DROP
+
+Other Settings
+--------------
+
+On NetBSD, depending on your network topology and applications, the following
+configuration might help. See sysctl(7).::
+
+ $ sysctl -w net.inet.ip.checkinterface=1
@@ -83,7 +83,7 @@ docs = \
INSTALL.SELinux.md \
INSTALL.SSL.md \
INSTALL.XenServer.md \
- INSTALL.userspace.md \
+ INSTALL.userspace.rst \
INSTALL.Windows.rst \
IntegrationGuide.md \
MAINTAINERS.md \
@@ -129,7 +129,7 @@ implementation built into Open vSwitch. This ought to work, without
writing any more code, as long as the netdev provider that you
implemented supports receiving packets. It yields poor performance,
however, because every packet passes through the ovs-vswitchd process.
-See [INSTALL.userspace.md] for instructions on how to configure a
+See [INSTALL.userspace.rst] for instructions on how to configure a
userspace switch.
If the userspace switch is not the right choice for your port, then
@@ -323,4 +323,4 @@ Questions
Please direct porting questions to dev@openvswitch.org. We will try
to use questions to improve this porting guide.
-[INSTALL.userspace.md]:INSTALL.userspace.md
+[INSTALL.userspace.rst]:INSTALL.userspace.rst
@@ -92,7 +92,7 @@ To use Open vSwitch...
- ...with Libvirt, read [INSTALL.Libvirt.md].
-- ...without using a kernel module, read [INSTALL.userspace.md].
+- ...without using a kernel module, read [INSTALL.userspace.rst].
- ...with DPDK, read [INSTALL.DPDK.rst].
@@ -125,7 +125,7 @@ bugs@openvswitch.org
[INSTALL.RHEL.md]:INSTALL.RHEL.md
[INSTALL.SELinux.md]:INSTALL.SELinux.md
[INSTALL.SSL.md]:INSTALL.SSL.md
-[INSTALL.userspace.md]:INSTALL.userspace.md
+[INSTALL.userspace.rst]:INSTALL.userspace.rst
[INSTALL.XenServer.md]:INSTALL.XenServer.md
[FAQ.md]:FAQ.md
[tutorial/Tutorial.md]:tutorial/Tutorial.md
Signed-off-by: Stephen Finucane <stephen@that.guru> --- INSTALL.DPDK-ADVANCED.md | 2 +- INSTALL.NetBSD.md | 4 +- INSTALL.rst | 3 +- INSTALL.userspace.md | 86 ---------------------------------------- INSTALL.userspace.rst | 101 +++++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- PORTING.md | 4 +- README.md | 4 +- 8 files changed, 110 insertions(+), 96 deletions(-) delete mode 100644 INSTALL.userspace.md create mode 100644 INSTALL.userspace.rst