Allow extra lines in /etc/hosts

This adds a --add-host host:ip flag which appends lines to /etc/hosts.  This is needed in places where you want the container to get a different name resolution than it would through DNS.  This was submitted before as #5525, closed, and now I am re-opening.  It has come up 2 or 3 times in the last couple days.

Signed-off-by: Tim Hockin <thockin@google.com>
Upstream-commit: 68e48b65a64df10fc797cbaa89d6caa2188eadc9
Component: engine

components/engine/docs/man/docker-run.1.md

@@ -7,6 +7,7 @@ docker-run - Run a command in a new container
 # SYNOPSIS
 **docker run**
 [**-a**|**--attach**[=*[]*]]
+[**--add-host**[=*[]*]]
 [**-c**|**--cpu-shares**[=*0*]]
 [**--cap-add**[=*[]*]]
 [**--cap-drop**[=*[]*]]
@@ -64,6 +65,10 @@ error. It can even pretend to be a TTY (this is what most commandline
 executables expect) and pass along signals. The **-a** option can be set for
 each of stdin, stdout, and stderr.
 
+**--add-host**=*hostname*:*ip*
+   Add a line to /etc/hosts. The format is hostname:ip.  The **--add-host**
+option can be set multiple times.
+
 **-c**, **--cpu-shares**=0
    CPU shares in relative weight. You can increase the priority of a container
 with the -c option. By default, all containers run at the same priority and get

components/engine/docs/sources/reference/commandline/cli.md

@@ -986,6 +986,7 @@ removed before the image is removed.
     Run a command in a new container
 
       -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
+      --add-host=[]              Add a custom host-to-IP mapping (host:ip)
       -c, --cpu-shares=0         CPU shares (relative weight)
       --cap-add=[]               Add Linux capabilities
       --cap-drop=[]              Drop Linux capabilities

components/engine/docs/sources/reference/run.md

@@ -139,6 +139,7 @@ example, `docker run ubuntu:14.04`.
                                  'none': no networking for this container
                                  'container:<name|id>': reuses another container network stack
                                  'host': use the host network stack inside the container
+    --add-host=""   : Add a line to /etc/hosts (host:IP)
 
 By default, all containers have networking enabled and they can make any
 outgoing connections. The operator can completely disable networking
@@ -196,6 +197,22 @@ running the `redis-cli` command and connecting to the Redis server over the
     $ # use the redis container's network stack to access localhost
     $ sudo docker run --rm -ti --net container:redis example/redis-cli -h 127.0.0.1
 
+### Managing /etc/hosts
+
+Your container will have lines in `/etc/hosts` which define the hostname of the
+container itself as well as `localhost` and a few other common things.  The
+`--add-host` flag can be used to add additional lines to `/etc/hosts`.  
+
+    $ /docker run -ti --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts
+    172.17.0.22     09d03f76bf2c
+    fe00::0         ip6-localnet
+    ff00::0         ip6-mcastprefix
+    ff02::1         ip6-allnodes
+    ff02::2         ip6-allrouters
+    127.0.0.1       localhost
+    ::1	            localhost ip6-localhost ip6-loopback
+    86.75.30.9      db-static
+
 ## Clean Up (–-rm)
 
 By default a container's file system persists even after the container