Podman

grep "^$USER:" /etc/subuid /etc/subgid          # user:start:count, for example jfields:100000:65536
podman unshare cat /proc/self/uid_map           # the mapping podman actually uses
#         0       1000          1
#         1     100000      65536
sudo usermod --add-subuids 200000-265535 --add-subgids 200000-265535 my-user   # allocate a range
podman system migrate                            # required after changing subuid/subgid so the pause process restarts

podman pull docker.io/library/nginx:1.29                   # fully qualified: no prompt, no ambiguity
podman pull --platform linux/arm64 registry.example.com/my-app:1.4
podman images --format '{{.Repository}}:{{.Tag}} {{.Size}} {{.Created}}'
podman image inspect -f '{{.Digest}} {{.Architecture}}' registry.example.com/my-app:1.4
podman image tree registry.example.com/my-app:1.4          # layers and what shares them
podman login registry.example.com                          # credentials in ${XDG_RUNTIME_DIR}/containers/auth.json
podman login --authfile ~/.config/containers/auth.json registry.example.com   # persistent location
podman build -t registry.example.com/my-app:1.4 -f Containerfile .
podman build --platform linux/amd64,linux/arm64 --manifest registry.example.com/my-app:1.4 .
podman manifest push --all registry.example.com/my-app:1.4  # multi-arch manifest list
podman push registry.example.com/my-app:1.4
podman save -o my-app.tar registry.example.com/my-app:1.4 && podman load -i my-app.tar
podman image prune -a                                      # removes every image without a container: rebuilds and re-pulls follow

# /etc/containers/registries.conf.d/mirror.conf
[[registry]]
prefix = "docker.io"
location = "docker.io"
[[registry.mirror]]
location = "mirror.example.com/docker"        # tried first; falls back to docker.io on failure

[[registry]]
location = "registry.internal.example.com"
insecure = true                               # plain HTTP or untrusted TLS; lab use only

podman run -d --name my-app \
  -p 127.0.0.1:8080:8080 \                      # bind to loopback; without an address, every interface
  -e TZ=Australia/Melbourne --env-file ./my-app.env \
  -v my-app-data:/var/lib/my-app \              # named volume; created on first use
  -v ./config:/etc/my-app:ro,Z \                # read-only bind mount with a private SELinux label
  --secret my-app-token,type=env,target=API_TOKEN \
  --memory 512m --pids-limit 256 \
  --read-only --tmpfs /tmp \                    # immutable rootfs; writable scratch
  --cap-drop ALL --security-opt no-new-privileges \
  --health-cmd 'curl -fsS http://localhost:8080/healthz || exit 1' --health-interval 30s \
  --label io.containers.autoupdate=registry \
  registry.example.com/my-app:1.4

podman ps -a --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
podman stop -t 20 my-app                        # SIGTERM, SIGKILL after 20 s (default 10)
podman rm -f my-app                             # stop and remove; anonymous volumes stay unless -v
podman stats --no-stream                        # CPU, memory, network per container
podman top my-app                               # processes with host and container PIDs
podman port my-app
podman cp my-app:/var/log/my-app/app.log .
podman diff my-app                              # files changed against the image layer
podman commit my-app registry.example.com/my-app:debug   # snapshot; for debugging, not for release

podman run -v ./site:/usr/share/nginx/html:ro,Z docker.io/library/nginx:1.29
podman run -v ./pgdata:/var/lib/postgresql/data:Z,U docker.io/library/postgres:18   # relabel and chown to the postgres user
podman volume create my-app-data
podman volume inspect my-app-data -f '{{.Mountpoint}}'
podman volume export my-app-data -o my-app-data.tar          # tarball of the contents
podman volume import my-app-data my-app-data.tar
podman volume prune                                          # deletes every volume not attached to a container
podman unshare ls -ln "$(podman volume inspect my-app-data -f '{{.Mountpoint}}')"   # view with container-side UIDs

podman network create my-net                                 # bridge, DNS enabled, subnet chosen automatically
podman network create --subnet 10.89.10.0/24 --gateway 10.89.10.1 my-net
podman network create --internal my-backend                  # no route out: for databases
podman network ls; podman network inspect my-net
podman run -d --name my-db --network my-net docker.io/library/postgres:18
podman run -d --name my-app --network my-net,my-backend -p 8080:8080 registry.example.com/my-app:1.4   # two networks
podman run --rm --network my-net docker.io/library/busybox:1.37 nslookup my-db     # resolves through aardvark-dns
podman network connect my-net my-existing-container; podman network disconnect my-net my-existing-container
podman run --network host ...                                # host namespace; rootless still cannot bind below 1024

