From eac95671f50a65279f8c39341c4f3be680add98a Mon Sep 17 00:00:00 2001 From: Pierre-Alain RIVIERE Date: Thu, 5 Dec 2013 19:02:19 +0100 Subject: [PATCH] refs #2490 : add a network page to docs --- docs/sources/use/index.rst | 1 + docs/sources/use/networking.rst | 147 ++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 docs/sources/use/networking.rst diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst index 38f61ba744..7b61c203d5 100644 --- a/docs/sources/use/index.rst +++ b/docs/sources/use/index.rst @@ -18,6 +18,7 @@ Contents: baseimages port_redirection puppet + networking host_integration working_with_volumes working_with_links_names diff --git a/docs/sources/use/networking.rst b/docs/sources/use/networking.rst new file mode 100644 index 0000000000..c37035114e --- /dev/null +++ b/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` 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=`` 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