From ba391efe53f42124324146e65727b3c8959b228e Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Tue, 1 Oct 2024 15:59:23 +0200 Subject: [PATCH] Update docs of `containers.conf` configs affecting /etc/hosts Signed-off-by: Daniel Rudolf --- docs/containers.conf.5.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/containers.conf.5.md b/docs/containers.conf.5.md index bc545c816..e8e587348 100644 --- a/docs/containers.conf.5.md +++ b/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,23 @@ 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. +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 the internal hostnames to `/etc/hosts` is silently skipped then. +Set this config to `none` to never add the internal hostnames to `/etc/hosts`. -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. +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. + +Note: This config has no effect with `podman machine`, because Podman isn't +modifying the guest's `/etc/hosts` file. The `host.containers.internal` and +`host.docker.internal` hostnames are instead resolved by the gvproxy DNS +resolver. Therefore it is not possible to disable the hostnames in this case. **http_proxy**=true @@ -290,8 +302,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