9 Podman Quadlets

Create Podman Quadlets to easily generate and manage systemd services for containers, pods, and other Podman objects.

Instead of generating a Podman service wrapper by using the podman generate systemd command and then maintaining all the systemd unit files individually, you can maintain a single Podman Quadlet and rely on the podman-systemd daemon to regenerate those systemd unit files for you whenever they're needed.

The other practical benefit of using a Quadlet is that when a new version of Podman is released, you can roll out fixes and enhancements to any templated systemd unit files by reinitializing the affected services.

Quadlets are managed by using a unit file with and appropriate file extension (.container, .volume, .network, .build, .pod, or .kube). It must also include a Podman section (for example, [Container]). For example, a Quadlet for a container might include: 

[Unit]
Description=your-description
After=local-fs.target

[Container]
Image=container_image
Exec=your-command-here

[Install]
# Start by default on boot
WantedBy=multi-user.target default.target

Creating Quadlets

Create Podman Quadlets that run containers, pods, volumes, and other Podman objects, using a systemd unit file, either for the root user, or for a user with standard permissions.

A system administrator can create Quadlets that run with root permissions. The Quadlet files use the file extensions .container, .volume, .network, .build, .pod and .kube. Save the Quadlet files in /usr/share/containers/systemd/ or /etc/containers/systemd/.

Note:

On Oracle Linux 8 hosts, Quadlets can only be run with root permissions. For more information, see Quadlets Fail For An Unprivileged User.

Quadlet files (with the file extensions of .container, .volume, .network, .build, .pod and .kube) can be created in the following locations, depending on the level of privilege for the Quadlet:

  • A system administrator can create a Quadlet that runs with root permissions in:

    /run/containers/systemd/ (temporary Quadlet location used for testing)

    /etc/containers/systemd/ (system administrator defined Quadlets)

    /usr/share/containers/systemd/ (distribution defined Quadlets)

  • A system administrator can create rootless Quadlets that run when any user connects to the system in:

    /etc/containers/systemd/users/

  • A system administrator can create rootless Quadlets that run when a user with a specific user ID connects to the system in:

    /etc/containers/systemd/users/$USERID

  • A user can create Quadlets in:

    $HOME/.config/containers/systemd/

A list of all the options that can be included in a Quadlet file are available in the upstream Podman documentation, or the podman-systemd.unit(5) manual page.

The Quadlet files are used to generated systemd unit files (with a .service extension). Podman generates a unit file for each Quadlet file. The unit files can be managed like any other systemd service using the systemctl command. Each Quadlet file has a custom section for Podman objects (for example, [Container]) that's handled by Podman, and all other sections are standard systemd options and are passed on untouched. This means you can use standard systemd configuration in Quadlet file, including drop in files.

Tip:

When a Quadlet starts a systemd service, any included containers are started. When a container is first started, Podman pulls the container images. To avoid any timeouts, it might be helpful to pull the container images before you start the systemd service created by a Quadlet. Or, you can increase the service startup timeout using the TimeoutStartSec option in the [Service] section of Quadlet files.

Quadlets require cgroup v2. To see if the system provides this, use:

podman info --format {{.Host.CgroupsVersion}}

Note:

To learn how to enable cgroups v2 on Oracle Linux 8 hosts, see Run Control Group Version 2 on Oracle Linux.

Example 9-1 Create a Quadlet for a container

  1. Create a unit file with the .container file extension. Save it to the appropriate location for the level of required user access. For example: 

    [Unit]
Description=My First Quadlet

[Container]
Image=container-registry.oracle.com/os/oraclelinux:9-slim
AutoUpdate=registry
Exec=sleep 60

[Service]
Restart=always
TimeoutStartSec=900

[Install]
WantedBy=multi-user.target default.target

  2. Reload the systemd services. To reload all systemd services, use: 

    sudo systemctl daemon-reload

    To reload systemd services for a standard user on an Oracle Linux 9 or Oracle Linux 10 host, use: 

    systemctl --user daemon-reload

  3. Confirm the unit files are created. To examine the unit files that have been created, you can use the -dryrun option with the quadlet command: 

    /usr/libexec/podman/quadlet -dryrun

    Add the -user option for Quadlet containers that run without root permissions. For example: 

    /usr/libexec/podman/quadlet -dryrun -user

  4. Start the systemd service. Manage the Quadlet the same way as any other systemd service using the systemctl command. For example, to start a Quadlet container called myquadlet, use: 

    sudo systemctl start myquadlet.service

    For a service without root permission, include the --user option. For example: 

    systemctl --user start myquadlet.service

  5. Confirm the systemd service is running. To confirm the service is running, use the systemctl status command. For example: 

    sudo systemctl status myquadlet.service

    For a service without root permission, include the --user option. For example: 

    systemctl --user status myquadlet.service

  6. Confirm the container is running.

    To verify the container is running, use the podman ps command. For example, for a container running in a service that has root permissions, use: 

    sudo podman ps

    Or, for a container running as a standard user:

    podman ps

  7. (Optional) Keep the service running after logout.

    If you want the systemd service to continue to run when a standard user logs out, enable lingering. For example: 

    sudo loginctl enable-linger username

  8. (Optional) Remove the service.

    To clean up after trying this example, remove the service and container using:

    systemctl stop myquadlet.service

    Or for a standard user:

    systemctl --user stop myquadlet.service

    The systemd service is stopped, which also stops the container.

