Merge pull request #2184 from PhrozenByte/docs-hosts-file

Update docs of `containers.conf` configs affecting `/etc/hosts`

docs/containers.conf.5.md

@@ -96,10 +96,12 @@ The default profile name is "container-default".
 
 **base_hosts_file**=""
 
-The hosts entries from the base hosts file are added to the containers hosts
-file. This must be either an absolute path or as special values "image" which
-uses the hosts file from the container image or "none" which means
-no base hosts file is used. The default is "" which will use /etc/hosts.
+Base file to create the `/etc/hosts` file inside the container. This must either
+be an absolute path to a file on the host system, or one of the following
+special flags:
+  ""      Use the host's `/etc/hosts` file (the default)
+  `none`  Do not use a base file (i.e. start with an empty file)
+  `image` Use the container image's `/etc/hosts` file as base file
 
 **cgroup_conf**=[]
 
@@ -195,13 +197,25 @@ Pass all host environment variables into the container.
 
 **host_containers_internal_ip**=""
 
-Set the ip for the host.containers.internal entry in the containers /etc/hosts
-file. This can be set to "none" to disable adding this entry. By default it
-will automatically choose the host ip.
-
-NOTE: When using podman machine this entry will never be added to the containers
-hosts file instead the gvproxy dns resolver will resolve this hostname. Therefore
-it is not possible to disable the entry in this case.
+Set the IP address the container should expect to connect to the host. The IP
+address is used by Podman to automatically add the `host.containers.internal`
+and `host.docker.internal` hostnames to the container's `/etc/hosts` file. It
+is also used for the *host-gateway* flag of Podman's `--add-host` CLI option.
+If no IP address is configured (the default), Podman will try to determine it
+automatically, but might fail to do so depending on the container's network
+setup. Adding these internal hostnames to `/etc/hosts` is silently skipped then.
+Set this config to `none` to never add the internal hostnames to `/etc/hosts`.
+
+Note: If Podman is running in a virtual machine using `podman machine` (this
+includes Mac and Windows hosts), Podman will silently skip adding the internal
+hostnames to `/etc/hosts`, unless an IP address was configured manually. The
+internal hostnames are resolved by the gvproxy DNS resolver instead. This config
+has no effect on gvproxy. However, since `/etc/hosts` bypasses the DNS resolver,
+a manually configured IP address still takes precedence.
+
+Note: This config doesn't affect the actual network setup, it just tells Podman
+the IP address it should expect. Configuring an IP address here doesn't ensure
+that the container can actually reach the host using this IP address.
 
 **http_proxy**=true
 
@@ -290,8 +304,10 @@ Options are:
 
 **no_hosts**=false
 
-Create /etc/hosts for the container. By default, container engines manage
-/etc/hosts, automatically adding  the container's  own  IP  address.
+Do not modify the `/etc/hosts` file in the container. Podman assumes control
+over the container's `/etc/hosts` file by default; refer to the `--add-host`
+CLI option for details. To disable this, either set this config to `true`, or
+use the functionally identical `--no-hosts` CLI option.
 
 **oom_score_adj**=0
 

pkg/config/containers.conf

@@ -27,16 +27,19 @@
 #
 #apparmor_profile = "container-default"
 
-# The hosts entries from the base hosts file are added to the containers hosts
-# file. This must be either an absolute path or as special values "image" which
-# uses the hosts file from the container image or "none" which means
-# no base hosts file is used. The default is "" which will use /etc/hosts.
+# Base file to create the `/etc/hosts` file inside the container. This must either
+# be an absolute path to a file on the host system, or one of the following
+# special flags:
+# ""      Use the host's `/etc/hosts` file (the default)
+# `none`  Do not use a base file (i.e. start with an empty file)
+# `image` Use the container image's `/etc/hosts` file as base file
 #
 #base_hosts_file = ""
 
 # List of cgroup_conf entries specifying a list of cgroup files to write to and
 # their values. For example `memory.high=1073741824` sets the
 # memory.high limit to 1GB.
+#
 # cgroup_conf = []
 
 # Default way to to create a cgroup namespace for the container
@@ -126,13 +129,25 @@ default_sysctls = [
 #
 #env_host = false
 
-# Set the ip for the host.containers.internal entry in the containers /etc/hosts
-# file. This can be set to "none" to disable adding this entry. By default it
-# will automatically choose the host ip.
-#
-# NOTE: When using podman machine this entry will never be added to the containers
-# hosts file instead the gvproxy dns resolver will resolve this hostname. Therefore
-# it is not possible to disable the entry in this case.
+# Set the IP address the container should expect to connect to the host. The IP
+# address is used by Podman to automatically add the `host.containers.internal`
+# and `host.docker.internal` hostnames to the container's `/etc/hosts` file. It
+# is also used for the *host-gateway* flag of Podman's `--add-host` CLI option.
+# If no IP address is configured (the default), Podman will try to determine it
+# automatically, but might fail to do so depending on the container's network
+# setup. Adding these internal hostnames to `/etc/hosts` is silently skipped then.
+# Set this config to `none` to never add the internal hostnames to `/etc/hosts`.
+#
+# Note: If Podman is running in a virtual machine using `podman machine` (this
+# includes Mac and Windows hosts), Podman will silently skip adding the internal
+# hostnames to `/etc/hosts`, unless an IP address was configured manually. The
+# internal hostnames are resolved by the gvproxy DNS resolver instead. This config
+# has no effect on gvproxy. However, since `/etc/hosts` bypasses the DNS resolver,
+# a manually configured IP address still takes precedence.
+#
+# Note: This config doesn't affect the actual network setup, it just tells Podman
+# the IP address it should expect. Configuring an IP address here doesn't ensure
+# that the container can actually reach the host using this IP address.
 #
 #host_containers_internal_ip = ""
 
@@ -221,8 +236,10 @@ default_sysctls = [
 #
 #netns = "private"
 
-# Create /etc/hosts for the container.  By default, container engine manage
-# /etc/hosts, automatically adding  the container's  own  IP  address.
+# Do not modify the `/etc/hosts` file in the container. Podman assumes control
+# over the container's `/etc/hosts` file by default; refer to the `--add-host`
+# CLI option for details. To disable this, either set this config to `true`, or
+# use the functionally identical `--no-hosts` CLI option.
 #
 #no_hosts = false