moby--moby/docs/sources/use/networking.rst

: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