diff --git a/docs/userguide/networking/configure-dns.md b/docs/userguide/networking/configure-dns.md
new file mode 100644
index 0000000000..b87436fada
--- /dev/null
+++ b/docs/userguide/networking/configure-dns.md
@@ -0,0 +1,138 @@
+
+
+# Embedded DNS server in user-defined networks
+
+The information in this section covers the embedded DNS server operation for
+containers in user-defined networks. DNS lookup for containers connected to
+user-defined networks works differently compared to the containers connected
+to `default bridge` network.
+
+> **Note**: In order to maintain backward compatibility, the DNS configuration
+> in `default bridge` network is retained with no behaviorial change.
+> Please refer to the [DNS in default bridge network](default_network/configure-dns.md)
+> for more information on DNS configuration in the `default bridge` network.
+
+As of Docker 1.10, the docker daemon implements an embedded DNS server which
+provides built-in service discovery for any container created with a valid
+`name` or `net-alias` or aliased by `link`. The exact details of how Docker
+manages the DNS configurations inside the container can change from one Docker
+version to the next. So you should not assume the way the files such as
+`/etc/hosts`, `/etc/resolv.conf` are managed inside the containers and leave
+the files alone and use the following Docker options instead.
+
+Various container options that affect container domain name services.
+
+
+
+
+
+ --name=CONTAINER-NAME
+
+ |
+
+
+ Container name configured using --name is used to discover a container within
+ an user-defined docker network. The embedded DNS server maintains the mapping between
+ the container name and its IP address (on the network the container is connected to).
+
+ |
+
+
+
+
+ --net-alias=ALIAS
+
+ |
+
+
+ In addition to --name as described above, a container is discovered by one or more
+ of its configured --net-alias (or --alias in docker network connect command)
+ within the user-defined network. The embedded DNS server maintains the mapping between
+ all of the container aliases and its IP address on a specific user-defined network.
+ A container can have different aliases in different networks by using the --alias
+ option in docker network connect command.
+
+ |
+
+
+
+
+ --link=CONTAINER_NAME:ALIAS
+
+ |
+
+
+ Using this option as you run a container gives the embedded DNS
+ an extra entry named ALIAS that points to the IP address
+ of the container identified by CONTAINER_NAME . When using --link
+ the embedded DNS will guarantee that localized lookup result only on that
+ container where the --link is used. This lets processes inside the new container
+ connect to container without without having to know its name or IP.
+
+ |
+
+
+
+ --dns=[IP_ADDRESS...]
+ |
+
+ The IP addresses passed via the --dns option is used by the embedded DNS
+ server to forward the DNS query if embedded DNS server is unable to resolve a name
+ resolution request from the containers.
+ These --dns IP addresses are managed by the embedded DNS server and
+ will not be updated in the container's /etc/resolv.conf file.
+ |
+
+
+ --dns-search=DOMAIN...
+ |
+
+ Sets the domain names that are searched when a bare unqualified hostname is
+ used inside of the container. These --dns-search options are managed by the
+ embedded DNS server and will not be updated in the container's /etc/resolv.conf file.
+ When a container process attempts to access host and the search
+ domain example.com is set, for instance, the DNS logic will not only
+ look up host but also host.example.com .
+
+ |
+
+
+
+ --dns-opt=OPTION...
+ |
+
+ Sets the options used by DNS resolvers. These options are managed by the embedded
+ DNS server and will not be updated in the container's /etc/resolv.conf file.
+
+
+ See documentation for resolv.conf for a list of valid options
+ |
+
+
+
+
+In the absence of the `--dns=IP_ADDRESS...`, `--dns-search=DOMAIN...`, or
+`--dns-opt=OPTION...` options, Docker uses the `/etc/resolv.conf` of the
+host machine (where the `docker` daemon runs). While doing so the daemon
+filters out all localhost IP address `nameserver` entries from the host's
+original file.
+
+Filtering is necessary because all localhost addresses on the host are
+unreachable from the container's network. After this filtering, if there are
+no more `nameserver` entries left in the container's `/etc/resolv.conf` file,
+the daemon adds public Google DNS nameservers (8.8.8.8 and 8.8.4.4) to the
+container's DNS configuration. If IPv6 is enabled on the daemon, the public
+IPv6 Google DNS nameservers will also be added (2001:4860:4860::8888 and
+2001:4860:4860::8844).
+
+> **Note**: If you need access to a host's localhost resolver, you must modify
+> your DNS service on the host to listen on a non-localhost address that is
+> reachable from within the container.
diff --git a/docs/userguide/networking/default_network/configure-dns.md b/docs/userguide/networking/default_network/configure-dns.md
index 5fe0d0e114..ab87c82a79 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.
+> **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.
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/dockerlinks.md b/docs/userguide/networking/default_network/dockerlinks.md
index ef8e160b1d..cee84cbd0b 100644
--- a/docs/userguide/networking/default_network/dockerlinks.md
+++ b/docs/userguide/networking/default_network/dockerlinks.md
@@ -11,7 +11,7 @@ weight=-2
# Legacy container links
-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.
+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
Docker link feature to allow containers to discover each other and securely
@@ -95,6 +95,12 @@ configurations. For example, if you've bound the container port to the
## Connect with the linking system
+> **Note**:
+> This section covers the legacy link feature in the default `bridge` network.
+> Please refer to [linking containers in user-defined networks]
+> (../work-with-networks.md#linking-containers-in-user-defined-networks)
+> for more information on links in user-defined networks.
+
Network port mappings are not the only way Docker containers can connect to one
another. Docker also has a linking system that allows you to link multiple
containers together and send connection information from one to another. When
diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md
index c91bf7b40e..b9f1a63b44 100644
--- a/docs/userguide/networking/dockernetworks.md
+++ b/docs/userguide/networking/dockernetworks.md
@@ -284,7 +284,7 @@ The default `docker0` bridge network supports the use of port mapping and `dock
## User-defined networks
You can create your own user-defined networks that better isolate containers.
-Docker provides some default **network drivers** for use creating these
+Docker provides some default **network drivers** for creating these
networks. You can create a new **bridge network** or **overlay network**. You
can also create a **network plugin** or **remote network** written to your own
specifications.
@@ -439,6 +439,10 @@ Docker Engine for use with `overlay` network. There are two options to set:
--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 |
+
@@ -485,17 +489,28 @@ 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).
-## Legacy links
+### 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 and securely transfer information about
-one container to another container. With the introduction of Docker networks,
-you can still create links but they are only supported on the default `bridge`
-network named `bridge` and appearing in your network stack as `docker0`.
-
-While links are still supported in this limited capacity, you should avoid them
-in preference of Docker networks. The link feature is expected to be deprecated
-and removed in a future release.
+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
diff --git a/docs/userguide/networking/get-started-overlay.md b/docs/userguide/networking/get-started-overlay.md
index 17e840c52f..39d7da9169 100644
--- a/docs/userguide/networking/get-started-overlay.md
+++ b/docs/userguide/networking/get-started-overlay.md
@@ -158,10 +158,16 @@ To create an overlay network
3. Create your `overlay` network.
- $ docker network create --driver overlay my-net
+ $ docker network create --driver overlay --subnet=10.0.9.0/24 my-net
You only need to create the network on a single host in the cluster. In this case, you used the Swarm master but you could easily have run it on any host in the cluster.
+> **Note** : It is highly recommended to use the `--subnet` option when creating
+> a network. If the `--subnet` is not specified, the docker daemon automatically
+> chooses and assigns a subnet for the network and it could overlap with another subnet
+> in your infrastructure that is not managed by docker. Such overlaps can cause
+> connectivity issues or failures when containers are connected to that network.
+
4. Check that the network is running:
$ docker network ls
@@ -308,41 +314,9 @@ to have external connectivity outside of their cluster.
## Step 6: Extra Credit with Docker Compose
-You can try starting a second network on your existing Swarm cluster using Docker Compose.
-
-1. If you haven't already, install Docker Compose.
-
-2. Change your environment to the Swarm master.
-
- $ eval $(docker-machine env --swarm mhs-demo0)
-
-3. Create a `docker-compose.yml` file.
-
-4. Add the following content to the file.
-
- web:
- image: bfirsh/compose-mongodb-demo
- environment:
- - "MONGO_HOST=counter_mongo_1"
- - "constraint:node==mhs-demo0"
- ports:
- - "80:5000"
- mongo:
- image: mongo
-
-5. Save and close the file.
-
-6. Start the application with Compose.
-
- $ docker-compose --x-networking --project-name=counter up -d
-
-7. Get the Swarm master's IP address.
-
- $ docker-machine ip mhs-demo0
-
-8. Put the IP address into your web browser.
-
- Upon success, the browser should display the web application.
+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
diff --git a/docs/userguide/networking/work-with-networks.md b/docs/userguide/networking/work-with-networks.md
index c187346e49..b668bc1c77 100644
--- a/docs/userguide/networking/work-with-networks.md
+++ b/docs/userguide/networking/work-with-networks.md
@@ -79,7 +79,13 @@ management that can assist your implementation.
When you create a network, Engine creates a non-overlapping subnetwork for the
network by default. You can override this default and specify a subnetwork
directly using the the `--subnet` option. On a `bridge` network you can only
-create a single subnet. An `overlay` network supports multiple subnets.
+specify a single subnet. An `overlay` network supports multiple subnets.
+
+> **Note** : It is highly recommended to use the `--subnet` option while creating
+> a network. If the `--subnet` is not specified, the docker daemon automatically
+> chooses and assigns a subnet for the network and it could overlap with another subnet
+> in your infrastructure that is not managed by docker. Such overlaps can cause
+> connectivity issues or failures when containers are connected to that network.
In addition to the `--subnetwork` option, you also specify the `--gateway` `--ip-range` and `--aux-address` options.
@@ -778,6 +784,25 @@ round-trip min/avg/max = 0.119/0.146/0.174 ms
/ #
```
+There are certain scenarios such as ungraceful docker daemon restarts in multi-host network,
+where the daemon is unable to cleanup stale connectivity endpoints. Such stale endpoints
+may cause an error `container already connected to network` when a new container is
+connected to that network with the same name as the stale endpoint. In order to cleanup
+these stale endpoints, first remove the container and force disconnect
+(`docker network disconnect -f`) the endpoint from the network. Once the endpoint is
+cleaned up, the container can be connected to the network.
+
+```
+$ docker run -d --name redis_db --net multihost redis
+ERROR: Cannot start container bc0b19c089978f7845633027aa3435624ca3d12dd4f4f764b61eac4c0610f32e: container already connected to network multihost
+
+$ docker rm -f redis_db
+$ docker network disconnect -f multihost redis_db
+
+$ docker run -d --name redis_db --net multihost redis
+7d986da974aeea5e9f7aca7e510bdb216d58682faa83a9040c2f2adc0544795a
+```
+
## Remove a network
When all the containers in a network are stopped or disconnected, you can remove a network.