Merge pull request #24043 from PhrozenByte/docs-add-host-gateway

[CI:DOCS] Update documentation of CLI options affecting `/etc/hosts`

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 <<container|pod>>'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`.

docs/source/markdown/options/hostname.container.md

@@ -4,6 +4,10 @@
 ####> are applicable to all of those.
 #### **--hostname**, **-h**=*name*
 
-Container host name
+Set the container's hostname inside the container.
 
-Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname is used.
+This option can only be used with a private UTS namespace `--uts=private`
+(default). If `--pod` is given and the pod shares the same UTS namespace
+(default), the pod's hostname is used. The given hostname is also added to the
+`/etc/hosts` file using the container's primary IP address (also see the
+**--add-host** option).

docs/source/markdown/options/hostname.pod.md

@@ -4,4 +4,7 @@
 ####> are applicable to all of those.
 #### **--hostname**=*name*
 
-Set a hostname to the pod.
+Set the pod's hostname inside all containers.
+
+The given hostname is also added to the `/etc/hosts` file using the container's
+primary IP address (also see the **--add-host** option).

docs/source/markdown/options/name.container.md

@@ -12,7 +12,9 @@ The operator can identify a container in three ways:
 - UUID short identifier (“f78375b1c487”);
 - Name (“jonah”).
 
-Podman generates a UUID for each container, and if a name is not assigned
-to the container with **--name** then it generates a random
-string name. The name can be useful as a more human-friendly way to identify containers.
-This works for both background and foreground containers.
+Podman generates a UUID for each container, and if no name is assigned to the
+container using **--name**, Podman generates a random string name. The name can
+be useful as a more human-friendly way to identify containers. This works for
+both background and foreground containers. The container's name is also added
+to the `/etc/hosts` file using the container's primary IP address (also see the
+**--add-host** option).

docs/source/markdown/options/no-hosts.md

@@ -4,6 +4,12 @@
 ####> are applicable to all of those.
 #### **--no-hosts**
 
-Do not create _/etc/hosts_ for the <<container|pod>>.
-By default, Podman manages _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**.
-**--no-hosts** disables this, and the image's _/etc/hosts_ is preserved unmodified.
+Do not modify the `/etc/hosts` file in the <<container|pod>>.
+
+Podman assumes control over the <<container|pod>>'s `/etc/hosts` file by
+default and adds entries for the container's name (see **--name** option) and
+hostname (see **--hostname** option), the internal `host.containers.internal`
+and `host.docker.internal` hosts, as well as any hostname added using the
+**--add-host** option. Refer to the **--add-host** option for details. Passing
+**--no-hosts** disables this, so that the image's `/etc/hosts` file is kept
+unmodified.