From a8987063b3bf2aa1c2095f88a5e910497818ad79 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 3 Jul 2023 16:34:55 +0200 Subject: [PATCH] docs: document special host-gateway value for add-host Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> (cherry picked from commit 299925f4c3847080b95f3bb84da256286431dc4d) Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/build.md | 12 ++++++++++- docs/reference/commandline/dockerd.md | 19 +++++++++++++++++ docs/reference/commandline/run.md | 30 +++++++++++++++------------ 3 files changed, 47 insertions(+), 14 deletions(-) diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index 0a770f6034..c3435f57c5 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -458,7 +458,17 @@ You can add other hosts into a container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds a static address for a host named `docker`: - $ docker build --add-host=docker:10.180.0.1 . +```console +$ docker build --add-host docker:10.180.0.1 . +``` + +If you need your build to connect to services running on the host, you can use +the special `host-gateway` value for `--add-host`. In the following example, +build containers resolve `host.docker.internal` to the host's gateway IP. + +```console +$ docker build --add-host host.docker.internal:host-gateway . +``` ### Specifying target build stage (--target) diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index ae733592d0..f290045471 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -1265,6 +1265,25 @@ the host. For details about how to use this feature, as well as limitations, see [Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/). +### Configure host gateway IP + +The Docker daemon supports a special `host-gateway` value for the `--add-host` +flag for the `docker run` and `docker build` commands. This value resolves to +the host's gateway IP and lets containers connect to services running on the +host. + +By default, `host-gateway` resolves to the IP address of the default bridge. +You can configure this to resolve to a different IP using the `--host-gateway-ip` +flag for the dockerd command line interface, or the `host-gateway-ip` key in +the daemon configuration file. + +```console +$ dockerd --host-gateway-ip 192.0.2.0 +$ docker run -it --add-host host.docker.internal:host-gateway \ + busybox ping host.docker.internal +PING host.docker.internal (192.0.2.0): 56 data bytes +``` + ### Miscellaneous options IP masquerading uses address translation to allow containers without a public diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index bb91fb61da..7b292be709 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -759,24 +759,28 @@ PING docker (93.184.216.34): 56 data bytes round-trip min/avg/max = 92.209/92.495/93.052 ms ``` -Sometimes you need to connect to the Docker host from within your -container. To enable this, pass the Docker host's IP address to -the container using the `--add-host` flag. To find the host's address, -use the `ip addr show` command. +The `--add-host` flag supports a special `host-gateway` value that resolves to +the internal IP address of the host. This is useful when you want containers to +connect to services running on the host machine. -The flags you pass to `ip addr show` depend on whether you are -using IPv4 or IPv6 networking in your containers. Use the following -flags for IPv4 address retrieval for a network device named `eth0`: +It's conventional to use `host.docker.internal` as the hostname referring to +`host-gateway`. Docker Desktop automatically resolves this hostname, see +[Explore networking features](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). + +The following example shows how the special `host-gateway` value works. The +example runs an HTTP server that serves a file from host to container over the +`host.docker.internal` hostname, which resolves to the host's internal IP. ```console -$ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` -$ docker run --add-host=docker:${HOSTIP} --rm -it debian +$ echo "hello from host!" > ./hello +$ python3 -m http.server 8000 +Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... +$ docker run \ + --add-host host.docker.internal:host-gateway \ + curlimages/curl -s host.docker.internal:8000/hello +hello from host! ``` -For IPv6 use the `-6` flag instead of the `-4` flag. For other network -devices, replace `eth0` with the correct device name (for example `docker0` -for the bridge device). - ### Set ulimits in container (--ulimit) Since setting `ulimit` settings in a container requires extra privileges not