Rocky Linux 10 Tutorial / Run rootless Podman services with Quadlet

To operate Podman containers as a service on Rocky Linux 10, you can declare run conditions in a Quadlet file and let systemd manage starting, stopping, and restarting. For automatic startup of regular user containers at boot, you need to check the Quadlet's target for starting and the linger setting that maintains the user manager even without logging in.

Relationship between Quadlet and user services

Quadlet is a Podman feature that describes container conditions such as images, ports, and volumes in a file. systemd's generator reads this file to create a regular service file, and then it is managed by systemctl. Beyond recording long podman run commands, it can manage the service's restart policy and start target together.

The source lab used regular user lfstudent on Rocky Linux 10.2 with Podman 5.8.2, systemd 257, cgroups v2 resource management and SELinux Enforcing. Reuse the official Nginx image verified in the rootless Podman lesson and local content, publishing only on 127.0.0.1:18028. This Quadlet runs as a user service; distinguish its commands from sudo systemctl commands that manage system services.

podman version
podman info --format '{{.Host.Security.Rootless}}'
podman info --format '{{.Host.CgroupsVersion}}'
systemctl --user list-unit-files
podman ps -a
ss -lnt 'sport = :18028'
loginctl show-user "$(id -un)" -p Linger

The rootless value should be true, and cgroups should be v2. If there are existing services, containers, or materials with the same name, do not overwrite them with new settings but check them first. The existing linger of this VM was no, and for the practice, it was changed to yes for that user only, and restored at the end.

Confirm the supported options according to the installed version. Podman 5.8 series Quadlet documentation explains the user search path, creation method, and the correspondence of each setting. Do not assume that new options in the latest documentation are supported in packages for previous distributions.

After checking the user services managed by this account, set linger only for the respective user. This is not an option for a single container but affects the lifespan of the user manager for that account. Accounts that were previously set to yes are not arbitrarily changed to no at the end of the practice.

sudo loginctl enable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger

The loginctl manual explains that linger is a feature that starts the user manager at boot and keeps it active even after logout.

Document path and preparation of the complete Quadlet file

The following is executed in a normal user shell. The data directory lf-course28 is newly created, reusing the image references recorded in Lesson 27. If Lesson 27 was not performed, you need to download the official image and check the source and digest to prepare the same reference file first.

LAB28="$HOME/lf-course28"
test ! -e "$LAB28" || { printf 'Inspect the existing lab directory and stop.\n' >&2; exit 1; }
mkdir -m 0755 "$LAB28"
mkdir -m 0755 "$LAB28/site"
printf 'LF28 Quadlet service works\n' > "$LAB28/site/index.html"
chmod 0644 "$LAB28/site/index.html"
mkdir -p "$HOME/.config/containers/systemd"
cat "$HOME/lf-course27/image.ref"

Save the following complete content in ~/.config/containers/systemd/lf-course28.container. The home path here is the actual practice user's path. If executing with another account, modify the source path of the Volume to match that account and specify the image reference with the value you have confirmed.

test ! -e "$HOME/.config/containers/systemd/lf-course28.container" || { printf 'Inspect the existing Quadlet file and stop.\n' >&2; exit 1; }
cat > "$HOME/.config/containers/systemd/lf-course28.container" <<'EOF'
[Unit]
Description=Course28 rootless web service
[Container]
Image=docker.io/library/nginx@sha256:583b7f2fce1cdb8da5ad5c39ebd3c33b98b87d493190e548bdee1fa8c619c311
ContainerName=lf-course28-web
Label=lf.course=28
PublishPort=127.0.0.1:18028:80
Volume=/home/lfstudent/lf-course28/site:/usr/share/nginx/html:ro,Z
Pull=never
[Service]
Restart=on-failure
RestartSec=2
TimeoutStartSec=90
[Install]
WantedBy=default.target
EOF
Section · Settings Role in this service
[Container] These are the Podman execution requirements such as image, name, port, and mount.
Pull=never It uses a locally saved image that has already been checked. If it is not in the cache, the start will fail, so prepare it in advance.
Volume=…:ro,Z Provide new dedicated documents in read-only mode and apply SELinux context suitable for the container.
Restart=on-failure Restart the service when it terminates abnormally. This is distinguished from an explicit stop.
WantedBy=default.target Link the service to the default startup target of the user manager.

Since this is not a configuration that automatically tracks temporary tags of the image, updating involves reviewing the new digest, changing the file, and then verifying it again. Only new dedicated paths are used for mounts, and do not mount or relabel the entire home directory.

Service creation, execution, and actual HTTP verification.

systemctl --user daemon-reload
systemctl --user cat lf-course28.service
systemctl --user start lf-course28.service
systemctl --user show lf-course28.service -p ActiveState -p SubState -p FragmentPath -p UnitFileState -p NRestarts
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/
journalctl --user -u lf-course28.service -b -n 30 --no-pager

The actually created service was in /run/user/1000/systemd/generator/lf-course28.service, and its status was generated. The created file contained container execution commands and stop/cleanup commands. Do not edit this file directly; modify the original .container file and recreate it by running daemon-reload.

This service was active/running and returned LF28 Quadlet service works. The default type of the created service is notify, and the container monitoring program conmon signals its start, but this alone is not considered enough to determine that the web application responds correctly. The actual HTTP response and the expected content are checked separately. A connection reset was observed once immediately after startup, so limited retries were used.

The method of applying systemctl --user enable lf-course28.service to the created service like a normal file is not used. The Quadlet generator handles the [Install] settings from the original file. Conditions under which the user manager itself starts at boot need to be checked separately.

Compare abnormal termination with an explicit stop.

