10 Podman Service Wrappers
Podman can integrate with systemd
services to manage pods and containers as system services. By using Podman service wrappers, you can configure containers or pods to start at system boot and you can manage them similarly as other services that run on the host system.
Caution:
The method of generating systemd
unit files in this section was deprecated in Podman 4.6. Instead, use Quadlets to create systemd
services. For more information, see Podman Quadlets.
Podman provides the tools to automatically generate systemd
service wrapper configuration files for any containers or pods on the system, so that you can manage container infrastructure using systemd
. You can use the podman generate systemd
command to automatically generate systemd
unit files.
You can use systemd
user services if you're running containers as a standard user, or you can configure system level services if you're running containers as the root user.
Generating Podman Service Wrappers
Use the podman generate systemd
command to automatically generate systemd
unit files for Podman containers and pods.
Instead of writing a systemd
service wrapper from scratch, you can use the podman generate systemd
command to automatically generate the service configuration file.
If you intend to run containers as root user system services, store the container service wrapper configuration files in /etc/systemd/system/
. If you intend to run containers as a standard user, save the container service wrapper configuration files in $HOME/.config/systemd/user/
.
Example 10-1 Generate a systemd service wrapper for a container
To generate a systemd
service wrapper for an individual container, and store it in the $HOME/.config/systemd/user
directory:
podman generate systemd --name containername > $HOME/.config/systemd/user/container-containername.service
Example 10-2 Generate a systemd service wrapper for a pod
To generate a Podman service wrapper for a specific pod, use the following command:
podman generate systemd --name podname
However, to include generating service wrapper configuration files for all the containers within a pod itself, use the --file
option with the command. In this case, run the command in the directory where you intend to generate the files.
Suppose that in $HOME/.config/systemd/user
, you want to generate Podman service wrappers for both mypod
and its containers. You would run the following commands:
cd $HOME/.config/systemd/user/
podman generate systemd --files --name mypod
With this command, the service wrapper that's responsible for mypod
includes dependencies on each of the container wrappers that are required for the pod to run successfully.
If you start or stop the pod by using its systemd
service wrapper, the container services automatically trigger the same action.
Starting and Restarting Podman Services
Caution:
If a container or pod is already running outside of the systemd
service wrapper, the service wrapper is unable to start the container or pod. If so, use the podman stop
or podman pod stop
command to stop the container or pod first.
As a root user, you can start a container if its service configuration is stored in /etc/systemd/system/
, for example:
sudo systemctl start container-containername.service
As a standard user, if you stored a service configuration in $HOME/.config/systemd/user
, you can start the container in the same way but you must use the --user
option:
systemctl --user start container-containername.service
Starting the service wrapper for a pod uses a parallel command syntax, as follows:
sudo systemctl start pod-podname.service
You can restart the service wrapper for a container or pod by using the systemctl restart
command. The following command restarts a pod as a standard user:
systemctl --user restart pod-podname.service
If you start or restart a pod, all containers that are part of the pod are equally started or restarted.
Stopping Podman Services
You can stop a container or pod by using the systemctl stop
command. The following command stops a pod as a standard user:
systemctl --user stop pod-podname.service
If you start or restart a pod, all containers that are part of the pod are equally started or restarted.
Checking the Status of Podman Services
You can check the current status of any service wrapper you create for containers or pods with the systemctl status
command, for example:
systemctl --user status container-containername.service
Enabling Automated Restore for Podman Services
You can add custom configuration steps when you generate service wrappers for Podman containers.
For example, to create a service wrapper that always restarts after a one second timeout, set the --restart-policy
flag with a parameter value, as shown:
sudo systemctl generate systemd --restart-policy=always -t 1 containername > /etc/systemd/user/container-containername.service
To set the service wrapper to run automatically when the system starts up, type:
sudo systemctl enable container-containername.service
You can use the same commands with the service wrapper for a pod:
sudo systemctl enable pod-podname.service
If services are running as a standard user, you would need to give the user permission to run processes when they're not logged in. Otherwise, the user can't enable the service. Type the following command as the root user:
sudo loginctl enable-linger user
Tip:
To try out using systemd
services, see the Use Systemd on Oracle Linux tutorial.
Changing Podman Service Wrapper Configuration
The systemd
service wrapper configuration files that are generated by Podman follow standard systemd
configuration format and specification. You can change any of the service wrapper configuration files that are generated by manually editing these files within a text editor.
Change the behavior of systemd
services wrappers on Oracle Linux by following the instructions in these books:
- Oracle Linux 8: Managing the System With systemd
- Oracle Linux 9: Managing the System With systemd
- Oracle Linux 10: System Management with systemd
For more information about how you can make modifications to the service wrapper you have generated with the podman generate systemd
command, see the upstream Podman documentation.