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)
57 $ systemctl --user start podman-kube@$escaped.service
58 $ systemctl --user is-active podman-kube@$escaped.service
59 active
60
64 --after=dependency_name
65 Add the systemd unit after (After=) option, that ordering dependencies
66 between the list of dependencies and this service. This option may be
67 specified more than once.
68 User-defined dependencies are appended to the generated unit file, but
71 any existing options needed or defined by default (e.g., online.target)
72 are not removed or overridden.
73 --container-prefix=prefix
76 Set the systemd unit name prefix for containers. The default is con‐
77 tainer.
78 --env, -e=env
81 Set environment variables to the systemd unit files.
82 If an environment variable is specified without a value, Podman checks
85 the host environment for a value and sets the variable only if it is
86 set on the host. As a special case, if an environment variable ending
87 in * is specified without a value, Podman searches the host environment
88 for variables starting with the prefix and adds those variables to the
89 systemd unit files.
90 --files, -f
93 Generate files instead of printing to stdout. The generated files are
94 named {container,pod}-{ID,name}.service and are placed in the current
95 working directory.
96 Note: On a system with SELinux enabled, the generated files inherits
99 contexts from the current working directory. Depending on the SELinux
100 setup, changes to the generated files using restorecon, chcon, or sem‐
101 anage may be required to allow systemd to access these files. Alterna‐
102 tively, use the -Z option when running mv or cp.
103 --format=format
106 Print the created units in the specified format (json). If --files is
107 specified, the paths to the created files are printed instead of the
108 unit content.
109 --name, -n
112 Use the name of the container for the start, stop, and description in
113 the unit file
114 --new
117 This option yields unit files that do not expect containers and pods to
118 exist. Instead, new containers and pods are created based on their
119 configuration files. The unit files are created best effort and may
120 need further editing; please review the generated files carefully be‐
121 fore using them in production.
122 Note that --new only works on containers and pods created directly via
125 Podman (i.e., podman [container] {create,run} or podman pod create).
126 It does not work on containers or pods created via the REST API or via
127 podman kube play. For podman kube play, use the podman-kube@.service
128 systemd template instead.
129 --no-header
132 Do not generate the header including meta data such as the Podman ver‐
133 sion and the timestamp.
134 --pod-prefix=prefix
137 Set the systemd unit name prefix for pods. The default is pod.
138 --requires=dependency_name
141 Set the systemd unit requires (Requires=) option. Similar to wants, but
142 declares a stronger requirement dependency.
143 --restart-policy=policy
146 Set the systemd restart policy. The restart-policy must be one of:
147 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-
148 abort", or "always". The default policy is on-failure unless the con‐
149 tainer was created with a custom restart policy.
150 Note that generating a unit without --new on a container with a custom
153 restart policy can lead to issues on shutdown; systemd attempts to stop
154 the unit while Podman tries to restart it. Creating the container
155 without --restart and using the --restart-policy option when generating
156 the unit file is recommended.
157 --restart-sec=time
160 Set the systemd service restartsec value. Configures the time to sleep
161 before restarting a service (as configured with restart-policy). Takes
162 a value in seconds.
163 --separator=separator
166 Set the systemd unit name separator between the name/id of a con‐
167 tainer/pod and the prefix. The default is -.
168 --start-timeout=value
171 Override the default start timeout for the container with the given
172 value in seconds.
173 --stop-timeout=value
176 Override the default stop timeout for the container with the given
177 value in seconds.
178 --template
181 Add template specifiers to run multiple services from the systemd unit
182 file.
183 Note that if --new was not set to true, it is set to true by default.
186 However, the command fails if --new is set to false explicitly.
187 --wants=dependency_name
190 Add the systemd unit wants (Wants=) option, that this service is (weak)
191 dependent on. This option may be specified more than once. This option
192 does not influence the order in which services are started or stopped.
193 User-defined dependencies are appended to the generated unit file, but
196 any existing options needed or defined by default (e.g., online.target)
197 are not removed or overridden.
198
201 Generate and print a systemd unit file for a container
202 Generate a systemd unit file for a container running nginx with an al‐
203 ways restart policy and 1-second timeout to stdout. Note that the Re‐
204 quiresMountsFor option in the Unit section ensures that the container
205 storage for both the GraphRoot and the RunRoot are mounted prior to
206 starting the service. For systems with container storage on disks like
207 iSCSI or other remote block protocols, this ensures that Podman is not
208 executed prior to any necessary storage operations coming online.
209 $ podman create --name nginx nginx:latest
211 $ podman generate systemd --restart-policy=always -t 1 nginx
212 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
213 # autogenerated by Podman 1.8.0
214 # Wed Mar 09 09:46:45 CEST 2020
215 [Unit]
217 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
218 Documentation=man:podman-generate-systemd(1)
219 Wants=network-online.target
220 After=network-online.target
221 RequiresMountsFor=/var/run/container/storage
222 [Service]
224 Restart=always
225 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
226 ExecStop=/usr/bin/podman stop
227 -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
228 KillMode=none
229 Type=forking
230 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
231 [Install]
233 WantedBy=default.target
234 Generate systemd unit file for a container with --new flag
238 The --new flag generates systemd unit files that create and remove con‐
239 tainers at service start and stop commands (see ExecStartPre and Exec‐
240 StopPost service actions). Such unit files are not tied to a single ma‐
241 chine and can easily be shared and used on other machines.
242 $ sudo podman generate systemd --new --files --name bb310a0780ae
244 # container-busy_moser.service
245 # autogenerated by Podman 1.8.3
246 # Fri Apr 3 09:40:47 EDT 2020
247 [Unit]
249 Description=Podman container-busy_moser.service
250 Documentation=man:podman-generate-systemd(1)
251 Wants=network-online.target
252 After=network-online.target
253 RequiresMountsFor=/var/run/container/storage
254 [Service]
256 Environment=PODMAN_SYSTEMD_UNIT=%n
257 Restart=on-failure
258 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
259 ExecStart=/usr/local/bin/podman run
260 --conmon-pidfile %t/%n-pid
261 --cidfile %t/%n-cid
262 --cgroups=no-conmon
263 -d
264 -dit alpine
265 ExecStop=/usr/local/bin/podman stop
266 --ignore
267 --cidfile %t/%n-cid -t 10
268 ExecStopPost=/usr/local/bin/podman rm
269 --ignore
270 -f
271 --cidfile %t/%n-cid
272 PIDFile=%t/%n-pid
273 KillMode=none
274 Type=forking
275 [Install]
277 WantedBy=default.target
278 Generate systemd unit files for a pod with two simple alpine containers
282 Note systemctl must only be used on the pod unit and not used to start
283 or stop containers individually. The containers are managed by the pod
284 service along with the internal infra-container.
285 Use systemctl status or journalctl to examine container or pod unit
288 files.
289 $ podman pod create --name systemd-pod
291 $ podman create --pod systemd-pod alpine top
292 $ podman create --pod systemd-pod alpine top
293 $ podman generate systemd --files --name systemd-pod
294 /home/user/pod-systemd-pod.service
295 /home/user/container-amazing_chandrasekhar.service
296 /home/user/container-jolly_shtern.service
297 $ cat pod-systemd-pod.service
298 # pod-systemd-pod.service
299 # autogenerated by Podman 1.8.0
300 # Wed Mar 09 09:52:37 CEST 2020
301 [Unit]
303 Description=Podman pod-systemd-pod.service
304 Documentation=man:podman-generate-systemd(1)
305 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
306 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
307 Wants=network-online.target
308 After=network-online.target
309 RequiresMountsFor=/var/run/container/storage
310 [Service]
312 Restart=on-failure
313 ExecStart=/usr/bin/podman start 77a818221650-infra
314 ExecStop=/usr/bin/podman stop
315 -t 10 77a818221650-infra
316 KillMode=none
317 Type=forking
318 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
319 [Install]
321 WantedBy=default.target
322 Installation of generated systemd unit files.
326 Podman-generated unit files include an [Install] section, which carries
327 installation information for the unit. It is used by the enable and
328 disable commands of systemctl(1) during installation.
329 Once the systemd unit file is generated, install it to /etc/sys‐
332 temd/system to be run by the root user or to $HOME/.config/systemd/user
333 for installing it as a non-root user. Enable the copied unit file or
334 files using systemctl enable.
335 Note: Copying unit files to /etc/systemd/system and enabling it marks
338 the unit file to be automatically started at boot. And similarly, copy‐
339 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
340 unit file to be automatically started on user login.
341 # Generated systemd files.
343 $ podman pod create --name systemd-pod
344 $ podman create --pod systemd-pod alpine top
345 $ podman generate systemd --files --name systemd-pod
346 # Copy all the generated files.
348 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
350 $ systemctl enable pod-systemd-pod.service
351 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
352 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
353 $ systemctl is-enabled pod-systemd-pod.service
354 enabled
355 To run the user services placed in $HOME/.config/systemd/user on first
359 login of that user, enable the service with --user flag.
360 $ systemctl --user enable <.service>
362 The systemd user instance is killed after the last session for the user
366 is closed. The systemd user instance can be started at boot and kept
367 running even after the user logs out by enabling lingering using
368 $ 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
389 $ podman pod ps
390 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
391 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
392 $ sudo podman ps # 0 Number of pods on root.
393 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
394 $ systemctl stop pod-systemd-pod.service
395 $ podman pod ps
396 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
397 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
398 Create a simple alpine container and generate the systemd unit file
402 with --new flag. Enable the service and control operations using the
403 systemctl commands.
404 Note: When starting the container using systemctl start rather than al‐
407 tering the already running container it spins up a "new" container with
408 similar configuration.
409 # Enable the service.
411 $ sudo podman ps -a
413 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
414 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
415 $ sudo systemctl start container-busy_moser.service
416 $ sudo podman ps -a
417 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
418 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second distracted_albattani
419 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
420
424 podman(1), podman-container(1), systemctl(1), systemd.unit(5), sys‐
425 temd.service(5), conmon(8), podman-systemd.unit(5)
426
429 April 2020, Updated details and added use case to use generated .ser‐
430 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
431 com)
432 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
435 redhat dot com)
436 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
439 com)
440 podman-generate-systemd(1)