podman pod create --name my-pod -p 8080:80 --network my-net
podman run -d --pod my-pod --name my-pod-web docker.io/library/nginx:1.29
podman run -d --pod my-pod --name my-pod-app registry.example.com/my-app:1.4    # nginx proxies to localhost:8080
podman pod ps; podman pod inspect my-pod
podman pod stop my-pod; podman pod start my-pod
podman pod rm -f my-pod                          # removes the pod and every container in it
podman kube generate my-pod > my-pod.yaml        # Kubernetes Pod manifest with the running configuration
podman kube play my-pod.yaml                     # creates the pod from YAML; accepts Deployment, PersistentVolumeClaim, ConfigMap, Secret
podman kube play --replace my-pod.yaml           # recreate; --down tears it down
podman kube down my-pod.yaml

# ~/.config/containers/systemd/my-net.network
[Network]
NetworkName=my-net
Subnet=10.89.10.0/24
Gateway=10.89.10.1
DNS=192.0.2.53                      # upstream resolver for aardvark-dns; omit to use the host's

# ~/.config/containers/systemd/my-app-data.volume
[Volume]
VolumeName=my-app-data

# ~/.config/containers/systemd/my-app.container
[Unit]
Description=my-app API
Wants=network-online.target
After=network-online.target

[Container]
Image=registry.example.com/my-app:1.4
ContainerName=my-app
AutoUpdate=registry                 # podman auto-update pulls a newer image and restarts this unit
Network=my-net.network              # depends on my-net-network.service
Volume=my-app-data.volume:/var/lib/my-app
Volume=%h/my-app/config:/etc/my-app:ro,Z    # %h is the user's home; systemd specifiers work
PublishPort=127.0.0.1:8080:8080
Environment=TZ=Australia/Melbourne
EnvironmentFile=%h/my-app/my-app.env
Secret=my-app-token,type=env,target=API_TOKEN
User=1000
UserNS=keep-id:uid=1000,gid=1000
ReadOnly=true
Tmpfs=/tmp
DropCapability=ALL
NoNewPrivileges=true
HealthCmd=curl -fsS http://localhost:8080/healthz || exit 1
HealthInterval=30s
HealthOnFailure=kill                # systemd then restarts the unit under Restart=
Notify=healthy                      # unit is "started" only once the first health check passes
LogDriver=journald

[Service]
Restart=always
RestartSec=5
TimeoutStartSec=900                 # the first start pulls the image; 90 s default is too short on slow links

[Install]
WantedBy=default.target             # multi-user.target for rootful units

# ~/.config/containers/systemd/my-pod.pod
[Pod]
PodName=my-pod
PublishPort=8080:80
Network=my-net.network

# ~/.config/containers/systemd/my-pod-web.container
[Container]
Image=docker.io/library/nginx:1.29
Pod=my-pod.pod                      # joins the pod; ports are on the pod
Volume=%h/my-pod/nginx.conf:/etc/nginx/nginx.conf:ro,Z

[Service]
Restart=always

[Install]
WantedBy=default.target

systemctl --user daemon-reload                                # runs the generator; errors are in the journal
/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun   # print the generated units, exits non-zero on a bad key
systemctl --user start my-app.service
systemctl --user status my-app.service my-net-network.service
journalctl --user -u my-app.service -f
loginctl enable-linger "$USER"                                # user manager runs at boot and survives logout
systemctl --user enable my-app.service                        # only needed if the [Install] section is absent; Quadlet enables via WantedBy

podman auto-update --dry-run --format '{{.Unit}} {{.Image}} {{.Updated}}'   # "pending" marks units with a newer image
podman auto-update                                                      # pull, restart, roll back on failure
systemctl --user enable --now podman-auto-update.timer                  # daily by default; override OnCalendar with a drop-in
systemctl --user list-timers podman-auto-update.timer
journalctl --user -u podman-auto-update.service --since yesterday

systemctl --user enable --now podman.socket                     # Docker-compatible API for docker-compose and other clients
export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock" # point Docker-API clients at it
podman compose up -d
podman compose ps; podman compose logs -f my-app
podman compose down -v                                          # removes containers, networks and named volumes

# Containers not running, with their exit code
podman ps -a --filter status=exited --format '{{.Names}}\t{{.Status}}'

# Health of every container that has a health check
podman ps --format '{{.Names}}' | xargs -I{} sh -c 'printf "%s\t%s\n" {} "$(podman inspect -f "{{.State.Health.Status}}" {})"'

# Memory usage per container, sorted
podman stats --no-stream --format '{{.MemUsage}}\t{{.Name}}' | sort -h

# Image and digest each container was created from
podman ps -a --format '{{.Names}}\t{{.Image}}\t{{.ImageID}}'

# Containers whose image has been replaced by a newer pull (dangling parent)
podman ps -a --format '{{.Names}} {{.ImageID}}' | while read -r n id; do podman image exists "$id" || echo "$n"; done

# Which container publishes a port
podman ps --format '{{.Names}}\t{{.Ports}}' | grep ':8080'

# Run a throwaway shell with the current directory mounted and relabelled
podman run --rm -it -v "$PWD":/work:Z -w /work docker.io/library/alpine:3.22 sh

