Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Podman Architecture: conmon, crun and Storage

See how Podman works inside: libpod, conmon, the OCI runtime crun, containers/storage, netavark, the REST API and the files and folders it uses.

You can use Podman for a long time without knowing how it is built, but a short tour of the parts pays back quickly. When a container fails to start, when a path looks strange, or when you read a log, you will recognise which component is speaking. This lesson names each piece, shows how a podman run flows through them, and lists where Podman keeps its data.

Think of Podman as a thin coordinator. It does not implement images, networking or the container start itself. It assembles libraries and helper programs, each of which does one job.

The components

Component Job
podman the command line you type; thin front end for the library
libpod the Go library with the container, pod, volume and network logic
containers/image pulls, pushes and verifies images from registries
containers/storage stores image layers and container file systems
conmon small monitor per container: holds the terminal, logs and exit code
crun (or runc) the OCI runtime: sets up namespaces and cgroups and starts the process
netavark + aardvark-dns create networks and answer DNS between containers
pasta (or slirp4netns) give rootless containers network access
catatonit tiny init program used as the pod's infra container and with --init

The names look many, but each step of a run uses only a few of them. Here is the flow for podman run.

sequenceDiagram
    participant U as You
    participant P as podman
    participant I as containers/image
    participant S as containers/storage
    participant N as netavark
    participant M as conmon
    participant R as crun
    U->>P: podman run alpine echo hi
    P->>I: pull image if missing
    I->>S: write layers
    P->>S: create container file system
    P->>N: set up network
    P->>M: start monitor
    M->>R: crun create + start
    R-->>M: process running
    P-->>U: exits (detached) or attaches

The podman process is short-lived. After the container starts, conmon and the container are what remain.

The OCI runtime: crun

The Open Container Initiative defines a runtime specification: a JSON file called config.json that describes the process, its mounts, namespaces and limits, and a runtime that turns that file into a running process. Podman writes that file and hands it to the runtime, which calls the kernel: clone with namespace flags, pivot_root into the container's file system, cgroup setup, capability and seccomp setup, then exec.

crun is written in C, starts faster and uses less memory than runc, which is written in Go. Both are compatible. podman info shows which is active. Other runtimes exist, for example kata for lightweight virtual machines and runsc (gVisor) for sandboxing. You switch with --runtime or in containers.conf.

conmon: why containers survive Podman

After crun starts the container, crun exits. The container's parent becomes conmon, a small C program. Its jobs:

  • keep the container's standard streams, so podman logs and podman attach work;
  • write logs to the chosen driver (a file or journald);
  • wait for the container to end and record its exit code;
  • keep running if the podman command that started it was closed.

That last point is why you can start a container, close your terminal, and find it still running. It is also why there is nothing like a daemon crash that takes everything down.

Storage: where images and containers live

containers/storage keeps layers in a graph driver. On modern systems this is overlayfs: each image layer is a read-only directory, and a container adds one writable layer on top. When two images share a base layer, it is stored once.

Mode Default location
Rootless ~/.local/share/containers/storage
Rootful /var/lib/containers/storage
Runtime state (tmpfs) /run/user/UID/containers or /run/containers
Configuration ~/.config/containers/ or /etc/containers/

You can check them from the command line:

Terminal
podman info --format '{{.Store.GraphRoot}}'
podman info --format '{{.Store.GraphDriverName}}'
podman system df

podman system df shows how much space images, containers and volumes use, and how much of it could be reclaimed.

Here is a stand-in that computes how layer sharing saves disk. It is arithmetic in JavaScript, with made-up sizes, not a Podman query.

JS Stand-in: shared layers save space

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Networking pieces

Containers on the default network get a private address from netavark, which creates bridges and firewall rules, and aardvark-dns, which lets containers on the same user-defined network find each other by name. Rootless containers cannot create real bridges on the host, so a helper gives them a user-space network stack: pasta in current releases (Podman 5), slirp4netns in older ones. Networking in the rootless chapter covers the effects.

The REST API and remote use

Podman can run an API service, by default only when something connects (socket activation):

Terminal
systemctl --user enable --now podman.socket
curl --unix-socket "$XDG_RUNTIME_DIR/podman/podman.sock" http://d/v5.0.0/libpod/info

It serves two interfaces: a libpod API with Podman's full features, and a Docker-compatible API. The same mechanism powers podman --remote and the macOS and Windows clients, which talk to Podman inside the VM over SSH. You can define connections with podman system connection add, and use --connection to choose one.

Reading a container's runtime view

podman inspect returns everything Podman knows. Pull out one field with a Go template:

Terminal
podman inspect --format '{{.State.Pid}} {{.OCIRuntime}} {{.ConmonPidFile}}' hello-web

Seeing the PID of the container's main process, the runtime name, and the conmon PID file helps when you debug on the host with ps or strace. In rootless mode, process IDs are real host IDs; you can see the container process with ps -ef.

Here is a last stand-in that formats a made-up inspect result with a simplified template renderer. It shows the idea of querying nested fields, nothing more.

JS Stand-in: inspect field lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component keeps a container's logs and exit code after the podman command has exited?

    conmon is the per-container monitor. It owns the standard streams, writes logs, and records the exit code.
  2. 2. What does the OCI runtime (crun) do?

    The runtime turns the OCI configuration into a running process by calling kernel features.
  3. 3. Where does rootless Podman store images by default?

    Rootless data lives in the user's home under .local/share/containers/storage. The /var/lib path is for rootful use.
  4. 4. Why do two images with the same base use less disk space than two full copies?

    containers/storage stores each layer once, and images reference the layers they need.

Summary

  • Podman is a front end over libraries and helpers: libpod, containers/image, containers/storage, netavark, conmon and an OCI runtime.
  • crun (or runc) starts the process; conmon supervises it and records the exit code.
  • Images are layered on overlayfs, and each layer is stored once.
  • Rootless data lives under your home directory, rootful data under /var/lib/containers.
  • An optional API socket serves libpod and Docker-compatible calls, and powers remote and VM use.
  • podman info, podman system df and podman inspect --format show what is happening inside.

Next: Container Run Options in Depth