1podman-generate-systemd(1)() 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
34 --after=dependency_name
35 Add the systemd unit after (After=) option, that ordering dependencies
36 between the list of dependencies and this service. This option may be
37 specified more than once.
38 User-defined dependencies will be appended to the generated unit file,
41 but any existing options such as needed or defined by default (e.g. on‐
42 line.target) will not be removed or overridden.
43 --container-prefix=prefix
46 Set the systemd unit name prefix for containers. The default is con‐
47 tainer.
48 --files, -f
51 Generate files instead of printing to stdout. The generated files are
52 named {container,pod}-{ID,name}.service and will be placed in the cur‐
53 rent working directory.
54 Note: On a system with SELinux enabled, the generated files will in‐
57 herit contexts from the current working directory. Depending on the
58 SELinux setup, changes to the generated files using restorecon, chcon,
59 or semanage may be required to allow systemd to access these files. Al‐
60 ternatively, use the -Z option when running mv or cp.
61 --format=format
64 Print the created units in specified format (json). If --files is spec‐
65 ified the paths to the created files will be printed instead of the
66 unit content.
67 --name, -n
70 Use the name of the container for the start, stop, and description in
71 the unit file
72 --new
75 Using this flag will yield unit files that do not expect containers and
76 pods to exist. Instead, new containers and pods are created based on
77 their configuration files. The unit files are created best effort and
78 may need to be further edited; please review the generated files care‐
79 fully before using them in production.
80 Note that --new only works on containers and pods created directly via
83 Podman (i.e., podman [container] {create,run} or podman pod create).
84 It does not work on containers or pods created via the REST API or via
85 podman play kube.
86 --no-header
89 Do not generate the header including meta data such as the Podman ver‐
90 sion and the timestamp.
91 --pod-prefix=prefix
94 Set the systemd unit name prefix for pods. The default is pod.
95 --requires=dependency_name
98 Set the systemd unit requires (Requires=) option. Similar to wants, but
99 declares a stronger requirement dependency.
100 --restart-policy=policy
103 Set the systemd restart policy. The restart-policy must be one of:
104 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-
105 abort", or "always". The default policy is on-failure.
106 --restart-sec=time
109 Set the systemd service restartsec value. Configures the time to sleep
110 before restarting a service (as configured with restart-policy). Takes
111 a value in seconds.
112 --separator=separator
115 Set the systemd unit name separator between the name/id of a con‐
116 tainer/pod and the prefix. The default is -.
117 --start-timeout =value
120 Override the default start timeout for the container with the given
121 value in seconds.
122 --stop-timeout =value
125 Override the default stop timeout for the container with the given
126 value in seconds.
127 --template
130 Add template specifiers to run multiple services from the systemd unit
131 file.
132 Note that if --new was not set to true, it is set to true by default.
135 However, if --new is set to false explicitly the command will fail.
136 --wants=dependency_name
139 Add the systemd unit wants (Wants=) option, that this service is (weak)
140 dependent on. This option may be specified more than once. This option
141 does not influence the order in which services are started or stopped.
142 User-defined dependencies will be appended to the generated unit file,
145 but any existing options such as needed or defined by default (e.g. on‐
146 line.target) will not be removed or overridden.
147
150 Generate and print a systemd unit file for a container
151 Generate a systemd unit file for a container running nginx with an al‐
152 ways restart policy and 1-second timeout to stdout. Note that the Re‐
153 quiresMountsFor option in the Unit section ensures that the container
154 storage for both the GraphRoot and the RunRoot are mounted prior to
155 starting the service. For systems with container storage on disks like
156 iSCSI or other remote block protocols, this ensures that Podman is not
157 executed prior to any necessary storage operations coming online.
158 $ podman create --name nginx nginx:latest
161 $ podman generate systemd --restart-policy=always -t 1 nginx
162 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
163 # autogenerated by Podman 1.8.0
164 # Wed Mar 09 09:46:45 CEST 2020
165 [Unit]
167 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
168 Documentation=man:podman-generate-systemd(1)
169 Wants=network-online.target
170 After=network-online.target
171 RequiresMountsFor=/var/run/container/storage
172 [Service]
174 Restart=always
175 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
176 ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
177 KillMode=none
178 Type=forking
179 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
180 [Install]
182 WantedBy=default.target
183 Generate systemd unit file for a container with --new flag
187 The --new flag generates systemd unit files that create and remove con‐
188 tainers at service start and stop commands (see ExecStartPre and Exec‐
189 StopPost service actions). Such unit files are not tied to a single ma‐
190 chine and can easily be shared and used on other machines.
191 $ sudo podman generate systemd --new --files --name bb310a0780ae
194 # container-busy_moser.service
195 # autogenerated by Podman 1.8.3
196 # Fri Apr 3 09:40:47 EDT 2020
197 [Unit]
199 Description=Podman container-busy_moser.service
200 Documentation=man:podman-generate-systemd(1)
201 Wants=network-online.target
202 After=network-online.target
203 RequiresMountsFor=/var/run/container/storage
204 [Service]
206 Environment=PODMAN_SYSTEMD_UNIT=%n
207 Restart=on-failure
208 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
209 ExecStart=/usr/local/bin/podman run
210 --conmon-pidfile %t/%n-pid
211 --cidfile %t/%n-cid
212 --cgroups=no-conmon
213 -d
214 -dit alpine
215 ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10
216 ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid
217 PIDFile=%t/%n-pid
218 KillMode=none
219 Type=forking
220 [Install]
222 WantedBy=default.target
223 Generate systemd unit files for a pod with two simple alpine containers
227 Note systemctl should only be used on the pod unit and one should not
228 start or stop containers individually via systemctl, as they are man‐
229 aged by the pod service along with the internal infra-container.
230 You can still use systemctl status or journalctl to examine container
233 or pod unit files.
234 $ podman pod create --name systemd-pod
237 $ podman create --pod systemd-pod alpine top
238 $ podman create --pod systemd-pod alpine top
239 $ podman generate systemd --files --name systemd-pod
240 /home/user/pod-systemd-pod.service
241 /home/user/container-amazing_chandrasekhar.service
242 /home/user/container-jolly_shtern.service
243 $ cat pod-systemd-pod.service
244 # pod-systemd-pod.service
245 # autogenerated by Podman 1.8.0
246 # Wed Mar 09 09:52:37 CEST 2020
247 [Unit]
249 Description=Podman pod-systemd-pod.service
250 Documentation=man:podman-generate-systemd(1)
251 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
252 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
253 Wants=network-online.target
254 After=network-online.target
255 RequiresMountsFor=/var/run/container/storage
256 [Service]
258 Restart=on-failure
259 ExecStart=/usr/bin/podman start 77a818221650-infra
260 ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra
261 KillMode=none
262 Type=forking
263 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
264 [Install]
266 WantedBy=default.target
267 Installation of generated systemd unit files.
271 Podman-generated unit files include an [Install] section, which carries
272 installation information for the unit. It is used by the enable and
273 disable commands of systemctl(1) during installation.
274 Once you have generated the systemd unit file, you can copy the gener‐
277 ated systemd file to /etc/systemd/system for installing as a root user
278 and to $HOME/.config/systemd/user for installing it as a non-root user.
279 Enable the copied unit file or files using systemctl enable.
280 Note: Copying unit files to /etc/systemd/system and enabling it marks
283 the unit file to be automatically started at boot. And similarly, copy‐
284 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
285 unit file to be automatically started on user login.
286 # Generated systemd files.
289 $ podman pod create --name systemd-pod
290 $ podman create --pod systemd-pod alpine top
291 $ podman generate systemd --files --name systemd-pod
292 # Copy all the generated files.
294 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
296 $ systemctl enable pod-systemd-pod.service
297 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
298 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
299 $ systemctl is-enabled pod-systemd-pod.service
300 enabled
301 To run the user services placed in $HOME/.config/systemd/user on first
305 login of that user, enable the service with --user flag.
306 $ systemctl --user enable <.service>
309 The systemd user instance is killed after the last session for the user
313 is closed. The systemd user instance can be started at boot and kept
314 running even after the user logs out by enabling lingering using
315 $ loginctl enable-linger <username>
318 Use systemctl to perform operations on generated installed unit files.
322 Create and enable systemd unit files for a pod using the above examples
323 as reference and use systemctl to perform operations.
324 Since systemctl defaults to using the root user, all the changes using
327 the systemctl can be seen by appending sudo to the podman cli commands.
328 To perform systemctl actions as a non-root user use the --user flag
329 when interacting with systemctl.
330 Note: If the previously created containers or pods are using shared re‐
333 sources, such as ports, make sure to remove them before starting the
334 generated systemd units.
335 $ systemctl --user start pod-systemd-pod.service
338 $ podman pod ps
339 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
340 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
341 $ sudo podman ps # 0 Number of pods on root.
342 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
343 $ systemctl stop pod-systemd-pod.service
344 $ podman pod ps
345 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
346 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
347 Create a simple alpine container and generate the systemd unit file
351 with --new flag. Enable the service and control operations using the
352 systemctl commands.
353 Note: When starting the container using systemctl start rather than al‐
356 tering the already running container it spins up a "new" container with
357 similar configuration.
358 # Enable the service.
361 $ sudo podman ps -a
363 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
364 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
365 $ sudo systemctl start container-busy_moser.service
366 $ sudo podman ps -a
367 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
368 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second ago distracted_albattani
369 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
370
374 podman(1), podman-container(1), systemctl(1), systemd.unit(5), sys‐
375 temd.service(5), conmon(8)
376
379 April 2020, Updated details and added use case to use generated .ser‐
380 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
381 com)
382 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
385 redhat dot com)
386 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
389 com)
390 podman-generate-systemd(1)()