From c67d8baeb60d13fa8ef598500a88cfae9606212c Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Wed, 25 Sep 2024 21:35:53 +0200 Subject: [PATCH] Update documentation of `--add-host` CLI option Document the special *host-gateway* flag introduced with #19152, mention the special `host.containers.internal` and `host.docker.internal` hostnames, and clarify the option's usage in general. Signed-off-by: Daniel Rudolf --- docs/source/markdown/options/add-host.md | 28 +++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md index 649bccf7b3..4b4ad1e7ec 100644 --- a/docs/source/markdown/options/add-host.md +++ b/docs/source/markdown/options/add-host.md @@ -2,10 +2,28 @@ ####> podman build, create, farm build, pod create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. -#### **--add-host**=*host:ip* +#### **--add-host**=*hostname[;hostname[;...]]*:*ip* -Add a custom host-to-IP mapping (host:ip) -Multiple hostnames for the same IP can be separated by semicolons. +Add a custom host-to-IP mapping to the <>'s `/etc/hosts` file. -Add a line to /etc/hosts. The format is hostname:ip or hostname1;hostname2;hostname3:ip if you want to map multiple hostnames to the same ip without duplicating the --add-host parameter. The **--add-host** -option can be set multiple times. Conflicts with the **--no-hosts** option. +The option takes one or multiple semicolon-separated hostnames to be mapped to +a single IPv4 or IPv6 address, separated by a colon. It can also be used to +overwrite the IP addresses of hostnames Podman adds to `/etc/hosts` by default +(also see the **--name** and **--hostname** options). This option can be +specified multiple times to add additional mappings to `/etc/hosts`. It +conflicts with the **--no-hosts** option. + +Instead of an IP address, the special flag *host-gateway* can be given. This +resolves to an IP address the container can use to connect to the host. The +IP address chosen depends on your network setup, thus there's no guarantee that +Podman can determine the *host-gateway* address automatically, which will then +cause Podman to fail with an error message. You can overwrite this IP address +using the *host_containers_internal_ip* option in *containers.conf*. + +The *host-gateway* address is also used by Podman to automatically add the +`host.containers.internal` and `host.docker.internal` hostnames to `/etc/hosts`. +You can prevent that by either giving the **--no-hosts** option, or by setting +*host_containers_internal_ip="none"* in *containers.conf*. If no *host-gateway* +address was configured manually and Podman fails to determine the IP address +automatically, Podman will silently skip adding these internal hostnames to +`/etc/hosts`.