instruction: Explain Legacy container links
output: Back
  Ask AI
  Start typing to search or try
  Contact support
  Manuals
  Get started
  Guides
  Legacy container links
  Page options
  Copy page as Markdown for LLMs
  View page as plain text
  Ask questions with Docs AI
  Claude
  Open in Claude
  Warning
  --link
  flag is a legacy feature of Docker. It may eventually
  be removed. Unless you absolutely need to continue using it, we recommend that you use
  user-defined networks to facilitate communication between two containers instead of using
  --link
  . One feature that user-defined networks do not support that you can do
  with
  --link
  is sharing environment variables between containers. However,
  you can use other mechanisms such as volumes to share environment variables
  between containers in a more controlled way.
  Differences between user-defined bridges and the default bridge
  for some alternatives to using
  --link
  The information in this section explains legacy container links within the
  Docker default
  bridge
  network which is created automatically when you install
  Docker.
  Before the
  Docker networks feature
  , you could use the
  Docker link feature to allow containers to discover each other and securely
  transfer information about one container to another container. With the
  introduction of the Docker networks feature, you can still create links but they
  behave differently between default
  bridge
  network and
  user defined networks
  This section briefly discusses connecting via a network port and then goes into
  detail on container linking in default
  bridge
  network.
  Connect using network port mapping
  Let's say you used this command to run a simple Python Flask application:
  docker run -d -P training/webapp python app.py
  Note
  Containers have an internal network and an IP address.
  Docker can have a variety of network configurations. You can see more
  information on Docker networking
  here
  When that container was created, the
  flag was used to automatically map
  any network port inside it to a random high port within an
  ephemeral port
  range
  on your Docker host. Next, when
  docker ps
  was run, you saw that port
  5000 in the container was bound to port 49155 on the host.
  docker ps nostalgic_morse
  CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
  bc533791f3f5 training/webapp:latest python app.py 5 seconds ago Up 2 seconds 0.0.0.0:49155->5000/tcp nostalgic_morse
  You also saw how you can bind a container's ports to a specific port using
  flag. Here port 80 of the host is mapped to port 5000 of the
  container:
  docker run -d -p 80:5000 training/webapp python app.py
  And you saw why this isn't such a great idea because it constrains you to
  only one container on that specific port.
  Instead, you may specify a range of host ports to bind a container port to
  that is different than the default
  ephemeral port range
  docker run -d -p 8000-9000:5000 training/webapp python app.py
  This would bind port 5000 in the container to a randomly available port
  between 8000 and 9000 on the host.
  There are also a few other ways you can configure the
  flag. By
  default the
  flag binds the specified port to all interfaces on
  the host machine. But you can also specify a binding to a specific
  interface, for example only to the
  localhost
  docker run -d -p 127.0.0.1:80:5000 training/webapp python app.py
  This would bind port 5000 inside the container to port 80 on the
  localhost
  interface on the host machine.
  Or, to bind port 5000 of the container to a dynamic port but only on the
  localhost
  , you could use:
  docker run -d -p 127.0.0.1::5000 training/webapp python app.py
  You can also bind UDP and SCTP (typically used by telecom protocols such as SIGTRAN, Diameter, and S1AP/X2AP) ports by adding a trailing
  /udp
  /sctp
  . For example:
  docker run -d -p 127.0.0.1:80:5000/udp training/webapp python app.py
  You also learned about the useful
  docker port
  shortcut which showed us the
  current port bindings. This is also useful for showing you specific port
  configurations. For example, if you've bound the container port to the
  localhost
  on the host machine, then the
  docker port
  output reflects that.
  docker port nostalgic_morse
  127.0.0.1:49155
  Note
  flag can be used multiple times to configure multiple ports.
  Connect with the linking system
  Note
  This section covers the legacy link feature in the default
  bridge
  network.
  Refer to
  differences between user-defined bridges and the default bridge
  for more information on links in user-defined networks.
  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 multiple
  containers together and send connection information from one to another. When
  containers are linked, information about a source container can be sent to a
  recipient container. This allows the recipient to see selected data describing
  aspects of the source container.
  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
  created name; indeed you've become familiar with our old friend
  nostalgic_morse
  during this guide. You can also name containers
  yourself. This naming provides two useful functions:
  It can be useful to name containers that do specific functions in a way
  that makes it easier for you to remember them, for example naming a
  container containing a web application
  It provides Docker with a reference point that allows it to refer to other
  containers, for example, you can specify to link the container
  to container
  You can name your container by using the
  --name
  flag, for example:
  docker run -d -P --name web training/webapp python app.py
  This launches a new container and uses the
  --name
  flag to
  name the container
  . You can see the container's name using the
  docker ps
  command.
  docker ps -l
  CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
  aed84ee21bde training/webapp:latest python app.py 12 hours ago Up 2 seconds 0.0.0.0:49154->5000/tcp web
  You can also use
  docker inspect
  to return the container's name.
  Note
  Container names must be unique. That means you can only call
  one container
  . If you want to re-use a container name you must delete
  the old container (with
  docker container rm
  ) before you can create a new
  container with the same name. As an alternative you can use the
  --rm
  flag with the
  docker run
  command. This deletes the container
  immediately after it is stopped.
  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 source container and a recipient container. The recipient can
  then access select data about the source. To create a link, you use the
  --link
  flag. First, create a new container, this time one containing a database.
  docker run -d --name db training/postgres
  This creates a new container called
  from the
  training/postgres
  image, which contains a PostgreSQL database.
  Now, you need to delete the
  container you created previously so you can replace it
  with a linked one:
  docker container rm -f web
  Now, create a new
  container and link it with your
  container.
  docker run -d -P --name web --link db:db training/webapp python app.py
  This links the new
  container with the
  container you created
  earlier. The
  --link
  flag takes the form:
  --link <name or id>:alias
  Where
  name
  is the name of the container we're linking to and
  alias
  is an
  alias for the link name. That alias is used shortly.
  --link
  flag also takes the form:
  --link <name or id>
  In this case the alias matches the name. You could write the previous
  example as:
  docker run -d -P --name web --link db training/webapp python app.py
  Next, inspect your linked containers with
  docker inspect
  docker inspect -f
  "{{ .HostConfig.Links }}"
  [/db:/web/db]
  You can see that the
  container is now linked to the
  container
  web/db
  . Which allows it to access information about the
  container.
  So what does linking the containers actually do? You've learned that a link allows a
  source container to provide information about itself to a recipient container. In
  our example, the recipient,
  , can access information about the source
  . To do
  this, Docker creates a secure tunnel between the containers that doesn't need to
  expose any ports externally on the container; when we started the
  container we did not use either the
  flags. That's a big benefit of
  linking: we don't need to expose the source container, here the PostgreSQL database, to
  the network.
  Docker exposes connectivity information for the source container to the
  recipient container in two ways:
  Environment variables,
  Updating the
  /etc/hosts
  file.
  Environment variables
  Docker creates several environment variables when you link containers. Docker
  automatically creates environment variables in the target container based on
  --link
  parameters. It also exposes all environment variables
  originating from Docker from the source container. These include variables from:
  commands in the source container's Dockerfile
  --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
  is linked to a database container called
  --link db:webdb
  then Docker creates a
  WEBDB_NAME=/web/webdb
  variable in the
  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
  <port>
  number exposed
  <protocol>
  which is either TCP or UDP
  Docker uses this prefix format to define three distinct environment variables:
  prefix_ADDR
  variable contains the IP Address from the URL, for
  example
  WEBDB_PORT_5432_TCP_ADDR=172.17.0.82
  prefix_PORT
  variable contains just the port number from the URL of
  example
  WEBDB_PORT_5432_TCP_PORT=5432
  prefix_PROTO
  variable contains just the protocol from the URL of
  example
  WEBDB_PORT_5432_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:5432
  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
  command to list the specified container's environment variables.
  docker run --rm --name web2 --link db:db training/webapp env
  <...>
  DB_NAME=/web2/db
  DB_PORT=tcp://172.17.0.5:5432
  DB_PORT_5432_TCP=tcp://172.17.0.5:5432
  DB_PORT_5432_TCP_PROTO=tcp
  DB_PORT_5432_TCP_PORT=5432
  DB_PORT_5432_TCP_ADDR=172.17.0.5
  <...>
  You can see that Docker has created a series of environment variables with
  useful information about the source
  container. Each variable is prefixed
  with
  , which is populated from the
  alias
  you specified above. If the
  alias
  were
  , the variables would be prefixed with
  DB1_
  . You can use these
  environment variables to configure your applications to connect to the database
  on the
  container. The connection is secure and private; only the
  linked
  container can communicate with the
  container.
  Important notes on Docker environment variables
  Unlike host entries in the
  /etc/hosts
  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
  , 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
  source container to the
  /etc/hosts
  file. Here's an entry for the
  container:
  docker run -t -i --rm --link db:webdb training/webapp /bin/bash
  root@aed84ee21bde:/opt/webapp# cat /etc/hosts
  172.17.0.7 aed84ee21bde
  <...>
  172.17.0.5 webdb 6e5cdeb2d300 db
  You can see two relevant host entries. The first is an entry for the
  container that uses the Container ID as a host name. The second entry uses the
  link alias to reference the IP address of the
  container. In addition to
  the alias you provide, the linked container's name, if unique from the alias
  provided to the
  --link
  parameter, and the linked container's hostname are
  also added to
  /etc/hosts
  for the linked container's IP address. You can ping
  that host via any of these entries:
  root@aed84ee21bde:/opt/webapp# apt-get install -yqq inetutils-ping
  root@aed84ee21bde:/opt/webapp# ping webdb
  PING webdb (172.17.0.5): 48 data bytes
  56 bytes from 172.17.0.5: icmp_seq=0 ttl=64 time=0.267 ms
  56 bytes from 172.17.0.5: icmp_seq=1 ttl=64 time=0.250 ms
  56 bytes from 172.17.0.5: icmp_seq=2 ttl=64 time=0.256 ms
  Note
  In the example, you had to install
  ping
  because it was not included
  in the container initially.
  Here, you used the
  ping
  command to ping the
  container using its host entry,
  which resolves to
  . You can use this host entry to configure an application
  to make use of your
  container.
  Note
  You can link multiple recipient containers to a single source. For
  example, you could have multiple (differently named) web containers attached to your
  container.
  If you restart the source container, the
  /etc/hosts
  files on the linked containers
  are automatically updated with the source container's new IP address,
  allowing linked communication to continue.
  docker restart db
  docker run -t -i --rm --link db:db training/webapp /bin/bash
  root@aed84ee21bde:/opt/webapp# cat /etc/hosts
  172.17.0.7 aed84ee21bde
  <...>
  172.17.0.9 db