Managing Podman Containers with Systemd - Traditional Methods vs. Quadlet#

Efficiently managing containers in production environments requires reliable automation and integration with the host system’s service management. For Linux systems using systemd, there are two primary approaches to running Podman containers as services: the traditional systemd service file approach and the newer, more declarative Quadlet method. This comprehensive guide explores both approaches, helping you choose the right strategy for your container management needs.

Understanding Container Management with Systemd#

Systemd’s unit file system provides a powerful framework for service management, offering features like dependency handling, automatic restarts, and parallel execution. When combined with Podman’s daemonless container engine, it creates a robust solution for running containers that:

Start automatically at boot time
Restart on failure
Manage dependencies between services
Provide logging through journald
Allow for fine-grained resource control
Support for rootless containers

1
graph TD
2
    A[Systemd Service Management] --> B[Container Runtime]
3
    B --> C[Podman]
4

5
    C --> D["Traditional Approach<br>(podman generate systemd)"]
6
    C --> E["Quadlet Approach<br>(declarative .container files)"]
7

8
    D --> F[Manual Service Files]
9
    E --> G[Automatic Service Generation]
10

11
    F --> H[systemctl operations]
12
    G --> H
13

14
    H --> I[Container Lifecycle Management]

Traditional Approach: Podman with Custom Systemd Service Files#

The traditional approach involves creating a systemd service file that defines how your container should run. This method gives you direct control over the service configuration.

Step 1: Creating Your Container#

First, define the container you want to run:

1
podman run -d \
2
  --name ubuntu-service \
3
  --restart=always \
4
  ubuntu:latest \
5
  tail -f /dev/null

Step 2: Creating the Systemd Service File#

Create a systemd service file in your user’s systemd directory for rootless containers:

1
mkdir -p ~/.config/systemd/user/

Then create a service file with detailed container specifications:

1
vi ~/.config/systemd/user/ubuntu-service.service

1
[Unit]
2
Description=Ubuntu Service Container
3
Wants=network-online.target
4
After=network-online.target
5
RequiresMountsFor=%t/containers
6

7
[Service]
8
Environment=PODMAN_SYSTEMD_UNIT=%n
9
Restart=on-failure
10
TimeoutStopSec=70
11
ExecStartPre=/bin/rm -f %t/%n.ctr-id
12
ExecStart=/usr/bin/podman run \
13
    --cidfile=%t/%n.ctr-id \
14
    --cgroups=no-conmon \
15
    --rm \
16
    --sdnotify=conmon \
17
    --replace \
18
    --name ubuntu-service \
19
    ubuntu:latest \
20
    tail -f /dev/null
21
ExecStop=/usr/bin/podman stop --ignore --cidfile=%t/%n.ctr-id
22
ExecStopPost=/usr/bin/podman rm -f --ignore --cidfile=%t/%n.ctr-id
23
Type=notify
24
NotifyAccess=all
25

26
[Install]
27
WantedBy=default.target

Step 3: Enabling and Starting the Service#

1
# Reload systemd to recognize the new service
2
systemctl --user daemon-reload
3

4
# Enable the service to start on boot
5
systemctl --user enable ubuntu-service
6

7
# Start the service
8
systemctl --user start ubuntu-service
9

10
# Enable lingering for your user (allows services to run without login)
11
loginctl enable-linger $USER

Step 4: Managing Your Service#

1
# Check service status
2
systemctl --user status ubuntu-service
3

4
# View logs
5
journalctl --user -u ubuntu-service
6

7
# Stop the service
8
systemctl --user stop ubuntu-service
9

10
# Restart the service
11
systemctl --user restart ubuntu-service

Generating Service Files Automatically#

Podman can generate systemd service files for existing containers:

1
# Create a container first
2
podman run -d --name webapp nginx:latest
3

4
# Generate a systemd service file
5
podman generate systemd --name webapp > webapp.service

Modern Approach: Podman with Quadlet#

Quadlet is a newer approach that allows you to define container services declaratively through simple configuration files. It’s now built into Podman (since version 4.0) and serves as a more elegant solution for container service management.

Step 1: Creating the Directory Structure#

For user services (rootless):

1
mkdir -p ~/.config/containers/systemd/

For system services (root):

1
sudo mkdir -p /etc/containers/systemd/

Step 2: Creating the Quadlet Container File#

Create a file with the .container extension:

1
vi ~/.config/containers/systemd/ubuntu-service.container

1
[Unit]
2
Description=Ubuntu Service Container
3
After=network-online.target
4

5
[Container]
6
Image=docker.io/library/ubuntu:latest
7
# Keep container running
8
Exec=tail -f /dev/null
9

10
# Resource limits (optional)
11
Memory=1G
12
CPUQuota=100%
13

14
# Environment variables (optional)
15
Environment=MY_VAR=value
16

17
# Volume mounts (optional)
18
Volume=/path/on/host:/path/in/container:Z
19

20
[Service]
21
Restart=always
22
TimeoutStartSec=900
23

24
[Install]
25
WantedBy=default.target

Step 3: Enabling and Starting the Service#

1
# Reload systemd to detect the new container configuration
2
systemctl --user daemon-reload
3

4
# Enable and start the service
5
systemctl --user enable --now container-ubuntu-service

Step 4: Managing Your Service#

1
# Check service status
2
systemctl --user status container-ubuntu-service
3

4
# View logs
5
journalctl --user -u container-ubuntu-service
6

7
# Restart the service
8
systemctl --user restart container-ubuntu-service

Comparison: Traditional vs. Quadlet Approach#

Let’s compare these two approaches across various dimensions:

Feature	Traditional Approach	Quadlet Approach
Configuration Style	Imperative (full service file)	Declarative (focused on container parameters)
Maintenance	Manual updates required when container changes	Automatic service generation
Complexity	More complex service files	Simplified configuration
Control	Fine-grained control over all aspects	Container-focused with reasonable defaults
Integration	Manual integration with systemd	Built-in integration
Updates	May need regeneration after Podman updates	Handles Podman updates transparently
Storage	Lives in systemd directories	Lives in container configuration directories
Features	All systemd features available	Most common container features pre-configured
Learning Curve	Steeper (requires systemd knowledge)	Gentler (focuses on container parameters)

Advanced Quadlet Features#

Quadlet supports more than just containers. It has several specialized file types for different container resources:

Volume Management#

Create a persistent named volume with a .volume file:

1
[Volume]
2
Driver=local
3
Device=tmpfs
4
UID=1000
5
GID=1000

Network Configuration#

Define a custom network with a .network file:

1
[Network]
2
Driver=bridge
3
Subnet=192.168.100.0/24
4
Gateway=192.168.100.1
5
IPRange=192.168.100.0/24

Pod Management#

Create a pod with multiple containers using a .pod file:

1
[Pod]
2
Name=web-app
3

4
[Container]
5
Name=web
6
Image=nginx:latest
7
Volume=/var/www/html:/usr/share/nginx/html:ro,Z
8

9
[Container]
10
Name=redis
11
Image=redis:alpine

Kubernetes-Style Deployments#

Deploy applications defined in Kubernetes YAML with a .kube file:

1
[Unit]
2
Description=Kubernetes-style Deployment
3

4
[Kube]
5
Yaml=./deployment.yaml

Practical Examples#

Example 1: Web Server with Persistent Storage#

Here’s how to create a NGINX web server with persistent storage using Quadlet:

1
[Unit]
2
Description=NGINX Web Server
3
After=network-online.target
4

5
[Container]
6
Image=docker.io/library/nginx:latest
7
PublishPort=8080:80
8
Volume=web-data:/usr/share/nginx/html:Z
9

10
[Service]
11
Restart=always
12

13
[Install]
14
WantedBy=default.target

1
[Volume]
2
Driver=local

Example 2: Database Server with Resource Limits#

1
[Unit]
2
Description=PostgreSQL Database
3
After=network-online.target
4

5
[Container]
6
Image=docker.io/library/postgres:14
7
Environment=POSTGRES_PASSWORD=secret
8
Environment=POSTGRES_USER=myapp
9
Environment=POSTGRES_DB=myapp_db
10
Volume=postgres-data:/var/lib/postgresql/data:Z
11
PublishPort=5432:5432
12
Memory=2G
13
CPUQuota=200%
14

15
[Service]
16
Restart=always
17
TimeoutStartSec=120
18

19
[Install]
20
WantedBy=default.target

1
[Volume]
2
Driver=local

Example 3: Multi-Container Application with a Network#

1
[Network]
2
Driver=bridge

1
[Unit]
2
Description=Web Application
3
After=network-online.target
4
After=container-redis-cache.service
5
Requires=container-redis-cache.service
6

7
[Container]
8
Image=docker.io/myapp:latest
9
PublishPort=8080:80
10
Network=app-network
11
Environment=REDIS_HOST=redis-cache
12
Environment=REDIS_PORT=6379
13

14
[Service]
15
Restart=always
16

17
[Install]
18
WantedBy=default.target

1
[Unit]
2
Description=Redis Cache
3
After=network-online.target
4

5
[Container]
6
Image=docker.io/library/redis:alpine
7
Network=app-network
8
AddHost=redis-cache:127.0.0.1
9

10
[Service]
11
Restart=always
12

13
[Install]
14
WantedBy=default.target

Best Practices#

Security Considerations#

Use rootless containers when possible:
```
1
[Container]
2
User=1000:1000
```

Apply SELinux labels to volumes:

1
[Container]
2
Volume=/path/on/host:/path/in/container:Z

Limit container capabilities:

1
[Container]
2
DropCapability=ALL
3
AddCapability=NET_BIND_SERVICE

Resource Management#

Set memory limits to prevent OOM issues:
```
1
[Container]
2
Memory=1G
3
MemorySwap=2G
```

Configure CPU constraints:

1
[Container]
2
CPUShares=1024
3
CPUQuota=50%

Service Dependencies#

Ensure network is available:

1
[Unit]
2
After=network-online.target
3
Wants=network-online.target

Create service dependencies:

1
[Unit]
2
After=container-database.service
3
Requires=container-database.service

Observability#

Configure healthchecks:

1
[Container]
2
HealthCmd=/bin/sh -c "wget -q --spider http://localhost:8080 || exit 1"
3
HealthInterval=30s
4
HealthTimeout=10s
5
HealthStartPeriod=5s
6
HealthRetries=3

Migrating from Traditional to Quadlet#

If you’re currently using traditional systemd service files for Podman containers, here’s how to migrate to Quadlet:

Step 1: Identify Current Container Parameters#

Extract the container run parameters from your existing service file:

1
# From a traditional service file like this:
2
ExecStart=/usr/bin/podman run \
3
    --name webapp \
4
    -v /data:/app/data:Z \
5
    -p 8080:80 \
6
    -e DATABASE_URL=postgres://user:pass@db/mydb \
7
    nginx:latest

Step 2: Create an Equivalent Quadlet File#

1
[Unit]
2
Description=Web Application
3

4
[Container]
5
Image=nginx:latest
6
Volume=/data:/app/data:Z
7
PublishPort=8080:80
8
Environment=DATABASE_URL=postgres://user:pass@db/mydb
9

10
[Service]
11
Restart=always
12

13
[Install]
14
WantedBy=default.target

Step 3: Test and Switch Over#

1
# Stop and disable the old service
2
systemctl --user stop webapp
3
systemctl --user disable webapp
4

5
# Enable and start the new Quadlet-based service
6
systemctl --user daemon-reload
7
systemctl --user enable --now container-webapp

Troubleshooting#

Service Won’t Start#

If your Quadlet-managed container won’t start, check these common issues:

Permission problems:

1
# Check journalctl for permission errors
2
journalctl --user -u container-webapp -n 50

Image not found:

1
# Pull the image manually to verify access
2
podman pull nginx:latest

Port conflicts:

1
# Check if ports are already in use
2
ss -tulpn | grep 8080

Container Crashes#

If your container starts but then crashes:

Check container logs:

1
# Look at the container logs directly
2
podman logs $(podman ps -a --filter name=webapp --format "{{.ID}}")

View systemd journal:

1
# Examine journal logs
2
journalctl --user -u container-webapp -f

Increase debug output:

1
# Add debug output to your container file
2
[Service]
3
Environment=PODMAN_LOG_LEVEL=debug

Resource Constraints#

If your container is hitting resource limits:

Check container resource usage:
Terminal window
```
1
podman stats
```

Adjust limits in your Quadlet file:

1
[Container]
2
Memory=2G  # Increase from previous value
3
CPUQuota=200%  # Allow use of 2 full CPUs

Conclusion#

Both the traditional method and Quadlet approach offer effective ways to integrate Podman containers with systemd, but they serve different needs:

Traditional Approach: Offers maximum flexibility and control but requires more maintenance and deeper systemd knowledge
Quadlet Approach: Provides a simpler, more declarative method that’s easier to maintain and more focused on container-specific parameters

For most users, especially those building new container deployments, Quadlet represents the future of Podman-systemd integration with its simplified syntax, automatic service generation, and built-in support for complex container resources like pods and networks. The traditional approach remains valuable for users who need very specific systemd configurations or who are maintaining existing deployments.

Whether you choose the traditional method or Quadlet, integrating your containers with systemd brings considerable benefits in terms of reliability, lifecycle management, and integration with the host system—making your containerized applications easier to manage and more resilient in production environments.

Managing Podman Containers with Systemd - Traditional Methods vs. Quadlet#

Understanding Container Management with Systemd#

Traditional Approach: Podman with Custom Systemd Service Files#

Step 1: Creating Your Container#

Step 2: Creating the Systemd Service File#

Step 3: Enabling and Starting the Service#

Step 4: Managing Your Service#

Generating Service Files Automatically#

Modern Approach: Podman with Quadlet#

Step 1: Creating the Directory Structure#

Step 2: Creating the Quadlet Container File#

Step 3: Enabling and Starting the Service#

Step 4: Managing Your Service#

Comparison: Traditional vs. Quadlet Approach#

Advanced Quadlet Features#

Volume Management#

Network Configuration#

Pod Management#

Kubernetes-Style Deployments#

Practical Examples#

Example 1: Web Server with Persistent Storage#

Example 2: Database Server with Resource Limits#

Example 3: Multi-Container Application with a Network#

Best Practices#

Security Considerations#

Resource Management#

Service Dependencies#

Observability#

Migrating from Traditional to Quadlet#

Step 1: Identify Current Container Parameters#

Step 2: Create an Equivalent Quadlet File#

Step 3: Test and Switch Over#

Troubleshooting#

Service Won’t Start#

Container Crashes#

Resource Constraints#

Conclusion#

Resources#