1podman-generate-systemd(1)  General Commands Manual podman-generate-systemd(1)
2
3
4

NAME

6       podman-generate-systemd - Generate systemd unit file(s) for a container
7       or pod
8
9

SYNOPSIS

11       podman generate systemd [options] container|pod
12
13

DESCRIPTION

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
19
20       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
25
26       _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
32
33       _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
43
44   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
50
51              $ 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
56
57

OPTIONS

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
64
65       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
69
70   --container-prefix=prefix
71       Set the systemd unit name prefix for containers. The  default  is  con‐
72       tainer.
73
74
75   --env, -e=env
76       Set environment variables to the systemd unit files.
77
78
79       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
86
87   --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
92
93       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
99
100   --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
105
106   --name, -n
107       Use the name of the container for the start, stop, and  description  in
108       the unit file
109
110
111   --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
118
119       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
124
125   --no-header
126       Do not generate the header including meta data such as the Podman  ver‐
127       sion and the timestamp.
128
129
130   --pod-prefix=prefix
131       Set the systemd unit name prefix for pods. The default is pod.
132
133
134   --requires=dependency_name
135       Set the systemd unit requires (Requires=) option. Similar to wants, but
136       declares a stronger requirement dependency.
137
138
139   --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
145
146       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
152
153   --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
158
159   --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
163
164   --start-timeout=value
165       Override the default start timeout for the  container  with  the  given
166       value in seconds.
167
168
169   --stop-timeout=value
170       Override  the  default  stop  timeout  for the container with the given
171       value in seconds.
172
173
174   --template
175       Add template specifiers to run multiple services from the systemd  unit
176       file.
177
178
179       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
182
183   --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
188
189       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
193

EXAMPLES

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
204
205              $ 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
211              [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
218              [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
227              [Install]
228              WantedBy=default.target
229
230
231
232   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
238
239              $ 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
244              [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
251              [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
272              [Install]
273              WantedBy=default.target
274
275
276
277   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
282
283       You  can  still use systemctl status or journalctl to examine container
284       or pod unit files.
285
286
287              $ 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
299              [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
308              [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
317              [Install]
318              WantedBy=default.target
319
320
321
322   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
327
328       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
333
334       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
339
340              # 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
345              # Copy all the generated files.
346
347              $ 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
354
355
356       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
359
360              $ systemctl --user enable <.service>
361
362
363
364       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
368
369              $ loginctl enable-linger <username>
370
371
372
373   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
377
378       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
383
384       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
388
389              $ 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
400
401
402       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
406
407       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
411
412              # Enable the service.
413
414              $ 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
423
424

SEE ALSO

426       podman(1),  podman-container(1),  systemctl(1),  systemd.unit(5),  sys‐
427       temd.service(5), conmon(8)
428
429

HISTORY

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
435
436       August 2019, Updated with pod support by Valentin Rothberg (rothberg at
437       redhat dot com)
438
439
440       April  2019,  Originally  compiled by Brent Baude (bbaude at redhat dot
441       com)
442
443
444
445                                                    podman-generate-systemd(1)
Impressum