Merge pull request docker#5607 from robmry/v6only/host_gateway_ip

Docs: host-gateway-ip daemon option IPv4+IPv6
thaJeztah · Nov 29, 2024 · 61b02e6 · 61b02e6
2 parents 3be8b8c + c629eca
commit 61b02e6
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 9 deletions.
diff --git a/docs/reference/dockerd.md b/docs/reference/dockerd.md
@@ -63,8 +63,8 @@ Options:
   -G, --group string                          Group for the unix socket (default "docker")
       --help                                  Print usage
   -H, --host list                             Daemon socket(s) to connect to
-      --host-gateway-ip ip                    IP address that the special 'host-gateway' string in --add-host resolves to.
-                                              Defaults to the IP address of the default bridge
+      --host-gateway-ip list                  IP addresses that the special 'host-gateway' string in --add-host resolves to.
+                                              Defaults to the IP addresses of the default bridge
       --http-proxy string                     HTTP proxy URL to use for outgoing traffic
       --https-proxy string                    HTTPS proxy URL to use for outgoing traffic
       --icc                                   Enable inter-container communication (default true)
@@ -839,21 +839,34 @@ For details about how to use this feature, as well as limitations, see
 
 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
+addresses on the host, so that containers can connect to services running on the
 host.
 
-By default, `host-gateway` resolves to the IP address of the default bridge.
+By default, `host-gateway` resolves to the IPv4 address of the default bridge,
+and its IPv6 address if it has one.
+
 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.
 
+To supply both IPv4 and IPv6 addresses on the command line, use two
+`--host-gateway-ip` options.
+
+To supply addresses in the daemon configuration file, use `"host-gateway-ips"`
+with a JSON array, as shown below. For compatibility with older versions of the
+daemon, a single IP address can also be specified as a JSON string in option
+`"host-gateway-ip"`.
+
 ```console
 $ cat > /etc/docker/daemon.json
-{ "host-gateway-ip": "192.0.2.0" }
+{ "host-gateway-ips": ["192.0.2.1", "2001:db8::1111"]}
 $ sudo systemctl restart docker
 $ 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
+PING host.docker.internal (192.0.2.1): 56 data bytes
+$ docker run -it --add-host host.docker.internal:host-gateway \
+  busybox ping -6 host.docker.internal
+PING host.docker.internal (2001:db8::1111): 56 data bytes
 ```
 
 ### Enable CDI devices

diff --git a/man/dockerd.8.md b/man/dockerd.8.md
@@ -35,8 +35,9 @@ dockerd - Enable daemon mode
 [**--fixed-cidr**[=*FIXED-CIDR*]]
 [**--fixed-cidr-v6**[=*FIXED-CIDR-V6*]]
 [**-G**|**--group**[=*docker*]]
-[**-H**|**--host**[=*[]*]]
 [**--help**]
+[**-H**|**--host**[=*[]*]]
+[**--host-gateway-ip**[=*HOST-GATEWAY-IP*]]
 [**--http-proxy**[*""*]]
 [**--https-proxy**[*""*]]
 [**--icc**[=**true**]]
@@ -244,13 +245,18 @@ $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-ru
   Group to assign the unix socket specified by -H when running in daemon mode.
   use '' (the empty string) to disable setting of a group. Default is `docker`.
 
+**--help**
+  Print usage statement
+
 **-H**, **--host**=[*unix:///var/run/docker.sock*]: tcp://[host:port] to bind or
 unix://[/path/to/socket] to use.
   The socket(s) to bind to in daemon mode specified using one or more
   tcp://host:port, unix:///path/to/socket, fd://\* or fd://socketfd.
 
-**--help**
-  Print usage statement
+**--host-gateway-ip**=[*2001:db8::1234*]
+  Supply host addresses to substitute for the special string host-gateway in
+  --add-host options. Addresses from the docker0 bridge are used by default.
+  Two of these options are allowed, one IPv4 and one IPv6 address.
 
 **--http-proxy***""*
   Proxy URL for HTTP requests unless overridden by NoProxy.