Learn Podman - Configuration & Storage

#Introduction

In episode 10 you managed containers as systemd services via Quadlet. Behind all of that lies a layer that has been silently at work: configuration and storage. Episode 11 dissects Podman's configuration files — containers.conf, registries.conf, storage.conf, policy.json, registries.d, and certs.d — including the big rework in Podman 6 with unified lookup and XDG_CONFIG_HOME, then continues to the overlayfs storage driver and the rootless versus rootful layout.

#The Configuration File Map

Podman doesn't use a single central file; configuration is spread across several files with different responsibilities:

All six can be defined per-user or per-system. containers.conf, registries.conf, and storage.conf define behavior; policy.json, registries.d, and certs.d define trust and verification. Distinguishing these two groups helps you decide which file to change for a particular problem.

#containers.conf: Runtime Configuration

This file manages engine behavior: default flags for podman run, default resource limits, user namespaces, and much more:

/etc/containers/containers.conf

[containers]
pids_limit = 2048
log_driver = "journald"
http_proxy = true
 
[engine]
cgroup_manager = "systemd"
events_logger = "journald"

The [containers] section manages container defaults — PID limit, log driver, proxy usage — while [engine] manages the runtime, cgroup manager, and events. Values defined here become defaults; CLI flags can still override them. Common locations: /etc/containers/containers.conf for the system, and containers.conf in the XDG config directory for per-user.

#registries.conf: Registry and Search

This file determines which registries are allowed and the search order when you run podman pull nginx without a domain prefix:

/etc/containers/registries.conf

[registries.search]
registries = ["docker.io", "quay.io"]
 
[registries.insecure]
registries = []
 
unqualified-search-registries = ["docker.io", "quay.io"]

unqualified-search-registries and the [registries.search] section determine which registries are tried when an image name is unqualified. [registries.insecure] registers registries allowed without TLS — strongly discouraged for production, since it exposes images and credentials in transit.

#storage.conf: Driver and Layout

This file determines how images and layers are stored on disk:

/etc/containers/storage.conf

[storage]
driver = "overlayfs"
graphroot = "/var/lib/containers/storage"
runroot = "/run/containers/storage"
 
[storage.options.overlay]
mount_program = "/usr/bin/fuse-overlayfs"

driver = "overlayfs" sets the default storage driver, graphroot the location where layers and images are stored, runroot the location of temporary state. mount_program uses fuse-overlayfs in rootless situations that lack full access to the kernel overlay. The rootless layout lives under the home directory, not in the system:

This separation ensures two users never interfere with each other's storage — a direct consequence of the daemonless architecture discussed in episode 5.

#policy.json, registries.d, certs.d

Image verification is an important security layer. These three files work together to determine who is trusted:

• policy.json — the global verification policy: whether images must be signed, by whom, and what happens when they don't match.
• registries.d — additional per-registry rules about where signature keys are located.
• certs.d — CA certificates specific to certain registries, for example a corporate internal registry.

/etc/containers/policy.json

{
  "default": [
    {
      "type": "insecureAcceptAnything"
    }
  ],
  "transports": {}
}

The example above accepts any image — a loose default setting. A healthy production policy usually replaces default with reject or signedBy for important registries, so only images signed by trusted keys can run. Full details will be discussed together with image signing in episode 14.

#Configuration Rework in Podman 6

Podman 6 brings fundamental changes to how configuration is processed:

• Unified lookup — containers.conf, registries.conf, and storage.conf are searched via one consistent flow, the same for all files.
• XDG_CONFIG_HOME — per-user configuration is searched in the XDG standard directory, not scattered legacy paths.
• Drop-ins — additional options are placed as separate files in directories like containers.conf.d, making overrides easy without overwriting the main file.

podman info is the first tool to verify the result of this lookup:

podman info
podman info --format "{{.Store.GraphDriverName}}"

podman info shows the effective configuration, storage driver, and the paths currently in use. The second line filters out only the graph driver name — a quick way to confirm overlayfs is really active.

#The Overlayfs Storage Driver

overlayfs is the default and most efficient driver for Linux containers. It uses the kernel overlay mount: each image is a series of read-only layers, and the container uses a thin writable layer on top. When a container writes a file, overlayfs copies the changed file to the upper layer — avoiding duplication of the entire image. Its main trade-off is space usage, which can balloon when many containers write large files; for that, podman system provides the tools.

#podman system Commands

The podman system command set gives you visibility and control over all storage and resources:

podman system df
podman system prune
podman system reset

• podman system df — shows disk usage per image, container, and volume.
• podman system prune — cleans up unused images and containers to reclaim space.
• podman system reset — removes everything: images, containers, volumes, and local configuration — back to factory conditions.

#Closing

Episode 11 covered Podman configuration and storage: the map of six configuration files, containers.conf for runtime, registries.conf for registries, storage.conf for storage, policy.json together with registries.d and certs.d for verification, the unified lookup rework and XDG_CONFIG_HOME in Podman 6, the overlayfs driver, the difference between rootless and rootful layouts, and the podman system commands.

The key points to take home:

• The six configuration files each have their own role — distinguish behavior files from trust files.
• Podman 6 uses unified lookup with drop-ins — change via containers.conf.d, not by overwriting the main file.
• Rootless and rootful have different storage layouts — podman info shows which is active.
• podman system reset is the most destructive command — use it with full awareness.

In the next episode, Episode 12, you'll level up from one container to many at once: Compose and orchestration — running docker-compose.yml with podman-compose, Podman Desktop integration, and opening the Docker API socket via podman system service so docker-compatible tooling keeps working.