Skip to content

quadlet.md

Latest commit

 

History

History
216 lines (170 loc) · 10.4 KB

quadlet.md

File metadata and controls

216 lines (170 loc) · 10.4 KB
Raw
description Reference for the systemd Quadlet units generated by podbox — .container, .build, .socket, and companion .service files with all supported keys.

Quadlet Keys Used

Four Quadlet/systemd unit files are generated per container:

File Path (5.6–5.x) Path (6.0+) Purpose
<name>.build ~/.config/containers/systemd/ ~/.config/containers/systemd/<name>/ Image build definition
<name>.container ~/.config/containers/systemd/ ~/.config/containers/systemd/<name>/ Container runtime
<name>.socket ~/.config/systemd/user/ ~/.config/systemd/user/ Host-guest Unix socket (custom)
<name>-host.service ~/.config/systemd/user/ ~/.config/systemd/user/ Host socket server (custom)
<name>-proxy.service ~/.config/systemd/user/ ~/.config/systemd/user/ D-Bus proxy (conditional, custom)
<name>-compositor.service ~/.config/systemd/user/ ~/.config/systemd/user/ Wayland firewall proxy (conditional, custom)

.build file

Key Value Notes
ImageTag localhost/podbox-<name>:latest Local tag for built image
File Absolute path to Containerfile Must be absolute
Retry From image.pull_retry Pull retry count (default 3)
RetryDelay From image.pull_retry_delay Pull retry delay (default 5s)

.socket file

Key Value Notes
ListenStream %t/podbox/<name>.sock %t = $XDG_RUNTIME_DIR
Service <name>-host.service Activates the host socket server
SocketMode 0600 User-only access
DirectoryMode 0700 Parent dir permissions

.container file

[Unit]

Key Value Notes
Description podbox -- <name> Human-readable name
Requires <name>.socket Socket must be available
After <name>.socket Socket starts first
Requires <name>-proxy.service D-Bus proxy (conditional on [dbus] rules)
After <name>-proxy.service Proxy starts first (conditional)
Requires <name>-compositor.service Wayland firewall (conditional on Wayland proxy)
After <name>-compositor.service Compositor starts first (conditional)
Requires User-defined from [systemd].requires Custom dependencies
After User-defined from [systemd].after Custom ordering
StartLimitBurst 5 Max restarts in interval
StartLimitIntervalSec 30s Restart burst window

[Container]

Key Value Notes
Image Prebuilt ref or localhost/podbox-<name>:latest Prebuilt images use the registry ref directly; custom builds use local tag
Retry From image.pull_retry Pull retries (prebuilt only)
RetryDelay From image.pull_retry_delay Pull retry delay (prebuilt only)
ContainerName <name> Podman container name
UserNS keep-id (default) User namespace mode (configurable via security.userns: keep-id, nomap, private)
User root Run as root inside the container (UID mapped via UserNS)
SecurityLabelDisable true Required for Wayland socket access
SeccompProfile From security.seccomp Seccomp profile (conditional, e.g. "default", "unconfined")
NoNewPrivileges true Emitted when security.no_new_privileges = true (default). Set false to allow sudo, su, AUR helpers.
Memory From container.memory Memory limit (conditional, e.g. "4G")
CpuQuota From container.cpus × 100000µs CPU quota (conditional, e.g. "2.0" → CpuQuota=200000)
ReadOnly true Read-only rootfs (conditional on security.read_only_rootfs)
AppArmorProfile From security.apparmor AppArmor profile (conditional, e.g. "unconfined")
AddDevice /dev/dri GPU (conditional on gpu=true or gpu="auto" with DRI present)
AddDevice -/dev/nvidiactl, -/dev/nvidia0 NVIDIA GPU (conditional on gpu="nvidia" or gpu="auto" with NVIDIA present)
AddDevice -/dev/nvidia-uvm NVIDIA UVM (conditional, when available)
Network From network.mode Network mode (default host)
PublishPort From network.ports Port mapping (conditional, ignored in host mode)
AutoUpdate registry or local Auto-update (conditional on lifecycle.auto_update; registry for prebuilt, local for custom)
ReloadCmd From container.reload_cmd Reload command (conditional)
SshAgent default SSH agent passthrough (conditional on ssh_agent, requires Podman ≥ 5.6)

Environment= entries

Variable Source Notes
HOME /home/%u Always set
HOST_USER Host username Injected into container
HOST_UID %U (systemd) Host UID
HOST_GID %G (systemd) Host GID
PATH /run/podbox/bin:... Interceptor directory prepended
WAYLAND_DISPLAY From host env Wayland display (conditional)
XDG_RUNTIME_DIR %t Always set when Wayland is enabled
MOZ_ENABLE_WAYLAND 1 Wayland-native Firefox/Thunderbird (conditional)
PIPEWIRE_RUNTIME_DIR %t PipeWire runtime dir (conditional)
PULSE_SERVER unix:%t/pulse/native PulseAudio server (conditional)
DBUS_SESSION_BUS_ADDRESS Proxy or direct D-Bus address (conditional)
SSH_AUTH_SOCK /run/podbox/ssh-agent.sock SSH agent (conditional, Podman ≥ 5.6)
GPG_TTY /dev/pts/0 GPG TTY (conditional)
GNUPGHOME /run/podbox/gnupg GPG home (conditional)
LANG, LC_ALL, LC_CTYPE From host locale Locale (conditional)
PODBOX_CONTAINER <name> Always set; identifies the container

