Chapter 5: Customization and configuration files

Introduction

The chapter introduces why Podman’s defaults may need customization and previews the configuration files and format used to change them.

• Reasons to customize defaults: Explain why Podman provides configuration files despite having security-conscious defaults: environments, machines, and rootless users may need different security, storage, or registry settings.
  Why it matters: Configuration files let you adapt Podman’s best-guess defaults to the machine and users running it.
• Configuration file responsibilities: Describe how the chapter divides configuration among storage, registry, engine, and system settings, and state that Podman’s task-specific libraries generally have separate configuration files while Podman and Buildah share containers.conf.
  Why it matters: Knowing which area a setting belongs to helps you look in the right configuration file.
• TOML configuration format: State that Podman’s nonsystem configuration files use TOML, with name-value options, section headings, and comments.
  Why it matters: Recognizing the file format makes the configuration examples easier to read.

Key terms: defaults, rootless, rootful, configuration files, storage.conf, registries.conf, policy.json, containers.conf, Buildah, TOML

5.1 Configuration files for storage

This section introduces storage.conf, where Podman finds it, and how to identify the file in use.

• Storage configuration purpose: Explain that Podman uses the containers/storage library to store filesystem layers, images, and containers, and that storage.conf configures that library. State that relocating container storage is a common reason to change the file.
  Why it matters: This explains why a Podman user might need to change storage settings at all.
• Storage file selection order: Describe the user-specific, system override, and distribution-provided locations for storage.conf, and explain that Podman uses the first applicable file rather than combining them. State that podman info shows which file a command is using.
  Why it matters: Knowing which file wins prevents edits to a configuration that Podman ignores.
• Remote storage configuration location: Explain that in remote mode, including Podman on Mac or Windows, the relevant storage.conf is on the Linux machine running the Podman service. Describe entering a Podman machine VM with podman machine ssh to modify it.
  Why it matters: Editing a local client file will not change the remote service's storage settings.

Key terms: containers/storage, storage.conf, filesystem layers, $XDG_CONFIG_HOME/containers/storage.conf, $HOME/.config/containers/storage.conf, /etc/containers/storage.conf, /usr/share/containers/storage.conf, podman info, remote mode, Podman service

5.1.1 Storage location

This section shows how to change Podman’s rootful and rootless storage locations and notes the SELinux work required when storage moves.

• Rootful storage location change: Describe the default rootful storage location and how to change it by editing graphroot in /etc/containers/storage.conf, then verify the result with podman info.
  Why it matters: Moving storage can put images and containers on a disk with enough space.
• Rootless storage path configuration: Distinguish rootless storage from rootful storage, and explain the per-user configuration option versus rootless_storage_path for configuring all users.
  Why it matters: A rootful storage change alone will not solve a rootless user’s storage-space problem.
• SELinux storage relabeling: Explain that changing Podman’s storage location on an SELinux system also requires telling SELinux how to label the new location and applying those labels on disk.
  Why it matters: A correctly configured storage path may still need suitable SELinux labels to work.

Key terms: graphroot, storage.conf, podman info, rootless, rootless_storage_path, $HOME/.config/containers/storage.conf, $HOME, $UID, SELinux, semanage

5.1.2 Storage drivers

This section explains how storage drivers assemble layered container images and introduces two overlay driver options for rootless and single-UID environments.

• Layered images and storage drivers: Explain that containers/storage keeps image layers on disk and mounts them together when a container runs, using a copy-on-write layered filesystem called a storage driver. State that Podman uses the overlay driver by default.
  Why it matters: This explains what the storage driver does when Podman runs a container from a layered image.
• Overlay mount program fallback: Describe how the mount_program option in storage.conf's [storage.options.overlay] table can select an executable instead of the kernel overlay driver. Explain that Podman automatically falls back to fuse-overlayfs, if installed, when rootless native overlay is unsupported.
  Why it matters: This option explains how overlay storage can work on systems without rootless native overlay support.
• Single UID image ownership option: Explain why the ignore_chown_errors option helps on HPC systems that permit only a single UID: it allows image files owned by different UIDs to be flattened into that one UID.
  Why it matters: It connects a storage setting to a concrete constraint on running containers in HPC environments.

Key terms: containers/storage, image layers, layered filesystem, copy-on-write (CoW), storage driver, overlay, storage.conf, [storage.options.overlay], mount_program, fuse-overlayfs

5.2 Configuration files for registries

This section introduces the files that configure image registries and signature verification, while noting that most users rely on distribution defaults.

• Registry configuration file roles: Explain that Podman uses the github.com/containers/image library to pull and push images, usually through registries; registries.conf specifies registries, while policy.json governs image signature verification.
  Why it matters: The two files serve different purposes when Podman works with images.
• Distribution configuration defaults: State that most users leave registries.conf and policy.json unchanged and use their distribution's defaults, as they generally do with the storage.conf file discussed earlier.
  Why it matters: These files are available for customization, but ordinary use does not usually require editing them.

