Merge pull request #11172 from duglin/5169-LinkEnvDocs

Add some text about env vars when linking containers

docs/sources/userguide/dockerlinks.md

@@ -11,7 +11,7 @@ applications running inside Docker containers. In this section, we'll briefly re
 connecting via a network port and then we'll introduce you to another method of access:
 container linking.
 
-## Network port mapping refresher
+## Connect using Network port mapping
 
 In [the Using Docker section](/userguide/usingdocker), you created a
 container that ran a Python Flask application:
@@ -72,7 +72,7 @@ configurations. For example, if you've bound the container port to the
 > **Note:** 
 > The `-p` flag can be used multiple times to configure multiple ports.
 
-## Docker Container Linking
+## Connect with the linking system
 
 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
@@ -81,7 +81,7 @@ When containers are linked, information about a source container can be sent to
 recipient container. This allows the recipient to see selected data describing
 aspects of the source container.
 
-## Container naming
+### The importance of naming
 
 To establish links, Docker relies on the names of your containers.
 You've already seen that each container you create has an automatically
@@ -121,7 +121,7 @@ You can also use `docker inspect` to return the container's name.
 > flag with the `docker run` command. This will delete the container
 > immediately after it is stopped.
 
-## Container Linking
+## Communication across links
 
 Links allow containers to discover each other and securely transfer information about one
 container to another container. When you set up a link, you create a conduit between a
@@ -176,41 +176,64 @@ recipient container in two ways:
 
 ### Environment Variables
 
-When two containers are linked, Docker will set some environment variables
-in the target container to enable programmatic discovery of information
-related to the source container.
-
-First, Docker will set an `<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 convenience:
-* `<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.
+Docker creates several environment variables when you link containers. Docker
+automatically creates environment variables in the target container based on
+the `--link` parameters.  It will also expose all environment variables 
+originating from Docker from the source container. These include variables from:
+
+* the `ENV` commands in the source container's Dockerfile
+* the `-e`, `--env` and `--env-file` options on the `docker run`
+command when the source container is started
+
+These environment variables enable programmatic discovery from within the
+target container of information related to the source container.
+
+> **Warning**:
+> It is important to understand that *all* environment variables originating
+> from Docker within a container are made available to *any* container
+> that links to it. This could have serious security implications if sensitive
+> data is stored in them.
+
+Docker sets an `<alias>_NAME` environment variable for each target container
+listed in the `--link` parameter. For example, if a new container called
+`web` is linked to a database container called `db` via `--link db:webdb`,
+then Docker creates a `WEBDB_NAME=/web/webdb` variable in the `web` container.
+
+Docker also defines a set of environment variables for each port exposed by the
+source container.  Each variable has a unique prefix in the form:
+
+`<name>_PORT_<port>_<protocol>`
+
+The components in this prefix are:
+
+* the alias `<name>` specified in the `--link` parameter (for example, `webdb`)
+* the `<port>` number exposed
+* a `<protocol>` which is either TCP or UDP
+
+Docker uses this prefix format to define three distinct environment variables:
+
+* The `prefix_ADDR` variable contains the IP Address from the URL, for
+example `WEBDB_PORT_8080_TCP_ADDR=172.17.0.82`.
+* The `prefix_PORT` variable contains just the port number from the URL for
+example `WEBDB_PORT_8080_TCP_PORT=8080`.
+* The `prefix_PROTO` variable contains just the protocol from the URL for
+example `WEBDB_PORT_8080_TCP_PROTO=tcp`.
+
+If the container exposes multiple ports, an environment variable set is
+defined for each one. This means, for example, if a container exposes 4 ports
+that Docker creates 12 environment variables, 3 for each port.
+
+Additionally, Docker creates an environment variable called `<alias>_PORT`.
+This variable contains the URL of the source container's first exposed port.
+The  'first' port is defined as the exposed port with the lowest number.
+For example, consider the `WEBDB_PORT=tcp://172.17.0.82:8080` variable.  If
+that port is used for both tcp and udp, then the tcp one is specified.
+
+Finally, Docker also exposes each Docker originated environment variable
+from the source container as an environment variable in the target. For each
+variable Docker creates an `<alias>_ENV_<name>` variable in the target 
+container. The variable's value is set to the value Docker used when it 
+started the source container.
 
 Returning back to our database example, you can run the `env`
 command to list the specified container's environment variables.
@@ -227,25 +250,26 @@ command to list the specified container's environment variables.
     . . .
 ```
 
-> **Note**:
-> These Environment variables are only set for the first process in the
-> container. Similarly, some daemons (such as `sshd`)
-> will scrub them when spawning shells for connection.
-
-> **Note**:
-> Unlike host entries in the [`/etc/hosts` file](#updating-the-etchosts-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.
-
 You can see that Docker has created a series of environment variables with
-useful information about the source `db` container. Each variable is prefixed with
+useful information about the source `db` container. Each variable is prefixed
+with
 `DB_`, which is populated from the `alias` you specified above. If the `alias`
 were `db1`, the variables would be prefixed with `DB1_`. You can use these
 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.
 
+### Important notes on Docker environment variables
+
+Unlike host entries in the [`/etc/hosts` file](#updating-the-etchosts-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.
+
+These environment variables are only set for the first process in the
+container. Some daemons, such as `sshd`, will scrub them when spawning shells
+for connection.
+
 ### Updating the `/etc/hosts` file
 
 In addition to the environment variables, Docker adds a host entry for the