+=====
+
+For multi-host networking with OVN and Docker, Docker has to be started
+with a destributed key-value store. For e.g., if you decide to use consul
+as your distributed key-value store, and your host IP address is $HOST_IP,
+start your Docker daemon with:
+
+```
+docker daemon --cluster-store=consul://127.0.0.1:8500 \
+--cluster-advertise=$HOST_IP:0
+```
+
+OVN provides network virtualization to containers. OVN's integration with
+Docker currently works in two modes - the "underlay" mode or the "overlay"
+mode.
+
+In the "underlay" mode, OVN requires a OpenStack setup to provide container
+networking. In this mode, one can create logical networks and can have
+containers running inside VMs, standalone VMs (without having any containers
+running inside them) and physical machines connected to the same logical
+network. This is a multi-tenant, multi-host solution.
+
+In the "overlay" mode, OVN can create a logical network amongst containers
+running on multiple hosts. This is a single-tenant (extendable to
+multi-tenants depending on the security characteristics of the workloads),
+multi-host solution. In this mode, you do not need a pre-created OpenStack
+setup.
+
+For both the modes to work, a user has to install and start Open vSwitch in
+each VM/host that he plans to run his containers.
+
+
+The "overlay" mode
+==================
+
+OVN in "overlay" mode needs a minimum Open vSwitch version of 2.5.
+
+* Start the central components.
+
+OVN architecture has a central component which stores your networking intent
+in a database. On one of your machines, with an IP Address of $CENTRAL_IP,
+where you have installed and started Open vSwitch, you will need to start some
+central components.
+
+Begin by making ovsdb-server listen on a TCP port by running:
+
+```
+ovs-appctl -t ovsdb-server ovsdb-server/add-remote ptcp:6640
+```
+
+Start ovn-northd daemon. This daemon translates networking intent from Docker
+stored in the OVN_Northbound database to logical flows in OVN_Southbound
+database.
+
+```
+/usr/share/openvswitch/scripts/ovn-ctl start_northd
+```
+
+* One time setup.
+
+On each host, where you plan to spawn your containers, you will need to
+run the following command once. (You need to run it again if your OVS database
+gets cleared. It is harmless to run it again in any case.)
+
+$LOCAL_IP in the below command is the IP address via which other hosts
+can reach this host. This acts as your local tunnel endpoint.
+
+$ENCAP_TYPE is the type of tunnel that you would like to use for overlay
+networking. The options are "geneve" or "stt". (Please note that your
+kernel should have support for your chosen $ENCAP_TYPE. Both geneve
+and stt are part of the Open vSwitch kernel module that is compiled from this
+repo. If you use the Open vSwitch kernel module from upstream Linux,
+you will need a minumum kernel version of 3.18 for geneve. There is no stt
+support in upstream Linux. You can verify whether you have the support in your
+kernel by doing a "lsmod | grep $ENCAP_TYPE".)
+
+```
+ovs-vsctl set Open_vSwitch . external_ids:ovn-remote="tcp:$CENTRAL_IP:6640" \
+ external_ids:ovn-encap-ip=$LOCAL_IP external_ids:ovn-encap-type="$ENCAP_TYPE"
+```
+
+And finally, start the ovn-controller. (You need to run the below command
+on every boot)
+
+```
+/usr/share/openvswitch/scripts/ovn-ctl start_controller
+```
+
+* Start the Open vSwitch network driver.
+
+By default Docker uses Linux bridge for networking. But it has support
+for external drivers. To use Open vSwitch instead of the Linux bridge,
+you will need to start the Open vSwitch driver.
+
+The Open vSwitch driver uses the Python's flask module to listen to
+Docker's networking api calls. So, if your host does not have Python's
+flask module, install it with:
+
+```
+easy_install -U pip
+pip install Flask
+```
+
+Start the Open vSwitch driver on every host where you plan to create your
+containers.
+
+```
+ovn-docker-overlay-driver --detach
+```
+
+Docker has inbuilt primitives that closely match OVN's logical switches
+and logical port concepts. Please consult Docker's documentation for
+all the possible commands. Here are some examples.
+
+* Create your logical switch.
+
+To create a logical switch with name 'foo', on subnet '192.168.1.0/24' run:
+
+```
+NID=`docker network create -d openvswitch --subnet=192.168.1.0/24 foo`
+```
+
+* List your logical switches.
+
+```
+docker network ls
+```
+
+You can also look at this logical switch in OVN's northbound database by
+running the following command.