github.com/endocode/docker@v1.4.2-0.20160113120958-46eb4700391e/docs/userguide/networking/default_network/configure-dns.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Configure container DNS"
     4  description = "Learn how to configure DNS in Docker"
     5  keywords = ["docker, bridge, docker0, network"]
     6  [menu.main]
     7  parent = "smn_networking_def"
     8  +++
     9  <![end-metadata]-->
    10  
    11  # Configure container DNS
    12  
    13  The information in this section explains configuring container DNS within
    14  the Docker default bridge. This is a `bridge` network named `bridge` created
    15  automatically when you install Docker.  
    16  
    17  **Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network.
    18  
    19  How can Docker supply each container with a hostname and DNS configuration, without having to build a custom image with the hostname written inside?  Its trick is to overlay three crucial `/etc` files inside the container with virtual files where it can write fresh information.  You can see this by running `mount` inside a container:
    20  
    21  ```
    22  $$ mount
    23  ...
    24  /dev/disk/by-uuid/1fec...ebdf on /etc/hostname type ext4 ...
    25  /dev/disk/by-uuid/1fec...ebdf on /etc/hosts type ext4 ...
    26  /dev/disk/by-uuid/1fec...ebdf on /etc/resolv.conf type ext4 ...
    27  ...
    28  ```
    29  
    30  This arrangement allows Docker to do clever things like keep `resolv.conf` up to date across all containers when the host machine receives new configuration over DHCP later.  The exact details of how Docker maintains these files inside the container can change from one Docker version to the next, so you should leave the files themselves alone and use the following Docker options instead.
    31  
    32  Four different options affect container domain name services.
    33  
    34  <table>
    35    <tr>
    36      <td>
    37      <p>
    38      <code>-h HOSTNAME</code> or <code>--hostname=HOSTNAME</code>
    39      </p>
    40      </td>
    41      <td>
    42      <p>
    43        Sets the hostname by which the container knows itself.  This is written
    44        into <code>/etc/hostname</code>, into <code>/etc/hosts</code> as the name
    45        of the container's host-facing IP address, and is the name that
    46        <code>/bin/bash</code> inside the container will display inside its
    47        prompt.  But the hostname is not easy to see from outside the container.
    48        It will not appear in <code>docker ps</code> nor in the
    49        <code>/etc/hosts</code> file of any other container.
    50      </p>
    51      </td>
    52    </tr>
    53    <tr>
    54      <td>
    55      <p>
    56      <code>--link=CONTAINER_NAME</code> or <code>ID:ALIAS</code>
    57      </p>
    58      </td>
    59      <td>
    60      <p>
    61        Using this option as you <code>run</code> a container gives the new
    62        container's <code>/etc/hosts</code> an extra entry named
    63        <code>ALIAS</code> that points to the IP address of the container
    64        identified by <code>CONTAINER_NAME_or_ID<c/ode>. This lets processes
    65        inside the new container connect to the hostname <code>ALIAS</code>
    66        without having to know its IP.  The <code>--link=</code> option is
    67        discussed in more detail below. Because Docker may assign a different IP
    68        address to the linked containers on restart, Docker updates the
    69        <code>ALIAS</code> entry in the <code>/etc/hosts</code> file of the
    70        recipient containers.   
    71  </p>
    72      </td>
    73    </tr>
    74    <tr>
    75      <td><p>
    76      <code>--dns=IP_ADDRESS...</code>
    77      </p></td>
    78      <td><p>
    79       Sets the IP addresses added as <code>server</code> lines to the container's
    80       <code>/etc/resolv.conf</code> file.  Processes in the container, when
    81       confronted with a hostname not in <code>/etc/hosts</code>, will connect to
    82       these IP addresses on port 53 looking for name resolution services.     </p></td>
    83    </tr>
    84    <tr>
    85      <td><p>
    86      <code>--dns-search=DOMAIN...</code>
    87      </p></td>
    88      <td><p>
    89      Sets the domain names that are searched when a bare unqualified hostname is
    90      used inside of the container, by writing <code>search</code> lines into the
    91      container's <code>/etc/resolv.conf</code>. When a container process attempts
    92      to access <code>host</code> and the search domain <code>example.com</code>
    93      is set, for instance, the DNS logic will not only look up <code>host</code>
    94      but also <code>host.example.com</code>.
    95      </p>
    96      <p>
    97      Use <code>--dns-search=.</code> if you don't wish to set the search domain.
    98      </p>
    99      </td>
   100    </tr>
   101    <tr>
   102      <td><p>
   103      <code>--dns-opt=OPTION...</code>
   104      </p></td>
   105      <td><p>
   106        Sets the options used by DNS resolvers by writing an <code>options<code>
   107        line into the container's <code>/etc/resolv.conf<code>.
   108      </p>
   109      <p>
   110      See documentation for <code>resolv.conf<code> for a list of valid options
   111      </p></td>
   112    </tr>
   113    <tr>
   114      <td><p></p></td>
   115      <td><p></p></td>
   116    </tr>
   117  </table>
   118  
   119  
   120  Regarding DNS settings, in the absence of the `--dns=IP_ADDRESS...`, `--dns-search=DOMAIN...`, or `--dns-opt=OPTION...` options, Docker makes each container's `/etc/resolv.conf` look like the `/etc/resolv.conf` of the host machine (where the `docker` daemon runs).  When creating the container's `/etc/resolv.conf`, the daemon filters out all localhost IP address `nameserver` entries from the host's original file.
   121  
   122  Filtering is necessary because all localhost addresses on the host are unreachable from the container's network.  After this filtering, if there  are no more `nameserver` entries left in the container's `/etc/resolv.conf` file, the daemon adds public Google DNS nameservers (8.8.8.8 and 8.8.4.4) to the container's DNS configuration.  If IPv6 is enabled on the daemon, the public IPv6 Google DNS nameservers will also be added (2001:4860:4860::8888 and 2001:4860:4860::8844).
   123  
   124  > **Note**: If you need access to a host's localhost resolver, you must modify your DNS service on the host to listen on a non-localhost address that is reachable from within the container.
   125  
   126  You might wonder what happens when the host machine's `/etc/resolv.conf` file changes.  The `docker` daemon has a file change notifier active which will watch for changes to the host DNS configuration.
   127  
   128  > **Note**: The file change notifier relies on the Linux kernel's inotify feature. Because this feature is currently incompatible with the overlay filesystem  driver, a Docker daemon using "overlay" will not be able to take advantage of the `/etc/resolv.conf` auto-update feature.
   129  
   130  When the host file changes, all stopped containers which have a matching `resolv.conf` to the host will be updated immediately to this newest host configuration.  Containers which are running when the host configuration changes will need to stop and start to pick up the host changes due to lack of a facility to ensure atomic writes of the `resolv.conf` file while the container is running. If the container's `resolv.conf` has been edited since it was started with the default configuration, no replacement will be attempted as it would overwrite the changes performed by the container. If the options (`--dns`, `--dns-search`, or `--dns-opt`) have been used to modify the default host configuration, then the replacement with an updated host's `/etc/resolv.conf` will not happen as well.
   131  
   132  > **Note**: For containers which were created prior to the implementation of the `/etc/resolv.conf` update feature in Docker 1.5.0: those containers will **not** receive updates when the host `resolv.conf` file changes. Only containers created with Docker 1.5.0 and above will utilize this auto-update feature.