From 02a859b9f3fdb965f1bba0ecab160521874bca74 Mon Sep 17 00:00:00 2001
From: Mary Anthony <mary@docker.com>
Date: Wed, 30 Sep 2015 13:11:36 -0700
Subject: [PATCH] First pass at consolidating Removing old networking.md
 Updating dockernetworks.md with images Adding information on network plugins
 Adding blurb about links to docker networking Updating the working
 documentation Adding Overlay Getting Started Downplaying links by removing
 refs/examples, adding refs/examples for network. Updating getting started to
 reflect networks not links Pulling out old network material Updating per
 discussion with Madhu to add Default docs section Updating with bridge
 default Fix bad merge Updating with new cluster-advertise behavior Update
 working and NetworkSettings examples Correcting example for default bridge
 discovery behavior Entering comments Fixing broken Markdown Syntax Updating
 with comments Updating all the links

Signed-off-by: Mary Anthony <mary@docker.com>
---
 docs/extend/plugins.md                        |   5 +-
 docs/extend/plugins_network.md                |  49 +++---
 docs/reference/builder.md                     |  88 +++++------
 docs/reference/commandline/attach.md          |   2 +-
 docs/reference/commandline/daemon.md          |  15 +-
 docs/reference/commandline/inspect.md         |   6 +-
 docs/reference/commandline/network_connect.md |   2 +-
 docs/reference/commandline/network_create.md  |   4 +-
 .../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/reference/commandline/run.md             |  80 ++++------
 docs/reference/glossary.md                    |  11 +-
 docs/reference/run.md                         | 142 ++++++------------
 experimental/README.md                        |   2 +-
 man/docker-attach.1.md                        |   2 +-
 man/docker-daemon.8.md                        |   5 +-
 man/docker-inspect.1.md                       |   2 +-
 19 files changed, 175 insertions(+), 248 deletions(-)

diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md
index 2ea373a2ed..4d73c8e310 100644
--- a/docs/extend/plugins.md
+++ b/docs/extend/plugins.md
@@ -18,9 +18,8 @@ plugins.
 
 Plugins extend Docker's functionality.  They come in specific types.  For
 example, a [volume plugin](plugins_volume.md) might enable Docker
-volumes to persist across multiple Docker hosts and a 
-[network plugin](plugins_network.md) might provide network plumbing
-using a favorite networking technology, such as vxlan overlay, ipvlan, EVPN, etc.
+volumes to persist across multiple Docker hosts and a
+[network plugin](plugins_network.md) might provide network plumbing.
 
 Currently Docker supports volume and network driver plugins. In the future it
 will support additional plugin types.
diff --git a/docs/extend/plugins_network.md b/docs/extend/plugins_network.md
index 335ee9d04a..b1c05558d3 100644
--- a/docs/extend/plugins_network.md
+++ b/docs/extend/plugins_network.md
@@ -1,7 +1,7 @@
 <!--[metadata]>
 +++
 title = "Docker network driver plugins"
-description = "Network drive plugins."
+description = "Network driver plugins."
 keywords = ["Examples, Usage, plugins, docker, documentation, user guide"]
 [menu.main]
 parent = "mn_extend"
@@ -11,41 +11,48 @@ weight=-1
 
 # Docker network driver plugins
 
