1podman-generate-systemd(1) General Commands Manual podman-generate-systemd(1)
2
6 podman-generate-systemd - [DEPRECATED] Generate systemd unit file(s)
7 for a container or pod
8
11 podman generate systemd [options] container|pod
12
15 DEPRECATED: Note: podman generate systemd is deprecated. We recommend
16 using [Quadlet] files when running Podman containers or pods under sys‐
17 temd.
18 podman generate systemd creates a systemd unit file that can be used to
21 control a container or pod. By default, the command prints the content
22 of the unit files to stdout.
23 Generating unit files for a pod requires the pod to be created with an
26 infra container (see --infra=true). An infra container runs across the
27 entire lifespan of a pod and is hence required for systemd to manage
28 the life cycle of the pod's main unit.
29 • Note: When using this command with the remote client, includ‐
32 ing Mac and Windows (excluding WSL2) machines, place the gen‐
33 erated units on the remote system. Moreover, make sure that
34 the XDG_RUNTIME_DIR environment variable is set. If unset,
35 set it via export XDG_RUNTIME_DIR=/run/user/$(id -u)._
36 • Note: The generated podman run command contains an --sdnotify
38 option with the value taken from the container. If the con‐
39 tainer does not have any explicitly set value or the value is
40 set to ignore, the value conmon is used. The reason for over‐
41 riding the default value container is that almost no container
42 workloads send notify messages. Systemd waits for a ready
43 message that never comes, if the value container is used for a
44 container that does not send notify messages. The use of the
45 default value might have been unintentional by the user,
46 therefore the overridden default value._
47 Kubernetes Integration
51 A Kubernetes YAML can be executed in systemd via the podman-kube@.ser‐
52 vice systemd template. The template's argument is the path to the YAML
53 file. Given a workload.yaml file in the home directory, it can be exe‐
54 cuted as follows:
55 $ escaped=$(systemd-escape ~/workload.yaml)
58 $ systemctl --user start podman-kube@$escaped.service
59 $ systemctl --user is-active podman-kube@$escaped.service
60 active
61
65 --after=dependency_name
66 Add the systemd unit after (After=) option, that ordering dependencies
67 between the list of dependencies and this service. This option may be
68 specified more than once.
69 User-defined dependencies are appended to the generated unit file, but
72 any existing options needed or defined by default (e.g., online.target)
73 are not removed or overridden.
74 --container-prefix=prefix
77 Set the systemd unit name prefix for containers. The default is con‐
78 tainer.
79 --env, -e=env
82 Set environment variables to the systemd unit files.
83 If an environment variable is specified without a value, Podman checks
86 the host environment for a value and sets the variable only if it is
87 set on the host. As a special case, if an environment variable ending
88 in * is specified without a value, Podman searches the host environment
89 for variables starting with the prefix and adds those variables to the
90 systemd unit files.
91 --files, -f
94 Generate files instead of printing to stdout. The generated files are
95 named {container,pod}-{ID,name}.service and are placed in the current
96 working directory.
97 Note: On a system with SELinux enabled, the generated files inherits
100 contexts from the current working directory. Depending on the SELinux
101 setup, changes to the generated files using restorecon, chcon, or sem‐
102 anage may be required to allow systemd to access these files. Alterna‐
103 tively, use the -Z option when running mv or cp.
104 --format=format
107 Print the created units in the specified format (json). If --files is
108 specified, the paths to the created files are printed instead of the
109 unit content.
110 --name, -n
113 Use the name of the container for the start, stop, and description in
114 the unit file
115 --new
118 This option yields unit files that do not expect containers and pods to
119 exist. Instead, new containers and pods are created based on their
120 configuration files. The unit files are created best effort and may
121 need further editing; please review the generated files carefully be‐
122 fore using them in production.
123 Note that --new only works on containers and pods created directly via
126 Podman (i.e., podman [container] {create,run} or podman pod create).
127 It does not work on containers or pods created via the REST API or via
128 podman kube play. For podman kube play, use the podman-kube@.service
129 systemd template instead.
130 --no-header
133 Do not generate the header including meta data such as the Podman ver‐
134 sion and the timestamp.
135 --pod-prefix=prefix
138 Set the systemd unit name prefix for pods. The default is pod.
139 --requires=dependency_name
142 Set the systemd unit requires (Requires=) option. Similar to wants, but
143 declares a stronger requirement dependency.
144 --restart-policy=policy
147 Set the systemd restart policy. The restart-policy must be one of:
148 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-
149 abort", or "always". The default policy is on-failure unless the con‐
150 tainer was created with a custom restart policy.
151 Note that generating a unit without --new on a container with a custom
154 restart policy can lead to issues on shutdown; systemd attempts to stop
155 the unit while Podman tries to restart it. Creating the container
156 without --restart and using the --restart-policy option when generating
157 the unit file is recommended.
158 --restart-sec=time
161 Set the systemd service restartsec value. Configures the time to sleep
162 before restarting a service (as configured with restart-policy). Takes
163 a value in seconds.
164 --separator=separator
167 Set the systemd unit name separator between the name/id of a con‐
168 tainer/pod and the prefix. The default is -.
169 --start-timeout=value
172 Override the default start timeout for the container with the given
173 value in seconds.
174 --stop-timeout=value
177 Override the default stop timeout for the container with the given
178 value in seconds.
179 --template
182 Add template specifiers to run multiple services from the systemd unit
183 file.
184 Note that if --new was not set to true, it is set to true by default.
187 However, the command fails if --new is set to false explicitly.
188 --wants=dependency_name
191 Add the systemd unit wants (Wants=) option, that this service is (weak)
192 dependent on. This option may be specified more than once. This option
193 does not influence the order in which services are started or stopped.
194 User-defined dependencies are appended to the generated unit file, but
197 any existing options needed or defined by default (e.g., online.target)
198 are not removed or overridden.
199
202 Generate and print a systemd unit file for a container
203 Generate a systemd unit file for a container running nginx with an al‐
204 ways restart policy and 1-second timeout to stdout. Note that the Re‐
205 quiresMountsFor option in the Unit section ensures that the container
206 storage for both the GraphRoot and the RunRoot are mounted prior to
207 starting the service. For systems with container storage on disks like
208 iSCSI or other remote block protocols, this ensures that Podman is not
209 executed prior to any necessary storage operations coming online.
210 $ podman create --name nginx nginx:latest
213 $ podman generate systemd --restart-policy=always -t 1 nginx
214 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
215 # autogenerated by Podman 1.8.0
216 # Wed Mar 09 09:46:45 CEST 2020
217 [Unit]
219 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
220 Documentation=man:podman-generate-systemd(1)
221 Wants=network-online.target
222 After=network-online.target
223 RequiresMountsFor=/var/run/container/storage
224 [Service]
226 Restart=always
227 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
228 ExecStop=/usr/bin/podman stop
229 -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
230 KillMode=none
231 Type=forking
232 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
233 [Install]
235 WantedBy=default.target
236 Generate systemd unit file for a container with --new flag
240 The --new flag generates systemd unit files that create and remove con‐
241 tainers at service start and stop commands (see ExecStartPre and Exec‐
242 StopPost service actions). Such unit files are not tied to a single ma‐
243 chine and can easily be shared and used on other machines.
244 $ sudo podman generate systemd --new --files --name bb310a0780ae
247 # container-busy_moser.service
248 # autogenerated by Podman 1.8.3
249 # Fri Apr 3 09:40:47 EDT 2020
250 [Unit]
252 Description=Podman container-busy_moser.service
253 Documentation=man:podman-generate-systemd(1)
254 Wants=network-online.target
255 After=network-online.target
256 RequiresMountsFor=/var/run/container/storage
257 [Service]
259 Environment=PODMAN_SYSTEMD_UNIT=%n
260 Restart=on-failure
261 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
262 ExecStart=/usr/local/bin/podman run
263 --conmon-pidfile %t/%n-pid
264 --cidfile %t/%n-cid
265 --cgroups=no-conmon
266 -d
267 -dit alpine
268 ExecStop=/usr/local/bin/podman stop
269 --ignore
270 --cidfile %t/%n-cid -t 10
271 ExecStopPost=/usr/local/bin/podman rm
272 --ignore
273 -f
274 --cidfile %t/%n-cid
275 PIDFile=%t/%n-pid
276 KillMode=none
277 Type=forking
278 [Install]
280 WantedBy=default.target
281 Generate systemd unit files for a pod with two simple alpine containers
285 Note systemctl must only be used on the pod unit and not used to start
286 or stop containers individually. The containers are managed by the pod
287 service along with the internal infra-container.
288 Use systemctl status or journalctl to examine container or pod unit
291 files.
292 $ podman pod create --name systemd-pod
295 $ podman create --pod systemd-pod alpine top
296 $ podman create --pod systemd-pod alpine top
297 $ podman generate systemd --files --name systemd-pod
298 /home/user/pod-systemd-pod.service
299 /home/user/container-amazing_chandrasekhar.service
300 /home/user/container-jolly_shtern.service
301 $ cat pod-systemd-pod.service
302 # pod-systemd-pod.service
303 # autogenerated by Podman 1.8.0
304 # Wed Mar 09 09:52:37 CEST 2020
305 [Unit]
307 Description=Podman pod-systemd-pod.service
308 Documentation=man:podman-generate-systemd(1)
309 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
310 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
311 Wants=network-online.target
312 After=network-online.target
313 RequiresMountsFor=/var/run/container/storage
314 [Service]
316 Restart=on-failure
317 ExecStart=/usr/bin/podman start 77a818221650-infra
318 ExecStop=/usr/bin/podman stop
319 -t 10 77a818221650-infra
320 KillMode=none
321 Type=forking
322 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
323 [Install]
325 WantedBy=default.target
326 Installation of generated systemd unit files.
330 Podman-generated unit files include an [Install] section, which carries
331 installation information for the unit. It is used by the enable and
332 disable commands of systemctl(1) during installation.
333 Once the systemd unit file is generated, install it to /etc/sys‐
336 temd/system to be run by the root user or to $HOME/.config/systemd/user
337 for installing it as a non-root user. Enable the copied unit file or
338 files using systemctl enable.
339 Note: Copying unit files to /etc/systemd/system and enabling it marks
342 the unit file to be automatically started at boot. And similarly, copy‐
343 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
344 unit file to be automatically started on user login.
345 # Generated systemd files.
348 $ podman pod create --name systemd-pod
349 $ podman create --pod systemd-pod alpine top
350 $ podman generate systemd --files --name systemd-pod
351 # Copy all the generated files.
353 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
355 $ systemctl enable pod-systemd-pod.service
356 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
357 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
358 $ systemctl is-enabled pod-systemd-pod.service
359 enabled
360 To run the user services placed in $HOME/.config/systemd/user on first
364 login of that user, enable the service with --user flag.
365 $ systemctl --user enable <.service>
368 The systemd user instance is killed after the last session for the user
372 is closed. The systemd user instance can be started at boot and kept
373 running even after the user logs out by enabling lingering using
374 $ loginctl enable-linger <username>
377 Use systemctl to perform operations on generated installed unit files.
381 Create and enable systemd unit files for a pod using the above examples
382 as reference and use systemctl to perform operations.
383 Since systemctl defaults to using the root user, all the changes using
386 the systemctl can be seen by appending sudo to the podman cli commands.
387 To perform systemctl actions as a non-root user use the --user flag
388 when interacting with systemctl.
389 Note: If the previously created containers or pods are using shared re‐
392 sources, such as ports, make sure to remove them before starting the
393 generated systemd units.
394 $ systemctl --user start pod-systemd-pod.service
397 $ podman pod ps
398 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
399 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
400 $ sudo podman ps # 0 Number of pods on root.
401 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
402 $ systemctl stop pod-systemd-pod.service
403 $ podman pod ps
404 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
405 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
406 Create a simple alpine container and generate the systemd unit file
410 with --new flag. Enable the service and control operations using the
411 systemctl commands.
412 Note: When starting the container using systemctl start rather than al‐
415 tering the already running container it spins up a "new" container with
416 similar configuration.
417 # Enable the service.
420 $ sudo podman ps -a
422 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
423 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
424 $ sudo systemctl start container-busy_moser.service
425 $ sudo podman ps -a
426 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
427 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second distracted_albattani
428 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
429
433 podman(1), podman-container(1), systemctl(1), systemd.unit(5), sys‐
434 temd.service(5), conmon(8), podman-systemd.unit(5)
435
438 April 2020, Updated details and added use case to use generated .ser‐
439 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
440 com)
441 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
444 redhat dot com)
445 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
448 com)
449 podman-generate-systemd(1)