1podman-generate-systemd(1) General Commands Manual podman-generate-systemd(1)
2
6 podman-generate-systemd - Generate systemd unit file(s) for a container
7 or pod
8
11 podman generate systemd [options] container|pod
12
15 podman generate systemd will create a systemd unit file that can be
16 used to control a container or pod. By default, the command will print
17 the content of the unit files to stdout.
18 Generating unit files for a pod requires the pod to be created with an
21 infra container (see --infra=true). An infra container runs across the
22 entire lifespan of a pod and is hence required for systemd to manage
23 the life cycle of the pod's main unit.
24 _Note: If you use this command with the remote client, including Mac
27 and Windows (excluding WSL2) machines, you would still have to place
28 the generated units on the remote system. Moreover, please make sure
29 that the XDG_RUNTIMEDIR environment variable is set. If unset, you may
30 set it via export XDG_RUNTIME_DIR=/run/user/$(id -u).
31 _Note: The generated podman run command contains an --sdnotify option
34 with the value taken from the container. If the container does not
35 have any explicitly set value or the value is set to ignore, the value
36 conmon is used. The reason for overriding the default value container
37 is that almost no container workloads send notify messages. Systemd
38 would wait for a ready message that never comes, if the value container
39 is used for a container that does not send notify messages. The use of
40 the default value might have been unintentional by the user, therefore
41 the overridden default value._
42 Kubernetes Integration
45 A Kubernetes YAML can be executed in systemd via the podman-kube@.ser‐
46 vice systemd template. The template's argument is the path to the YAML
47 file. Given a workload.yaml file in the home directory, it can be exe‐
48 cuted as follows:
49 $ escaped=$(systemd-escape ~/workload.yaml)
52 $ systemctl --user start podman-kube@$escaped.service
53 $ systemctl --user is-active podman-kube@$escaped.service
54 active
55
59 --after=dependency_name
60 Add the systemd unit after (After=) option, that ordering dependencies
61 between the list of dependencies and this service. This option may be
62 specified more than once.
63 User-defined dependencies will be appended to the generated unit file,
66 but any existing options such as needed or defined by default (e.g. on‐
67 line.target) will not be removed or overridden.
68 --container-prefix=prefix
71 Set the systemd unit name prefix for containers. The default is con‐
72 tainer.
73 --env, -e=env
76 Set environment variables to the systemd unit files.
77 If an environment variable is specified without a value, Podman will
80 check the host environment for a value and set the variable only if it
81 is set on the host. As a special case, if an environment variable end‐
82 ing in * is specified without a value, Podman will search the host en‐
83 vironment for variables starting with the prefix and will add those
84 variables to the systemd unit files.
85 --files, -f
88 Generate files instead of printing to stdout. The generated files are
89 named {container,pod}-{ID,name}.service and will be placed in the cur‐
90 rent working directory.
91 Note: On a system with SELinux enabled, the generated files will in‐
94 herit contexts from the current working directory. Depending on the
95 SELinux setup, changes to the generated files using restorecon, chcon,
96 or semanage may be required to allow systemd to access these files. Al‐
97 ternatively, use the -Z option when running mv or cp.
98 --format=format
101 Print the created units in specified format (json). If --files is spec‐
102 ified the paths to the created files will be printed instead of the
103 unit content.
104 --name, -n
107 Use the name of the container for the start, stop, and description in
108 the unit file
109 --new
112 Using this flag will yield unit files that do not expect containers and
113 pods to exist. Instead, new containers and pods are created based on
114 their configuration files. The unit files are created best effort and
115 may need to be further edited; please review the generated files care‐
116 fully before using them in production.
117 Note that --new only works on containers and pods created directly via
120 Podman (i.e., podman [container] {create,run} or podman pod create).
121 It does not work on containers or pods created via the REST API or via
122 podman kube play.
123 --no-header
126 Do not generate the header including meta data such as the Podman ver‐
127 sion and the timestamp.
128 --pod-prefix=prefix
131 Set the systemd unit name prefix for pods. The default is pod.
132 --requires=dependency_name
135 Set the systemd unit requires (Requires=) option. Similar to wants, but
136 declares a stronger requirement dependency.
137 --restart-policy=policy
140 Set the systemd restart policy. The restart-policy must be one of:
141 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-
142 abort", or "always". The default policy is on-failure unless the con‐
143 tainer was created with a custom restart policy.
144 Note that generating a unit without --new on a container with a custom
147 restart policy can lead to issues on shutdown; systemd will attempt to
148 stop the unit while Podman tries to restart it. It is recommended to
149 to create the container without --restart and use the --restart-policy
150 option instead when generating the unit file.
151 --restart-sec=time
154 Set the systemd service restartsec value. Configures the time to sleep
155 before restarting a service (as configured with restart-policy). Takes
156 a value in seconds.
157 --separator=separator
160 Set the systemd unit name separator between the name/id of a con‐
161 tainer/pod and the prefix. The default is -.
162 --start-timeout=value
165 Override the default start timeout for the container with the given
166 value in seconds.
167 --stop-timeout=value
170 Override the default stop timeout for the container with the given
171 value in seconds.
172 --template
175 Add template specifiers to run multiple services from the systemd unit
176 file.
177 Note that if --new was not set to true, it is set to true by default.
180 However, if --new is set to false explicitly the command will fail.
181 --wants=dependency_name
184 Add the systemd unit wants (Wants=) option, that this service is (weak)
185 dependent on. This option may be specified more than once. This option
186 does not influence the order in which services are started or stopped.
187 User-defined dependencies will be appended to the generated unit file,
190 but any existing options such as needed or defined by default (e.g. on‐
191 line.target) will not be removed or overridden.
192
195 Generate and print a systemd unit file for a container
196 Generate a systemd unit file for a container running nginx with an al‐
197 ways restart policy and 1-second timeout to stdout. Note that the Re‐
198 quiresMountsFor option in the Unit section ensures that the container
199 storage for both the GraphRoot and the RunRoot are mounted prior to
200 starting the service. For systems with container storage on disks like
201 iSCSI or other remote block protocols, this ensures that Podman is not
202 executed prior to any necessary storage operations coming online.
203 $ podman create --name nginx nginx:latest
206 $ podman generate systemd --restart-policy=always -t 1 nginx
207 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
208 # autogenerated by Podman 1.8.0
209 # Wed Mar 09 09:46:45 CEST 2020
210 [Unit]
212 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
213 Documentation=man:podman-generate-systemd(1)
214 Wants=network-online.target
215 After=network-online.target
216 RequiresMountsFor=/var/run/container/storage
217 [Service]
219 Restart=always
220 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
221 ExecStop=/usr/bin/podman stop
222 -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
223 KillMode=none
224 Type=forking
225 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
226 [Install]
228 WantedBy=default.target
229 Generate systemd unit file for a container with --new flag
233 The --new flag generates systemd unit files that create and remove con‐
234 tainers at service start and stop commands (see ExecStartPre and Exec‐
235 StopPost service actions). Such unit files are not tied to a single ma‐
236 chine and can easily be shared and used on other machines.
237 $ sudo podman generate systemd --new --files --name bb310a0780ae
240 # container-busy_moser.service
241 # autogenerated by Podman 1.8.3
242 # Fri Apr 3 09:40:47 EDT 2020
243 [Unit]
245 Description=Podman container-busy_moser.service
246 Documentation=man:podman-generate-systemd(1)
247 Wants=network-online.target
248 After=network-online.target
249 RequiresMountsFor=/var/run/container/storage
250 [Service]
252 Environment=PODMAN_SYSTEMD_UNIT=%n
253 Restart=on-failure
254 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
255 ExecStart=/usr/local/bin/podman run
256 --conmon-pidfile %t/%n-pid
257 --cidfile %t/%n-cid
258 --cgroups=no-conmon
259 -d
260 -dit alpine
261 ExecStop=/usr/local/bin/podman stop
262 --ignore
263 --cidfile %t/%n-cid -t 10
264 ExecStopPost=/usr/local/bin/podman rm
265 --ignore
266 -f
267 --cidfile %t/%n-cid
268 PIDFile=%t/%n-pid
269 KillMode=none
270 Type=forking
271 [Install]
273 WantedBy=default.target
274 Generate systemd unit files for a pod with two simple alpine containers
278 Note systemctl should only be used on the pod unit and one should not
279 start or stop containers individually via systemctl, as they are man‐
280 aged by the pod service along with the internal infra-container.
281 You can still use systemctl status or journalctl to examine container
284 or pod unit files.
285 $ podman pod create --name systemd-pod
288 $ podman create --pod systemd-pod alpine top
289 $ podman create --pod systemd-pod alpine top
290 $ podman generate systemd --files --name systemd-pod
291 /home/user/pod-systemd-pod.service
292 /home/user/container-amazing_chandrasekhar.service
293 /home/user/container-jolly_shtern.service
294 $ cat pod-systemd-pod.service
295 # pod-systemd-pod.service
296 # autogenerated by Podman 1.8.0
297 # Wed Mar 09 09:52:37 CEST 2020
298 [Unit]
300 Description=Podman pod-systemd-pod.service
301 Documentation=man:podman-generate-systemd(1)
302 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
303 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
304 Wants=network-online.target
305 After=network-online.target
306 RequiresMountsFor=/var/run/container/storage
307 [Service]
309 Restart=on-failure
310 ExecStart=/usr/bin/podman start 77a818221650-infra
311 ExecStop=/usr/bin/podman stop
312 -t 10 77a818221650-infra
313 KillMode=none
314 Type=forking
315 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
316 [Install]
318 WantedBy=default.target
319 Installation of generated systemd unit files.
323 Podman-generated unit files include an [Install] section, which carries
324 installation information for the unit. It is used by the enable and
325 disable commands of systemctl(1) during installation.
326 Once you have generated the systemd unit file, you can copy the gener‐
329 ated systemd file to /etc/systemd/system for installing as a root user
330 and to $HOME/.config/systemd/user for installing it as a non-root user.
331 Enable the copied unit file or files using systemctl enable.
332 Note: Copying unit files to /etc/systemd/system and enabling it marks
335 the unit file to be automatically started at boot. And similarly, copy‐
336 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
337 unit file to be automatically started on user login.
338 # Generated systemd files.
341 $ podman pod create --name systemd-pod
342 $ podman create --pod systemd-pod alpine top
343 $ podman generate systemd --files --name systemd-pod
344 # Copy all the generated files.
346 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
348 $ systemctl enable pod-systemd-pod.service
349 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
350 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
351 $ systemctl is-enabled pod-systemd-pod.service
352 enabled
353 To run the user services placed in $HOME/.config/systemd/user on first
357 login of that user, enable the service with --user flag.
358 $ systemctl --user enable <.service>
361 The systemd user instance is killed after the last session for the user
365 is closed. The systemd user instance can be started at boot and kept
366 running even after the user logs out by enabling lingering using
367 $ loginctl enable-linger <username>
370 Use systemctl to perform operations on generated installed unit files.
374 Create and enable systemd unit files for a pod using the above examples
375 as reference and use systemctl to perform operations.
376 Since systemctl defaults to using the root user, all the changes using
379 the systemctl can be seen by appending sudo to the podman cli commands.
380 To perform systemctl actions as a non-root user use the --user flag
381 when interacting with systemctl.
382 Note: If the previously created containers or pods are using shared re‐
385 sources, such as ports, make sure to remove them before starting the
386 generated systemd units.
387 $ systemctl --user start pod-systemd-pod.service
390 $ podman pod ps
391 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
392 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
393 $ sudo podman ps # 0 Number of pods on root.
394 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
395 $ systemctl stop pod-systemd-pod.service
396 $ podman pod ps
397 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
398 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
399 Create a simple alpine container and generate the systemd unit file
403 with --new flag. Enable the service and control operations using the
404 systemctl commands.
405 Note: When starting the container using systemctl start rather than al‐
408 tering the already running container it spins up a "new" container with
409 similar configuration.
410 # Enable the service.
413 $ sudo podman ps -a
415 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
416 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
417 $ sudo systemctl start container-busy_moser.service
418 $ sudo podman ps -a
419 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
420 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second ago distracted_albattani
421 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
422
426 podman(1), podman-container(1), systemctl(1), systemd.unit(5), sys‐
427 temd.service(5), conmon(8)
428
431 April 2020, Updated details and added use case to use generated .ser‐
432 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
433 com)
434 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
437 redhat dot com)
438 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
441 com)
442 podman-generate-systemd(1)