INSTALL.userspace

   1               Using Open vSwitch without kernel support
   2               =========================================
   3
   4 Open vSwitch can operate, at a cost in performance, entirely in
   5 userspace, without assistance from a kernel module.  This file
   6 explains how to install Open vSwitch in such a mode.
   7
   8 The userspace-only mode of Open vSwitch is considered experimental.
   9 It has not been thoroughly tested.
  10
  11 This version of Open vSwitch should be built manually with "configure"
  12 and "make".  Debian packaging for Open vSwitch is also included, but
  13 it has not been recently tested, and so Debian packages are not a
  14 recommended way to use this version of Open vSwitch.
  15
  16 Building and Installing
  17 -----------------------
  18
  19 The requirements and procedure for building, installing, and
  20 configuring Open vSwitch are the same as those given in INSTALL.
  21 You may omit configuring, building, and installing the kernel module,
  22 and the related requirements.
  23
  24 On Linux, the userspace switch additionally requires the kernel
  25 TUN/TAP driver to be available, either built into the kernel or loaded
  26 as a module.  If you are not sure, check for a directory named
  27 /sys/class/misc/tun.  If it does not exist, then attempt to load the
  28 module with "modprobe tun".
  29
  30 The tun device must also exist as /dev/net/tun.  If it does not exist,
  31 then create /dev/net (if necessary) with "mkdir /dev/net", then create
  32 /dev/net/tun with "mknod /dev/net/tun c 10 200".
  33
  34 On FreeBSD and NetBSD, the userspace switch additionally requires the
  35 kernel tap(4) driver to be available, either built into the kernel or
  36 loaded as a module.
  37
  38 Using the Userspace Datapath with ovs-vswitchd
  39 ----------------------------------------------
  40
  41 To use ovs-vswitchd in userspace mode, create a bridge with datapath_type
  42 "netdev" in the configuration database.  For example:
  43
  44     ovs-vsctl add-br br0
  45     ovs-vsctl set bridge br0 datapath_type=netdev
  46     ovs-vsctl add-port br0 eth0
  47     ovs-vsctl add-port br0 eth1
  48     ovs-vsctl add-port br0 eth2
  49
  50 ovs-vswitchd will create a TAP device as the bridge's local interface,
  51 named the same as the bridge, as well as for each configured internal
  52 interface.
  53
  54 Currently, on FreeBSD, the functionality required for in-band control
  55 support is not implemented.  To avoid related errors, you can disable
  56 the in-band support with the following command.
  57
  58     ovs-vsctl set bridge br0 other_config:disable-in-band=true
  59
  60 Firewall Rules
  61 --------------
  62
  63 On Linux, when a physical interface is in use by the userspace
  64 datapath, packets received on the interface still also pass into the
  65 kernel TCP/IP stack.  This can cause surprising and incorrect
  66 behavior.  You can use "iptables" to avoid this behavior, by using it
  67 to drop received packets.  For example, to drop packets received on
  68 eth0:
  69
  70     iptables -A INPUT -i eth0 -j DROP
  71     iptables -A FORWARD -i eth0 -j DROP
  72
  73 Other settings
  74 --------------
  75
  76 On NetBSD, depending on your network topology and applications, the
  77 following configuration might help.  See sysctl(7).
  78
  79         sysctl net.inet.ip.checkinterface=1
  80
  81 Bug Reporting
  82 -------------
  83
  84 Please report problems to bugs@openvswitch.org.