From 1069ef55fe7d06ff0f6bf687d38454d9d2aa1d5c Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Fri, 4 Oct 2024 19:03:58 +0200 Subject: [PATCH] Update docs of `containers.conf` configs affecting /etc/hosts Signed-off-by: Daniel Rudolf --- docs/containers.conf.5.md | 42 +++++++++++++++++++++++++------------ pkg/config/containers.conf | 43 ++++++++++++++++++++++++++------------ 2 files changed, 59 insertions(+), 26 deletions(-) diff --git a/docs/containers.conf.5.md b/docs/containers.conf.5.md index bc545c816..f3466f98d 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,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 diff --git a/pkg/config/containers.conf b/pkg/config/containers.conf index 7f0954931..b7e585390 100644 --- a/pkg/config/containers.conf +++ b/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