Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Systemd and Operations

Systemd Services and Auto-Update

Keep Podman containers running with systemd: restart policies, generate systemd and why Quadlet replaced it, enabling lingering, podman auto-update, timers and automatic rollback.

A container that stops when you close your terminal is a toy; a container that starts at boot, restarts after a crash and updates itself safely is a service. Podman has no always-running daemon, so it hands that job to systemd, which already supervises everything else on a Linux server. This lesson shows how the pieces fit together: restart policies, systemd units, lingering for rootless users, and podman auto-update for keeping images current.

systemd and registries are not available in the browser, so commands are read-only; the stand-ins simulate restart policies and auto-update decisions.

Restart policies

You can ask Podman itself to restart a container:

Terminal
podman run -d --restart=on-failure:5 --name job docker.io/library/alpine:3 sh -c 'exit 1'
podman run -d --restart=always --name web docker.io/library/nginx:stable
Policy Restarts when
no (default) never
on-failure[:N] exit code is non-zero, at most N times
always always, including after the container exited cleanly
unless-stopped like always, except after you stopped it manually

The catch: --restart only works while something is running to apply it. After a reboot nothing restarts the container, because Podman has no daemon. Since Podman 4, a built-in podman-restart.service can start containers marked --restart=always at boot (systemctl enable podman-restart.service), but the cleaner approach is to let systemd own the container.

Python Restart policy simulator (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Systemd and Quadlet

systemd needs a unit file. There are two ways to get one:

  1. Quadlet (recommended): write a .container file as in Quadlet: Containers as systemd Units. It is declarative, survives Podman upgrades and supports pods, volumes and networks.
  2. podman generate systemd: an older command that prints a .service file for an existing container. It still works but is deprecated; new setups should use Quadlet.
Terminal
podman generate systemd --new --files --name web     # older approach

Either way, control the service with systemctl, using --user for rootless containers:

Terminal
systemctl --user enable --now web.service     # for hand-written/generated services
systemctl --user status web.service
systemctl --user restart web.service
journalctl --user -u web.service -n 50

(For Quadlet-generated units there is no enable; the [Install] section in the .container file does the job.)

Starting rootless services at boot

By default a user's systemd instance starts at first login and stops after the last logout, taking containers with it. Enable lingering to keep it running:

Terminal
sudo loginctl enable-linger alice
loginctl show-user alice --property=Linger

Useful service settings

Add them in the [Service] section of the unit (or the Quadlet file):

INI
[Service]
Restart=on-failure
RestartSec=5
TimeoutStartSec=300

TimeoutStartSec matters for the first start after a new image, because podman pull can take longer than systemd's default start timeout. Restart= replaces Podman's own --restart: do not use both.

Auto-update

Images get security fixes. podman auto-update checks whether the registry has a newer image for each labeled container and restarts the container with it. Opt in with the label io.containers.autoupdate=registry, which Quadlet sets for you with AutoUpdate=registry:

INI
[Container]
Image=docker.io/library/nginx:stable
AutoUpdate=registry

Rules to know:

  • It only works for containers managed by systemd units (it restarts the unit).
  • Use a fully qualified image name; short names are rejected.
  • AutoUpdate=local compares with images already in local storage (useful when you build locally).
  • The tag is followed, not pinned: nginx:stable moves with the publisher's stable tag.

Run it by hand or on a timer:

Terminal
podman auto-update --dry-run          # report what would change
podman auto-update                    # update and restart
systemctl --user enable --now podman-auto-update.timer
systemctl --user list-timers

The timer runs podman-auto-update.service daily by default; override the schedule with systemctl --user edit podman-auto-update.timer.

Rollback

If the new container fails to start, podman auto-update can roll back to the previous image automatically. The check works through systemd: the unit must signal success with sd_notify (Quadlet containers are started with --sdnotify=conmon, which reports "ready" once the container is running). If the restarted service does not become active, the old image is restored and restarted. You can improve this by using a health check with --sdnotify=healthy, so "ready" means the application passes its check, not only that the process exists.

Auto-update is convenient for stateless services. For databases or anything with schema migrations, pin versions and update deliberately.

Python Auto-update decision (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Putting it together

A robust rootless service: a Quadlet .container file with Restart=on-failure, AutoUpdate=registry, HealthCmd= for readiness, lingering enabled for the user, and podman-auto-update.timer enabled. Logs go to the journal (see Health Checks, Logs and Events).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does --restart=always not bring containers back after a reboot by itself?

    Without a daemon nothing applies the policy at boot. systemd units (or podman-restart.service) do.
  2. 2. What keeps a rootless user's containers running after logout?

    Lingering keeps the user's systemd instance, and its services, running without a login session.
  3. 3. Which label or key opts a container in to registry auto-update?

    The label tells podman auto-update to check the registry for that container's image.
  4. 4. What does auto-update do if the new container does not start successfully?

    podman auto-update watches the restarted unit through systemd and restores the old image on failure.

Summary

  • --restart policies need a running supervisor; systemd units give start at boot and proper supervision.
  • Prefer Quadlet over the deprecated podman generate systemd; use systemctl --user for rootless services and enable-linger for boot start.
  • AutoUpdate=registry plus podman-auto-update.timer keeps tag-following images fresh, with rollback if the new version does not start.
  • Do not combine Podman's --restart with systemd Restart=; let systemd decide.
  • Pin and update deliberately for stateful services.

Next: Health Checks, Logs and Events