[mirror_ovs.git] / INSTALL.userspace.rst

..
      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

Bug Reporting
-------------

Please report problems to bugs@openvswitch.org.
Commit	Line	Data
8eb443d4 SF	1	..
	2	Licensed under the Apache License, Version 2.0 (the "License"); you may
	3	not use this file except in compliance with the License. You may obtain
	4	a copy of the License at
	5
	6	http://www.apache.org/licenses/LICENSE-2.0
	7
	8	Unless required by applicable law or agreed to in writing, software
	9	distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	10	WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	11	License for the specific language governing permissions and limitations
	12	under the License.
	13
	14	Convention for heading levels in Open vSwitch documentation:
	15
	16	======= Heading 0 (reserved for the title in a document)
	17	------- Heading 1
	18	~~~~~~~ Heading 2
	19	+++++++ Heading 3
	20	''''''' Heading 4
	21
	22	Avoid deeper levels because they do not render well.
	23
	24	===================================
	25	Open vSwitch Without Kernel Support
	26	===================================
	27
	28	Open vSwitch can operate, at a cost in performance, entirely in userspace,
	29	without assistance from a kernel module. This file explains how to install
	30	Open vSwitch in such a mode.
	31
	32	This version of Open vSwitch should be built manually with ``configure`` and
	33	``make``. Debian packaging for Open vSwitch is also included, but it has not
	34	been recently tested, and so Debian packages are not a recommended way to use
	35	this version of Open vSwitch.
	36
	37	.. warning::
	38	The userspace-only mode of Open vSwitch is considered experimental. It has
	39	not been thoroughly tested.
	40
	41	Building and Installing
	42	-----------------------
	43
	44	The requirements and procedure for building, installing, and configuring Open
	45	vSwitch are the same as those given in the `installation guide
	46	<INSTALL.rst>`__. You may omit configuring, building, and installing the
	47	kernel module, and the related requirements.
	48
	49	On Linux, the userspace switch additionally requires the kernel TUN/TAP driver
	50	to be available, either built into the kernel or loaded as a module. If you
	51	are not sure, check for a directory named ``/sys/class/misc/tun``. If it does
	52	not exist, then attempt to load the module with ``modprobe tun``.
	53
	54	The tun device must also exist as ``/dev/net/tun``. If it does not exist, then
	55	create ``/dev/net`` (if necessary) with ``mkdir /dev/net``, then create
	56	``/dev/net/tun`` with ``mknod /dev/net/tun c 10 200``.
	57
	58	On FreeBSD and NetBSD, the userspace switch additionally requires the kernel
	59	tap(4) driver to be available, either built into the kernel or loaded as a
	60	module.
	61
	62	Using the Userspace Datapath with ovs-vswitchd
	63	----------------------------------------------
	64
65	To use ovs-vswitchd in userspace mode, create a bridge with
dc76953f	66	``datapath_type=netdev`` in the configuration database. For example::
8eb443d4 SF	67
	68	$ ovs-vsctl add-br br0
	69	$ ovs-vsctl set bridge br0 datapath_type=netdev
	70	$ ovs-vsctl add-port br0 eth0
	71	$ ovs-vsctl add-port br0 eth1
	72	$ ovs-vsctl add-port br0 eth2
	73
	74	ovs-vswitchd will create a TAP device as the bridge's local interface, named
	75	the same as the bridge, as well as for each configured internal interface.
	76
	77	Currently, on FreeBSD, the functionality required for in-band control support
	78	is not implemented. To avoid related errors, you can disable the in-band
dc76953f	79	support with the following command::
8eb443d4 SF	80
	81	$ ovs-vsctl set bridge br0 other_config:disable-in-band=true
	82
	83	Firewall Rules
	84	--------------
	85
	86	On Linux, when a physical interface is in use by the userspace datapath,
	87	packets received on the interface still also pass into the kernel TCP/IP stack.
	88	This can cause surprising and incorrect behavior. You can use "iptables" to
	89	avoid this behavior, by using it to drop received packets. For example, to
dc76953f	90	drop packets received on eth0::
8eb443d4 SF	91
	92	$ iptables -A INPUT -i eth0 -j DROP
	93	$ iptables -A FORWARD -i eth0 -j DROP
	94
	95	Other Settings
	96	--------------
	97
	98	On NetBSD, depending on your network topology and applications, the following
	99	configuration might help. See sysctl(7).::
	100
	101	$ sysctl -w net.inet.ip.checkinterface=1
	102
	103	Bug Reporting
	104	-------------
	105
	106	Please report problems to bugs@openvswitch.org.