Creating Quadlets With the Podman Shell

On Oracle Linux 9 and Oracle Linux 10 hosts, you can use the Podman login shell to run shell commands in a container. This feature provides the advantage of ensuring that users are kept within established boundaries while working inside containers. Users are configured to use the /usr/bin/podmansh shell instead of normal shells such as /bin/bash. The command starts the user's session in a rootless container called podmansh. This container continues to run until the user exits the session, at which point the container is removed.

Administrators configure users to use this feature through Quadlet files. These files define the parameters for users when they work in containers, such as the visibility of the host system when users are in the containers, access limitations, security privileges, and resource usage. For more information, see Podman Quadlets.

All the settings defined for the user in the Quadlet file transparently run without any need for user or administrator intervention.

The Podman login shell and other defined parameters combine to isolate the user and therefore ensures container security. The container is removed at the end of a session, and logging back in re-creates the same confined environment for the user. So, working with containers becomes more straightforward.

The following is an example of how you can configure a user to use the Podman login shell and other set parameters when working in a container. Assume that the Quadlet applies to a specific $USERID, and the Quadlet file is named podmansh.container. 

[Unit]
Description=The Podmansh container
After=local-fs.target

[Container]
Image=container-registry.oracle.com/os/oraclelinux:9-slim
ContainerName=podmansh
RemapUsers=keep-id
RunInit=yes

Exec=sleep infinity

[Install]
RequiredBy=default.target

A list of all the options that can be included in this file are available in the upstream Podman documentation, or the podman-systemd.unit(5) manual page.

Note:

Note that the name of the container (ContainerName) must be podmansh. This sets the /usr/bin/podmansh shell to run podman exec in the container.

The user with the ID that matches the Quadlet's $USERID would log in as follows: 

ssh user@systemname

More information about using the podmansh shell is available in the upstream Podman documentation, or the podmansh(1) manual page.

Quadlet Services

All systemd services created by Quadlets are managed using the systemctl command.

After you have created a systemd service for any containers, pods, or other Podman objects, you can use systemctl commands to manage those services, and therefore all the Podman objects in the services. In the same way you manage regular systemd services, you can start, restart, stop and check the service status using systemctl. Enabling services to boot automatically is a little different as services created using Quadlets are transient services. If you're running containers as a standard user on an Oracle Linux 9 or Oracle Linux 10 host, all systemctl commands must include the --user option.

Tip:

To try out using systemd services, see the Use Systemd on Oracle Linux tutorial.

Starting Services

To start a systemd service created by a Quadlet, use the systemctl start command.

Example 9-2 Start a Quadlet service

sudo systemctl start myquadlet.service

As a standard user, include the --user option. For example: 

systemctl --user start myquadlet.service

Restarting Services

Restart the service using the systemctl restart command. Restarting the service stops and re-creates all objects in the service (containers, pods, and so on).

Example 9-3 Restart a Quadlet service

sudo systemctl restart myquadlet.service

For a standard user, include the --user option. For example. 

systemctl --user restart myquadlet.service

Stopping Services

Stop a systemd service using the systemctl stop command. Stopping a service created by a Quadlet stops all objects in the service (containers, pods, and so on).

Example 9-4 Stop a Quadlet service

sudo systemctl stop myquadlet.service

To stop the service as a standard user, include the --user option. For example: 

systemctl --user stop myquadlet.service

Checking the Service Status

Check the current status of a systemd service with the systemctl status command.

Example 9-5 Check the status of a Quadlet service

sudo systemctl status myquadlet.service

To see the service status as a standard user, include the --user option. For example: 

systemctl --user status myquadlet.service

Enabling Services

Services created by Quadlets are considered transient services, and they don't have the same persistence as regular systemd services. Because of this, you can't use the systemctl enable command to set them to start when the host OS boots. Instead, the Podman generator uses the information in the [Install] section of Quadlet files when generating service unit files. For example, you can set the service to start when the OS boots by including: 

[Install]
WantedBy=default.target

If services are running as a standard user, you can enable lingering so services start automatically when the user signs in to the OS. For example:

sudo loginctl enable-linger user