The test targets only the container created in this tutorial. The container ID and the number of restarts are recorded before startup, and abnormal termination is reproduced using the SIGKILL signal, which is a forced termination. The same command is not applied directly to production services.

podman inspect lf-course28-web --format '{{.Id}}'
systemctl --user show lf-course28.service -p NRestarts
podman kill --signal KILL lf-course28-web
systemctl --user show lf-course28.service -p ActiveState -p SubState -p NRestarts
podman inspect lf-course28-web --format '{{.Id}}'
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/

In the source lab, the container ID changed from 01951ad831a1… to 610769498aeb…, the service counter became NRestarts=1, and a separate HTTP request returned the expected content. Immediately after stopping, queries may fail due to waiting for a restart or container replacement, so compare the results together with service logs and status after stabilization. This setting not only preserves processes within the same container but also allows creating a new container under the generated execution conditions.

systemctl --user stop lf-course28.service
systemctl --user is-active lf-course28.service
podman container exists lf-course28-web
systemctl --user start lf-course28.service

After explicitly stopping, it was inactive, and the container existence check returned exit code 1. Even after 3 seconds, it was not automatically recreated, and it responded again after manually starting. During service operation, management is based on systemd's policies and status rather than redundantly applying a separate restart policy to Podman. systemd.service document explains the behavior of Restart conditions and manual stops.

Verify persistence after logout and startup before login

Start the service, end the SSH session and reconnect without issuing another start command. In the source lab, HTTP still worked at 02:32:48 with the service start time unchanged at 02:30:56. Comparing start times helps distinguish persistence from a service newly started by the next login.

systemctl --user show lf-course28.service -p ActiveState -p ActiveEnterTimestamp -p ActiveEnterTimestampMonotonic
loginctl show-user "$(id -un)" -p Linger
curl -fsS http://127.0.0.1:18028/
cat /proc/sys/kernel/random/boot_id
sha256sum "$HOME/lf-course28/site/index.html"
sudo systemctl reboot

Rebooting will disconnect the SSH connection. Perform this only on a dedicated practice VM where console access is available, and after reconnecting, check the new boot ID and status before manually starting the service. The following command is a query to compare whether the service started before the first login.

cat /proc/sys/kernel/random/boot_id
systemctl --user show lf-course28.service -p ActiveState -p SubState -p ActiveEnterTimestampMonotonic -p UnitFileState
loginctl show-session "$XDG_SESSION_ID" -p TimestampMonotonic
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/
sha256sum "$HOME/lf-course28/site/index.html"
journalctl --user -u lf-course28.service -b -n 30 --no-pager

In the source verification, the boot ID had changed and the service was active/running. The service activation timestamp, measured in microseconds since that boot, was 319329250 microseconds, and the start of the first SSH session was 361617018 microseconds. Comparing within the same boot shows that the service started about 42 seconds before login. The document and Quadlet file hashes were the same, and the HTTP body was preserved.

The reboot of this VM took a total of about 5 minutes 22 seconds, including approximately 4 minutes 57 seconds in the kernel phase, and cbc-aes-aesni self-check left rc=-110 warnings. The first SSH attempt during the boot delay failed, and verification was performed after confirming console responses and that the system was ready for connection. Quadlet auto-start was confirmed, but this result should not be interpreted as an environment that passed the encryption self-check normally. Do not mix the cause of the boot delay with the service auto-start settings.

Distinction between services that are not created and services that fail to start

Unit not found The creation may have failed before the container execution. First, check the file extension .container, the user search path, the section name, and the keys supported by the installed version. If there is a created file but execution fails, check the image cache, mount source, ports, and application logs.

QUADLET_UNIT_DIRS="$HOME/.config/containers/systemd" /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
systemctl --user cat lf-course28.service
systemctl --user status lf-course28.service --no-pager
journalctl --user -u lf-course28.service -b -n 40 --no-pager
podman ps -a

The source lab placed an incorrect NotARealKey in a separate test folder outside the actual search path and only performed a generator dry-run. The generator returned exit code 1 and unsupported key and did not create the execution command. The dry-run limited to normal sources had exit code 0, and the service remained active during execution. You can diagnose syntax in a separate path without deliberately corrupting operational files.

After changing the original settings, daemon-reload is the task of rereading the service definition. To recreate an already running container with the new settings, you need to perform systemctl --user restart lf-course28.service considering the necessary downtime and recheck status, actual response, and data. Any incorrect modifications should be reverted to the stored original and reverified in the same order.

Disabling auto-start and cleaning up practice.

When removing the practice setup, first stop the user service. After moving the original Quadlet outside the search path and performing daemon-reload, the generated files and startup target connections are also cleaned up. If it is a service that will continue to operate, do not execute this cleanup command.

systemctl --user stop lf-course28.service
mv "$HOME/.config/containers/systemd/lf-course28.container" "$HOME/lf-course28/lf-course28.container.saved"
systemctl --user daemon-reload
systemctl --user show lf-course28.service -p LoadState
podman container exists lf-course28-web
restorecon -RFv "$HOME/lf-course28/site"
ss -lnt 'sport = :18028' 

The source cleanup result was LoadState=not-found, container existence check exit code 1, and an empty listener list numbered 18028. Documents were left intact, and the SELinux context of the dedicated path that had finished use was reverted to the general home file context. Only empty configuration directories that did not exist before the practice were removed, and the original user settings were maintained.

sudo loginctl disable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger

The above linger release was originally set to no and applies only to this practice account where other long-running user services are not needed. After cleanup in the source lab, it was restored to no, and existing SSH, firewall, Nginx, hosts, fstab, user ID mapping, and SELinux local settings were preserved. Service definitions and materials remain in the dedicated record directory for restoration and review.