# Podman Knowledge Patch > Podman - Skill: `nevaberry/podman-knowledge-patch` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add nevaberry/podman-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/podman-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/podman-knowledge-patch --- # Podman knowledge patch Use this patch before changing Podman commands, configuration, Quadlets, machine workflows, Kubernetes replay, networking, storage, image automation, or REST clients. Treat defaults, platform support, and machine-readable output as version-sensitive. Read the topic reference that matches the work instead of assuming Docker behavior or older Podman behavior. ## Reference index | Reference | Read for | | --- | --- | | [APIs, bindings, and observability](references/apis-bindings-and-observability.md) | Libpod and Compat endpoints, Go bindings, remote connections, inspect/list output, events, and TLS | | [Containers and runtime](references/containers-and-runtime.md) | Create/run/update/exec, health checks, pods, signals, filters, checkpoint/restore, devices, and runtime defaults | | [Images, builds, and artifacts](references/images-builds-and-artifacts.md) | Builds, image operations, signing, OCI artifacts, SBOMs, and artifact APIs | | [Kubernetes, network, and storage](references/kubernetes-network-and-storage.md) | `kube play/generate/down`, CDI, networks, volumes, secrets, host files, and storage checks | | [Machines and platforms](references/machines-and-platforms.md) | Machine providers, VM provisioning, host mounts, Windows/macOS support, TLS trust, and machine OS management | | [Migration and configuration](references/migration-and-configuration.md) | Upgrade prerequisites, removed stacks, unified config lookup and precedence, database migration, packaging, and security fixes | | [Quadlet](references/quadlet.md) | Unit types, installation, discovery, drop-ins, dependencies, resource keys, and generated-service behavior | ## Breaking changes and migration hazards ### Migrate BoltDB safely - Prefer a reboot so migration runs without competing Podman processes. - Use Podman 5.8.1 or later for migration when persistent Quadlets exist; the 5.8.0 path can leave a partial SQLite database and has no automatic recovery. - Before `podman system migrate --migrate-db`, stop every other Podman process, including socket-activated services and Quadlets. - Preserve the legacy database. Podman retains it when migration fails. - Only move `db.sql` aside and retry on 5.8.1 or later when no persistent containers, pods, or volumes need to be preserved. ```console podman system migrate --migrate-db ``` ### Remove unsupported platform and network assumptions For Podman 6 deployments, require Linux kernel 5.2 or newer and migrate away from: - Intel macOS hosts and Windows 10; - cgroups v1 for the engine; - iptables networking and CNI; - `slirp4netns` and its removed global `--network-cmd-path` option. Use cgroups v2, nftables, Netavark, and Pasta as applicable. Pair Podman 6 with Buildah 1.44.0, Skopeo 1.23, Netavark and Aardvark 2.0.0, and containers/common configuration 0.68.0. A Podman 6.0.2 remote client can run on a cgroups v1 Linux host, but the Podman 6 engine still cannot. ### Apply unified configuration precedence Do not merge every main file. For each supported config, Podman selects only the highest-priority existing main file: user, then administrator, then vendor. Even an empty user main file suppresses lower-tier main files. Then apply drop-ins from all applicable tiers: 1. Mask earlier same-named files with files from later locations. 2. Sort the surviving files globally by filename. 3. Let lexicographically later filenames win, regardless of tier; a vendor `99-*.conf` can override a user `33-*.conf`. Use `CONTAINERS__CONF` to select one file and disable normal loading. Use `CONTAINERS__CONF_OVERRIDE` to load one final override after the normal stack. Restart the Podman service process after configuration changes; in-process reload is gone. ### Update configuration and Go consumers - Stop using `/etc/containers/containers.rootless.conf`; put root-mode customization in drop-ins. - Replace storage `rootless_storage_path` with `graphroot` in a rootless drop-in. - Replace registries.conf V1 and `REGISTRIES_CONFIG_PATH` with V2 and `CONTAINERS_REGISTRIES_CONF`. - Cache `DefaultStoreOptions()` in storage-library code; `ReloadConfigurationFile()`, `UpdateStoreOptions()`, and `Save()` are removed. - Move Go imports from `github.com/containers/podman/v5` to `go.podman.io/podman/v6`. - Remove the redundant `nameOrID` argument from binding calls to `artifacts.Remove()`. ### Account for changed defaults and output - Network isolation is enabled by default. - `podman volume prune` removes only unused anonymous volumes; use `--all` for the former scope and `--dry-run` to preview. Before 6.1, do not combine `--all` with a label filter. - `podman commit` pauses the container by default; use `--pause=false` only when inconsistent concurrent changes are acceptable. - Repeated volume-list filters and repeated supported `label!=` filters combine with AND. - An unset inspected `MemorySwappiness` is `nil`, not `-1`. - `{{json .Labels}}` in container, pod, and volume list templates produces comma-separated `key=value` text, not a JSON object. - Pod start/stop prints the identifier supplied by the caller, not necessarily a full ID. - SIGTERM no longer implies a successful Podman exit. - A one-element inspected command appears in `Path` with an empty `Args` array. ## Security and compatibility floors Use a patched maintenance release whenever the affected path is present: | Minimum | Reason | | --- | --- | | 5.6.1 | Prevent crafted `ConfigMap` or `Secret` symlinks in `kube play` YAML from overwriting host content; restore runc 1.3 startup compatibility | | 5.6.2 | Restore non-root Containerfile builds that use cache mounts | | 5.7.0 | Address the runc arbitrary-write/procfs container-escape and denial-of-service path | | 5.7.1 | Restore rootless user-namespace recreation after both Conmon and the pause process die | | 5.8.1 | Avoid the Quadlet-related partial-database migration path | | 5.8.2 | Prevent command execution from a crafted Hyper-V machine image path; fix `unless-stopped` reboot behavior and Quadlet parsing | | 5.8.3 | Prevent malicious Git or tar build contexts from escaping `ADD`/`COPY` boundaries | | 5.8.4 | Prevent malformed image `Env` entries from exposing host environment variables | | 5.8.6 | Make `quadlet install --replace` truncate shorter replacement files safely | | 6.0.1 | Avoid stale Pasta/Pesto forwarding rules during experimental rootless bridge forwarding | | 6.0.2 | Restore remote-client operation on cgroups v1 Linux hosts without restoring engine support | | 6.1 | Make `volume prune --all` honor label filters | ## High-value command and configuration patterns ### Manage Quadlets locally Use `podman quadlet install`, `list`, `print`, and `rm` for current-user units. These commands were local-only when introduced. A bundled install file may contain several units; separate sections with `---` and start each with `# FileName=`. ```ini # FileName=app.container [Container] Image=docker.io/library/alpine:latest --- # FileName=data.volume [Volume] ``` Expect installed units and auxiliary files in subdirectories rather than a tracked `.app` file. Use `podman quadlet list --format ...` for scriptable output; it suppresses headings, can filter by status, and exposes a container unit's pod. ### Use current container controls ```console podman update --ulimit nofile=4096:8192 web podman update --no-healthcheck web podman exec --no-session web true podman wait --return-on-first ctr1 ctr2 podman run --userns=keep-id:size=65536 IMAGE podman run --mount type=volume,src=myvol,dst=/mnt,nocreate IMAGE ``` - Update environment with `podman update --env` and `--unsetenv`; target the newest container with `--latest`. - Use `--health-log-destination`, `--health-max-log-count`, and `--health-max-log-size` to bound health logs. - Expect timed-out health checks to receive SIGTERM and then SIGKILL after a delay. - Use `--gpus` for AMD GPUs as well as other supported GPU devices. - Use `--log-opt label=...` only with the journald log driver. ### Use current volume, network, and Kubernetes features ```console podman volume prune --dry-run podman run --net mynet:ip=10.0.0.2,ip=10.0.0.3 IMAGE podman network create --route 10.20.30.0/24,blackhole isolated podman kube play app.yaml worker.yaml ``` - Use `subpath=` to mount only a volume subdirectory and `nocreate` to require an existing named volume. - Use `podman volume create --uid ... --gid ...` to set ownership at creation. - Repeat `ip=` to assign several addresses on one network; attachment order follows the command line. - Use `--no-pod-prefix` cautiously: a pod and container with the same resulting name conflict. - Treat untrusted Kubernetes YAML as hostile and enforce the security floor above. ### Use stable OCI artifacts Manage artifacts with `podman artifact add`, `inspect`, `ls`, `pull`, `push`, and `rm`. Mount them with `type=artifact`; use `name=` to choose the exposed filename. A single-blob artifact mounts as a file when the destination does not already exist in the image. ```console podman run --mount type=artifact,src=example.com/acme/data:latest,dst=/data,name=payload IMAGE ``` Use `.artifact` Quadlet units for systemd-managed artifacts. For service-local content, use the local artifact API; for remote uploads, use the tar-body endpoint in the API reference. ### Work across machine providers Treat the configured machine provider as the default for new VMs only. Every machine command can address VMs from every provider. Select a provider at creation and suppress default-connection prompts explicitly in automation: ```console podman machine init --provider libkrun --update-connection=false dev ``` Recreate existing Linux machine VMs after adopting Podman 6 because systemd-based host volume mounting is incompatible with their old mounts. Use `--import-native-ca` when the VM must trust host CAs, and remember that `machine os update` is unavailable with WSL. ## Verification checklist - Inspect the relevant topic reference before editing commands or parsing output. - Confirm the installed maintenance release before relying on a security or compatibility fix. - Preview destructive storage work with `--dry-run` where supported and stop background services before database migration. - Restart the system service after configuration changes. - Test remote and local clients separately when a feature has transport-specific coverage. - Recheck scripts that parse IDs, labels, statuses, image fields, or Compat API responses.