INSTALL.Docker.md

   1 How to Use Open vSwitch with Docker
   2 ====================================
   3
   4 This document describes how to use Open vSwitch with Docker 1.2.0 or
   5 later.  This document assumes that you followed [INSTALL](INSTALL.md)
   6 or installed Open vSwitch from distribution packaging such as a .deb
   7 or .rpm.  Consult www.docker.com for instructions on how to install
   8 Docker.
   9
  10 Limitations
  11 -----------
  12 Currently there is no native integration of Open vSwitch in Docker, i.e.,
  13 one cannot use the Docker client to automatically add a container's
  14 network interface to an Open vSwitch bridge during the creation of the
  15 container.  This document describes addition of new network interfaces to an
  16 already created container and in turn attaching that interface as a port to an
  17 Open vSwitch bridge.
  18
  19 Setup
  20 -----
  21 * Create your container, e.g.:
  22
  23 ```
  24 % docker run -d ubuntu:14.04 /bin/sh -c \
  25 "while true; do echo hello world; sleep 1; done"
  26 ```
  27
  28 The above command creates a container with one network interface 'eth0'
  29 and attaches it to a Linux bridge called 'docker0'.  'eth0' by default
  30 gets an IP address in the 172.17.0.0/16 space.  Docker sets up iptables
  31 NAT rules to let this interface talk to the outside world.  Also since
  32 it is connected to 'docker0' bridge, it can talk to all other containers
  33 connected to the same bridge.  If you prefer that no network interface be
  34 created by default, you can start your container with
  35 the option '--net=none', e,g.:
  36
  37 ```
  38 % docker run -d --net=none ubuntu:14.04 /bin/sh -c \
  39 "while true; do echo hello world; sleep 1; done"
  40 ```
  41
  42 The above commands will return a container id.  You will need to pass this
  43 value to the utility 'ovs-docker' to create network interfaces attached to an
  44 Open vSwitch bridge as a port.  This document will reference this value
  45 as $CONTAINER_ID in the next steps.
  46
  47 * Add a new network interface to the container and attach it to an Open vSwitch
  48   bridge.  e.g.:
  49
  50 `% ovs-docker add-port br-int eth1 $CONTAINER_ID`
  51
  52 The above command will create a network interface 'eth1' inside the container
  53 and then attaches it to the Open vSwitch bridge 'br-int'.  This is done by
  54 creating a veth pair.  One end of the interface becomes 'eth1' inside the
  55 container and the other end attaches to 'br-int'.
  56
  57 The script also lets one to add an IP address to the interface.  e.g.:
  58
  59 `% ovs-docker add-port br-int eth1 $CONTAINER_ID 192.168.1.1/24`
  60
  61 * A previously added network interface can be deleted.  e.g.:
  62
  63 `% ovs-docker del-port br-int eth1 $CONTAINER_ID`
  64
  65 All the previously added Open vSwitch interfaces inside a container can be
  66 deleted.  e.g.:
  67
  68 `% ovs-docker del-ports br-int $CONTAINER_ID`
  69
  70 It is important that the same $CONTAINER_ID be passed to both add-port
  71 and del-port[s] commands.
  72
  73 * More network control.
  74
  75 Once a container interface is added to an Open vSwitch bridge, one can
  76 set VLANs, create Tunnels, add OpenFlow rules etc for more network control.
  77 Please read the man pages of ovs-vsctl, ovs-ofctl, ovs-vswitchd,
  78 ovsdb-server ovs-vswitchd.conf.db etc for more details.
  79
  80 Docker networking is quite flexible and can be used in multiple ways.  For more
  81 information, please read:
  82 https://docs.docker.com/articles/networking
  83
  84 Bug Reporting
  85 -------------
  86
  87 Please report problems to bugs@openvswitch.org.