Debian 13 Tutorial / Manage Quadlet User Services, Restarts, linger and Boot Startup
To operate rootless containers as user services on Debian 13, you create the original Quadlet and manage the services generated by the user systemd. The restart on abnormal termination, explicit stop, persistence after logout, and automatic start at boot are different conditions, so each must be checked separately. In this tutorial, we create separate web containers and volumes, preserve the original value of linger, and then verify the HTTP response.
Distinguish Quadlet Source Files from Generated Services
Quadlet is a Podman feature that reads files with extensions such as .container to generate systemd services. Ordinary users usually place the source in ~/.config/containers/systemd and manage it with systemctl --user. If you modify a generated .service file under /run/user/UID/systemd/generator directly, it will disappear upon regeneration, so you fix the original file.
This tutorial was run in a Podman 5.4.2, cgroup v2, systemd user manager environment. According to the Quadlet documentation of Podman 5.4.2, we use the supported keys Image, ContainerName, PublishPort, Volume, and Pull. To avoid problems where services are not generated by directly using keys from newer documentation, first check the installed version and the generator output.
The generated service is not something managed via systemctl enable like a regular permanent service file. If you put WantedBy=default.target in the [Install] section of the original file, the generator creates a link to the user's default target. Do not try to switch accounts by adding User= in a rootless original file; work as the actual normal user instead.
Prepare the User Session, Image and Dedicated Volume
Use the normal user Podman environment verified in the previous lesson. Only package installations are done with sudo, and the following podman and systemctl --user commands are executed as a normal user. Port 8080 and the name lf-web28 should be available. This example uses lf-web28-data, which is different from the volume in the previous lesson.
sudo apt install podman uidmap passt fuse-overlayfs curl
podman --version
podman info --format json
systemctl --user is-system-running
loginctl show-user "$(id -un)" -p Linger
ss -ltn
In a new Bash terminal, execute the following preparation block. Linger applies to the entire user manager for the account, so consider the maintenance scope before using it on an account with other user services. Keep a separate record of the original value to avoid changing an account that was originally yes to no while cleaning it up.
set -euo pipefail
record="$HOME/lf-course28-linger-before.txt"
qdir="$HOME/.config/containers/systemd"
for p in "$record" "$qdir/lf-web28.container"; do
if test -e "$p"; then
echo "Path already exists: $p" >&2
exit 1
fi
done
if podman container exists lf-web28; then exit 1; fi
if podman volume exists lf-web28-data; then exit 1; fi
loginctl show-user "$(id -un)" -p Linger --value > "$record"
cat "$record"
podman pull docker.io/library/httpd:2.4.71-trixie
image=$(podman image inspect docker.io/library/httpd:2.4.71-trixie --format '{{index .RepoDigests 0}}')
case "$image" in
docker.io/library/httpd@sha256:*) ;;
*) echo "Check the image reference." >&2; exit 1 ;;
esac
podman image exists "$image"
podman volume create lf-web28-data
podman run --rm --network none -v lf-web28-data:/data --entrypoint /bin/sh "$image" -c 'printf "LF QUADLET 28\n" > /data/index.html'
mkdir -p "$qdir"
This exercise fetches the image in advance and uses a digest. Pull=never in the service prevents it from attempting to download at boot, so if the image is not local, the start will fail. Do not assume that it will automatically recover even if the image is deleted; establish procedures for image retention and updates together. The web root of the official httpd image can be checked in httpd image guide.
Write the Complete Quadlet and Inspect Generator Output
Save the entire configuration below in the same terminal. Since the CONF of the heredoc is not quoted, the previously defined $image will be expanded to the actual digest. This file is the configuration for that user.
cat > "$qdir/lf-web28.container" <<CONF
[Unit]
Description=LF rootless web lab 28
[Container]
Image=$image
ContainerName=lf-web28
PublishPort=127.0.0.1:8080:80
Volume=lf-web28-data:/usr/local/apache2/htdocs:ro
Pull=never
[Service]
Restart=on-failure
RestartSec=2
TimeoutStartSec=180
[Install]
WantedBy=default.target
CONF
| Settings | Meaning |
|---|---|
| PublishPort=127.0.0.1:8080:80 | Publish the port only to the VM's loopback. |
| Volume=...:ro | Mount the web data volume as read-only. |
| Restart=on-failure | Request systemd to restart services that exited due to failure. |
| RestartSec=2 | Wait between restarts. This does not remove the limit for repeated failures. |
| TimeoutStartSec=180 | Set a time limit to wait for the service to start. This does not check the HTTP readiness status. |
| WantedBy=default.target | The generator connects to start from the user manager’s default target. |
Before reading a new source, check the generator output in the restricted directory and perform daemon-reload. --dryrun is a feature to view the generated contents and does not start the container.
QUADLET_UNIT_DIRS="$qdir" /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
systemctl --user daemon-reload
systemctl --user cat lf-web28.service
systemctl --user show lf-web28.service -p FragmentPath -p SourcePath
On this VM, the SourcePath was lf-web28.container in the home directory, and the FragmentPath was /run/user/1000/systemd/generator/lf-web28.service. The generated file included Podman run/cleanup commands and the image digest. If the service does not exist, check the source path, file extension, supported keys, and generator errors, and do not manually create and overwrite the generated file.
Enable linger, Start the Service and Check HTTP
Enabling linger starts this account’s user manager at boot and keeps it available after logout. As the Debian loginctl manual explains, this affects the user manager, rather than just this single service. In the recorded lab, linger was initially no and was changed to yes only for verification.
sudo loginctl enable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger
systemctl --user start lf-web28.service
systemctl --user is-active lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/
podman port lf-web28
The expected response is LF QUADLET 28. 'active' means that the generated service is active, and it does not equate to HTTP being ready. In verification, one request immediately after start failed with "Empty reply from server" but succeeded after it was ready. Do not attribute all failures to a readiness delay; try the request again shortly after, and if it continues to fail, check the following logs and the status of ports and volumes.
systemctl --user status lf-web28.service --no-pager
journalctl --user -u lf-web28.service -n 50 --no-pager
podman logs lf-web28
podman inspect lf-web28
Compare Failure Restarts with an Explicit Stop
The following comparison is limited to dedicated practice containers that provide only static files. Do not apply forced termination tests as-is to actual write services such as databases. First, record the container ID and restart count, then send a KILL signal to produce a failure termination.
first=$(podman inspect lf-web28 --format '{{.Id}}')
systemctl --user show lf-web28.service -p NRestarts
podman kill --signal KILL lf-web28
sleep 3
systemctl --user is-active lf-web28.service
systemctl --user show lf-web28.service -p NRestarts
podman inspect lf-web28 --format '{{.Id}}'
curl --noproxy '*' -fsS http://127.0.0.1:8080/
In verification, NRestarts increased, the container ID changed, and HTTP responses succeeded again. The 3 seconds is an example to start the check and does not guarantee recovery time in all environments. If repeated failures hit the limit, correct the cause found in the journal, then reset-failed and restart only the affected service. Restart counts can be reset by administrator restarts and are not used as-is for long-term failure statistics.
Now explicitly request a stop in systemd. Having Restart=on-failure does not mean the service will restart automatically after an administrator stop request. The conditions of the policy follow systemd service restart explanation.
systemctl --user stop lf-web28.service
sleep 3
if systemctl --user is-active --quiet lf-web28.service; then
echo "The explicitly stopped service is still active." >&2
exit 1
fi
systemctl --user show lf-web28.service -p ActiveState
podman ps -a --filter name=lf-web28
systemctl --user start lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/
After stopping, the result was inactive and the dedicated container was also removed. The example stops with an error if it remains active, and if it stops normally, it checks ActiveState=inactive before restarting. If a response is not ready immediately after starting, check the status and logs as described in the previous section and retry the request. Volumes remain independently of container removal.
Verify Startup Before Login and Persistence After Logout
After rebooting, SSH in with the same user, and the service being active alone does not prove automatic start prior to login. This is because user-managed services could start during the login process. In this tutorial, a read-only HTTP probe as root, which does not depend on user services, was scheduled to record responses and session lists at times when no login session exists.
To verify in the same way, after confirming that all the dedicated paths below do not exist, a root management probe can be prepared. It does not modify existing timers or logs on other servers. Even if the code runs as root, it performs HTTP GET and session queries and writes its own root-only evidence log; it does not add dependencies such as user@1000.service.
for p in /var/backups/lf-debian13-28 /usr/local/sbin/lf-boot28-probe /etc/systemd/system/lf-boot28-probe.service /etc/systemd/system/lf-boot28-probe.timer; do
if test -e "$p"; then echo "Already exists: $p" >&2; exit 1; fi
done
sudo install -d -m 700 /var/backups/lf-debian13-28
sudo tee /usr/local/sbin/lf-boot28-probe > /dev/null <<'PROBE'
#!/bin/bash
set -euo pipefail
label=${1:-boot}
case "$label" in boot|logout) ;; *) exit 1;; esac
dest="/var/backups/lf-debian13-28/$label-$(cat /proc/sys/kernel/random/boot_id).txt"
{
date -u --iso-8601=seconds
cat /proc/uptime
loginctl list-sessions --no-legend
for i in $(seq 1 15); do
if curl --noproxy '*' --max-time 2 -fsS http://127.0.0.1:8080/ | grep -Fx 'LF QUADLET 28'; then echo HTTP_PROBE_PASSED; exit 0; fi
sleep 1
done
exit 1
} > "$dest" 2>&1
PROBE
sudo chmod 700 /usr/local/sbin/lf-boot28-probe
sudo tee /etc/systemd/system/lf-boot28-probe.service > /dev/null <<'UNIT'
[Unit]
Description=Read-only HTTP evidence before user login for lab 28
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/lf-boot28-probe boot
UNIT
sudo tee /etc/systemd/system/lf-boot28-probe.timer > /dev/null <<'TIMER'
[Unit]
Description=One boot HTTP evidence for lab 28
[Timer]
OnBootSec=35s
AccuracySec=1s
Unit=lf-boot28-probe.service
[Install]
WantedBy=timers.target
TIMER
sudo systemctl daemon-reload
sudo systemctl enable lf-boot28-probe.timer
First, test whether it is maintained after logout. If the scheduling below succeeds, log out of all interactive sessions for the target user, wait at least 70 seconds, then log in again to read the recorded data. Keeping the session open immediately after scheduling is not a logout verification. If a transient unit with the same name remains, check the existing state and avoid duplicate execution.
sudo systemd-run --unit=lf-logout28-probe --on-active=15s --timer-property=AccuracySec=1s /usr/local/sbin/lf-boot28-probe logout
The probe records the session list before its retry loop, so that list alone is insufficient if you log in while it is still retrying. After reconnecting, inspect sudo journalctl -b -u lf-logout28-probe.service --no-pager and compare the successful job completion time with the login time shown by loginctl session-status. Use the equivalent journal query for lf-boot28-probe.service after reboot. Accept evidence only if the probe succeeded and finished before the target user logged in. Account for time-zone offsets when comparing the UTC file timestamp with journal/session times. The 70/90-second waits allow for the probe’s bounded retries under ordinary load; elapsed time alone is not proof.
After logging in again, check the probe's time, session list, and HTTP_PROBE_PASSED using the following command. Distinguish between the manager class user manager session and the actual login session of the user class. If there was another user session running at the time the probe was executed, it is not used as evidence for maintaining the session after logout.
sudo cat "/var/backups/lf-debian13-28/logout-$(cat /proc/sys/kernel/random/boot_id).txt"
sudo systemctl show lf-logout28-probe.service -p Result -p ExecMainStatus
The following are the steps to normally reboot the VM after checking console access and the impact on other services in operation. Write down the boot ID before starting, and after rebooting, keep that user logged out for at least 90 seconds. Accessing before the timer runs can confuse the results, so compare the recorded time with the actual login time as well.
cat /proc/sys/kernel/random/boot_id
sudo systemctl reboot
After logging in again, check whether the new boot ID is different from the previous one, and read the records for that boot. If there is no log or if it failed, it is not treated as an auto-start success.
cat /proc/sys/kernel/random/boot_id
sudo cat "/var/backups/lf-debian13-28/boot-$(cat /proc/sys/kernel/random/boot_id).txt"
systemctl --user is-active lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/
On the verification VM, HTTP succeeded at around 46 seconds after the new boot when only the manager session existed and the state was lingering. A separate logout test also succeeded when there was no actual user session. The initial probe scheduled with the default timer accuracy was not used as evidence because it overlapped with the verification re-login, and it was rechecked specifying AccuracySec=1s. The criterion is whether results remained before login rather than the exact execution time.
Remove the Source and Volume, Then Restore linger
Stopping will halt the current execution, but if the original with [Install] remains, it can come back on the next user manager start. To remove the practice setup, delete the corresponding original and run daemon-reload to clean up the generated links. The first block below should be run as a regular user.
systemctl --user stop lf-web28.service
rm -- "$HOME/.config/containers/systemd/lf-web28.container"
systemctl --user daemon-reload
podman ps -a --filter name=lf-web28
podman volume rm lf-web28-data
Deleting volumes means deleting data, so first save any necessary content. Then, remove only the practice system timers and scripts. Evidence records can be left in a root-only backup path.
sudo systemctl disable --now lf-boot28-probe.timer
sudo rm -- /etc/systemd/system/lf-boot28-probe.timer /etc/systemd/system/lf-boot28-probe.service /usr/local/sbin/lf-boot28-probe
sudo systemctl daemon-reload
original_linger=$(cat "$HOME/lf-course28-linger-before.txt")
case "$original_linger" in
no) sudo loginctl disable-linger "$(id -un)" ;;
yes) echo "Preserving the original enabled linger state." ;;
*) echo "Cannot determine the original linger value." >&2; exit 1 ;;
esac
loginctl show-user "$(id -un)" -p Linger
ss -ltn
In the actual cleanup, the dedicated original, created services, containers, volumes, and probes were removed, the 8080 listener was closed, and linger returned to its original 'no' setting. Existing images and other services were preserved. When deciding whether to continue running regular user services, manage account lifetimes, data retention, and update and restore procedures together.