# Enter a container's network namespace tools without changing the image
podman run --rm -it --network container:my-app docker.io/nicolaka/netshoot ss -ltnp

# The user-namespace UID a host file appears as inside containers
podman unshare stat -c '%u %g %n' ./data/*

# Fix ownership of a bind mount for container UID 999 (postgres) without sudo
podman unshare chown -R 999:999 ./pgdata

# Explain a denial for the last container started
sudo ausearch -m avc -ts recent -c podman -c my-app 2>/dev/null | tail -5

# Regenerate and validate Quadlet units without starting anything
/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun >/dev/null && echo ok

# Units Quadlet generated for this user
systemctl --user list-units 'my-*' --all

# Pending image updates
podman auto-update --dry-run --format '{{.Unit}}\t{{.Updated}}' | grep -w pending

# Reclaim: stopped containers, unused networks, dangling images and build cache
podman system prune -f

# Space by category, then the biggest images
podman system df && podman images --sort size --format '{{.Size}}\t{{.Repository}}:{{.Tag}}' | head

# Export a container's rootfs for offline inspection
podman export my-app | tar -tvf - | sort -k3 -n | tail

# Check whether a registry needs login before a scripted pull
podman search --list-tags --limit 5 registry.example.com/my-app

# Copy an image between registries without a local pull
skopeo copy --all docker://registry.example.com/my-app:1.4 docker://mirror.example.com/my-app:1.4

# Wait for a container to become healthy in a script
until [ "$(podman inspect -f '{{.State.Health.Status}}' my-app)" = healthy ]; do sleep 2; done

# Every environment variable a container was started with (values included: treat as sensitive)
podman inspect -f '{{range .Config.Env}}{{println .}}{{end}}' my-app

#!/usr/bin/env bash
# usage: podman-health.sh   (runs against the invoking user's containers)
set -euo pipefail

rc=0
while IFS=$'\t' read -r name state health started; do
  since=$(( $(date +%s) - $(date -d "$started" +%s) ))
  flag=ok
  if [[ $state != running ]]; then flag="state=$state"; rc=1
  elif [[ $health != healthy && $health != '' ]]; then flag="health=$health"; rc=1
  elif (( since < 3600 )); then flag="restarted ${since}s ago"; rc=1
  fi
  printf '%-24s %-8s %-10s %s\n' "$name" "$state" "${health:-none}" "$flag"
done < <(podman ps -a --format '{{.Names}}' | while read -r n; do
  podman inspect -f $'{{.Name}}\t{{.State.Status}}\t{{.State.Health.Status}}\t{{.State.StartedAt}}' "$n"
done)
exit "$rc"

#!/usr/bin/env bash
# usage: podman-reclaim.sh [max-used-percent]   default 80
set -euo pipefail
limit=${1:-80}
root=$(podman info --format '{{.Store.GraphRoot}}')

used() { df --output=pcent "$root" | tail -1 | tr -dc '0-9'; }
step() { printf '%s (%s%% used)\n' "$1" "$(used)"; shift; "$@" >/dev/null; }

printf 'storage %s at %s%% (limit %s%%)\n' "$root" "$(used)" "$limit"
(( $(used) > limit )) || exit 0
step 'pruning stopped containers'        podman container prune -f
(( $(used) > limit )) || exit 0
step 'pruning dangling images'           podman image prune -f
(( $(used) > limit )) || exit 0
step 'pruning build cache and networks'  podman system prune -f
(( $(used) > limit )) || exit 0
step 'pruning unused images'             podman image prune -a -f
(( $(used) > limit )) || exit 0
step 'pruning unattached volumes'        podman volume prune -f
(( $(used) > limit )) && { printf 'still %s%% used: inspect %s manually\n' "$(used)" "$root" >&2; exit 1; }

#!/usr/bin/env bash
# usage: container-to-quadlet.sh NAME > ~/.config/containers/systemd/NAME.container
set -euo pipefail
c=${1:?container name}
podman container exists "$c"
json=$(podman inspect "$c")
{
  echo '[Container]'
  jq -r '.[0] | "Image=\(.ImageName)\nContainerName=\(.Name)"' <<<"$json"
  jq -r '.[0].HostConfig.PortBindings // {} | to_entries[] | .key as $k | .value[]
         | "PublishPort=\(if .HostIp != "" then .HostIp + ":" else "" end)\(.HostPort):\($k | split("/")[0])"' <<<"$json"
  jq -r '.[0].Mounts[] | "Volume=\(.Source):\(.Destination)\(if .RW then "" else ":ro" end)"' <<<"$json"
  jq -r '.[0].Config.Env[] | select(startswith("PATH=") or startswith("HOME=") | not) | "Environment=\(.)"' <<<"$json"
  jq -r '.[0].NetworkSettings.Networks // {} | keys[] | select(. != "podman") | "Network=\(.)"' <<<"$json"
  printf '\n[Service]\nRestart=always\n\n[Install]\nWantedBy=default.target\n'
}