github.com/jogo/docker@v1.7.0-rc1/docs/sources/userguide/dockerlinks.md (about) 1 page_title: Linking containers together 2 page_description: Learn how to connect Docker containers together. 3 page_keywords: Examples, Usage, user guide, links, linking, docker, documentation, examples, names, name, container naming, port, map, network port, network 4 5 # Linking containers together 6 7 In [the Using Docker section](/userguide/usingdocker), you saw how you can 8 connect to a service running inside a Docker container via a network 9 port. But a port connection is only one way you can interact with services and 10 applications running inside Docker containers. In this section, we'll briefly revisit 11 connecting via a network port and then we'll introduce you to another method of access: 12 container linking. 13 14 ## Connect using network port mapping 15 16 In [the Using Docker section](/userguide/usingdocker), you created a 17 container that ran a Python Flask application: 18 19 $ docker run -d -P training/webapp python app.py 20 21 > **Note:** 22 > Containers have an internal network and an IP address 23 > (as we saw when we used the `docker inspect` command to show the container's 24 > IP address in the [Using Docker](/userguide/usingdocker/) section). 25 > Docker can have a variety of network configurations. You can see more 26 > information on Docker networking [here](/articles/networking/). 27 28 When that container was created, the `-P` flag was used to automatically map 29 any network port inside it to a random high port within an *ephemeral port 30 range* on your Docker host. Next, when `docker ps` was run, you saw that port 31 5000 in the container was bound to port 49155 on the host. 32 33 $ docker ps nostalgic_morse 34 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 35 bc533791f3f5 training/webapp:latest python app.py 5 seconds ago Up 2 seconds 0.0.0.0:49155->5000/tcp nostalgic_morse 36 37 You also saw how you can bind a container's ports to a specific port using 38 the `-p` flag. Here port 80 of the host is mapped to port 5000 of the 39 container: 40 41 $ docker run -d -p 80:5000 training/webapp python app.py 42 43 And you saw why this isn't such a great idea because it constrains you to 44 only one container on that specific port. 45 46 There are also a few other ways you can configure the `-p` flag. By 47 default the `-p` flag will bind the specified port to all interfaces on 48 the host machine. But you can also specify a binding to a specific 49 interface, for example only to the `localhost`. 50 51 $ docker run -d -p 127.0.0.1:80:5000 training/webapp python app.py 52 53 This would bind port 5000 inside the container to port 80 on the 54 `localhost` or `127.0.0.1` interface on the host machine. 55 56 Or, to bind port 5000 of the container to a dynamic port but only on the 57 `localhost`, you could use: 58 59 $ docker run -d -p 127.0.0.1::5000 training/webapp python app.py 60 61 You can also bind UDP ports by adding a trailing `/udp`. For example: 62 63 $ docker run -d -p 127.0.0.1:80:5000/udp training/webapp python app.py 64 65 You also learned about the useful `docker port` shortcut which showed us the 66 current port bindings. This is also useful for showing you specific port 67 configurations. For example, if you've bound the container port to the 68 `localhost` on the host machine, then the `docker port` output will reflect that. 69 70 $ docker port nostalgic_morse 5000 71 127.0.0.1:49155 72 73 > **Note:** 74 > The `-p` flag can be used multiple times to configure multiple ports. 75 76 ## Connect with the linking system 77 78 Network port mappings are not the only way Docker containers can connect 79 to one another. Docker also has a linking system that allows you to link 80 multiple containers together and send connection information from one to another. 81 When containers are linked, information about a source container can be sent to a 82 recipient container. This allows the recipient to see selected data describing 83 aspects of the source container. 84 85 ### The importance of naming 86 87 To establish links, Docker relies on the names of your containers. 88 You've already seen that each container you create has an automatically 89 created name; indeed you've become familiar with our old friend 90 `nostalgic_morse` during this guide. You can also name containers 91 yourself. This naming provides two useful functions: 92 93 1. It can be useful to name containers that do specific functions in a way 94 that makes it easier for you to remember them, for example naming a 95 container containing a web application `web`. 96 97 2. It provides Docker with a reference point that allows it to refer to other 98 containers, for example, you can specify to link the container `web` to container `db`. 99 100 You can name your container by using the `--name` flag, for example: 101 102 $ docker run -d -P --name web training/webapp python app.py 103 104 This launches a new container and uses the `--name` flag to 105 name the container `web`. You can see the container's name using the 106 `docker ps` command. 107 108 $ docker ps -l 109 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 110 aed84ee21bde training/webapp:latest python app.py 12 hours ago Up 2 seconds 0.0.0.0:49154->5000/tcp web 111 112 You can also use `docker inspect` to return the container's name. 113 114 $ docker inspect -f "{{ .Name }}" aed84ee21bde 115 /web 116 117 > **Note:** 118 > Container names have to be unique. That means you can only call 119 > one container `web`. If you want to re-use a container name you must delete 120 > the old container (with `docker rm`) before you can create a new 121 > container with the same name. As an alternative you can use the `--rm` 122 > flag with the `docker run` command. This will delete the container 123 > immediately after it is stopped. 124 125 ## Communication across links 126 127 Links allow containers to discover each other and securely transfer information about one 128 container to another container. When you set up a link, you create a conduit between a 129 source container and a recipient container. The recipient can then access select data 130 about the source. To create a link, you use the `--link` flag. First, create a new 131 container, this time one containing a database. 132 133 $ docker run -d --name db training/postgres 134 135 This creates a new container called `db` from the `training/postgres` 136 image, which contains a PostgreSQL database. 137 138 Now, you need to delete the `web` container you created previously so you can replace it 139 with a linked one: 140 141 $ docker rm -f web 142 143 Now, create a new `web` container and link it with your `db` container. 144 145 $ docker run -d -P --name web --link db:db training/webapp python app.py 146 147 This will link the new `web` container with the `db` container you created 148 earlier. The `--link` flag takes the form: 149 150 --link <name or id>:alias 151 152 Where `name` is the name of the container we're linking to and `alias` is an 153 alias for the link name. You'll see how that alias gets used shortly. 154 The `--link` flag also takes the form: 155 156 --link <name or id> 157 158 In which case the alias will match the name. You could have written the previous 159 example as: 160 161 $ docker run -d -P --name web --link db training/webapp python app.py 162 163 Next, inspect your linked containers with `docker inspect`: 164 165 $ docker inspect -f "{{ .HostConfig.Links }}" web 166 [/db:/web/db] 167 168 You can see that the `web` container is now linked to the `db` container 169 `web/db`. Which allows it to access information about the `db` container. 170 171 So what does linking the containers actually do? You've learned that a link allows a 172 source container to provide information about itself to a recipient container. In 173 our example, the recipient, `web`, can access information about the source `db`. To do 174 this, Docker creates a secure tunnel between the containers that doesn't need to 175 expose any ports externally on the container; you'll note when we started the 176 `db` container we did not use either the `-P` or `-p` flags. That's a big benefit of 177 linking: we don't need to expose the source container, here the PostgreSQL database, to 178 the network. 179 180 Docker exposes connectivity information for the source container to the 181 recipient container in two ways: 182 183 * Environment variables, 184 * Updating the `/etc/hosts` file. 185 186 ### Environment variables 187 188 Docker creates several environment variables when you link containers. Docker 189 automatically creates environment variables in the target container based on 190 the `--link` parameters. It will also expose all environment variables 191 originating from Docker from the source container. These include variables from: 192 193 * the `ENV` commands in the source container's Dockerfile 194 * the `-e`, `--env` and `--env-file` options on the `docker run` 195 command when the source container is started 196 197 These environment variables enable programmatic discovery from within the 198 target container of information related to the source container. 199 200 > **Warning**: 201 > It is important to understand that *all* environment variables originating 202 > from Docker within a container are made available to *any* container 203 > that links to it. This could have serious security implications if sensitive 204 > data is stored in them. 205 206 Docker sets an `<alias>_NAME` environment variable for each target container 207 listed in the `--link` parameter. For example, if a new container called 208 `web` is linked to a database container called `db` via `--link db:webdb`, 209 then Docker creates a `WEBDB_NAME=/web/webdb` variable in the `web` container. 210 211 Docker also defines a set of environment variables for each port exposed by the 212 source container. Each variable has a unique prefix in the form: 213 214 `<name>_PORT_<port>_<protocol>` 215 216 The components in this prefix are: 217 218 * the alias `<name>` specified in the `--link` parameter (for example, `webdb`) 219 * the `<port>` number exposed 220 * a `<protocol>` which is either TCP or UDP 221 222 Docker uses this prefix format to define three distinct environment variables: 223 224 * The `prefix_ADDR` variable contains the IP Address from the URL, for 225 example `WEBDB_PORT_8080_TCP_ADDR=172.17.0.82`. 226 * The `prefix_PORT` variable contains just the port number from the URL for 227 example `WEBDB_PORT_8080_TCP_PORT=8080`. 228 * The `prefix_PROTO` variable contains just the protocol from the URL for 229 example `WEBDB_PORT_8080_TCP_PROTO=tcp`. 230 231 If the container exposes multiple ports, an environment variable set is 232 defined for each one. This means, for example, if a container exposes 4 ports 233 that Docker creates 12 environment variables, 3 for each port. 234 235 Additionally, Docker creates an environment variable called `<alias>_PORT`. 236 This variable contains the URL of the source container's first exposed port. 237 The 'first' port is defined as the exposed port with the lowest number. 238 For example, consider the `WEBDB_PORT=tcp://172.17.0.82:8080` variable. If 239 that port is used for both tcp and udp, then the tcp one is specified. 240 241 Finally, Docker also exposes each Docker originated environment variable 242 from the source container as an environment variable in the target. For each 243 variable Docker creates an `<alias>_ENV_<name>` variable in the target 244 container. The variable's value is set to the value Docker used when it 245 started the source container. 246 247 Returning back to our database example, you can run the `env` 248 command to list the specified container's environment variables. 249 250 ``` 251 $ docker run --rm --name web2 --link db:db training/webapp env 252 . . . 253 DB_NAME=/web2/db 254 DB_PORT=tcp://172.17.0.5:5432 255 DB_PORT_5432_TCP=tcp://172.17.0.5:5432 256 DB_PORT_5432_TCP_PROTO=tcp 257 DB_PORT_5432_TCP_PORT=5432 258 DB_PORT_5432_TCP_ADDR=172.17.0.5 259 . . . 260 ``` 261 262 You can see that Docker has created a series of environment variables with 263 useful information about the source `db` container. Each variable is prefixed 264 with 265 `DB_`, which is populated from the `alias` you specified above. If the `alias` 266 were `db1`, the variables would be prefixed with `DB1_`. You can use these 267 environment variables to configure your applications to connect to the database 268 on the `db` container. The connection will be secure and private; only the 269 linked `web` container will be able to talk to the `db` container. 270 271 ### Important notes on Docker environment variables 272 273 Unlike host entries in the [`/etc/hosts` file](#updating-the-etchosts-file), 274 IP addresses stored in the environment variables are not automatically updated 275 if the source container is restarted. We recommend using the host entries in 276 `/etc/hosts` to resolve the IP address of linked containers. 277 278 These environment variables are only set for the first process in the 279 container. Some daemons, such as `sshd`, will scrub them when spawning shells 280 for connection. 281 282 ### Updating the `/etc/hosts` file 283 284 In addition to the environment variables, Docker adds a host entry for the 285 source container to the `/etc/hosts` file. Here's an entry for the `web` 286 container: 287 288 $ docker run -t -i --rm --link db:webdb training/webapp /bin/bash 289 root@aed84ee21bde:/opt/webapp# cat /etc/hosts 290 172.17.0.7 aed84ee21bde 291 . . . 292 172.17.0.5 webdb 6e5cdeb2d300 db 293 294 You can see two relevant host entries. The first is an entry for the `web` 295 container that uses the Container ID as a host name. The second entry uses the 296 link alias to reference the IP address of the `db` container. In addition to 297 the alias you provide, the linked container's name--if unique from the alias 298 provided to the `--link` parameter--and the linked container's hostname will 299 also be added in `/etc/hosts` for the linked container's IP address. You can ping 300 that host now via any of these entries: 301 302 root@aed84ee21bde:/opt/webapp# apt-get install -yqq inetutils-ping 303 root@aed84ee21bde:/opt/webapp# ping webdb 304 PING webdb (172.17.0.5): 48 data bytes 305 56 bytes from 172.17.0.5: icmp_seq=0 ttl=64 time=0.267 ms 306 56 bytes from 172.17.0.5: icmp_seq=1 ttl=64 time=0.250 ms 307 56 bytes from 172.17.0.5: icmp_seq=2 ttl=64 time=0.256 ms 308 309 > **Note:** 310 > In the example, you'll note you had to install `ping` because it was not included 311 > in the container initially. 312 313 Here, you used the `ping` command to ping the `db` container using its host entry, 314 which resolves to `172.17.0.5`. You can use this host entry to configure an application 315 to make use of your `db` container. 316 317 > **Note:** 318 > You can link multiple recipient containers to a single source. For 319 > example, you could have multiple (differently named) web containers attached to your 320 >`db` container. 321 322 If you restart the source container, the linked containers `/etc/hosts` files 323 will be automatically updated with the source container's new IP address, 324 allowing linked communication to continue. 325 326 $ docker restart db 327 db 328 $ docker run -t -i --rm --link db:db training/webapp /bin/bash 329 root@aed84ee21bde:/opt/webapp# cat /etc/hosts 330 172.17.0.7 aed84ee21bde 331 . . . 332 172.17.0.9 db 333 334 # Next step 335 336 Now that you know how to link Docker containers together, the next step is 337 learning how to manage data, volumes and mounts inside your containers. 338 339 Go to [Managing Data in Containers](/userguide/dockervolumes). 340