Merge pull request #3051 from pariviere/2490-docs-network

Network documentation page

docs/sources/use/index.rst

@@ -18,6 +18,7 @@ Contents:
    baseimages
    port_redirection
    puppet
+   networking
    host_integration
    working_with_volumes
    working_with_links_names

docs/sources/use/networking.rst

@@ -0,0 +1,147 @@
+:title: Docker networking
+:description: Docker networking
+:keywords: network, networking, bridge, docker, documentation
+
+
+Networking
+==========
+
+Docker uses Linux bridge capabilities to provide network connectivity 
+to containers. The ``docker0`` bridge interface is managed by Docker itself
+for this purpose. Thus, when the Docker daemon starts it :
+
+- creates the ``docker0`` bridge if not present
+- searches for an IP address range which doesn't overlap with an existing route
+- picks an IP in the selected range
+- assigns this IP to the ``docker0`` bridge
+
+
+.. code-block:: bash
+    
+    # List host bridges
+    $ sudo brctl show
+    bridge	name	bridge id		STP enabled	interfaces
+    docker0		8000.000000000000	no	
+
+    # Show docker0 IP address
+    $ sudo ifconfig docker0
+    docker0   Link encap:Ethernet  HWaddr xx:xx:xx:xx:xx:xx
+   	 inet addr:172.17.42.1  Bcast:0.0.0.0  Mask:255.255.0.0
+
+
+
+At runtime, a :ref:`specific kind of virtual interface<vethxxxx-device>` is 
+given to each containers which is then bonded to the ``docker0`` bridge. 
+Each containers also receives a dedicated IP address from the same range 
+as ``docker0``. The ``docker0`` IP address is then used as the default 
+gateway for the containers.
+
+.. code-block:: bash
+
+    # Run a container
+    $ sudo docker run -t -i -d base /bin/bash
+    52f811c5d3d69edddefc75aff5a4525fc8ba8bcfa1818132f9dc7d4f7c7e78b4
+
+    $ sudo brctl show
+    bridge	name	bridge id		STP enabled	interfaces
+    docker0		8000.fef213db5a66	no		vethQCDY1N
+
+
+Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface which is dedicated
+to the 52f811c5d3d6 container.
+
+
+How to use a specific IP address range
+---------------------------------------
+Docker will try hard to find an IP range which is not used by the host. 
+Even if it works for most cases, it's not bullet-proof and sometimes you need 
+to have more control over the IP addressing scheme.
+
+For this purpose, Docker allows you to manage the ``docker0`` bridge or 
+your own one using the ``-b=<bridgename>`` parameter.
+
+In this scenario:
+
+- ensure Docker is stopped
+- create your own bridge (``bridge0`` for example)
+- assign a specific IP to this bridge
+- start Docker with the ``-b=bridge0`` parameter
+
+
+.. code-block:: bash
+
+    # Stop Docker
+    $ sudo service docker stop
+
+    # Clean docker0 bridge and
+    # add your very own bridge0
+    $ sudo ifconfig docker0 down
+    $ sudo brctl addbr bridge0
+    $ sudo ifconfig bridge0 192.168.227.1 netmask 255.255.255.0
+
+    # Edit your Docker startup file
+    $ echo "DOCKER_OPTS=\"-b=bridge0\"" /etc/default/docker 
+    
+    # Start Docker 
+    $ sudo service docker start
+
+    # Ensure bridge0 IP is not changed by Docker
+    $ sudo ifconfig bridge0
+    bridge0   Link encap:Ethernet  HWaddr xx:xx:xx:xx:xx:xx
+              inet addr:192.168.227.1  Bcast:192.168.227.255  Mask:255.255.255.0
+
+    # Run a container
+    $ docker run -i -t base /bin/bash
+
+    # Container IP in the 192.168.227/24 range
+    root@261c272cd7d5:/# ifconfig eth0
+    eth0      Link encap:Ethernet  HWaddr xx:xx:xx:xx:xx:xx
+              inet addr:192.168.227.5  Bcast:192.168.227.255  Mask:255.255.255.0
+
+    # bridge0 IP as the default gateway
+    root@261c272cd7d5:/# route -n
+    Kernel IP routing table
+    Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
+    0.0.0.0         192.168.227.1   0.0.0.0         UG    0      0        0 eth0
+    192.168.227.0   0.0.0.0         255.255.255.0   U     0      0        0 eth0
+
+    # hits CTRL+P then CTRL+Q to detach
+   
+    # Display bridge info 
+    $ sudo brctl show
+    bridge 	name	bridge id		STP enabled	interfaces
+    bridge0		8000.fe7c2e0faebd	no		vethAQI2QT
+    
+    
+Container intercommunication
+-------------------------------
+Containers can communicate with each other according to the ``icc`` parameter 
+value of the Docker daemon.
+
+- The default, ``-icc=true`` allows containers to communicate with each other.
+- ``-icc=false`` means containers are isolated from each other.
+
+Under the hood, ``iptables`` is used by Docker to either accept or drop communication 
+between containers.
+
+
+.. _vethxxxx-device:
+
+What's about the vethXXXX device?
+-----------------------------------
+Well. Things get complicated here.
+
+The ``vethXXXX`` interface is the host side of a point-to-point link between the 
+host and the corresponding container, the other side of the link being
+materialized by the container's ``eth0`` interface. This pair (host ``vethXXX`` and 
+container ``eth0``) are connected like a tube. Everything that comes in one side will
+come out the other side.
+
+All the plumbing is delegated to Linux network capabilities (check the ip link
+command) and the namespaces infrastructure.
+
+
+I want more
+------------
+Jérôme Petazzoni has create ``pipework`` to connect together containers in 
+arbitrarily complex scenarios : https://github.com/jpetazzo/pipework