Docs cleanup for networking features added in v1.10

Signed-off-by: Madhu Venugopal <madhu@docker.com>

docs/userguide/networking/configure-dns.md

@@ -0,0 +1,138 @@
+<!--[metadata]>
++++
+title = "Configure container DNS in user-defined networks"
+description = "Learn how to configure DNS in user-defined networks"
+keywords = ["docker, DNS, network"]
+[menu.main]
+parent = "smn_networking"
++++
+<![end-metadata]-->
+
+# 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.
+
+<table>
+  <tr>
+    <td>
+    <p>
+    <code>--name=CONTAINER-NAME</code>
+    </p>
+    </td>
+    <td>
+    <p>
+     Container name configured using <code>--name</code> 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).
+    </p>
+    </td>
+  </tr>
+  <tr>
+    <td>
+    <p>
+    <code>--net-alias=ALIAS</code>
+    </p>
+    </td>
+    <td>
+    <p>
+     In addition to <code>--name</code> as described above, a container is discovered by one or more 
+     of its configured <code>--net-alias</code> (or <code>--alias</code> in <code>docker network connect</code> 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 <code>--alias</code>
+     option in <code>docker network connect</code> command.
+    </p>
+    </td>
+  </tr>
+  <tr>
+    <td>
+    <p>
+    <code>--link=CONTAINER_NAME:ALIAS</code>
+    </p>
+    </td>
+    <td>
+    <p>
+      Using this option as you <code>run</code> a container gives the embedded DNS
+      an extra entry named <code>ALIAS</code> that points to the IP address
+      of the container identified by <code>CONTAINER_NAME</code>. When using <code>--link</code>
+      the embedded DNS will guarantee that localized lookup result only on that
+      container where the <code>--link</code> is used. This lets processes inside the new container 
+      connect to container without without having to know its name or IP.
+    </p>
+    </td>
+  </tr>
+  <tr>
+    <td><p>
+    <code>--dns=[IP_ADDRESS...]</code>
+    </p></td>
+    <td><p>
+     The IP addresses passed via the <code>--dns</code> 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  <code>--dns</code> IP addresses are managed by the embedded DNS server and
+     will not be updated in the container's <code>/etc/resolv.conf</code> file.
+  </tr>
+  <tr>
+    <td><p>
+    <code>--dns-search=DOMAIN...</code>
+    </p></td>
+    <td><p>
+    Sets the domain names that are searched when a bare unqualified hostname is
+    used inside of the container. These <code>--dns-search</code> options are managed by the
+    embedded DNS server and will not be updated in the container's <code>/etc/resolv.conf</code> file.
+    When a container process attempts to access <code>host</code> and the search
+    domain <code>example.com</code> is set, for instance, the DNS logic will not only
+    look up <code>host</code> but also <code>host.example.com</code>.
+    </p>
+    </td>
+  </tr>
+  <tr>
+    <td><p>
+    <code>--dns-opt=OPTION...</code>
+    </p></td>
+    <td><p>
+      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 <code>/etc/resolv.conf</code> file.
+    </p>
+    <p>
+    See documentation for <code>resolv.conf</code> for a list of valid options
+    </p></td>
+  </tr>
+</table>
+
+
+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.

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:
 

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

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:
         <td><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td>
         <td>The IP address or interface of the HOST used for clustering.</td>
     </tr>
+    <tr>
+        <td><pre>--cluster-store-opt=KEY-VALUE OPTIONS</pre></td>
+        <td>Options such as TLS certificate or tuning discovery Timers</td>
+    </tr>
     </tbody>
 </table>
 
@@ -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
 

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
 

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.