From cc5debcb2e8621358721eb860c07f33f8b83d684 Mon Sep 17 00:00:00 2001 From: Charles Smith Date: Tue, 26 Jul 2016 20:40:17 -0700 Subject: [PATCH] add overlay networking security model node Signed-off-by: Charles Smith --- docs/reference/commandline/network_connect.md | 2 +- docs/reference/commandline/network_create.md | 2 +- .../commandline/network_disconnect.md | 2 +- docs/reference/commandline/network_inspect.md | 2 +- docs/reference/commandline/network_ls.md | 2 +- docs/reference/commandline/network_rm.md | 2 +- docs/security/security.md | 9 +- docs/userguide/index.md | 6 +- .../networking/default_network/binding.md | 4 +- .../default_network/build-bridges.md | 2 +- .../default_network/configure-dns.md | 2 +- .../container-communication.md | 2 +- .../default_network/custom-docker0.md | 2 +- .../networking/default_network/dockerlinks.md | 2 +- .../networking/get-started-overlay.md | 78 ++- docs/userguide/networking/index.md | 572 +++++++++++++++++- docs/userguide/networking/menu.md | 22 + .../networking/overlay-security-model.md | 66 ++ .../networking/work-with-networks.md | 2 +- 19 files changed, 735 insertions(+), 46 deletions(-) create mode 100644 docs/userguide/networking/menu.md create mode 100644 docs/userguide/networking/overlay-security-model.md diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md index 60accc763c..5a9ed866ef 100644 --- a/docs/reference/commandline/network_connect.md +++ b/docs/reference/commandline/network_connect.md @@ -93,5 +93,5 @@ You can connect a container to one or more networks. The networks need not be th * [network disconnect](network_disconnect.md) * [network ls](network_ls.md) * [network rm](network_rm.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) * [Work with networks](../../userguide/networking/work-with-networks.md) diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index b6039734fe..67884bb0b9 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -192,4 +192,4 @@ to create an externally isolated `overlay` network, you can specify the * [network disconnect](network_disconnect.md) * [network ls](network_ls.md) * [network rm](network_rm.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md index 9d0c31580d..2d43ccb1e9 100644 --- a/docs/reference/commandline/network_disconnect.md +++ b/docs/reference/commandline/network_disconnect.md @@ -34,4 +34,4 @@ Disconnects a container from a network. The container must be running to disconn * [network create](network_create.md) * [network ls](network_ls.md) * [network rm](network_rm.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md index e2e3dc7833..1f35592b5d 100644 --- a/docs/reference/commandline/network_inspect.md +++ b/docs/reference/commandline/network_inspect.md @@ -119,4 +119,4 @@ $ docker network inspect simple-network * [network create](network_create.md) * [network ls](network_ls.md) * [network rm](network_rm.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index e8ba6d97fb..d1d92f4be8 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -209,4 +209,4 @@ d1584f8dc718: host * [network create](network_create.md) * [network inspect](network_inspect.md) * [network rm](network_rm.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md index 949d9b56b9..d57254636a 100644 --- a/docs/reference/commandline/network_rm.md +++ b/docs/reference/commandline/network_rm.md @@ -50,4 +50,4 @@ deletion. * [network create](network_create.md) * [network ls](network_ls.md) * [network inspect](network_inspect.md) -* [Understand Docker container networks](../../userguide/networking/dockernetworks.md) +* [Understand Docker container networks](../../userguide/networking/index.md) diff --git a/docs/security/security.md b/docs/security/security.md index 7ab127cb5a..2450f2bf7a 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -120,10 +120,10 @@ certificates](https.md). The daemon is also potentially vulnerable to other inputs, such as image loading from either disk with 'docker load', or from the network with -'docker pull'. As of Docker 1.3.2, images are now extracted in a chrooted -subprocess on Linux/Unix platforms, being the first-step in a wider effort -toward privilege separation. As of Docker 1.10.0, all images are stored and -accessed by the cryptographic checksums of their contents, limiting the +'docker pull'. As of Docker 1.3.2, images are now extracted in a chrooted +subprocess on Linux/Unix platforms, being the first-step in a wider effort +toward privilege separation. As of Docker 1.10.0, all images are stored and +accessed by the cryptographic checksums of their contents, limiting the possibility of an attacker causing a collision with an existing image. Eventually, it is expected that the Docker daemon will run restricted @@ -272,3 +272,4 @@ pull requests, and communicate via the mailing list. * [Seccomp security profiles for Docker](../security/seccomp.md) * [AppArmor security profiles for Docker](../security/apparmor.md) * [On the Security of Containers (2014)](https://medium.com/@ewindisch/on-the-security-of-containers-2c60ffe25a9e) +* [Docker swarm mode overlay network security model](../userguide/networking/overlay-security-model.md) diff --git a/docs/userguide/index.md b/docs/userguide/index.md index 9188c8ad15..99a41e77a0 100644 --- a/docs/userguide/index.md +++ b/docs/userguide/index.md @@ -43,7 +43,7 @@ This guide helps users learn how to use Docker Engine. ## Configure networks -- [Understand Docker container networks](networking/dockernetworks.md) +- [Understand Docker container networks](networking/index.md) - [Embedded DNS server in user-defined networks](networking/configure-dns.md) - [Get started with multi-host networking](networking/get-started-overlay.md) - [Work with network commands](networking/work-with-networks.md) @@ -55,8 +55,8 @@ This guide helps users learn how to use Docker Engine. - [Binding container ports to the host](networking/default_network/binding.md) - [Build your own bridge](networking/default_network/build-bridges.md) - [Configure container DNS](networking/default_network/configure-dns.md) -- [Customize the docker0 bridge](networking/default_network/custom-docker0.md) -- [IPv6 with Docker](networking/default_network/ipv6.md) +- [Customize the docker0 bridge](networking/default_network/custom-docker0.md) +- [IPv6 with Docker](networking/default_network/ipv6.md) ## Misc diff --git a/docs/userguide/networking/default_network/binding.md b/docs/userguide/networking/default_network/binding.md index 0ec495a173..2197784525 100644 --- a/docs/userguide/networking/default_network/binding.md +++ b/docs/userguide/networking/default_network/binding.md @@ -12,7 +12,7 @@ parent = "smn_networking_def" The information in this section explains binding container ports within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -> **Note**: The [Docker networks feature](../dockernetworks.md) allows you to +> **Note**: The [Docker networks feature](../index.md) allows you to create user-defined networks in addition to the default bridge network. By default Docker containers can make connections to the outside world, but the @@ -100,6 +100,6 @@ address: this alternative is preferred for performance reasons. ## Related information -- [Understand Docker container networks](../dockernetworks.md) +- [Understand Docker container networks](../index.md) - [Work with network commands](../work-with-networks.md) - [Legacy container links](dockerlinks.md) diff --git a/docs/userguide/networking/default_network/build-bridges.md b/docs/userguide/networking/default_network/build-bridges.md index 0cd70215df..7f7cb4451f 100644 --- a/docs/userguide/networking/default_network/build-bridges.md +++ b/docs/userguide/networking/default_network/build-bridges.md @@ -14,7 +14,7 @@ This section explains how to build your own bridge to replace the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -> **Note**: The [Docker networks feature](../dockernetworks.md) allows you to +> **Note**: The [Docker networks feature](../index.md) allows you to create user-defined networks in addition to the default bridge network. You can set up your own bridge before starting Docker and use `-b BRIDGE` or diff --git a/docs/userguide/networking/default_network/configure-dns.md b/docs/userguide/networking/default_network/configure-dns.md index 71f189e141..f803025007 100644 --- a/docs/userguide/networking/default_network/configure-dns.md +++ b/docs/userguide/networking/default_network/configure-dns.md @@ -14,7 +14,7 @@ The information in this section explains configuring container DNS within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -> **Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network. Please refer to the [Docker Embedded DNS](../configure-dns.md) section for more information on DNS configurations in user-defined networks. +> **Note**: The [Docker networks feature](../index.md) allows you to create user-defined networks in addition to the default bridge network. Please refer to the [Docker Embedded DNS](../configure-dns.md) section for more information on DNS configurations in user-defined networks. How can Docker supply each container with a hostname and DNS configuration, without having to build a custom image with the hostname written inside? Its trick is to overlay three crucial `/etc` files inside the container with virtual files where it can write fresh information. You can see this by running `mount` inside a container: diff --git a/docs/userguide/networking/default_network/container-communication.md b/docs/userguide/networking/default_network/container-communication.md index 8e2110af6e..d49d469c38 100644 --- a/docs/userguide/networking/default_network/container-communication.md +++ b/docs/userguide/networking/default_network/container-communication.md @@ -14,7 +14,7 @@ The information in this section explains container communication within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -**Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network. +**Note**: The [Docker networks feature](../index.md) allows you to create user-defined networks in addition to the default bridge network. ## Communicating to the outside world diff --git a/docs/userguide/networking/default_network/custom-docker0.md b/docs/userguide/networking/default_network/custom-docker0.md index b9d7156c18..eb8e1cd8f7 100644 --- a/docs/userguide/networking/default_network/custom-docker0.md +++ b/docs/userguide/networking/default_network/custom-docker0.md @@ -12,7 +12,7 @@ parent = "smn_networking_def" The information in this section explains how to customize the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -**Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network. +**Note**: The [Docker networks feature](../index.md) allows you to create user-defined networks in addition to the default bridge network. By default, the Docker server creates and configures the host system's `docker0` interface as an _Ethernet bridge_ inside the Linux kernel that can pass packets back and forth between other physical or virtual network interfaces so that they behave as a single Ethernet network. diff --git a/docs/userguide/networking/default_network/dockerlinks.md b/docs/userguide/networking/default_network/dockerlinks.md index 95f32cb4c1..b465756fea 100644 --- a/docs/userguide/networking/default_network/dockerlinks.md +++ b/docs/userguide/networking/default_network/dockerlinks.md @@ -13,7 +13,7 @@ weight=-2 The information in this section explains legacy container links within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. -Before the [Docker networks feature](../dockernetworks.md), you could use the +Before the [Docker networks feature](../index.md), you could use the Docker link feature to allow containers to discover each other and securely transfer information about one container to another container. With the introduction of the Docker networks feature, you can still create links but they diff --git a/docs/userguide/networking/get-started-overlay.md b/docs/userguide/networking/get-started-overlay.md index 39812abd31..73b2d44181 100644 --- a/docs/userguide/networking/get-started-overlay.md +++ b/docs/userguide/networking/get-started-overlay.md @@ -14,19 +14,69 @@ weight=-3 This article uses an example to explain the basics of creating a multi-host network. Docker Engine supports multi-host networking out-of-the-box through the `overlay` network driver. Unlike `bridge` networks, overlay networks require -some pre-existing conditions before you can create one. These conditions are: +some pre-existing conditions before you can create one: -* Access to a key-value store. Docker supports Consul, Etcd, and ZooKeeper (Distributed store) key-value stores. +* [Docker Engine running in swarm mode](#overlay-networking-and-swarm-mode) + +OR + +* [A cluster of hosts using a key value store](#overlay-networking-with-an-external-key-value-store) + +## Overlay networking and swarm mode + +Using docker engine running in [swarm mode](../../swarm/swarm-mode.md), you can create an overlay network on a manager node. + +The swarm makes the overlay network available only to nodes in the swarm that +require it for a service. When you create a service that uses an overlay +network, the manager node automatically extends the overlay network to nodes +that run service tasks. + +To learn more about running Docker Engine in swarm mode, refer to the +[Swarm mode overview](../../swarm/index.md). + +The example below shows how to create a network and use it for a service from a manager node in the swarm: + +```bash +# Create an overlay network `my-multi-host-network`. +$ docker network create \ + --driver overlay \ + --subnet 10.0.9.0/24 \ + my-multi-host-network + +400g6bwzd68jizzdx5pgyoe95 + +# Create an nginx service and extend the my-multi-host-network to nodes where +# the service's tasks run. +$ $ docker service create --replicas 2 --network my-multi-host-network --name my-web nginx + +716thylsndqma81j6kkkb5aus +``` + +Overlay networks for a swarm are not available to unmanaged containers. For more information refer to [Docker swarm mode overlay network security model](overlay-security-model.md). + + +## Overlay networking with an external key-value store + +To use an Docker engine with an external key-value store, you need the +following: + +* Access to the key-value store. Docker supports Consul, Etcd, and ZooKeeper +(Distributed store) key-value stores. * A cluster of hosts with connectivity to the key-value store. * A properly configured Engine `daemon` on each host in the cluster. -* Hosts within the cluster must have unique hostnames because the key-value store uses the hostnames to identify cluster members. +* Hosts within the cluster must have unique hostnames because the key-value +store uses the hostnames to identify cluster members. Though Docker Machine and Docker Swarm are not mandatory to experience Docker -multi-host networking, this example uses them to illustrate how they are -integrated. You'll use Machine to create both the key-value store -server and the host cluster. This example creates a Swarm cluster. +multi-host networking with a key-value store, this example uses them to +illustrate how they are integrated. You'll use Machine to create both the +key-value store server and the host cluster. This example creates a Swarm +cluster. -## Prerequisites +>**Note:** Docker Engine running in swarm mode is not compatible with networking +with an external key-value store. + +### Prerequisites Before you begin, make sure you have a system on your network with the latest version of Docker Engine and Docker Machine installed. The example also relies @@ -37,7 +87,7 @@ If you have not already done so, make sure you upgrade Docker Engine and Docker Machine to the latest versions. -## Step 1: Set up a key-value store +### Set up a key-value store An overlay network requires a key-value store. The key-value store holds information about the network state which includes discovery, networks, @@ -80,7 +130,7 @@ key-value stores. This example uses Consul. Keep your terminal open and move onto the next step. -## Step 2: Create a Swarm cluster +### Create a Swarm cluster In this step, you use `docker-machine` to provision the hosts for your network. At this point, you won't actually create the network. You'll create several @@ -123,7 +173,7 @@ At this point you have a set of hosts running on your network. You are ready to Leave your terminal open and go onto the next step. -## Step 3: Create the overlay Network +### Create the overlay Network To create an overlay network @@ -213,7 +263,7 @@ To create an overlay network Both agents report they have the `my-net` network with the `6b07d0be843f` ID. You now have a multi-host container network running! -## Step 4: Run an application on your Network +### Run an application on your Network Once your network is created, you can start a container on any of the hosts and it automatically is part of the network. @@ -263,7 +313,7 @@ Once your network is created, you can start a container on any of the hosts and - 100% |*******************************| 612 0:00:00 ETA -## Step 5: Check external connectivity +### Check external connectivity As you've seen, Docker's built-in overlay network driver provides out-of-the-box connectivity between the containers on multiple hosts within the same network. @@ -326,7 +376,7 @@ to have external connectivity outside of their cluster. the `my-net` overlay network. While the `eth1` interface represents the container interface that is connected to the `docker_gwbridge` network. -## Step 6: Extra Credit with Docker Compose +### Extra Credit with Docker Compose Please refer to the Networking feature introduced in [Compose V2 format] (https://docs.docker.com/compose/networking/) and execute the @@ -334,7 +384,7 @@ multi-host networking scenario in the Swarm cluster used above. ## Related information -* [Understand Docker container networks](dockernetworks.md) +* [Understand Docker container networks](index.md) * [Work with network commands](work-with-networks.md) * [Docker Swarm overview](https://docs.docker.com/swarm) * [Docker Machine overview](https://docs.docker.com/machine) diff --git a/docs/userguide/networking/index.md b/docs/userguide/networking/index.md index eb613c6d16..8731dcbe45 100644 --- a/docs/userguide/networking/index.md +++ b/docs/userguide/networking/index.md @@ -1,21 +1,571 @@ -# Docker networks feature overview +# Understand Docker container networks -This sections explains how to use the Docker networks feature. This feature allows users to define their own networks and connect containers to them. Using this feature you can create a network on a single host or a network that spans across multiple hosts. +This section provides an overview of the default networking behavior that Docker +Engine delivers natively. It describes the type of networks created by default +and how to create your own, user-defined networks. It also describes the +resources required to create networks on a single host or across a cluster of +hosts. + +## Default Networks + +When you install Docker, it creates three networks automatically. You can list +these networks using the `docker network ls` command: + +``` +$ docker network ls + +NETWORK ID NAME DRIVER +7fca4eb8c647 bridge bridge +9f904ee27bf5 none null +cf03ee007fb4 host host +``` + +Historically, these three networks are part of Docker's implementation. When +you run a container you can use the `--network` flag to specify which network you +want to run a container on. These three networks are still available to you. + +The `bridge` network represents the `docker0` network present in all Docker +installations. Unless you specify otherwise with the `docker run +--network=` option, the Docker daemon connects containers to this network +by default. You can see this bridge as part of a host's network stack by using +the `ifconfig` command on the host. + +``` +$ ifconfig + +docker0 Link encap:Ethernet HWaddr 02:42:47:bc:3a:eb + inet addr:172.17.0.1 Bcast:0.0.0.0 Mask:255.255.0.0 + inet6 addr: fe80::42:47ff:febc:3aeb/64 Scope:Link + UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 + RX packets:17 errors:0 dropped:0 overruns:0 frame:0 + TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:1100 (1.1 KB) TX bytes:648 (648.0 B) +``` + +The `none` network adds a container to a container-specific network stack. That container lacks a network interface. Attaching to such a container and looking at its stack you see this: + +``` +$ docker attach nonenetcontainer + +root@0cb243cd1293:/# cat /etc/hosts +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +fe00::0 ip6-localnet +ff00::0 ip6-mcastprefix +ff02::1 ip6-allnodes +ff02::2 ip6-allrouters +root@0cb243cd1293:/# ifconfig +lo Link encap:Local Loopback + inet addr:127.0.0.1 Mask:255.0.0.0 + inet6 addr: ::1/128 Scope:Host + UP LOOPBACK RUNNING MTU:65536 Metric:1 + RX packets:0 errors:0 dropped:0 overruns:0 frame:0 + TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) + +root@0cb243cd1293:/# +``` +>**Note**: You can detach from the container and leave it running with `CTRL-p CTRL-q`. + +The `host` network adds a container on the hosts network stack. You'll find the +network configuration inside the container is identical to the host. + +With the exception of the `bridge` network, you really don't need to +interact with these default networks. While you can list and inspect them, you +cannot remove them. They are required by your Docker installation. However, you +can add your own user-defined networks and these you can remove when you no +longer need them. Before you learn more about creating your own networks, it is +worth looking at the default `bridge` network a bit. + + +### The default bridge network in detail +The default `bridge` network is present on all Docker hosts. The `docker network inspect` +command returns information about a network: + +``` +$ docker network inspect bridge + +[ + { + "Name": "bridge", + "Id": "f7ab26d71dbd6f557852c7156ae0574bbf62c42f539b50c8ebde0f728a253b6f", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.17.0.1/16", + "Gateway": "172.17.0.1" + } + ] + }, + "Containers": {}, + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "9001" + } + } +] +``` +The Engine automatically creates a `Subnet` and `Gateway` to the network. +The `docker run` command automatically adds new containers to this network. + +``` +$ docker run -itd --name=container1 busybox + +3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c + +$ docker run -itd --name=container2 busybox + +94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c +``` + +Inspecting the `bridge` network again after starting two containers shows both newly launched containers in the network. Their ids show up in the "Containers" section of `docker network inspect`: + +``` +$ docker network inspect bridge + +{[ + { + "Name": "bridge", + "Id": "f7ab26d71dbd6f557852c7156ae0574bbf62c42f539b50c8ebde0f728a253b6f", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.17.0.1/16", + "Gateway": "172.17.0.1" + } + ] + }, + "Containers": { + "3386a527aa08b37ea9232cbcace2d2458d49f44bb05a6b775fba7ddd40d8f92c": { + "EndpointID": "647c12443e91faf0fd508b6edfe59c30b642abb60dfab890b4bdccee38750bc1", + "MacAddress": "02:42:ac:11:00:02", + "IPv4Address": "172.17.0.2/16", + "IPv6Address": "" + }, + "94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c": { + "EndpointID": "b047d090f446ac49747d3c37d63e4307be745876db7f0ceef7b311cbba615f48", + "MacAddress": "02:42:ac:11:00:03", + "IPv4Address": "172.17.0.3/16", + "IPv6Address": "" + } + }, + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "9001" + } + } +] +``` + +The `docker network inspect` command above shows all the connected containers and their network resources on a given network. Containers in this default network are able to communicate with each other using IP addresses. Docker does not support automatic service discovery on the default bridge network. If you want to communicate with container names in this default bridge network, you must connect the containers via the legacy `docker run --link` option. + +You can `attach` to a running `container` and investigate its configuration: + +``` +$ docker attach container1 + +root@0cb243cd1293:/# ifconfig +ifconfig +eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:02 + inet addr:172.17.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 + inet6 addr: fe80::42:acff:fe11:2/64 Scope:Link + UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 + RX packets:16 errors:0 dropped:0 overruns:0 frame:0 + TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:1296 (1.2 KiB) TX bytes:648 (648.0 B) + +lo Link encap:Local Loopback + inet addr:127.0.0.1 Mask:255.0.0.0 + inet6 addr: ::1/128 Scope:Host + UP LOOPBACK RUNNING MTU:65536 Metric:1 + RX packets:0 errors:0 dropped:0 overruns:0 frame:0 + TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) +``` + +Then use `ping`to send three ICMP requests and test the connectivity of the +containers on this `bridge` network. + +``` +root@0cb243cd1293:/# ping -w3 172.17.0.3 + +PING 172.17.0.3 (172.17.0.3): 56 data bytes +64 bytes from 172.17.0.3: seq=0 ttl=64 time=0.096 ms +64 bytes from 172.17.0.3: seq=1 ttl=64 time=0.080 ms +64 bytes from 172.17.0.3: seq=2 ttl=64 time=0.074 ms + +--- 172.17.0.3 ping statistics --- +3 packets transmitted, 3 packets received, 0% packet loss +round-trip min/avg/max = 0.074/0.083/0.096 ms +``` + +Finally, use the `cat` command to check the `container1` network configuration: + +``` +root@0cb243cd1293:/# cat /etc/hosts + +172.17.0.2 3386a527aa08 +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +fe00::0 ip6-localnet +ff00::0 ip6-mcastprefix +ff02::1 ip6-allnodes +ff02::2 ip6-allrouters +``` +To detach from a `container1` and leave it running use `CTRL-p CTRL-q`.Then, attach to `container2` and repeat these three commands. + +``` +$ docker attach container2 + +root@0cb243cd1293:/# ifconfig + +eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 + inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 + inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link + UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 + RX packets:15 errors:0 dropped:0 overruns:0 frame:0 + TX packets:13 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:1166 (1.1 KiB) TX bytes:1026 (1.0 KiB) + +lo Link encap:Local Loopback + inet addr:127.0.0.1 Mask:255.0.0.0 + inet6 addr: ::1/128 Scope:Host + UP LOOPBACK RUNNING MTU:65536 Metric:1 + RX packets:0 errors:0 dropped:0 overruns:0 frame:0 + TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) + +root@0cb243cd1293:/# ping -w3 172.17.0.2 + +PING 172.17.0.2 (172.17.0.2): 56 data bytes +64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.067 ms +64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms +64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.072 ms + +--- 172.17.0.2 ping statistics --- +3 packets transmitted, 3 packets received, 0% packet loss +round-trip min/avg/max = 0.067/0.071/0.075 ms +/ # cat /etc/hosts +172.17.0.3 94447ca47985 +127.0.0.1 localhost +::1 localhost ip6-localhost ip6-loopback +fe00::0 ip6-localnet +ff00::0 ip6-mcastprefix +ff02::1 ip6-allnodes +ff02::2 ip6-allrouters +``` + +The default `docker0` bridge network supports the use of port mapping and `docker run --link` to allow communications between containers in the `docker0` network. These techniques are cumbersome to set up and prone to error. While they are still available to you as techniques, it is better to avoid them and define your own bridge networks instead. + +## User-defined networks + +You can create your own user-defined networks that better isolate containers. +Docker provides some default **network drivers** for creating these networks. +You can create a new **bridge network**, **overlay network** or **MACVLAN +network**. You can also create a **network plugin** or **remote network** +written to your own specifications. + +You can create multiple networks. You can add containers to more than one +network. Containers can only communicate within networks but not across +networks. A container attached to two networks can communicate with member +containers in either network. When a container is connected to multiple +networks, its external connectivity is provided via the first non-internal +network, in lexical order. + +The next few sections describe each of Docker's built-in network drivers in +greater detail. + +### A bridge network + +The easiest user-defined network to create is a `bridge` network. This network +is similar to the historical, default `docker0` network. There are some added +features and some old features that aren't available. + +``` +$ docker network create --driver bridge isolated_nw +1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b + +$ docker network inspect isolated_nw + +[ + { + "Name": "isolated_nw", + "Id": "1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.21.0.0/16", + "Gateway": "172.21.0.1/16" + } + ] + }, + "Containers": {}, + "Options": {} + } +] + +$ docker network ls + +NETWORK ID NAME DRIVER +9f904ee27bf5 none null +cf03ee007fb4 host host +7fca4eb8c647 bridge bridge +c5ee82f76de3 isolated_nw bridge + +``` + +After you create the network, you can launch containers on it using the `docker run --network=` option. + +``` +$ docker run --network=isolated_nw -itd --name=container3 busybox + +8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c + +$ docker network inspect isolated_nw +[ + { + "Name": "isolated_nw", + "Id": "1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + {} + ] + }, + "Containers": { + "8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c": { + "EndpointID": "93b2db4a9b9a997beb912d28bcfc117f7b0eb924ff91d48cfa251d473e6a9b08", + "MacAddress": "02:42:ac:15:00:02", + "IPv4Address": "172.21.0.2/16", + "IPv6Address": "" + } + }, + "Options": {} + } +] +``` + +The containers you launch into this network must reside on the same Docker host. +Each container in the network can immediately communicate with other containers +in the network. Though, the network itself isolates the containers from external +networks. + +![An isolated network](images/bridge_network.png) + +Within a user-defined bridge network, linking is not supported. You can +expose and publish container ports on containers in this network. This is useful +if you want to make a portion of the `bridge` network available to an outside +network. + +![Bridge network](images/network_access.png) + +A bridge network is useful in cases where you want to run a relatively small +network on a single host. You can, however, create significantly larger networks +by creating an `overlay` network. + + +### An overlay network with Docker Engine swarm mode + +You can create an overlay network on a manager node running in swarm mode +without an external key-value store. The swarm makes the overlay network +available only to nodes in the swarm that require it for a service. When you +create a service that uses the overlay network, the manager node automatically +extends the overlay network to nodes that run service tasks. + +To learn more about running Docker Engine in swarm mode, refer to the +[Swarm mode overview](../../swarm/index.md). + +The example below shows how to create a network and use it for a service from a manager node in the swarm: + +```bash +# Create an overlay network `my-multi-host-network`. +$ docker network create \ + --driver overlay \ + --subnet 10.0.9.0/24 \ + my-multi-host-network + +400g6bwzd68jizzdx5pgyoe95 + +# Create an nginx service and extend the my-multi-host-network to nodes where +# the service's tasks run. +$ $ docker service create --replicas 2 --network my-multi-host-network --name my-web nginx + +716thylsndqma81j6kkkb5aus +``` + +Overlay networks for a swarm are not available to containers started with +`docker run` that don't run as part of a swarm mode service. For more +information refer to [Docker swarm mode overlay network security model](overlay-security-model.md). + +### An overlay network with an external key-value store + +If you are not using Docker Engine in swarm mode, the `overlay` network requires +a valid key-value store service. Supported key-value stores include Consul, +Etcd, and ZooKeeper (Distributed store). Before creating a network on this +version of the Engine, you must install and configure your chosen key-value +store service. The Docker hosts that you intend to network and the service must +be able to communicate. + +>**Note:** Docker Engine running in swarm mode is not compatible with networking +with an external key-value store. + +![Key-value store](images/key_value.png) + +Each host in the network must run a Docker Engine instance. The easiest way to +provision the hosts is with Docker Machine. + +![Engine on each host](images/engine_on_net.png) + +You should open the following ports between each of your hosts. + +| Protocol | Port | Description | +|----------|------|-----------------------| +| udp | 4789 | Data plane (VXLAN) | +| tcp/udp | 7946 | Control plane | + +Your key-value store service may require additional ports. +Check your vendor's documentation and open any required ports. + +Once you have several machines provisioned, you can use Docker Swarm to quickly +form them into a swarm which includes a discovery service as well. + +To create an overlay network, you configure options on the `daemon` on each +Docker Engine for use with `overlay` network. There are three options to set: + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
--cluster-store=PROVIDER://URL
Describes the location of the KV service.
--cluster-advertise=HOST_IP|HOST_IFACE:PORT
The IP address or interface of the HOST used for clustering.
--cluster-store-opt=KEY-VALUE OPTIONS
Options such as TLS certificate or tuning discovery Timers
+ +Create an `overlay` network on one of the machines in the Swarm. + + $ docker network create --driver overlay my-multi-host-network + +This results in a single network spanning multiple hosts. An `overlay` network +provides complete isolation for the containers. + +![An overlay network](images/overlay_network.png) + +Then, on each host, launch containers making sure to specify the network name. + + $ docker run -itd --network=my-multi-host-network busybox + +Once connected, each container has access to all the containers in the network +regardless of which Docker host the container was launched on. + +![Published port](images/overlay-network-final.png) + +If you would like to try this for yourself, see the [Getting started for +overlay](get-started-overlay.md). + +### Custom network plugin + +If you like, you can write your own network driver plugin. A network +driver plugin makes use of Docker's plugin infrastructure. In this +infrastructure, a plugin is a process running on the same Docker host as the +Docker `daemon`. + +Network plugins follow the same restrictions and installation rules as other +plugins. All plugins make use of the plugin API. They have a lifecycle that +encompasses installation, starting, stopping and activation. + +Once you have created and installed a custom network driver, you use it like the +built-in network drivers. For example: + + $ docker network create --driver weave mynet + +You can inspect it, add containers to and from it, and so forth. Of course, +different plugins may make use of different technologies or frameworks. Custom +networks can include features not present in Docker's default networks. For more +information on writing plugins, see [Extending Docker](../../extend/index.md) and +[Writing a network driver plugin](../../extend/plugins_network.md). + +### Docker embedded DNS server + +Docker daemon runs an embedded DNS server to provide automatic service discovery +for containers connected to user defined networks. Name resolution requests from +the containers are handled first by the embedded DNS server. If the embedded DNS +server is unable to resolve the request it will be forwarded to any external DNS +servers configured for the container. To facilitate this when the container is +created, only the embedded DNS server reachable at `127.0.0.11` will be listed +in the container's `resolv.conf` file. More information on embedded DNS server on +user-defined networks can be found in the [embedded DNS server in user-defined networks] +(configure-dns.md) + +## Links + +Before the Docker network feature, you could use the Docker link feature to +allow containers to discover each other. With the introduction of Docker networks, +containers can be discovered by its name automatically. But you can still create +links but they behave differently when used in the default `docker0` bridge network +compared to user-defined networks. For more information, please refer to +[Legacy Links](default_network/dockerlinks.md) for link feature in default `bridge` network +and the [linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks) for links +functionality in user-defined networks. + +## Related information -- [Understand Docker container networks](dockernetworks.md) - [Work with network commands](work-with-networks.md) - [Get started with multi-host networking](get-started-overlay.md) - -If you are already familiar with Docker's default bridge network, `docker0` that network continues to be supported. It is created automatically in every installation. The default bridge network is also named `bridge`. To see a list of topics related to that network, read the articles listed in the [Docker default bridge network](default_network/index.md). +- [Managing Data in Containers](../../tutorials/dockervolumes.md) +- [Docker Machine overview](https://docs.docker.com/machine) +- [Docker Swarm overview](https://docs.docker.com/swarm) +- [Investigate the LibNetwork project](https://github.com/docker/libnetwork) diff --git a/docs/userguide/networking/menu.md b/docs/userguide/networking/menu.md new file mode 100644 index 0000000000..f168b70afb --- /dev/null +++ b/docs/userguide/networking/menu.md @@ -0,0 +1,22 @@ + + +# Docker networks feature overview + +This sections explains how to use the Docker networks feature. This feature allows users to define their own networks and connect containers to them. Using this feature you can create a network on a single host or a network that spans across multiple hosts. + +- [Understand Docker container networks](index.md) +- [Work with network commands](work-with-networks.md) +- [Get started with multi-host networking](get-started-overlay.md) + +If you are already familiar with Docker's default bridge network, `docker0` that network continues to be supported. It is created automatically in every installation. The default bridge network is also named `bridge`. To see a list of topics related to that network, read the articles listed in the [Docker default bridge network](default_network/index.md). diff --git a/docs/userguide/networking/overlay-security-model.md b/docs/userguide/networking/overlay-security-model.md new file mode 100644 index 0000000000..ab35cd551c --- /dev/null +++ b/docs/userguide/networking/overlay-security-model.md @@ -0,0 +1,66 @@ + + +# Docker swarm mode overlay network security model + +Overlay networking for Docker Engine swarm mode comes secure out of the box. The +swarm nodes exchange overlay network information using a gossip protocol. By +default the nodes encrypt and authenticate information they exchange via gossip +using the [AES algorithm](https://en.wikipedia.org/wiki/Galois/Counter_Mode) in +GCM mode. Manager nodes in the swarm rotate the key used to encrypt gossip data +every 12 hours. + +You can also encrypt data exchanged between containers on different nodes on the +overlay network. To enable encryption, when you create an overlay network pass +the `--opt encrypted` flag: + +```bash +$ docker network create --opt encrypted --driver overlay my-multi-host-network + +dt0zvqn0saezzinc8a5g4worx +``` + +When you enable overlay encryption, Docker creates IPSEC tunnels between all the +nodes where tasks are scheduled for services attached to the overlay network. +These tunnels also use the AES algorithm in GCM mode and manager nodes +automatically rotate the keys every 12 hours. + +## Swarm mode overlay networks and unmanaged containers + +Because the overlay networks for swarm mode use encryption keys from the manager +nodes to encrypt the gossip communications, only containers running as tasks in +the swarm have access to the keys. Consequently, containers started outside of +swarm mode using `docker run` (unmanaged containers) cannot attach to the +overlay network. + +For example: + +```bash +$ docker run --network my-multi-host-network nginx + +docker: Error response from daemon: swarm-scoped network +(my-multi-host-network) is not compatible with `docker create` or `docker +run`. This network can only be used by a docker service. +``` + +To work around this situation, migrate the unmanaged containers to managed +services. For instance: + +```bash +$ docker service create --network my-multi-host-network my-image +``` + +Because [swarm mode](../../swarm/index.md) is an optional feature, the Docker +Engine preserves backward compatibility. You can continue to rely on a +third-party key-value store to support overlay networking if you wish. +However, switching to swarm-mode is strongly encouraged. In addition to the +security benefits described in this article, swarm mode enables you to leverage +the substantially greater scalability provided by the new services API. diff --git a/docs/userguide/networking/work-with-networks.md b/docs/userguide/networking/work-with-networks.md index bc22f66f26..737d9c93fe 100644 --- a/docs/userguide/networking/work-with-networks.md +++ b/docs/userguide/networking/work-with-networks.md @@ -23,7 +23,7 @@ available through the Docker Engine CLI. These commands are: * `docker network inspect` While not required, it is a good idea to read [Understanding Docker -network](dockernetworks.md) before trying the examples in this section. The +network](index.md) before trying the examples in this section. The examples for the rely on a `bridge` network so that you can try them immediately. If you would prefer to experiment with an `overlay` network see the [Getting started with multi-host networks](get-started-overlay.md) instead.