Ever wanted to run a container, or pod, as a systemd service on Linux? This allows the container to be started automatically and even restarted on failure. I’m got a container running like this right now thanks to Podman which makes this incredibly easy and a bit more secure. If managing your containers as services is something you’re interested in, then this tutorial is for you.


This tutorial lays out the steps to manage a Podman container as a systemd service. A UniFi Controller container, derived from a Kubernetes YAML file, will be used as an example. Steps are provided for both rootless and root configurations. This tutorial continues the series on Podman. Previous tutorials include Podman Compose, Translate Docker Compose to Kubernetes With Podman, and Automatically Update Podman Containers. The target system is elementary OS 5.1, based on Ubuntu 18.04. You’ll need to have Podman installed, of course. To install Podman on an Ubuntu system, follow the instructions in Install Podman on Ubuntu. You are expected to be familiar with Linux containers, Podman, the command-line, the Kubernetes configuration format, {Git}, systemd, and anything else I forgot to mention…​

  1. Clone the repository with the Kubernetes YAML file for the UniFi Controller.

    ➜ git clone git@github.com:jwillikers/unifi-controller.git ~/Projects/unifi-controller
  2. Provide the generated Kubernetes YAML to podman-play-kube(1) to create and launch the pod.

    ➜ podman play kube ~/Projects/unifi-controller/unifi-controller.yml
    sudo podman play kube ~/Projects/unifi-controller/unifi-controller.yml
  3. Change into the directory where you want the systemd unit files to be placed. Below are common locations for these files.

    cd ~/.config/systemd/user
    cd /etc/systemd/system
  4. Generate the systemd service unit files using podman-generate-systemd(1). The following commands use a couple of extra options. By default, podman-generate-systemd will output the content of the units to the console. --files places the output in the appropriate files. In this particular situation, it will create a service unit file for the pod and a service unit file for the single container. The --name option will use the names of the pod and containers instead of their hash id’s. The --new option causes the pods and containers to be created each time the service starts or restarts. When running containers as systemd services, this option is required for Podman’s auto-update functionality to work. For details on auto-update, checkout Automatically Update Podman Containers. The last argument to the command is the pod’s identifier.

    ➜ podman generate systemd --files --name --new unifi-controller
    sudo podman generate systemd --files --name --new unifi-controller
  5. Enable the systemd service. For the rootless configuration, the service will start upon the user logging in. For the root configuration, the service will be activated on boot.

    ➜ systemctl --user enable --now pod-unifi-controller.service
    Created symlink /home/jordan/.config/systemd/user/multi-user.target.wants/pod-unifi-controller.service → /home/jordan/.config/systemd/user/pod-unifi-controller.service.
    Created symlink /home/jordan/.config/systemd/user/default.target.wants/pod-unifi-controller.service → /home/jordan/.config/systemd/user/pod-unifi-controller.service.
    sudo systemctl enable --now pod-unifi-controller.service
    Created symlink /etc/systemd/system/multi-user.target.wants/pod-unifi-controller.service → /etc/systemd/system/pod-unifi-controller.service.
    Created symlink /etc/systemd/system/default.target.wants/pod-unifi-controller.service → /etc/systemd/system/pod-unifi-controller.service.
  6. Access the controller’s web console at

    ➜ open
    Other shells
    ➜ xdg-open

See Also

On Red Hat’s Enable Sysadmin publication, the article Improved systemd integration with Podman 2.0 delves into Podman’s systemd and auto-update functionality.

An article on Red Hat’s Developer Blog, https://developers.redhat.com/blog/2019/04/24/how-to-run-systemd-in-a-container/How to run systemd in a container], describes how to run systemd from within containers.

Toolbox is a simplified wrapper for using Podman containers for development.


Given the simplicity of managing Podman containers as systemd services, why not use them yourself if they fit your use case?