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 --no-header
60 Do not generate the header including meta data such as the Podman ver‐
61 sion and the timestamp.
62 --time, -t=value
65 Override the default stop timeout for the container with the given
66 value.
67 --restart-policy=policy
70 Set the systemd restart policy. The restart-policy must be one of:
71 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog",
72 "on-abort", or "always". The default policy is on-failure.
73 --container-prefix=prefix
76 Set the systemd unit name prefix for containers. The default is con‐
77 tainer.
78 --pod-prefix=prefix
81 Set the systemd unit name prefix for pods. The default is pod.
82 --separator=separator
85 Set the systemd unit name separator between the name/id of a con‐
86 tainer/pod and the prefix. The default is -.
87
90 Generate and print a systemd unit file for a container
91 Generate a systemd unit file for a container running nginx with an al‐
92 ways restart policy and 1-second timeout to stdout. Note that the Re‐
93 quiresMountsFor option in the Unit section ensures that the container
94 storage for both the GraphRoot and the RunRoot are mounted prior to
95 starting the service. For systems with container storage on disks like
96 iSCSI or other remote block protocols, this ensures that Podman is not
97 executed prior to any necessary storage operations coming online.
98 $ podman create --name nginx nginx:latest
101 $ podman generate systemd --restart-policy=always -t 1 nginx
102 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
103 # autogenerated by Podman 1.8.0
104 # Wed Mar 09 09:46:45 CEST 2020
105 [Unit]
107 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
108 Documentation=man:podman-generate-systemd(1)
109 Wants=network.target
110 After=network-online.target
111 RequiresMountsFor=/var/run/container/storage
112 [Service]
114 Restart=always
115 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
116 ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
117 KillMode=none
118 Type=forking
119 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid
120 [Install]
122 WantedBy=multi-user.target default.target
123 Generate systemd unit file for a container with --new flag
127 The --new flag generates systemd unit files that create and remove con‐
128 tainers at service start and stop commands (see ExecStartPre and Exec‐
129 StopPost service actions). Such unit files are not tied to a single ma‐
130 chine and can easily be shared and used on other machines.
131 $ sudo podman generate systemd --new --files --name bb310a0780ae
134 # container-busy_moser.service
135 # autogenerated by Podman 1.8.3
136 # Fri Apr 3 09:40:47 EDT 2020
137 [Unit]
139 Description=Podman container-busy_moser.service
140 Documentation=man:podman-generate-systemd(1)
141 Wants=network.target
142 After=network-online.target
143 RequiresMountsFor=/var/run/container/storage
144 [Service]
146 Environment=PODMAN_SYSTEMD_UNIT=%n
147 Restart=on-failure
148 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
149 ExecStart=/usr/local/bin/podman run --conmon-pidfile %t/%n-pid --cidfile %t/%n-cid --cgroups=no-conmon -d -dit alpine
150 ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10
151 ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid
152 PIDFile=%t/%n-pid
153 KillMode=none
154 Type=forking
155 [Install]
157 WantedBy=multi-user.target default.target
158 Generate systemd unit files for a pod with two simple alpine containers
162 Note systemctl should only be used on the pod unit and one should not
163 start or stop containers individually via systemctl, as they are man‐
164 aged by the pod service along with the internal infra-container.
165 You can still use systemctl status or journalctl to examine container
168 or pod unit files.
169 $ podman pod create --name systemd-pod
172 $ podman create --pod systemd-pod alpine top
173 $ podman create --pod systemd-pod alpine top
174 $ podman generate systemd --files --name systemd-pod
175 /home/user/pod-systemd-pod.service
176 /home/user/container-amazing_chandrasekhar.service
177 /home/user/container-jolly_shtern.service
178 $ cat pod-systemd-pod.service
179 # pod-systemd-pod.service
180 # autogenerated by Podman 1.8.0
181 # Wed Mar 09 09:52:37 CEST 2020
182 [Unit]
184 Description=Podman pod-systemd-pod.service
185 Documentation=man:podman-generate-systemd(1)
186 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
187 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
188 Wants=network.target
189 After=network-online.target
190 RequiresMountsFor=/var/run/container/storage
191 [Service]
193 Restart=on-failure
194 ExecStart=/usr/bin/podman start 77a818221650-infra
195 ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra
196 KillMode=none
197 Type=forking
198 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid
199 [Install]
201 WantedBy=multi-user.target default.target
202 Installation of generated systemd unit files.
206 Podman-generated unit files include an [Install] section, which carries
207 installation information for the unit. It is used by the enable and
208 disable commands of systemctl(1) during installation.
209 Once you have generated the systemd unit file, you can copy the gener‐
212 ated systemd file to /etc/systemd/system for installing as a root user
213 and to $HOME/.config/systemd/user for installing it as a non-root user.
214 Enable the copied unit file or files using systemctl enable.
215 Note: Copying unit files to /etc/systemd/system and enabling it marks
218 the unit file to be automatically started at boot. And similarly, copy‐
219 ing a unit file to $HOME/.config/systemd/user and enabling it marks the
220 unit file to be automatically started on user login.
221 # Generated systemd files.
224 $ podman pod create --name systemd-pod
225 $ podman create --pod systemd-pod alpine top
226 $ podman generate systemd --files --name systemd-pod
227 # Copy all the generated files.
229 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
231 $ systemctl enable pod-systemd-pod.service
232 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
233 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
234 $ systemctl is-enabled pod-systemd-pod.service
235 enabled
236 To run the user services placed in $HOME/.config/systemd/user on first
240 login of that user, enable the service with --user flag.
241 $ systemctl --user enable <.service>
244 The systemd user instance is killed after the last session for the user
248 is closed. The systemd user instance can be kept running ever after the
249 user logs out by enabling lingering using
250 $ loginctl enable-linger <username>
253 Use systemctl to perform operations on generated installed unit files.
257 Create and enable systemd unit files for a pod using the above examples
258 as reference and use systemctl to perform operations.
259 Since systemctl defaults to using the root user, all the changes using
262 the systemctl can be seen by appending sudo to the podman cli commands.
263 To perform systemctl actions as a non-root user use the --user flag
264 when interacting with systemctl.
265 Note: If the previously created containers or pods are using shared re‐
268 sources, such as ports, make sure to remove them before starting the
269 generated systemd units.
270 $ systemctl --user start pod-systemd-pod.service
273 $ podman pod ps
274 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
275 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe
276 $ sudo podman ps # 0 Number of pods on root.
277 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
278 $ systemctl stop pod-systemd-pod.service
279 $ podman pod ps
280 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID
281 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe
282 Create a simple alpine container and generate the systemd unit file
286 with --new flag. Enable the service and control operations using the
287 systemctl commands.
288 Note: When starting the container using systemctl start rather than al‐
291 tering the already running container it spins up a "new" container with
292 similar configuration.
293 # Enable the service.
296 $ sudo podman ps -a
298 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
299 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser
300 $ sudo systemctl start container-busy_moser.service
301 $ sudo podman ps -a
302 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
303 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second ago distracted_albattani
304 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
305
309 [podman(1)], [podman-container(1)], systemctl(1), systemd.unit(5), sys‐
310 temd.service(5), conmon(8).
311
314 April 2020, Updated details and added use case to use generated .ser‐
315 vice files as root and non-root, by Sujil Shah (sushah at redhat dot
316 com)
317 August 2019, Updated with pod support by Valentin Rothberg (rothberg at
320 redhat dot com)
321 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot
324 com)
325 podman-generate-systemd(1)()