From 61387427cb9b1ed6a4c34e0a7960183159ee305d Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Sat, 11 Oct 2014 09:15:54 -0700 Subject: [PATCH] Add more info about the LINK env vars created @SvenDowideit see what you think. I'd like to get your take on this before I submit the PR. Closes #4789 Signed-off-by: Doug Davis --- docs/sources/userguide/dockerlinks.md | 42 ++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/sources/userguide/dockerlinks.md b/docs/sources/userguide/dockerlinks.md index 717ab43409..5778eab85b 100644 --- a/docs/sources/userguide/dockerlinks.md +++ b/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 `_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: + +* `_PORT__` will contain a URL reference to the +port. Where `` is the alias name specified in the `--link` parameter +(e.g. `webdb`), `` is the port number being exposed, and `` +is either `TCP` or `UDP`. The format of the URL will be: +`://:` +(e.g. `tcp://172.17.0.82:8080`). This URL will then be +split into the following 3 environment variables for convinience: +* `_PORT___ADDR` will contain just the IP address +from the URL (e.g. `WEBDB_PORT_8080_TCP_ADDR=172.17.0.82`). +* `_PORT___PORT` will contain just the port number +from the URL (e.g. `WEBDB_PORT_8080_TCP_PORT=8080`). +* `_PORT___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 `_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: