Merge pull request #8525 from duglin/Issue4789

Add more info about the LINK env vars created

docs/sources/userguide/dockerlinks.md

@@ -179,7 +179,45 @@ recipient container in two ways:
 * Environment variables,
 * Updating the `/etc/hosts` file.
 
-Docker can set a number of environment variables. You run the `env`
+### Environment Variables
+
+When two containers are linked, Docker will set some envrionment variables
+in the target container to enable programmatic discovery of information
+related to the source container.
+
+First, Docker will set a `<alias>_NAME` environment variable specifying the
+alias of each target container that was given in a `--link` parameter. So,
+for example, if a new container called `web` is being linked to a database
+container called `db` via `--link db:webdb` then in the `web` container
+would be `WEBDB_NAME=/web/webdb`.
+
+Docker will then also define a set of environment variables for each
+port that is exposed by the source container. The pattern followed is:
+
+* `<name>_PORT_<port>_<protocol>` will contain a URL reference to the
+port. Where `<name>` is the alias name specified in the `--link` parameter
+(e.g. `webdb`), `<port>` is the port number being exposed, and `<protocol>`
+is either `TCP` or `UDP`. The format of the URL will be: 
+`<protocol>://<container_ip_address>:<port>`
+(e.g. `tcp://172.17.0.82:8080`).  This URL will then be
+split into the following 3 environment variables for convinience:
+* `<name>_PORT_<port>_<protocol>_ADDR` will contain just the IP address 
+from the URL (e.g. `WEBDB_PORT_8080_TCP_ADDR=172.17.0.82`).
+* `<name>_PORT_<port>_<protocol>_PORT` will contain just the port number
+from the URL (e.g. `WEBDB_PORT_8080_TCP_PORT=8080`).
+* `<name>_PORT_<port>_<protocol>_PROTO` will contain just the protocol
+from the URL (e.g. `WEBDB_PORT_8080_TCP_PROTO=tcp`).
+
+If there are multiple ports exposed then the above set of environment
+variables will be defined for each one.
+
+Finally, there will be an environment variable called `<alias>_PORT` that will
+contain the URL of the first exposed port of the source container.
+For example, `WEBDB_PORT=tcp://172.17.0.82:8080`. In this case, 'first'
+is defined as the lowest numbered port that is exposed. If that port is
+used for both tcp and udp, then the tcp one will be specified.
+
+Returning back to our database example, you can run the `env`
 command to list the specified container's environment variables.
 
 ```
@@ -207,6 +245,8 @@ environment variables to configure your applications to connect to the database
 on the `db` container. The connection will be secure and private; only the
 linked `web` container will be able to talk to the `db` container.
 
+### Updating the `/etc/hosts` file
+
 In addition to the environment variables, Docker adds a host entry for the
 source container to the `/etc/hosts` file. Here's an entry for the `web`
 container: