add overlay networking security model node

sfsmithcha · sfsmithcha · commit cc5debcb2e86 · 2016-08-12T13:17:24.000-07:00
Signed-off-by: Charles Smith &lt;charles.smith@docker.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
+
+>**Note:** Docker Engine running in swarm mode is not compatible with networking
+with an external key-value store.
 
-## Prerequisites
+### 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
 		</html>
 		-                    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,15 +376,15 @@ 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
 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
diff --git a/docs/userguide/networking/menu.md b/docs/userguide/networking/menu.md
diff --git a/docs/userguide/networking/overlay-security-model.md b/docs/userguide/networking/overlay-security-model.md
diff --git a/docs/userguide/networking/work-with-networks.md b/docs/userguide/networking/work-with-networks.md