-Docker supports network driver plugins via
-[LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are
-implemented as "remote drivers" for LibNetwork, which shares plugin
-infrastructure with Docker. In effect this means that network driver plugins
-are activated in the same way as other plugins, and use the same kind of
-protocol.
+Docker network plugins enable Docker deployments to be extended to support a
+wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN or
+something completely different. Network driver plugins are supported via the
+LibNetwork project. Each plugin is implemented asa  "remote driver" for
+LibNetwork, which shares plugin infrastructure with Docker. Effectively,
+network driver plugins are activated in the same way as other plugins, and use
+the same kind of protocol.
 
 ## Using network driver plugins
 
-The means of installing and running a network driver plugin will depend on the
-particular plugin.
+The means of installing and running a network driver plugin depend on the
+particular plugin. So, be sure to install your plugin according to the
+instructions obtained from the plugin developer.
 
 Once running however, network driver plugins are used just like the built-in
 network drivers: by being mentioned as a driver in network-oriented Docker
 commands. For example,
 
-    docker network create -d weave mynet
+    $ docker network create --driver weave mynet
 
 Some network driver plugins are listed in [plugins](plugins.md)
 
-The network thus created is owned by the plugin, so subsequent commands
-referring to that network will also be run through the plugin such as,
+The `mynet` network is now owned by `weave`, so subsequent commands
+referring to that network will be sent to the plugin,
 
-    docker run --net=mynet busybox top
+    $ docker run --net=mynet busybox top
 
-## Network driver plugin protocol
 
-The network driver protocol, additional to the plugin activation call, is
-documented as part of LibNetwork:
+## Write a network plugin
+
+Network plugins implement the [Docker plugin
+API](https://docs.docker.com/extend/plugin_api/) and the network plugin protocol
+
+## Network plugin protocol
+
+The network driver protocol, in addition to the plugin activation call, is
+documented as part of libnetwork:
 [https://github.com/docker/libnetwork/blob/master/docs/remote.md](https://github.com/docker/libnetwork/blob/master/docs/remote.md).
 
-# Related GitHub PRs and issues
+# Related Information
 
-Please record your feedback in the following issue, on the usual
-Google Groups, or the IRC channel #docker-network.
+To interact with the Docker maintainers and other interested users, se the IRC channel `#docker-network`.
 
- - [#14083](https://github.com/docker/docker/issues/14083) Feedback on
-   experimental networking features
+-  [Docker networks feature overview](../userguide/networking/index.md)
+-  The [LibNetwork](https://github.com/docker/libnetwork) project
diff --git a/docs/reference/builder.md b/docs/reference/builder.md
index b1ed35ded2..5479bb001e 100644
--- a/docs/reference/builder.md
+++ b/docs/reference/builder.md
@@ -43,7 +43,7 @@ Dockerfile.
 
 >**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes
 >the build to transfer the entire contents of your hard drive to the Docker
->daemon. 
+>daemon.
 
 To use a file in the build context, the `Dockerfile` refers to the file specified
 in an instruction, for example,  a `COPY` instruction. To increase the build's
@@ -159,7 +159,7 @@ Example (parsed representation is displayed after the `#`):
     ADD . $foo       # ADD . /bar
     COPY \$foo /quux # COPY $foo /quux
 
-Environment variables are supported by the following list of instructions in 
+Environment variables are supported by the following list of instructions in
 the `Dockerfile`:
 
 * `ADD`
@@ -177,7 +177,7 @@ as well as:
 * `ONBUILD` (when combined with one of the supported instructions above)
 
 > **Note**:
-> prior to 1.4, `ONBUILD` instructions did **NOT** support environment 
+> prior to 1.4, `ONBUILD` instructions did **NOT** support environment
 > variable, even when combined with any of the instructions listed above.
 
 Environment variable substitution will use the same value for each variable
@@ -187,7 +187,7 @@ throughout the entire command. In other words, in this example:
     ENV abc=bye def=$abc
     ENV ghi=$abc
 
-will result in `def` having a value of `hello`, not `bye`. However, 
+will result in `def` having a value of `hello`, not `bye`. However,
 `ghi` will have a value of `bye` because it is not part of the same command
 that set `abc` to `bye`.
 
@@ -354,13 +354,13 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME'
 > Unlike the *shell* form, the *exec* form does not invoke a command shell.
 > This means that normal shell processing does not happen. For example,
 > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
-> If you want shell processing then either use the *shell* form or execute 
+> If you want shell processing then either use the *shell* form or execute
 > a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`.
 
 The cache for `RUN` instructions isn't invalidated automatically during
-the next build. The cache for an instruction like 
-`RUN apt-get dist-upgrade -y` will be reused during the next build. The 
-cache for `RUN` instructions can be invalidated by using the `--no-cache` 
+the next build. The cache for an instruction like
+`RUN apt-get dist-upgrade -y` will be reused during the next build. The
+cache for `RUN` instructions can be invalidated by using the `--no-cache`
 flag, for example `docker build --no-cache`.
 
 See the [`Dockerfile` Best Practices
@@ -399,8 +399,8 @@ the executable, in which case you must specify an `ENTRYPOINT`
 instruction as well.
 
 > **Note**:
-> If `CMD` is used to provide default arguments for the `ENTRYPOINT` 
-> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified 
+> If `CMD` is used to provide default arguments for the `ENTRYPOINT`
+> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified
 > with the JSON array format.
 
 > **Note**:
@@ -411,7 +411,7 @@ instruction as well.
 > Unlike the *shell* form, the *exec* form does not invoke a command shell.
 > This means that normal shell processing does not happen. For example,
 > `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
-> If you want shell processing then either use the *shell* form or execute 
+> If you want shell processing then either use the *shell* form or execute
 > a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`.
 
 When used in the shell or exec formats, the `CMD` instruction sets the command
@@ -461,7 +461,7 @@ An image can have more than one label. To specify multiple labels,
 Docker recommends combining labels into a single `LABEL` instruction where
 possible. Each `LABEL` instruction produces a new layer which can result in an
 inefficient image if you use many labels. This example results in a single image
-layer. 
+layer.
 
     LABEL multi.label1="value1" multi.label2="value2" other="value3"
 
@@ -470,7 +470,7 @@ The above can also be written as:
     LABEL multi.label1="value1" \
           multi.label2="value2" \
           other="value3"
-    
+
 Labels are additive including `LABEL`s in `FROM` images. If Docker
 encounters a label/key that already exists, the new value overrides any previous
 labels with identical keys.
@@ -494,12 +494,15 @@ To view an image's labels, use the `docker inspect` command.
 The `EXPOSE` instruction informs Docker that the container listens on the
 specified network ports at runtime. `EXPOSE` does not make the ports of the
 container accessible to the host. To do that, you must use either the `-p` flag
-to publish a range of ports or the `-P` flag to publish all of the exposed ports.
-You can expose one port number and publish it externally under another number.
- 
-Docker uses exposed and published ports to interconnect containers using links
-(see [Linking containers together](../userguide/dockerlinks.md))
-and to set up port redirection on the host system when [using the -P flag](run.md#expose-incoming-ports).
+to publish a range of ports or the `-P` flag to publish all of the exposed
+ports. You can expose one port number and publish it externally under another
+number.
+
+To set up port redirection on the host system, see [using the -P
+flag](run.md#expose-incoming-ports). The Docker network feature supports
+creating networks without the need to expose ports within the network, for
+detailed information see the  [overview of this
+feature](../userguide/networking/index.md)).
 
 ## ENV
 
@@ -507,17 +510,18 @@ and to set up port redirection on the host system when [using the -P flag](run.m
     ENV <key>=<value> ...
 
 The `ENV` instruction sets the environment variable `<key>` to the value
-`<value>`. This value will be in the environment of all "descendent" `Dockerfile`
-commands and can be [replaced inline](#environment-replacement) in many as well.
+`<value>`. This value will be in the environment of all "descendent"
+`Dockerfile` commands and can be [replaced inline](#environment-replacement) in
+many as well.
 
 The `ENV` instruction has two forms. The first form, `ENV <key> <value>`,
 will set a single variable to a value. The entire string after the first
-space will be treated as the `<value>` - including characters such as 
+space will be treated as the `<value>` - including characters such as
 spaces and quotes.
 
-The second form, `ENV <key>=<value> ...`, allows for multiple variables to 
-be set at one time. Notice that the second form uses the equals sign (=) 
-in the syntax, while the first form does not. Like command line parsing, 
+The second form, `ENV <key>=<value> ...`, allows for multiple variables to
+be set at one time. Notice that the second form uses the equals sign (=)
+in the syntax, while the first form does not. Like command line parsing,
 quotes and backslashes can be used to include spaces within values.
 
 For example:
@@ -531,7 +535,7 @@ and
     ENV myDog Rex The Dog
     ENV myCat fluffy
 
-will yield the same net results in the final container, but the first form 
+will yield the same net results in the final container, but the first form
 is preferred because it produces a single cache layer.
 
 The environment variables set using `ENV` will persist when a container is run
@@ -555,8 +559,8 @@ whitespace)
 The `ADD` instruction copies new files, directories or remote file URLs from `<src>`
 and adds them to the filesystem of the container at the path `<dest>`.  
 
-Multiple `<src>` resource may be specified but if they are files or 
-directories then they must be relative to the source directory that is 
+Multiple `<src>` resource may be specified but if they are files or
+directories then they must be relative to the source directory that is
 being built (the context of the build).
 
 Each `<src>` may contain wildcards and matching will be done using Go's
@@ -619,8 +623,8 @@ guide](../articles/dockerfile_best-practices.md#build-cache) for more informatio
   appropriate filename can be discovered in this case (`http://example.com`
   will not work).
 
-- If `<src>` is a directory, the entire contents of the directory are copied, 
-  including filesystem metadata. 
+- If `<src>` is a directory, the entire contents of the directory are copied,
+  including filesystem metadata.
 
 > **Note**:
 > The directory itself is not copied, just its contents.
@@ -640,7 +644,7 @@ guide](../articles/dockerfile_best-practices.md#build-cache) for more informatio
   at `<dest>/base(<src>)`.
 
 - If multiple `<src>` resources are specified, either directly or due to the
-  use of a wildcard, then `<dest>` must be a directory, and it must end with 
+  use of a wildcard, then `<dest>` must be a directory, and it must end with
   a slash `/`.
 
 - If `<dest>` does not end with a trailing slash, it will be considered a
@@ -688,8 +692,8 @@ All new files and directories are created with a UID and GID of 0.
   `docker build` is to send the context directory (and subdirectories) to the
   docker daemon.
 
-- If `<src>` is a directory, the entire contents of the directory are copied, 
-  including filesystem metadata. 
+- If `<src>` is a directory, the entire contents of the directory are copied,
+  including filesystem metadata.
 
 > **Note**:
 > The directory itself is not copied, just its contents.
@@ -700,7 +704,7 @@ All new files and directories are created with a UID and GID of 0.
   at `<dest>/base(<src>)`.
 
 - If multiple `<src>` resources are specified, either directly or due to the
-  use of a wildcard, then `<dest>` must be a directory, and it must end with 
+  use of a wildcard, then `<dest>` must be a directory, and it must end with
   a slash `/`.
 
 - If `<dest>` does not end with a trailing slash, it will be considered a
@@ -729,7 +733,7 @@ Command line arguments to `docker run <image>` will be appended after all
 elements in an *exec* form `ENTRYPOINT`, and will override all elements specified
 using `CMD`.
 This allows arguments to be passed to the entry point, i.e., `docker run <image> -d`
-will pass the `-d` argument to the entry point. 
+will pass the `-d` argument to the entry point.
 You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint`
 flag.
 
@@ -760,10 +764,10 @@ When you run the container, you can see that `top` is the only process:
     %Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
     KiB Mem:   2056668 total,  1616832 used,   439836 free,    99352 buffers
     KiB Swap:  1441840 total,        0 used,  1441840 free.  1324440 cached Mem
-    
+
       PID USER      PR  NI    VIRT    RES    SHR S %CPU %MEM     TIME+ COMMAND
         1 root      20   0   19744   2336   2080 R  0.0  0.1   0:00.04 top
-    
+
 To examine the result further, you can use `docker exec`:
 
     $ docker exec -it test ps aux
@@ -867,7 +871,7 @@ sys	0m 0.03s
 > Unlike the *shell* form, the *exec* form does not invoke a command shell.
 > This means that normal shell processing does not happen. For example,
 > `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
-> If you want shell processing then either use the *shell* form or execute 
+> If you want shell processing then either use the *shell* form or execute
 > a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`.
 > Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by
 > the `Dockerfile` parser.
@@ -941,12 +945,12 @@ and marks it as holding externally mounted volumes from native host or other
 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
 /var/db`. For more information/examples and mounting instructions via the
-Docker client, refer to 
+Docker client, refer to
 [*Share Directories via Volumes*](../userguide/dockervolumes.md#mount-a-host-directory-as-a-data-volume)
 documentation.
 
-The `docker run` command initializes the newly created volume with any data 
-that exists at the specified location within the base image. For example, 
+The `docker run` command initializes the newly created volume with any data
+that exists at the specified location within the base image. For example,
 consider the following Dockerfile snippet:
 
     FROM ubuntu
@@ -955,7 +959,7 @@ consider the following Dockerfile snippet:
     VOLUME /myvol
 
 This Dockerfile results in an image that causes `docker run`, to
-create a new mount point at `/myvol` and copy the  `greeting` file 
+create a new mount point at `/myvol` and copy the  `greeting` file
 into the newly created volume.
 
 > **Note**:
diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md
index 04a44cdd6d..d746190d60 100644
--- a/docs/reference/commandline/attach.md
+++ b/docs/reference/commandline/attach.md
@@ -22,7 +22,7 @@ The `docker attach` command allows you to attach to a running container using
 the container's ID or name, either to view its ongoing output or to control it
 interactively. You can attach to the same contained process multiple times
 simultaneously, screen sharing style, or quickly view the progress of your
-daemonized process.
+detached  process.
 
 You can detach from the container and leave it running with `CTRL-p CTRL-q`
 (for a quiet exit) or with `CTRL-c` if `--sig-proxy` is false.
diff --git a/docs/reference/commandline/daemon.md b/docs/reference/commandline/daemon.md
index 6ac3876353..91fd3c6cf0 100644
--- a/docs/reference/commandline/daemon.md
+++ b/docs/reference/commandline/daemon.md
@@ -23,7 +23,7 @@ weight = -1
       --default-gateway=""                   Container default gateway IPv4 address
       --default-gateway-v6=""                Container default gateway IPv6 address
       --cluster-store=""                     URL of the distributed storage backend
-      --cluster-advertise=""                 Address of the daemon instance to advertise
+      --cluster-advertise=""                 Address of the daemon instance on the cluster
       --cluster-store-opt=map[]              Set cluster options
       --dns=[]                               DNS server to use
       --dns-opt=[]                           DNS options to use
@@ -547,13 +547,16 @@ please check the [run](run.md) reference.
 
 ## Nodes discovery
 
-`--cluster-advertise` specifies the 'host:port' combination that this particular
-daemon instance should use when advertising itself to the cluster. The daemon
-is reached by remote hosts on this 'host:port' combination.
+The `--cluster-advertise` option specifies the 'host:port' or `interface:port`
+combination that this particular daemon instance should use when advertising
+itself to the cluster. The daemon is reached by remote hosts through this value.
+If you  specify an interface, make sure it includes the IP address of the actual
+Docker host. For Engine installation created through `docker-machine`, the
+interface is typically `eth1`.
 
 The daemon uses [libkv](https://github.com/docker/libkv/) to advertise
-the node within the cluster.  Some Key/Value backends support mutual
-TLS, and the client TLS settings used by the daemon can be configured
+the node within the cluster. Some key-value backends support mutual
+TLS. To configure the client TLS settings used by the daemon can be configured
 using the `--cluster-store-opt` flag, specifying the paths to PEM encoded
 files. For example:
 
diff --git a/docs/reference/commandline/inspect.md b/docs/reference/commandline/inspect.md
index e9aea381ff..6620163f70 100644
--- a/docs/reference/commandline/inspect.md
+++ b/docs/reference/commandline/inspect.md
@@ -33,14 +33,14 @@ describes all the details of the format.
 For the most part, you can pick out any field from the JSON in a fairly
 straightforward manner.
 
-    $ docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID
+    $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID
 
 **Get an instance's MAC Address:**
 
 For the most part, you can pick out any field from the JSON in a fairly
 straightforward manner.
 
-    $ docker inspect --format='{{.NetworkSettings.MacAddress}}' $INSTANCE_ID
+    $ docker inspect '{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID
 
 **Get an instance's log path:**
 
@@ -58,7 +58,7 @@ output:
 The `.Field` syntax doesn't work when the field name begins with a
 number, but the template language's `index` function does. The
 `.NetworkSettings.Ports` section contains a map of the internal port
-mappings to a list of external address/port objects, so to grab just the
+mappings to a list of external address/port objects. To grab just the
 numeric public port, you use `index` to find the specific port map, and
 then `index` 0 contains the first object inside of that. Then we ask for
 the `HostPort` field to get the public address.
diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md
index 70f42f65b2..b3b5773457 100644
--- a/docs/reference/commandline/network_connect.md
+++ b/docs/reference/commandline/network_connect.md
@@ -2,7 +2,7 @@
 +++
 title = "network connect"
 description = "The network connect command description and usage"
-keywords = ["network, connect"]
+keywords = ["network, connect, user-defined"]
 [menu.main]
 parent = "smn_cli"
 +++
diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md
index 01ebda7222..eb80952d12 100644
--- a/docs/reference/commandline/network_create.md
+++ b/docs/reference/commandline/network_create.md
@@ -2,7 +2,7 @@
 +++
 title = "network create"
 description = "The network create command description and usage"
-keywords = ["network create"]
+keywords = ["network, create"]
 [menu.main]
 parent = "smn_cli"
 +++
@@ -55,7 +55,7 @@ The `docker daemon` options that support the `overlay` network are:
 
 To read more about these options and how to configure them, see ["*Get started
 with multi-host network*"](../../userguide/networking/get-started-overlay.md).
- 
+
 It is also a good idea, though not required, that you install Docker Swarm on to
 manage the cluster that makes up your network. Swarm provides sophisticated
 discovery and server management that can assist your implementation.
diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md
index c0104d9ec6..bbb351d24f 100644
--- a/docs/reference/commandline/network_disconnect.md
+++ b/docs/reference/commandline/network_disconnect.md
@@ -2,7 +2,7 @@
 +++
 title = "network disconnect"
 description = "The network disconnect command description and usage"
-keywords = ["network, disconnect"]
+keywords = ["network, disconnect, user-defined"]
 [menu.main]
 parent = "smn_cli"
 +++
diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md
index fa5b0b656d..aedf5c41cc 100644
--- a/docs/reference/commandline/network_inspect.md
+++ b/docs/reference/commandline/network_inspect.md
@@ -2,7 +2,7 @@
 +++
 title = "network inspect"
 description = "The network inspect command description and usage"
-keywords = ["network, inspect"]
+keywords = ["network, inspect, user-defined"]
 [menu.main]
 parent = "smn_cli"
 +++
diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md
index 2a102f5f6d..9b4dbddc83 100644
--- a/docs/reference/commandline/network_ls.md
+++ b/docs/reference/commandline/network_ls.md
@@ -2,7 +2,7 @@
 +++
 title = "network ls"
 description = "The network ls command description and usage"
-keywords = ["network, list"]
+keywords = ["network, list, user-defined"]
 [menu.main]
 parent = "smn_cli"
 +++
diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md
index 34093cd38f..ef79fcac84 100644
--- a/docs/reference/commandline/network_rm.md
+++ b/docs/reference/commandline/network_rm.md
@@ -2,7 +2,7 @@
 +++
 title = "network rm"
 description = "the network rm command description and usage"
-keywords = ["network, rm"]
+keywords = ["network, rm, user-defined"]
 [menu.main]
 parent = "smn_cli"
 +++
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index fdfd96b2da..5e7dd5dd9e 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -86,14 +86,10 @@ specified image, and then `starts` it using the specified command. That is,
 previous changes intact using `docker start`. See `docker ps -a` to view a list
 of all containers.
 
-There is detailed information about `docker run` in the [Docker run reference](run.md).
-
 The `docker run` command can be used in combination with `docker commit` to
-[*change the command that a container runs*](commit.md).
+[*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md).
 
-See the [Docker User Guide](../../userguide/dockerlinks.md) for more detailed
-information about the `--expose`, `-p`, `-P` and `--link` parameters,
-and linking containers.
+For information on connecting a container to a network, see the ["*Docker network overview*"](../../userguide/networking/index.md).
 
 ## Examples
 
@@ -185,16 +181,15 @@ manipulate the host's Docker daemon.
 
     $ docker run -p 127.0.0.1:80:8080 ubuntu bash
 
-This binds port `8080` of the container to port `80` on `127.0.0.1` of
-the host machine. The [Docker User Guide](../../userguide/dockerlinks.md)
+This binds port `8080` of the container to port `80` on `127.0.0.1` of the host
+machine. The [Docker User
+Guide](../../userguide/networking/default_network/dockerlinks.md)
 explains in detail how to manipulate ports in Docker.
 
     $ docker run --expose 80 ubuntu bash
 
-This exposes port `80` of the container for use within a link without
-publishing the port to the host system's interfaces. The [Docker User
-Guide](../../userguide/dockerlinks.md) explains in detail how to manipulate
-ports in Docker.
+This exposes port `80` of the container without publishing the port to the host
+system's interfaces.
 
 ### Set environment variables (-e, --env, --env-file)
 
@@ -302,21 +297,29 @@ For additional information on working with labels, see [*Labels - custom
 metadata in Docker*](../../userguide/labels-custom-metadata.md) in the Docker User
 Guide.
 
-### Add link to another container (--link)
+### Connect a container to a network (--net)
 
-    $ docker run --link /redis:redis --name console ubuntu bash
+When you start a container use the `--net` flag to connect it to a network.
+This adds the `busybox` container to the `mynet` network.
 
-The `--link` flag will link the container named `/redis` into the newly
-created container with the alias `redis`. The new container can access the
-network and environment of the `redis` container via environment variables.
-The `--link` flag will also just accept the form `<name or id>` in which case
-the alias will match the name. For instance, you could have written the previous
-example as:
+```bash
+$ docker run -itd --net=my-multihost-network busybox
+```
 
-    $ docker run --link redis --name console ubuntu bash
+If you want to add a running container to a network use the `docker network connect` subcommand.
 
-The `--name` flag will assign the name `console` to the newly created
-container.
+You can connect multiple containers to the same network. Once connected, the
+containers can communicate easily need only another container's IP address
+or name. For `overlay` networks or custom plugins that support multi-host
+connectivity, containers connected to the same multi-host network but launched
+from different Engines can also communicate in this way.
+
+**Note**: Service discovery is unavailable on the default bridge network.
+Containers can communicate via their IP addresses by default. To communicate
+by name, they must be linked.
+
+You can disconnect a container from a network using the `docker network
+disconnect` command.
 
 ### Mount volumes from container (--volumes-from)
 
@@ -537,34 +540,3 @@ the three processes quota set for the `daemon` user.
 The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
 This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
 or a signal name in the format SIGNAME, for instance SIGKILL.
-
-### A complete example
-
-    $ docker run -d --name static static-web-files sh
-    $ docker run -d --expose=8098 --name riak riakserver
-    $ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
-    $ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
-    $ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
-
-This example shows five containers that might be set up to test a web
-application change:
-
-1. Start a pre-prepared volume image `static-web-files` (in the background)
-   that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
-   the Dockerfile to allow the web server to use those files);
-2. Start a pre-prepared `riakserver` image, give the container name `riak` and
-   expose port `8098` to any containers that link to it;
-3. Start the `appserver` image, restricting its memory usage to 100MB, setting
-   two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
-   current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
-4. Start the `webserver`, mapping port `443` in the container to port `1443` on
-   the Docker server, setting the DNS server to `10.0.0.1` and DNS search
-   domain to `dev.org`, creating a volume to put the log files into (so we can
-   access it from another container), then importing the files from the volume
-   exposed by the `static` container, and linking to all exposed ports from
-   `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
-   consistent with the pre-generated SSL certificate;
-5. Finally, we create a container that runs `tail -f access.log` using the logs
-   volume from the `web` container, setting the workdir to `/var/log/httpd`. The
-   `--rm` option means that when the container exits, the container's layer is
-   removed.
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
index 3f7e7a0326..ff4398c249 100644
--- a/docs/reference/glossary.md
+++ b/docs/reference/glossary.md
@@ -135,16 +135,14 @@ after the container is created.
 ## libnetwork
 
 libnetwork provides a native Go implementation for creating and managing container
-network namespaces and other network resources. It manage the networking lifecycle 
+network namespaces and other network resources. It manage the networking lifecycle
 of the container performing additional operations after the container is created.
 
 ## link
 
-links provide an interface to connect Docker containers running on the same host
-to each other without exposing the hosts' network ports. When you set up a link,
-you create a conduit between a source container and a recipient container.
-The recipient can then access select data about the source. To create a link,
-you can use the `--link` flag.
+links provide a legacy interface to connect Docker containers running on the
+same host to each other without exposing the hosts' network ports. Use the
+Docker networks feature instead.
 
 ## Machine
 
@@ -221,4 +219,3 @@ Compared to to containers, a Virtual Machine is heavier to run, provides more is
 gets its own set of resources and does minimal sharing.
 
 *Also known as : VM*
-
diff --git a/docs/reference/run.md b/docs/reference/run.md
index 7a5acf01b0..a7aabecc42 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -154,13 +154,14 @@ The operator can identify a container in three ways:
 -   UUID short identifier ("f78375b1c487")
 -   Name ("evil_ptolemy")
 
-The UUID identifiers come from the Docker daemon, and if you do not
-assign a name to the container with `--name` then the daemon will also
-generate a random string name too. The name can become a handy way to
-add meaning to a container since you can use this name when defining
-[*links*](../userguide/dockerlinks.md) (or any
-other place you need to identify a container). This works for both
-background and foreground Docker containers.
+The UUID identifiers come from the Docker daemon. If you do not assign a
+container name with the `--name` option, then the daemon generates a random
+string name for you. Defining a `name` can be a handy way to add meaning to a
+container. If you specify a `name`, you can use it  when referencing the
+container within a Docker network. This works for both background and foreground
+Docker containers.
+
+**Note**: Containers on the default bridge network must be linked to communicate by name.  
 
 ### PID equivalent
 
@@ -259,8 +260,7 @@ with `docker run --net none` which disables all incoming and outgoing
 networking. In cases like this, you would perform I/O through files or
 `STDIN` and `STDOUT` only.
 
-Publishing ports and linking to other containers will not work
-when `--net` is anything other than the default (bridge).
+Publishing ports and linking to other containers only works with the the default (bridge). The linking feature is a legacy feature. You should always prefer using Docker network drivers over linking.
 
 Your container will use the same DNS servers as the host by default, but
 you can override this with `--dns`.
@@ -331,6 +331,9 @@ container's namespaces in addition to the `loopback` interface.  An IP
 address will be allocated for containers on the bridge's network and
 traffic will be routed though this bridge to the container.
 
+Containers can communicate via their IP addresses by default. To communicate by
+name, they must be linked.
+
 #### Network: host
 
 With the network set to `host` a container will share the host's
@@ -366,19 +369,23 @@ running the `redis-cli` command and connecting to the Redis server over the
     $ # use the redis container's network stack to access localhost
     $ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1
 
-#### Network: User-Created NETWORK
+#### User-defined network
 
-In addition to all the above special networks, user can create a network using
-their favorite network driver or external plugin. The driver used to create the
-network takes care of all the network plumbing requirements for the container
-connected to that network.
+You can create a network using a Docker network driver or an external network
+driver plugin. You can connect multiple containers to the same network. Once
+connected to a user-defined network, the containers can communicate easily using
+only another container's IP address or name.  
 
-Example creating a network using the inbuilt overlay network driver and running 
-a container in the created network
+For `overlay` networks or custom plugins that support multi-host connectivity,
+containers connected to the same multi-host network but launched from different
+Engines can also communicate in this way.
+
+The following example creates a network using the built-in `bridge` network
+driver and running a container in the created network
 
 ```
-$ docker network create -d overlay multi-host-network
-$ docker run --net=multi-host-network -itd --name=container3 busybox
+$ docker network create -d overlay my-net
+$ docker run --net=my-net -itd --name=container3 busybox
 ```
 
 ### Managing /etc/hosts
@@ -510,8 +517,8 @@ the container exits**, you can add the `--rm` flag:
 
     --rm=false: Automatically remove the container when it exits (incompatible with -d)
 
-> **Note**: When you set the `--rm` flag, Docker also removes the volumes 
-associated with the container when the container is removed. This is similar 
+> **Note**: When you set the `--rm` flag, Docker also removes the volumes
+associated with the container when the container is removed. This is similar
 to running `docker rm -v my-container`.
 
 ## Security configuration
@@ -664,7 +671,7 @@ same as the hard memory limit.
 
 Memory reservation is a soft-limit feature and does not guarantee the limit
 won't be exceeded. Instead, the feature attempts to ensure that, when memory is
-heavily contended for, memory is allocated based on the reservation hints/setup. 
+heavily contended for, memory is allocated based on the reservation hints/setup.
 
 The following example limits the memory (`-m`) to 500M and sets the memory
 reservation to 200M.
@@ -1186,12 +1193,12 @@ specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be
 bound to 42800 on the host. To find the mapping between the host ports
 and the exposed ports, use `docker port`.
 
-If the operator uses `--link` when starting a new client container,
-then the client container can access the exposed port via a private
-networking interface. Docker will set some environment variables in the
-client container to help indicate which interface and port to use. For
-more information on linking, see [the guide on linking container
-together](../userguide/dockerlinks.md)
+If the operator uses `--link` when starting a new client container, then the
+client container can access the exposed port via a private networking interface.
+Linking is a legacy feature that is only supported on the default bridge
+network. You should prefer the Docker networks feature instead. For more
+information on this feature, see the [*Docker network
+overview*""](../userguide/networking/index.md)).
 
 ### ENV (environment variables)
 
@@ -1227,11 +1234,6 @@ variables automatically:
  </tr>
 </table>
 
-The container may also include environment variables defined
-as a result of the container being linked with another container. See
-the [*Container Links*](../userguide/dockerlinks.md#connect-with-the-linking-system)
-section for more details.
-
 Additionally, the operator can **set any environment variable** in the
 container by using one or more `-e` flags, even overriding those mentioned
 above, or already defined by the developer with a Dockerfile `ENV`:
@@ -1248,69 +1250,11 @@ above, or already defined by the developer with a Dockerfile `ENV`:
 
 Similarly the operator can set the **hostname** with `-h`.
 
-`--link <name or id>:alias` also sets environment variables, using the *alias* string to
-define environment variables within the container that give the IP and PORT
-information for connecting to the service container. Let's imagine we have a
-container running Redis:
-
-    # Start the service container, named redis-name
-    $ docker run -d --name redis-name dockerfiles/redis
-    4241164edf6f5aca5b0e9e4c9eccd899b0b8080c64c0cd26efe02166c73208f3
-
-    # The redis-name container exposed port 6379
-    $ docker ps
-    CONTAINER ID        IMAGE                        COMMAND                CREATED             STATUS              PORTS               NAMES
-    4241164edf6f        $ dockerfiles/redis:latest   /redis-stable/src/re   5 seconds ago       Up 4 seconds        6379/tcp            redis-name
-
-    # Note that there are no public ports exposed since we didn᾿t use -p or -P
-    $ docker port 4241164edf6f 6379
-    2014/01/25 00:55:38 Error: No public port '6379' published for 4241164edf6f
-
-Yet we can get information about the Redis container's exposed ports
-with `--link`. Choose an alias that will form a
-valid environment variable!
-
-    $ docker run --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c export
-    declare -x HOME="/"
-    declare -x HOSTNAME="acda7f7b1cdc"
-    declare -x OLDPWD
-    declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-    declare -x PWD="/"
-    declare -x REDIS_ALIAS_NAME="/distracted_wright/redis"
-    declare -x REDIS_ALIAS_PORT="tcp://172.17.0.32:6379"
-    declare -x REDIS_ALIAS_PORT_6379_TCP="tcp://172.17.0.32:6379"
-    declare -x REDIS_ALIAS_PORT_6379_TCP_ADDR="172.17.0.32"
-    declare -x REDIS_ALIAS_PORT_6379_TCP_PORT="6379"
-    declare -x REDIS_ALIAS_PORT_6379_TCP_PROTO="tcp"
-    declare -x SHLVL="1"
-    declare -x container="lxc"
-
-And we can use that information to connect from another container as a client:
-
-    $ docker run -i -t --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c '/redis-stable/src/redis-cli -h $REDIS_ALIAS_PORT_6379_TCP_ADDR -p $REDIS_ALIAS_PORT_6379_TCP_PORT'
-    172.17.0.32:6379>
-
-Docker will also map the private IP address to the alias of a linked
-container by inserting an entry into `/etc/hosts`.  You can use this
-mechanism to communicate with a linked container by its alias:
-
-    $ docker run -d --name servicename busybox sleep 30
-    $ docker run -i -t --link servicename:servicealias busybox ping -c 1 servicealias
-
-If you restart the source container (`servicename` in this case), the recipient
-container's `/etc/hosts` entry will be automatically updated.
-
-> **Note**:
-> Unlike host entries in the `/etc/hosts` file, IP addresses stored in the
-> environment variables are not automatically updated if the source container is
-> restarted. We recommend using the host entries in `/etc/hosts` to resolve the
-> IP address of linked containers.
-
 ### VOLUME (shared filesystems)
 
     -v=[]: Create a bind mount with: [host-dir:]container-dir[:<options>], where
-    options are comma delimited and selected from [rw|ro] and [z|Z]. 
-           If 'host-dir' is missing, then docker creates a new volume. 
+    options are comma delimited and selected from [rw|ro] and [z|Z].
+           If 'host-dir' is missing, then docker creates a new volume.
 		   If neither 'rw' or 'ro' is specified then the volume is mounted
 		   in read-write mode.
     --volumes-from="": Mount all volumes from the given container(s)
@@ -1325,17 +1269,17 @@ one or more `VOLUME`'s associated with an image, but only the operator
 can give access from one container to another (or from a container to a
 volume mounted on the host).
 
-The `container-dir` must always be an absolute path such as `/src/docs`. 
-The `host-dir` can either be an absolute path or a `name` value. If you 
-supply an absolute path for the `host-dir`, Docker bind-mounts to the path 
+The `container-dir` must always be an absolute path such as `/src/docs`.
+The `host-dir` can either be an absolute path or a `name` value. If you
+supply an absolute path for the `host-dir`, Docker bind-mounts to the path
 you specify. If you supply a `name`, Docker creates a named volume by that `name`.
 
-A `name` value must start with start with an alphanumeric character, 
-followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). 
+A `name` value must start with start with an alphanumeric character,
+followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen).
 An absolute path starts with a `/` (forward slash).
 
-For example, you can specify either `/foo` or `foo` for a `host-dir` value. 
-If you supply the `/foo` value, Docker creates a bind-mount. If you supply 
+For example, you can specify either `/foo` or `foo` for a `host-dir` value.
+If you supply the `/foo` value, Docker creates a bind-mount. If you supply
 the `foo` specification, Docker creates a named volume.
 
 ### USER
diff --git a/experimental/README.md b/experimental/README.md
index ca4f102261..d2eff37d8d 100644
--- a/experimental/README.md
+++ b/experimental/README.md
@@ -1,4 +1,4 @@
-# Docker Experimental Features 
+# Docker Experimental Features
 
 This page contains a list of features in the Docker engine which are
 experimental. Experimental features are **not** ready for production. They are
diff --git a/man/docker-attach.1.md b/man/docker-attach.1.md
index 658228cddb..96fb3756a3 100644
--- a/man/docker-attach.1.md
+++ b/man/docker-attach.1.md
@@ -16,7 +16,7 @@ The **docker attach** command allows you to attach to a running container using
 the container's ID or name, either to view its ongoing output or to control it
 interactively.  You can attach to the same contained process multiple times
 simultaneously, screen sharing style, or quickly view the progress of your
-daemonized process.
+detached process.
 
 You can detach from the container (and leave it running) with `CTRL-p CTRL-q`
 (for a quiet exit) or `CTRL-c` which will send a `SIGKILL` to the container.
diff --git a/man/docker-daemon.8.md b/man/docker-daemon.8.md
index accc3b1dbb..b85a9a76fa 100644
--- a/man/docker-daemon.8.md
+++ b/man/docker-daemon.8.md
@@ -81,8 +81,9 @@ format.
   URL of the distributed storage backend
 
 **--cluster-advertise**=""
-  Specifies the 'host:port' combination that this particular daemon instance should use when advertising
-  itself to the cluster. The daemon is reached by remote hosts on this 'host:port' combination.
+  Specifies the 'host:port' or `interface:port` combination that this particular
+  daemon instance should use when advertising itself to the cluster. The daemon
+  is reached through this value.
 
 **--cluster-store-opt**=""
   Specifies options for the Key/Value store.
diff --git a/man/docker-inspect.1.md b/man/docker-inspect.1.md
index 82a7907d22..34dd04a93a 100644
--- a/man/docker-inspect.1.md
+++ b/man/docker-inspect.1.md
@@ -194,7 +194,7 @@ To get information on a container use its ID or instance name:
 
 To get the IP address of a container use:
 
-    $ docker inspect --format='{{.NetworkSettings.IPAddress}}' d2cc496561d6
+    $ docker inspect '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' d2cc496561d6
     172.17.0.2
 
 ## Listing all port bindings