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 _Note: If you use this command with the remote client, you would still
21 have to place the generated units on the remote system. Moreover,
22 please make sure that the XDG_RUNTIMEDIR environment variable is set.
23 If unset, you may set it via export XDG_RUNTIME_DIR=/run/user/$(id -u).
24
27 --files, -f
28 Generate files instead of printing to stdout. The generated files are
29 named {container,pod}-{ID,name}.service and will be placed in the cur‐
30 rent working directory.
31 Note: On a system with SELinux enabled, the generated files will in‐
34 herit contexts from the current working directory. Depending on the
35 SELinux setup, changes to the generated files using restorecon, chcon,
36 or semanage may be required to allow systemd to access these files. Al‐
37 ternatively, use the -Z option when running mv or cp.
38 --format=format
41 Print the created units in specified format (json). If --files is spec‐
42 ified the paths to the created files will be printed instead of the
43 unit content.
44 --name, -n
47 Use the name of the container for the start, stop, and description in
48 the unit file
49 --new
52 Using this flag will yield unit files that do not expect containers and
53 pods to exist. Instead, new containers and pods are created based on
54 their configuration files. The unit files are created best effort and
55 may need to be further edited; please review the generated files care‐
56 fully before using them in production.
57 Note that --new only works on containers and pods created directly via
60 Podman (i.e., podman [container] {create,run} or podman pod create).
61 It does not work on containers or pods created via the REST API or via
62 podman play kube.
63 --no-header
66 Do not generate the header including meta data such as the Podman ver‐
67 sion and the timestamp.
68 --time, -t=value
71 Override the default stop timeout for the container with the given
72 value.
73 --restart-policy=policy
76 Set the systemd restart policy. The restart-policy must be one of:
77 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-
78 abort", or "always". The default policy is on-failure.
79 --container-prefix=prefix
82 Set the systemd unit name prefix for containers. The default is con‐
83 tainer.
84 --pod-prefix=prefix
87 Set the systemd unit name prefix for pods. The default is pod.
88 --separator=separator
91 Set the systemd unit name separator between the name/id of a con‐
92 tainer/pod and the prefix. The default is -.
93
96 Generate and print a systemd unit file for a container
97 Generate a systemd unit file for a container running nginx with an al‐
98 ways restart policy and 1-second timeout to stdout. Note that the Re‐
99 quiresMountsFor option in the Unit section ensures that the container
100 storage for both the GraphRoot and the RunRoot are mounted prior to
101 starting the service. For systems with container storage on disks like
102 iSCSI or other remote block protocols, this ensures that Podman is not
103 executed prior to any necessary storage operations coming online.
104 $ podman create --name nginx nginx:latest
107 $ podman generate systemd --restart-policy=always -t 1 nginx
108 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
109 # autogenerated by Podman 1.8.0
110 # Wed Mar 09 09:46:45 CEST 2020
111 [Unit]
113 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
114 Documentation=man:podman-generate-systemd(1)
115 Wants=network-online.target
116 After=network-online.target
117 RequiresMountsFor=/var/run/container/storage
118 [Service]
120 Restart=always
121 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
122 ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
123 KillMode=none
124 Type=forking
125 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
126 [Install]
128 WantedBy=multi-user.target default.target
129 Generate systemd unit file for a container with --new flag
133 The --new flag generates systemd unit files that create and remove con‐
134 tainers at service start and stop commands (see ExecStartPre and Exec‐
135 StopPost service actions). Such unit files are not tied to a single ma‐
136 chine and can easily be shared and used on other machines.
137 $ sudo podman generate systemd --new --files --name bb310a0780ae
140 # container-busy_moser.service
141 # autogenerated by Podman 1.8.3
142 # Fri Apr 3 09:40:47 EDT 2020
143 [Unit]
145 Description=Podman container-busy_moser.service
146 Documentation=man:podman-generate-systemd(1)
147 Wants=network-online.target
148 After=network-online.target
149 RequiresMountsFor=/var/run/container/storage
150 [Service]
152 Environment=PODMAN_SYSTEMD_UNIT=%n
153 Restart=on-failure
154 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
155 ExecStart=/usr/local/bin/podman run --conmon-pidfile %t/%n-pid --cidfile %t/%n-cid --cgroups=no-conmon -d -dit alpine
156 ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10
157 ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid
158 PIDFile=%t/%n-pid
159 KillMode=none
160 Type=forking
161 [Install]
163 WantedBy=multi-user.target default.target
164 Generate systemd unit files for a pod with two simple alpine containers
168 Note systemctl should only be used on the pod unit and one should not
169 start or stop containers individually via systemctl, as they are man‐
170 aged by the pod service along with the internal infra-container.
171 You can still use systemctl status or journalctl to examine container
174 or pod unit files.
175 $ podman pod create --name systemd-pod
178 $ podman create --pod systemd-pod alpine top
179 $ podman create --pod systemd-pod alpine top
180 $ podman generate systemd --files --name systemd-pod
181 /home/user/pod-systemd-pod.service
182 /home/user/container-amazing_chandrasekhar.service
183 /home/user/container-jolly_shtern.service
184 $ cat pod-systemd-pod.service
185 # pod-systemd-pod.service
186 # autogenerated by Podman 1.8.0
187 # Wed Mar 09 09:52:37 CEST 2020
188 [Unit]
190 Description=Podman pod-systemd-pod.service
191 Documentation=man:podman-generate-systemd(1)
192 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
193 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
194 Wants=network-online.target
195 After=network-online.target
196 RequiresMountsFor=/var/run/container/storage
197 [Service]
199 Restart=on-failure
200 ExecStart=/usr/bin/podman start 77a818221650-infra
201 ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra
202 KillMode=none
203 Type=forking
204 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
205 [Install]
207 WantedBy=multi-user.target default.target
208 Installation of generated systemd unit files.
212 Podman-generated unit files include an [Install] section, which carries
213 installation information for the unit. It is used by the enable and
214 disable commands of systemctl(1) during installation.
215 Once you have generated the systemd unit file, you can copy the gener‐
218 ated systemd file to /etc/systemd/system for installing as a root user
219 and to $HOME/.config/systemd/user for installing it as a non-root user.
220 Enable the copied unit file or files using systemctl enable.
221 Note: Copying unit files to /etc/systemd/system and enabling it marks
224 the unit file to be automatically started at boot. And similarly, copy‐
225 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
226 unit file to be automatically started on user login.
227 # Generated systemd files.
230 $ podman pod create --name systemd-pod
231 $ podman create --pod systemd-pod alpine top
232 $ podman generate systemd --files --name systemd-pod
233 # Copy all the generated files.
235 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
237 $ systemctl enable pod-systemd-pod.service
238 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
239 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
240 $ systemctl is-enabled pod-systemd-pod.service
241 enabled
242 To run the user services placed in $HOME/.config/systemd/user on first
246 login of that user, enable the service with --user flag.
247 $ systemctl --user enable <.service>
250 The systemd user instance is killed after the last session for the user
254 is closed. The systemd user instance can be kept running ever after the
255 user logs out by enabling lingering using
256 $ loginctl enable-linger <username>
259 Use systemctl to perform operations on generated installed unit files.
263 Create and enable systemd unit files for a pod using the above examples
264 as reference and use systemctl to perform operations.
265 Since systemctl defaults to using the root user, all the changes using
268 the systemctl can be seen by appending sudo to the podman cli commands.
269 To perform systemctl actions as a non-root user use the --user flag
270 when interacting with systemctl.
271 Note: If the previously created containers or pods are using shared re‐
274 sources, such as ports, make sure to remove them before starting the
275 generated systemd units.
276 $ systemctl --user start pod-systemd-pod.service
279 $ podman pod ps
280 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
281 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
282 $ sudo podman ps # 0 Number of pods on root.
283 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
284 $ systemctl stop pod-systemd-pod.service
285 $ podman pod ps
286 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
287 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
288 Create a simple alpine container and generate the systemd unit file
292 with --new flag. Enable the service and control operations using the
293 systemctl commands.
294 Note: When starting the container using systemctl start rather than al‐
297 tering the already running container it spins up a "new" container with
298 similar configuration.
299 # Enable the service.
302 $ sudo podman ps -a
304 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
305 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
306 $ sudo systemctl start container-busy_moser.service
307 $ sudo podman ps -a
308 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
309 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second ago distracted_albattani
310 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
311
315 [podman(1)], [podman-container(1)], systemctl(1), systemd.unit(5), sys‐
316 temd.service(5), conmon(8).
317
320 April 2020, Updated details and added use case to use generated .ser‐
321 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
322 com)
323 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
326 redhat dot com)
327 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
330 com)
331 podman-generate-systemd(1)()