Custom [container.env] entries are also passed as Environment=.

Volume= entries

Source Destination Mode Condition
<context>/.flatpak-info /.flatpak-info ro Always (sandbox detection — tricks apps into using portals)
%h/containers/<name> /home/%u Z Always (isolated home)
XDG dirs /home/%u/<dir> ro,z or z Per [integration.xdg_dirs]
%h/.themes /home/%u/.themes ro sync_themes + path exists
%h/.local/share/themes /home/%u/.local/share/themes ro sync_themes + path exists
%h/.icons /home/%u/.icons ro sync_icons + path exists
%h/.local/share/icons /home/%u/.local/share/icons ro sync_icons + path exists
%h/.fonts /home/%u/.fonts ro sync_fonts + path exists
%h/.local/share/fonts /home/%u/.local/share/fonts ro sync_fonts + path exists
/etc/localtime /etc/localtime ro File exists on host
/etc/timezone /etc/timezone ro File exists on host
Wayland socket Wayland socket ro wayland = true
%t/pipewire-0 %t/pipewire-0 (none) audio = true + PipeWire present
%t/pulse %t/pulse (none) audio = true + PulseAudio present
D-Bus socket D-Bus socket (none) dbus = true
GPG agent socket /run/podbox/gnupg/S.gpg-agent ro gpg_agent = true
%t/podbox/<name>.sock %t/podbox/<name>.sock (none) Always (host-guest socket)
Extra mounts Per config Per config From [container.mounts].extra

PodmanArgs=

Arg Notes
--init catatonit as PID 1 (zombie reaping)
--workdir=/home/%u Default working directory
--cap-add=<cap> Per security.cap_preset + security.cap_add (conditional)

[Service]

Key Value Notes
Restart on-failure Auto-restart on crash
RestartSec 2s Delay between restarts
AutoRemove true Only when lifecycle.on_stop = "remove"

[Install]

Key Value Notes
WantedBy default.target Only when lifecycle.autostart = true

Companion .service files

<name>-host.service

Generated at ~/.config/containers/systemd/<name>-host.service:

[Unit]
Description=podbox host socket server -- <name>

[Service]
Type=simple
ExecStart=<podbox> serve <name>
Restart=on-failure
RestartSec=2s
RuntimeDirectory=podbox

[Install]
WantedBy=<name>.socket

<name>-proxy.service (D-Bus proxy)

Generated when [dbus] talk/own rules are configured. See dbus-proxy.md for details.

<name>-compositor.service (Wayland firewall)

Generated when wayland.firewall = true (default). Runs podbox compositor <name> to filter Wayland protocol access.

Podman Version Targeting

Podbox targets Podman 5.5+ with feature gating at 5.6 and 6.0.

Feature Podman 5.5.x Podman ≥ 5.6, < 6.0 Podman ≥ 6.0
ssh_agent Warns and skips SshAgent=default + Environment= SshAgent=default + Environment=
Quadlet install Manual copy into ~/.config/containers/systemd/ podman quadlet install --replace with file args (flat layout) podman quadlet install --replace --application <name> <dir> (app-subdir layout)
Quadlet uninstall Manual file remove + systemctl daemon-reload podman quadlet rm <name>.container (flat) podman quadlet rm --recursive <name> (app-subdir) + flat fallback
Container list podman ps --filter label=podbox.* podman quadlet list podman quadlet list

Layout by version:

  • 5.6–5.x: Units at …/systemd/<name>.container (flat).
  • 6.0+: Units at …/systemd/<name>/<name>.container (app-subdir via --application).

Status, doctor, and start probes check both layouts, so upgrades between versions are transparent.

See podbox doctor to check Podman version compatibility.

Important Notes

  • %t is the systemd specifier for $XDG_RUNTIME_DIR — never substitute it.
  • %h is the systemd specifier for the user's home — never substitute it.
  • %U / %G expand to the user's UID and GID at unit start time.
  • Quadlet files (.container, .build) go in ~/.config/containers/systemd/.
    • Podman 5.6–5.x: flat layout (<name>.container).
    • Podman 6.0+: app-subdir layout (<name>/<name>.container).
  • Custom systemd units (.socket, -host.service, etc.) always go in ~/.config/systemd/user/.
  • Re-running podbox enable is safe — it uses --replace to overwrite existing Quadlet files idempotently.