INSTALL.userspace.rst

   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
  66 ``datapath_type=netdev`` in the configuration database.  For example:::
  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
  79 support with the following command:::
  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
  90 drop packets received on eth0:::
  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.