Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: host-gateway-ip daemon option IPv4+IPv6 #5607

Merged
merged 3 commits into from
Nov 29, 2024
+28 −9
Merged

Docs: host-gateway-ip daemon option IPv4+IPv6 #5607

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf88ab0
Docs: host-gateway-ip daemon option IPv4+IPv6
robmry Nov 11, 2024
ea84e8f
Add --host-gateway to the dockerd manpage
robmry Nov 29, 2024
c629eca
Put --help before --host in the dockerd manpage
robmry Nov 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions docs/reference/dockerd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hate Cobra for this; we should probably look if we can make it show a custom type. "list" is ... not very informative. The ugly bit is that Cobra doesn't allow you to set it per flag, but it's really tied to the type you're using 😞 (perhaps we can come with some trickery to initialise it for a specific flag 🤔)

Copy link
Contributor Author

@robmry robmry Dec 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We almost have the trickery, it's not just used / there's a bit of plumbing missing - it's not configurable in a ListOpts so those options report list.

For ListOpts / NamedListOpts it comes from...
https://github.com/moby/moby/blob/af0b973595323cbd43132624ee2204af9a503588/opts/opts.go#L109-L112

For the new NamedIPListOpts, it's here ... https://github.com/moby/moby/blob/af0b973595323cbd43132624ee2204af9a503588/internal/opts/named_iplist_opts.go#L41-L43

So, we could come up with a better scheme if we wanted to.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it's not really a new problem, but something we should look at across the board. Things like string are pretty useless to the user, and ideally these would show <some type that can be documented>. Similar to, e.g. man wget would show more specific types (ISTR I found better examples, but couldn't remember where);

       -e command
       --execute command
           Execute command as if it were a part of .wgetrc.  A command thus invoked will be executed after the commands in .wgetrc, thus
           taking precedence over them.  If you need to specify more than one wgetrc command, use multiple instances of -e.

   Logging and Input File Options
       -o logfile
       --output-file=logfile
           Log all messages to logfile.  The messages are normally reported to standard error.

       -a logfile
       --append-output=logfile
           Append to logfile.  This is the same as -o, only it appends to logfile instead of overwriting the old log file.  If logfile
           does not exist, a new file is created.

If such types are somewhat standardised in our codebase, that would also allow them to be documented, e.g.

--platform PLATFORM

--gpus gpu-request
--health-interval duration

Then we could even provide links to those formats in our docs (i.e., here's where the format is described for platform or ip or duration).

Ideally, we'd also come with a format that can indicate "can be specified multiple times" ([]platform ? other options?)

There's some fun bug/issue still to fix for that though, because Cobra currently requires "multiple times" to be suffixed by List or Array to make auto-completion work properly 😞

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)
Expand Down Expand Up @@ -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
Expand Down
12 changes: 9 additions & 3 deletions man/dockerd.8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**]]
Expand Down Expand Up @@ -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.
Expand Down
Loading