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