Podman quadlets on openSUSE: your first rootless service

What a quadlet is

A quadlet is a systemd unit file for a container, minus the boilerplate. You write a short .container file describing the image, ports and volumes; at every daemon-reload, podman's systemd generator translates it into a full .service. From then on systemd starts it at boot, restarts it on failure and collects its logs, like any other service.

A first quadlet

As the container user from the rootless podman guide, no root needed:

mkdir -p ~/.config/containers/systemd
nano ~/.config/containers/systemd/whoami.container

[Unit]
Description=whoami test web server

[Container]
Image=docker.io/traefik/whoami:latest
PublishPort=8080:80
AutoUpdate=registry

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

The file name becomes the service name: whoami.container turns into whoami.service. WantedBy=default.target starts it when the user's service manager starts, which with lingering means at boot. A tested version with notes is in the whoami quadlet example.

Start, check, read the logs

systemctl --user daemon-reload             # run the generator
systemctl --user start whoami
systemctl --user status whoami
curl http://localhost:8080                 # prints request details
journalctl --user -u whoami -n 50          # the container's output

To reach it from another machine, open 8080/tcp in firewalld (needs root), as shown in the firewalld basics guide. The systemctl and journalctl guide covers the rest of the service commands.

When the service does not appear

"Unit whoami.service not found" after a daemon-reload means the generator rejected the file. It logs why, but the quickest check is a dry run:

/usr/lib/systemd/user-generators/podman-user-generator --dryrun      # rootless
sudo /usr/lib/systemd/system-generators/podman-system-generator --dryrun   # rootful
podman quadlet list                        # podman 5.6 and newer (Tumbleweed)

The dry run prints the generated service, or the line it choked on: a typo in a key, a key in the wrong section, or a file name without a known extension.

Both cases for real, with the generator pointed at a scratch folder through QUADLET_UNIT_DIRS (paths shortened to the usual folder). A good file:

$ cat whoami.container
[Unit]
Description=whoami test web server

[Container]
Image=docker.io/traefik/whoami:latest
PublishPort=127.0.0.1:8080:80
AutoUpdate=registry

[Service]
Restart=on-failure

[Install]
WantedBy=default.target
$ QUADLET_UNIT_DIRS=$PWD /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
quadlet-generator[3120683]: Loading source unit file ~/.config/containers/systemd/whoami.container
---whoami.service---
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=whoami test web server
SourcePath=~/.config/containers/systemd/whoami.container
RequiresMountsFor=%t/containers

[X-Container]
Image=docker.io/traefik/whoami:latest
PublishPort=127.0.0.1:8080:80
AutoUpdate=registry

[Service]
Restart=on-failure
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStop=/usr/bin/podman rm -v -f -i systemd-%N
ExecStopPost=-/usr/bin/podman rm -v -f -i systemd-%N
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name systemd-%N --replace --rm --cgroups=split --sdnotify=conmon -d --label io.containers.autoupdate=registry --publish 127.0.0.1:8080:80 docker.io/traefik/whoami:latest

[Install]
WantedBy=default.target

And one letter too many (PublishPorts=). The generator names the key and exits with 1 instead of 0:

$ QUADLET_UNIT_DIRS=$PWD /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
quadlet-generator[3120214]: Loading source unit file ~/.config/containers/systemd/typo.container
quadlet-generator[3120214]: converting "typo.container": unsupported key 'PublishPorts' in group 'Container' in ~/.config/containers/systemd/typo.container
quadlet-generator[3120214]: processing encountered some errors
$ QUADLET_UNIT_DIRS=$PWD /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun >/dev/null 2>&1; echo "exit=$?"
exit=1

Updating the image

AutoUpdate=registry marks the container for podman's auto-update. Turn on the timer once per user, and podman pulls newer images and restarts the service, rolling back if the new one fails to start:

systemctl --user enable --now podman-auto-update.timer
podman auto-update --dry-run               # what would be updated

Pin a version tag instead of latest for anything with a database: an unattended major upgrade is not a fun way to start the day.

Common mistakes

Frequently asked questions