Key terms: github.com/containers/image, registries.conf, policy.json, signature verification, distribution defaults, storage.conf

5.2.1 registries.conf

This section shows how registries.conf controls where Podman looks for images, which registries it blocks, and when it pulls from a mirror.

• Registry configuration file location: Explain that Podman uses $HOME/.config/containers/registries.conf when it exists and otherwise uses /etc/containers/registries.conf. Describe where to edit the file when using remote Podman.
  Why it matters: Editing the wrong machine or file will leave registry behavior unchanged.
• Short-name registry search order: Explain how unqualified-search-registries supplies an ordered list of registries to try when pulling an image by a short name, and what using just one registry changes.
  Why it matters: Search settings determine where a short-name image pull looks for its image.
• Registry-specific pull blocking: Describe how a registries.conf [[registry]] entry can set rules for an individual registry, including blocking pulls from docker.io, and how to check and test the change.
  Why it matters: Administrators can prevent users from pulling content from a specified registry.
• Transparent registry mirror pulls: Explain how a registries.conf mirror lets users request an image by its expected registry name while Podman actually pulls a copy from an internal registry.
  Why it matters: A mirror can supply images to systems that cannot reach the original internet registry.

Key terms: registries.conf, $HOME/.config/containers/registries.conf, /etc/containers/registries.conf, remote mode, podman machine ssh, unqualified-search-registries, short names, podman info, [[registry]], docker.io

5.3 Configuration files for engines

This section explains how containers.conf sets Podman’s non-storage, non-registry defaults and shows how to adapt those defaults for running Podman inside a container.

• Containers configuration layering: Explain that Podman reads containers.conf files for defaults unrelated to storage and registries, with additional files available in rootless mode. Describe how fields from those files merge rather than one file completely replacing another, and how CONTAINERS_CONF instead selects a single file.
  Why it matters: File layering determines which default a Podman command actually uses.
• Default container settings: Describe how containers.conf organizes options into five tables and can change defaults applied when containers launch, such as environment variables, volumes, and namespaces. Give the section’s example of setting foo=bar as a default environment variable.
  Why it matters: Choosing the right table and field lets you change routine container behavior without repeating options for every launch.
• Nested Podman engine defaults: Explain why the podman/stable image uses containers.conf to adjust Podman defaults for running inside a container. Describe its cgroup and namespace choices, filesystem-based logging, event, and cgroup settings in place of unavailable systemd and journald services, and its choice of the smaller crun runtime.
  Why it matters: Defaults suited to a host may not work when the container engine itself runs inside a container.
• Rootless nested container run: Describe the two run-time additions the example needs to run a container with Podman inside podman/stable: --user podman to make the inner Podman rootless, and access to /dev/fuse for its fuse-overlay driver.
  Why it matters: These additions connect the example’s configuration to a working nested-container run.
• Remote configuration location: Distinguish where containers.conf settings generally take effect in remote mode: most are used on the Linux server, while a file in the client user’s home directory stores connection data.
  Why it matters: Editing a client-side file will not necessarily change how the remote Linux engine launches containers.

Key terms: containers.conf, rootless, CONTAINERS_CONF, built-in defaults, tables, env, foo=bar, namespaces, quay.io/podman/stable, cgroups

5.4 System configuration files

This section explains how rootless Podman uses system files to allocate subordinate IDs, why those allocations must not overlap, and how to apply changes after Podman has started.

• Subordinate ID allocation and mapping: Explain how /etc/subuid and /etc/subgid assign UID and GID ranges to a user for rootless containers, and how Podman uses newuidmap and newgidmap to check that its requested ranges are allocated to that user. Describe the three colon-separated fields in an entry: login name or UID, starting subordinate ID, and ID count.
  Why it matters: These entries determine which host IDs a user's rootless containers can use.
• Nonoverlapping subordinate ID ranges: Justify keeping each user's subordinate ID ranges unique and clear of system UIDs: overlapping ranges could let users' container processes attack each other from a user-namespace perspective. Distinguish the mapping tools' check that IDs are allocated to a user from the manual check for overlap; useradd normally selects unique ranges.
  Why it matters: An allocated range is not necessarily a safely isolated range if it overlaps another user's IDs.
• Applying changed ID allocations: Explain why editing /etc/subuid or /etc/subgid may not immediately change a user's rootless containers: Podman keeps a podman pause process in a user namespace that later containers join. State that podman system migrate stops that process and re-creates the user namespace so the new allocation takes effect.
  Why it matters: Without refreshing the user namespace, a corrected ID allocation may appear not to work.

Key terms: /etc/subuid, /etc/subgid, UID ranges, GID ranges, newuidmap, newgidmap, subordinate ID ranges, useradd, user namespace, podman pause process

5.5 Summary

The summary maps Podman’s configuration files to the storage, registry, general-default, and rootless user-namespace settings they control.