1podman-systemd.unit(5) File Formats Manual podman-systemd.unit(5)
2
6 podman-systemd.unit - systemd units using Podman Quadlet
7
10 name.container, name.volume, name.network, *.kube
11 Podman unit search path
14 • /etc/containers/systemd/
15 • /usr/share/containers/systemd/
17 Podman user unit search path
21 • $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/contain‐
22 ers/systemd/
23 • /etc/containers/systemd/users/$(UID)
25 • /etc/containers/systemd/users/
27
31 Podman supports starting containers (and creating volumes) via systemd
32 by using a systemd generator. These files are read during boot (and
33 when systemctl daemon-reload is run) and generate corresponding regular
34 systemd service unit files. Both system and user systemd units are sup‐
35 ported.
36 The Podman generator reads the search paths above and reads files with
39 the extensions .container .volume and *.kube, and for each file gener‐
40 ates a similarly named .service file. Be aware that existing vendor
41 services (i.e., in /usr/) are replaced if they have the same name. The
42 generated unit files can be started and managed with systemctl like any
43 other systemd service. systemctl {--user} list-unit-files lists exist‐
44 ing unit files on the system.
45 Files with the .network extension are only read if they are mentioned
48 in a .container file. See the Network= key.
49 The Podman files use the same format as regular systemd unit files.
52 Each file type has a custom section (for example, [Container]) that is
53 handled by Podman, and all other sections are passed on untouched, al‐
54 lowing the use of any normal systemd configuration options like depen‐
55 dencies or cgroup limits.
56 For rootless containers, when administrators place Quadlet files in the
59 /etc/containers/systemd/users directory, all users' sessions execute
60 the Quadlet when the login session begins. If the administrator places
61 a Quadlet file in the /etc/containers/systemd/users/${UID}/ directory,
62 then only the user with the matching UID execute the Quadlet when the
63 login session gets started. For unit files placed in subdirectories
64 within /etc/containers/systemd/user/${UID}/ and the other user unit
65 search paths, Quadlet will recursively search and run the unit files
66 present in these subdirectories.
67 Note: When a Quadlet is starting, Podman often pulls one more container
70 images which may take a considerable amount of time. Systemd defaults
71 service start time to 90 seconds, or fails the service. Pre-pulling the
72 image or extending the systemd timeout time for the service using the
73 TimeoutStartSec Service option can fix the problem.
74 Adding the following snippet to a Quadlet file extends the systemd
77 timeout to 15 minutes.
78 [Service]
81 TimeoutStartSec=900
82 Enabling unit files
86 The services created by Podman are considered transient by systemd,
87 which means they don't have the same persistence rules as regular
88 units. In particular, it is not possible to "systemctl enable" them in
89 order for them to become automatically enabled on the next boot.
90 To compensate for this, the generator manually applies the [Install]
93 section of the container definition unit files during generation, in
94 the same way systemctl enable does when run later.
95 For example, to start a container on boot, add something like this to
98 the file:
99 [Install]
102 WantedBy=default.target
103 Currently, only the Alias, WantedBy and RequiredBy keys are supported.
107 NOTE: To express dependencies between containers, use the generated
110 names of the service. In other words WantedBy=other.service, not Want‐
111 edBy=other.container. The same is true for other kinds of dependencies,
112 too, like After=other.service.
113 Debugging unit files
116 After placing the unit file in one of the unit search paths (mentioned
117 above), you can start it with systemctl start {--user}. If it fails
118 with "Failed to start example.service: Unit example.service not
119 found.", then it is possible that you used incorrect syntax or you used
120 an option from a newer version of Podman Quadlet and the generator
121 failed to create a service file.
122 View the generated files and/or error messages with:
125 /usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun
128 Debugging a limited set of unit files
132 If you would like to debug a limited set of unit files, you can copy
133 them to a separate directory and set the QUADLET_UNIT_DIRS environment
134 variable to this directory when running the command below:
135 QUADLET_UNIT_DIRS=<Directory> /usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun
138 This will instruct Quadlet to look for units in this directory instead
142 of the common ones and by that limit the output to only the units you
143 are debugging.
144
147 Container units are named with a .container extension and contain a
148 [Container] section describing the container that is run as a service.
149 The resulting service file contains a line like ExecStart=podman run …
150 image-name, and most of the keys in this section control the command-
151 line options passed to Podman. However, some options also affect the
152 details of how systemd is set up to run and interact with the con‐
153 tainer.
154 By default, the Podman container has the same name as the unit, but
157 with a systemd- prefix, i.e. a $name.container file creates a
158 $name.service unit and a systemd-$name Podman container. The Container‐
159 Name option allows for overriding this default name with a user-pro‐
160 vided one.
161 There is only one required key, Image, which defines the container im‐
164 age the service runs.
165 Valid options for [Container] are listed below:
168 ┌───────────────────────────────┬────────────────────────────────┐
171 │[Container] options │ podman run equivalent │
172 ├───────────────────────────────┼────────────────────────────────┤
173 │AddCapability=CAP │ --cap-add CAP │
174 ├───────────────────────────────┼────────────────────────────────┤
175 │AddDevice=/dev/foo │ --device /dev/foo │
176 ├───────────────────────────────┼────────────────────────────────┤
177 │Annotation="XYZ" │ --annotation "XYZ" │
178 ├───────────────────────────────┼────────────────────────────────┤
179 │AutoUpdate=registry │ --label "io.containers.autoup‐ │
180 │ │ date=registry" │
181 ├───────────────────────────────┼────────────────────────────────┤
182 │ContainerName=name │ --name name │
183 ├───────────────────────────────┼────────────────────────────────┤
184 │DNS=192.168.55.1 │ --dns=192.168.55.1 │
185 ├───────────────────────────────┼────────────────────────────────┤
186 │DNSSearch=foo.com │ --dns-search=foo.com │
187 ├───────────────────────────────┼────────────────────────────────┤
188 │DNSOption=ndots:1 │ --dns-option=ndots:1 │
189 ├───────────────────────────────┼────────────────────────────────┤
190 │DropCapability=CAP │ --cap-drop=CAP │
191 ├───────────────────────────────┼────────────────────────────────┤
192 │Environment=foo=bar │ --env foo=bar │
193 ├───────────────────────────────┼────────────────────────────────┤
194 │EnvironmentFile=/tmp/env │ --env-file /tmp/env │
195 ├───────────────────────────────┼────────────────────────────────┤
196 │EnvironmentHost=true │ --env-host │
197 ├───────────────────────────────┼────────────────────────────────┤
198 │Exec=/usr/bin/command │ Command after image specifica‐ │
199 │ │ tion - /usr/bin/command │
200 ├───────────────────────────────┼────────────────────────────────┤
201 │ExposeHostPort=50-59 │ --expose 50-59 │
202 ├───────────────────────────────┼────────────────────────────────┤
203 │Group=1234 │ --user UID:1234 │
204 ├───────────────────────────────┼────────────────────────────────┤
205 │HealthCmd="/usr/bin/command" │ --health-cmd="/usr/bin/com‐ │
206 │ │ mand" │
207 ├───────────────────────────────┼────────────────────────────────┤
208 │HealthInterval=2m │ --health-interval=2m │
209 ├───────────────────────────────┼────────────────────────────────┤
210 │HealthOnFailure=kill │ --health-on-failure=kill │
211 ├───────────────────────────────┼────────────────────────────────┤
212 │HealthRetries=5 │ --health-retries=5 │
213 ├───────────────────────────────┼────────────────────────────────┤
214 │HealthStartPeriod=1m │ --health-start-period=pe‐ │
215 │ │ riod=1m │
216 ├───────────────────────────────┼────────────────────────────────┤
217 │HealthStartupCmd="command" │ --health-startup-cmd="command" │
218 ├───────────────────────────────┼────────────────────────────────┤
219 │HealthStartupInterval=1m │ --health-startup-interval=1m │
220 ├───────────────────────────────┼────────────────────────────────┤
221 │HealthStartupRetries=8 │ --health-startup-retries=8 │
222 ├───────────────────────────────┼────────────────────────────────┤
223 │HealthStartupSuccess=2 │ --health-startup-success=2 │
224 ├───────────────────────────────┼────────────────────────────────┤
225 │HealthStartupTimeout=1m33s │ --health-startup-timeout=1m33s │
226 ├───────────────────────────────┼────────────────────────────────┤
227 │HealthTimeout=20s │ --health-timeout=20s │
228 ├───────────────────────────────┼────────────────────────────────┤
229 │HostName=new-host-name │ --hostname="new-host-name" │
230 ├───────────────────────────────┼────────────────────────────────┤
231 │Image=ubi8 │ Image specification - ubi8 │
232 ├───────────────────────────────┼────────────────────────────────┤
233 │IP=192.5.0.1 │ --ip 192.5.0.1 │
234 ├───────────────────────────────┼────────────────────────────────┤
235 │IP6=2001:db8::1 │ --ip6 2001:db8::1 │
236 ├───────────────────────────────┼────────────────────────────────┤
237 │Label="XYZ" │ --label "XYZ" │
238 ├───────────────────────────────┼────────────────────────────────┤
239 │LogDriver=journald │ --log-driver journald │
240 ├───────────────────────────────┼────────────────────────────────┤
241 │Mount=type=... │ --mount type=... │
242 ├───────────────────────────────┼────────────────────────────────┤
243 │Network=host │ --net host │
244 ├───────────────────────────────┼────────────────────────────────┤
245 │NoNewPrivileges=true │ --security-opt no-new-privi‐ │
246 │ │ leges │
247 ├───────────────────────────────┼────────────────────────────────┤
248 │Rootfs=/var/lib/rootfs │ --rootfs /var/lib/rootfs │
249 ├───────────────────────────────┼────────────────────────────────┤
250 │Notify=true │ --sdnotify container │
251 ├───────────────────────────────┼────────────────────────────────┤
252 │PidsLimit=10000 │ --pids-limit 10000 │
253 ├───────────────────────────────┼────────────────────────────────┤
254 │PodmanArgs=--add-host foobar │ --add-host foobar │
255 ├───────────────────────────────┼────────────────────────────────┤
256 │PublishPort=50-59 │ --publish 50-59 │
257 ├───────────────────────────────┼────────────────────────────────┤
258 │Pull=never │ --pull=never │
259 ├───────────────────────────────┼────────────────────────────────┤
260 │ReadOnly=true │ --read-only │
261 ├───────────────────────────────┼────────────────────────────────┤
262 │RunInit=true │ --init │
263 ├───────────────────────────────┼────────────────────────────────┤
264 │SeccompProfile=/tmp/s.json │ --security-opt sec‐ │
265 │ │ comp=/tmp/s.json │
266 ├───────────────────────────────┼────────────────────────────────┤
267 │SecurityLabelDisable=true │ --security-opt label=disable │
268 ├───────────────────────────────┼────────────────────────────────┤
269 │SecurityLabelFileType=usr_t │ --security-opt label=file‐ │
270 │ │ type:usr_t │
271 ├───────────────────────────────┼────────────────────────────────┤
272 │SecurityLabelLevel=s0:c1,c2 │ --security-opt la‐ │
273 │ │ bel=level:s0:c1,c2 │
274 ├───────────────────────────────┼────────────────────────────────┤
275 │SecurityLabelNested=true │ --security-opt label=nested │
276 ├───────────────────────────────┼────────────────────────────────┤
277 │SecurityLabelType=spc_t │ --security-opt la‐ │
278 │ │ bel=type:spc_t │
279 ├───────────────────────────────┼────────────────────────────────┤
280 │ShmSize=100m │ --shm-size=100m │
281 ├───────────────────────────────┼────────────────────────────────┤
282 │Sysctl=name=value │ --sysctl=name=value │
283 ├───────────────────────────────┼────────────────────────────────┤
284 │Timezone=local │ --tz local │
285 ├───────────────────────────────┼────────────────────────────────┤
286 │Tmpfs=/work │ --tmpfs /work │
287 ├───────────────────────────────┼────────────────────────────────┤
288 │Ulimit=nofile:1000:10000 │ --ulimit nofile:1000:10000 │
289 ├───────────────────────────────┼────────────────────────────────┤
290 │User=bin │ --user bin │
291 ├───────────────────────────────┼────────────────────────────────┤
292 │UserNS=keep-id:uid=200,gid=210 │ --userns keep- │
293 │ │ id:uid=200,gid=210 │
294 ├───────────────────────────────┼────────────────────────────────┤
295 │VolatileTmp=true │ --tmpfs /tmp │
296 ├───────────────────────────────┼────────────────────────────────┤
297 │Volume=/source:/dest │ --volume /source:/dest │
298 ├───────────────────────────────┼────────────────────────────────┤
299 │WorkingDir=$HOME │ --workdir $HOME │
300 └───────────────────────────────┴────────────────────────────────┘
301 Description of [Container] section are:
303 AddCapability=
306 Add these capabilities, in addition to the default Podman capability
307 set, to the container.
308 This is a space separated list of capabilities. This key can be listed
311 multiple times.
312 For example:
315 AddCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER
318 AddDevice=
322 Adds a device node from the host into the container. The format of this
323 is HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS], where HOST-DEVICE is
324 the path of the device node on the host, CONTAINER-DEVICE is the path
325 of the device node in the container, and PERMISSIONS is a list of per‐
326 missions combining 'r' for read, only if it exists on the host.
327 This key can be listed multiple times.
330 Annotation=
333 Set one or more OCI annotations on the container. The format is a list
334 of key=value items, similar to Environment.
335 This key can be listed multiple times.
338 AutoUpdate=
341 Indicates whether the container will be auto-updated (podman-auto-up‐
342 date(1)). The following values are supported:
343 • registry: Requires a fully-qualified image reference (e.g.,
346 quay.io/podman/stable:latest) to be used to create the con‐
347 tainer. This enforcement is necessary to know which image to
348 actually check and pull. If an image ID was used, Podman does
349 not know which image to check/pull anymore.
350 • local: Tells Podman to compare the image a container is using
352 to the image with its raw name in local storage. If an image
353 is updated locally, Podman simply restarts the systemd unit
354 executing the container.
355 ContainerName=
359 The (optional) name of the Podman container. If this is not specified,
360 the default value of systemd-%N is used, which is the same as the ser‐
361 vice name but with a systemd- prefix to avoid conflicts with user-man‐
362 aged containers.
363 DNS=
366 Set network-scoped DNS resolver/nameserver for containers in this net‐
367 work.
368 This key can be listed multiple times.
371 DNSOption=
374 Set custom DNS options.
375 This key can be listed multiple times.
378 DNSSearch=
381 Set custom DNS search domains. Use DNSSearch=. to remove the search do‐
382 main.
383 This key can be listed multiple times.
386 DropCapability=
389 Drop these capabilities from the default podman capability set, or all
390 to drop all capabilities.
391 This is a space separated list of capabilities. This key can be listed
394 multiple times.
395 For example:
398 DropCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER
401 Environment=
405 Set an environment variable in the container. This uses the same format
406 as services in systemd and can be listed multiple times.
407 EnvironmentFile=
410 Use a line-delimited file to set environment variables in the con‐
411 tainer. The path may be absolute or relative to the location of the
412 unit file. This key may be used multiple times, and the order persists
413 when passed to podman run.
414 EnvironmentHost=
417 Use the host environment inside of the container.
418 Exec=
421 If this is set then it defines what command line to run in the con‐
422 tainer. If it is not set the default entry point of the container image
423 is used. The format is the same as for systemd command lines.
424 ExposeHostPort=
427 Exposes a port, or a range of ports (e.g. 50-59), from the host to the
428 container. Equivalent to the Podman --expose option.
429 This key can be listed multiple times.
432 Group=
435 The (numeric) GID to run as inside the container. This does not need to
436 match the GID on the host, which can be modified with UsersNS, but if
437 that is not specified, this GID is also used on the host.
438 HealthCmd=
441 Set or alter a healthcheck command for a container. A value of none
442 disables existing healthchecks. Equivalent to the Podman --health-cmd
443 option.
444 HealthInterval=
447 Set an interval for the healthchecks. An interval of disable results in
448 no automatic timer setup. Equivalent to the Podman --health-interval
449 option.
450 HealthOnFailure=
453 Action to take once the container transitions to an unhealthy state.
454 The "kill" action in combination integrates best with systemd. Once the
455 container turns unhealthy, it gets killed, and systemd restarts the
456 service. Equivalent to the Podman --health-on-failure option.
457 HealthRetries=
460 The number of retries allowed before a healthcheck is considered to be
461 unhealthy. Equivalent to the Podman --health-retries option.
462 HealthStartPeriod=
465 The initialization time needed for a container to bootstrap. Equiva‐
466 lent to the Podman --health-start-period option.
467 HealthStartupCmd=
470 Set a startup healthcheck command for a container. Equivalent to the
471 Podman --health-startup-cmd option.
472 HealthStartupInterval=
475 Set an interval for the startup healthcheck. An interval of disable re‐
476 sults in no automatic timer setup. Equivalent to the Podman --health-
477 startup-interval option.
478 HealthStartupRetries=
481 The number of attempts allowed before the startup healthcheck restarts
482 the container. Equivalent to the Podman --health-startup-retries op‐
483 tion.
484 HealthStartupSuccess=
487 The number of successful runs required before the startup healthcheck
488 succeeds and the regular healthcheck begins. Equivalent to the Podman
489 --health-startup-success option.
490 HealthStartupTimeout=
493 The maximum time a startup healthcheck command has to complete before
494 it is marked as failed. Equivalent to the Podman --health-startup-
495 timeout option.
496 HealthTimeout=
499 The maximum time allowed to complete the healthcheck before an interval
500 is considered failed. Equivalent to the Podman --health-timeout op‐
501 tion.
502 HostName=
505 Sets the host name that is available inside the container. Equivalent
506 to the Podman --hostname option.
507 Image=
510 The image to run in the container. It is recommended to use a fully
511 qualified image name rather than a short name, both for performance and
512 robustness reasons.
513 The format of the name is the same as when passed to podman run, so it
516 supports e.g., using :tag or using digests guarantee a specific image
517 version.
518 IP=
521 Specify a static IPv4 address for the container, for example
522 10.88.64.128. Equivalent to the Podman --ip option.
523 IP6=
526 Specify a static IPv6 address for the container, for example
527 fd46:db93:aa76:ac37::10. Equivalent to the Podman --ip6 option.
528 Label=
531 Set one or more OCI labels on the container. The format is a list of
532 key=value items, similar to Environment.
533 This key can be listed multiple times.
536 LogDriver=
539 Set the log-driver used by Podman when running the container. Equiva‐
540 lent to the Podman --log-driver option.
541 Mount=
544 Attach a filesystem mount to the container. This is equivalent to the
545 Podman --mount option, and generally has the form type=TYPE,TYPE-SPE‐
546 CIFIC-OPTION[,...].
547 As a special case, for type=volume if source ends with .volume, a Pod‐
550 man named volume called systemd-$name is used as the source, and the
551 generated systemd service contains a dependency on the $name-vol‐
552 ume.service. Such a volume can be automatically be lazily created by
553 using a $name.volume Quadlet file.
554 This key can be listed multiple times.
557 Network=
560 Specify a custom network for the container. This has the same format as
561 the --network option to podman run. For example, use host to use the
562 host network in the container, or none to not set up networking in the
563 container.
564 As a special case, if the name of the network ends with .network, a
567 Podman network called systemd-$name is used, and the generated systemd
568 service contains a dependency on the $name-network.service. Such a net‐
569 work can be automatically created by using a $name.network Quadlet
570 file.
571 This key can be listed multiple times.
574 NoNewPrivileges= (defaults to no)
577 If enabled, this disables the container processes from gaining addi‐
578 tional privileges via things like setuid and file capabilities.
579 Rootfs=
582 The rootfs to use for the container. Rootfs points to a directory on
583 the system that contains the content to be run within the container.
584 This option conflicts with the Image option.
585 The format of the rootfs is the same as when passed to podman run
588 --rootfs, so it supports overlay mounts as well.
589 Note: On SELinux systems, the rootfs needs the correct label, which is
592 by default unconfined_u:object_r:container_file_t:s0.
593 Notify= (defaults to no)
596 By default, Podman is run in such a way that the systemd startup notify
597 command is handled by the container runtime. In other words, the ser‐
598 vice is deemed started when the container runtime starts the child in
599 the container. However, if the container application supports sd_no‐
600 tify, then setting Notify to true passes the notification details to
601 the container allowing it to notify of startup on its own.
602 PidsLimit=
605 Tune the container's pids limit. This is equivalent to the Podman
606 --pids-limit option.
607 PodmanArgs=
610 This key contains a list of arguments passed directly to the end of the
611 podman run command in the generated file (right before the image name
612 in the command line). It can be used to access Podman features other‐
613 wise unsupported by the generator. Since the generator is unaware of
614 what unexpected interactions can be caused by these arguments, it is
615 not recommended to use this option.
616 The format of this is a space separated list of arguments, which can
619 optionally be individually escaped to allow inclusion of whitespace and
620 other control characters.
621 This key can be listed multiple times.
624 PublishPort=
627 Exposes a port, or a range of ports (e.g. 50-59), from the container to
628 the host. Equivalent to the Podman --publish option. The format is sim‐
629 ilar to the Podman options, which is of the form ip:hostPort:container‐
630 Port, ip::containerPort, hostPort:containerPort or containerPort, where
631 the number of host and container ports must be the same (in the case of
632 a range).
633 If the IP is set to 0.0.0.0 or not set at all, the port is bound on all
636 IPv4 addresses on the host; use [::] for IPv6.
637 Note that not listing a host port means that Podman automatically se‐
640 lects one, and it may be different for each invocation of service. This
641 makes that a less useful option. The allocated port can be found with
642 the podman port command.
643 This key can be listed multiple times.
646 Pull=
649 Set the image pull policy. This is equivalent to the Podman --pull op‐
650 tion
651 ReadOnly= (defaults to no)
654 If enabled, makes the image read-only.
655 RunInit= (default to no)
658 If enabled, the container has a minimal init process inside the con‐
659 tainer that forwards signals and reaps processes.
660 SeccompProfile=
663 Set the seccomp profile to use in the container. If unset, the default
664 podman profile is used. Set to either the pathname of a json file, or
665 unconfined to disable the seccomp filters.
666 SecurityLabelDisable=
669 Turn off label separation for the container.
670 SecurityLabelFileType=
673 Set the label file type for the container files.
674 SecurityLabelLevel=
677 Set the label process level for the container processes.
678 SecurityLabelNested=
681 Allow SecurityLabels to function within the container. This allows sep‐
682 aration of containers created within the container.
683 SecurityLabelType=
686 Set the label process type for the container processes.
687 Secret=
690 Use a Podman secret in the container either as a file or an environment
691 variable. This is equivalent to the Podman --secret option and gener‐
692 ally has the form secret[,opt=opt ...]
693 ShmSize=
696 Size of /dev/shm.
697 This is equivalent to the Podman --shm-size option and generally has
700 the form number[unit]
701 Sysctl=
704 Configures namespaced kernel parameters for the container. The format
705 is Sysctl=name=value.
706 This is a space separated list of kernel parameters. This key can be
709 listed multiple times.
710 For example:
713 Sysctl=net.ipv6.conf.all.disable_ipv6=1 net.ipv6.conf.all.use_tempaddr=1
716 Tmpfs=
720 Mount a tmpfs in the container. This is equivalent to the Podman
721 --tmpfs option, and generally has the form CONTAINER-DIR[:OPTIONS].
722 This key can be listed multiple times.
725 Timezone= (if unset uses system-configured default)
728 The timezone to run the container in.
729 Ulimit=
732 Ulimit options. Sets the ulimits values inside of the container.
733 User=
736 The (numeric) UID to run as inside the container. This does not need to
737 match the UID on the host, which can be modified with UserNS, but if
738 that is not specified, this UID is also used on the host.
739 UserNS=
742 Set the user namespace mode for the container. This is equivalent to
743 the Podman --userns option and generally has the form MODE[:OP‐
744 TIONS,...].
745 VolatileTmp= (defaults to no)
748 If enabled, the container has a fresh tmpfs mounted on /tmp.
749 NOTE: Podman automatically copies any content from the image onto the
752 tmpfs
753 Volume=
756 Mount a volume in the container. This is equivalent to the Podman
757 --volume option, and generally has the form [[SOURCE-VOLUME|HOST-
758 DIR:]CONTAINER-DIR[:OPTIONS]].
759 If SOURCE-VOLUME starts with ., Quadlet resolves the path relative to
762 the location of the unit file.
763 As a special case, if SOURCE-VOLUME ends with .volume, a Podman named
766 volume called systemd-$name is used as the source, and the generated
767 systemd service contains a dependency on the $name-volume.service. Such
768 a volume can be automatically be lazily created by using a $name.volume
769 Quadlet file.
770 This key can be listed multiple times.
773 WorkingDir=
776 Working directory inside the container.
777 The default working directory for running binaries within a container
780 is the root directory (/). The image developer can set a different de‐
781 fault with the WORKDIR instruction. This option overrides the working
782 directory by using the -w option.
783
786 Kube units are named with a .kube extension and contain a [Kube] sec‐
787 tion describing how podman kube play runs as a service. The resulting
788 service file contains a line like ExecStart=podman kube play …
789 file.yml, and most of the keys in this section control the command-line
790 options passed to Podman. However, some options also affect the details
791 of how systemd is set up to run and interact with the container.
792 There is only one required key, Yaml, which defines the path to the Ku‐
795 bernetes YAML file.
796 Valid options for [Kube] are listed below:
799 ┌──────────────────────────────────┬────────────────────────────────────────────────────────────────┐
802 │[Kube] options │ podman kube play equivalent │
803 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
804 │AutoUpdate=registry │ --annotation "io.containers.autoupdate=registry" │
805 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
806 │ConfigMap=/tmp/config.map │ --config-map /tmp/config.map │
807 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
808 │LogDriver=journald │ --log-driver journald │
809 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
810 │Network=host │ --net host │
811 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
812 │PodmanArgs=--annotation=key=value │ --annotation=key=value │
813 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
814 │PublishPort=59-60 │ --publish=59-60 │
815 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
816 │SetWorkingDirectory=yaml │ Set WorkingDirectory of unit file to location of the YAML file │
817 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
818 │UserNS=keep-id:uid=200,gid=210 │ --userns keep-id:uid=200,gid=210 │
819 ├──────────────────────────────────┼────────────────────────────────────────────────────────────────┤
820 │Yaml=/tmp/kube.yaml │ podman kube play /tmp/kube.yaml │
821 └──────────────────────────────────┴────────────────────────────────────────────────────────────────┘
822 Supported keys in the [Kube] section are:
824 AutoUpdate=
827 Indicates whether containers will be auto-updated (podman-auto-up‐
828 date(1)). AutoUpdate can be specified multiple times. The following
829 values are supported:
830 • registry: Requires a fully-qualified image reference (e.g.,
833 quay.io/podman/stable:latest) to be used to create the con‐
834 tainer. This enforcement is necessary to know which images to
835 actually check and pull. If an image ID was used, Podman does
836 not know which image to check/pull anymore.
837 • local: Tells Podman to compare the image a container is using
839 to the image with its raw name in local storage. If an image
840 is updated locally, Podman simply restarts the systemd unit
841 executing the Kubernetes Quadlet.
842 • name/(local|registry): Tells Podman to perform the local or
844 registry autoupdate on the specified container name.
845 ConfigMap=
849 Pass the Kubernetes ConfigMap YAML path to podman kube play via the
850 --configmap argument. Unlike the configmap argument, the value may
851 contain only one path but it may be absolute or relative to the loca‐
852 tion of the unit file.
853 This key may be used multiple times
856 ExitCodePropagation=
859 Control how the main PID of the systemd service should exit. The fol‐
860 lowing values are supported: - all: exit non-zero if all containers
861 have failed (i.e., exited non-zero) - any: exit non-zero if any con‐
862 tainer has failed - none: exit zero and ignore failed containers
863 The current default value is none.
866 LogDriver=
869 Set the log-driver Podman uses when running the container. Equivalent
870 to the Podman --log-driver option.
871 Mask=
874 Specify the paths to mask separated by a colon. Mask=/path/1:/path/2.
875 A masked path cannot be accessed inside the container.
876 Network=
879 Specify a custom network for the container. This has the same format as
880 the --network option to podman kube play. For example, use host to use
881 the host network in the container, or none to not set up networking in
882 the container.
883 As a special case, if the name of the network ends with .network, a
886 Podman network called systemd-$name is used, and the generated systemd
887 service contains a dependency on the $name-network.service. Such a net‐
888 work can be automatically created by using a $name.network Quadlet
889 file.
890 This key can be listed multiple times.
893 PodmanArgs=
896 This key contains a list of arguments passed directly to the end of the
897 podman kube play command in the generated file (right before the path
898 to the yaml file in the command line). It can be used to access Podman
899 features otherwise unsupported by the generator. Since the generator is
900 unaware of what unexpected interactions can be caused by these argu‐
901 ments, is not recommended to use this option.
902 The format of this is a space separated list of arguments, which can
905 optionally be individually escaped to allow inclusion of whitespace and
906 other control characters.
907 This key can be listed multiple times.
910 PublishPort=
913 Exposes a port, or a range of ports (e.g. 50-59), from the container to
914 the host. Equivalent to the podman kube play's --publish option. The
915 format is similar to the Podman options, which is of the form ip:host‐
916 Port:containerPort, ip::containerPort, hostPort:containerPort or con‐
917 tainerPort, where the number of host and container ports must be the
918 same (in the case of a range).
919 If the IP is set to 0.0.0.0 or not set at all, the port is bound on all
922 IPv4 addresses on the host; use [::] for IPv6.
923 The list of published ports specified in the unit file is merged with
926 the list of ports specified in the Kubernetes YAML file. If the same
927 container port and protocol is specified in both, the entry from the
928 unit file takes precedence
929 This key can be listed multiple times.
932 SetWorkingDirectory=
935 Set the WorkingDirectory field of the Service group of the Systemd ser‐
936 vice unit file. Used to allow podman kube play to correctly resolve
937 relative paths. Supported values are yaml and unit to set the working
938 directory to that of the YAML or Quadlet Unit file respectively.
939 Alternatively, users can explicitly set the WorkingDirectory field of
942 the Service group in the .kube file. Please note that if the Work‐
943 ingDirectory field of the Service group is set, Quadlet will not set it
944 even if SetWorkingDirectory is set
945 Unmask=
948 Specify the paths to unmask separated by a colon. unmask=ALL or
949 /path/1:/path/2, or shell expanded paths (/proc/*):
950 If set to ALL, Podman will unmask all the paths that are masked or made
953 read-only by default.
954 The default masked paths are /proc/acpi, /proc/kcore, /proc/keys,
957 /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list,
958 /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.
959 The default paths that are read-only are /proc/asound, /proc/bus,
962 /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
963 UserNS=
966 Set the user namespace mode for the container. This is equivalent to
967 the Podman --userns option and generally has the form MODE[:OP‐
968 TIONS,...].
969 Yaml=
972 The path, absolute or relative to the location of the unit file, to the
973 Kubernetes YAML file to use.
974
977 Network files are named with a .network extension and contain a section
978 [Network] describing the named Podman network. The generated service is
979 a one-time command that ensures that the network exists on the host,
980 creating it if needed.
981 By default, the Podman network has the same name as the unit, but with
984 a systemd- prefix, i.e. for a network file named $NAME.network, the
985 generated Podman network is called systemd-$NAME, and the generated
986 service file is $NAME-network.service. The NetworkName option allows
987 for overriding this default name with a user-provided one.
988 Please note that stopping the corresponding service will not remove the
991 podman network. In addition, updating an existing network is not sup‐
992 ported. In order to update the network parameters you will first need
993 to manually remove the podman network and then restart the service.
994 Using network units allows containers to depend on networks being auto‐
997 matically pre-created. This is particularly interesting when using spe‐
998 cial options to control network creation, as Podman otherwise creates
999 networks with the default options.
1000 Valid options for [Network] are listed below:
1003 ┌──────────────────────────────┬──────────────────────────────────┐
1006 │[Network] options │ podman network create equivalent │
1007 ├──────────────────────────────┼──────────────────────────────────┤
1008 │DisableDNS=true │ --disable-dns │
1009 ├──────────────────────────────┼──────────────────────────────────┤
1010 │DNS=192.168.55.1 │ --dns=192.168.55.1 │
1011 ├──────────────────────────────┼──────────────────────────────────┤
1012 │Driver=bridge │ --driver bridge │
1013 ├──────────────────────────────┼──────────────────────────────────┤
1014 │Gateway=192.168.55.3 │ --gateway 192.168.55.3 │
1015 ├──────────────────────────────┼──────────────────────────────────┤
1016 │Internal=true │ --internal │
1017 ├──────────────────────────────┼──────────────────────────────────┤
1018 │IPAMDriver=dhcp │ --ipam-driver dhcp │
1019 ├──────────────────────────────┼──────────────────────────────────┤
1020 │IPRange=192.168.55.128/25 │ --ip-range 192.168.55.128/25 │
1021 ├──────────────────────────────┼──────────────────────────────────┤
1022 │IPv6=true │ --ipv6 │
1023 ├──────────────────────────────┼──────────────────────────────────┤
1024 │Label="XYZ" │ --label "XYZ" │
1025 ├──────────────────────────────┼──────────────────────────────────┤
1026 │NetworkName=foo │ podman network create foo │
1027 ├──────────────────────────────┼──────────────────────────────────┤
1028 │Options=isolate │ --opt isolate │
1029 ├──────────────────────────────┼──────────────────────────────────┤
1030 │PodmanArgs=--dns=192.168.55.1 │ --dns=192.168.55.1 │
1031 ├──────────────────────────────┼──────────────────────────────────┤
1032 │Subnet=192.5.0.0/16 │ --subnet 192.5.0.0/16 │
1033 └──────────────────────────────┴──────────────────────────────────┘
1034 Supported keys in [Network] section are:
1036 DisableDNS= (defaults to no)
1039 If enabled, disables the DNS plugin for this network.
1040 This is equivalent to the Podman --disable-dns option
1043 DNS=
1046 Set network-scoped DNS resolver/nameserver for containers in this net‐
1047 work.
1048 This key can be listed multiple times.
1051 Driver= (defaults to bridge)
1054 Driver to manage the network. Currently bridge, macvlan and ipvlan are
1055 supported.
1056 This is equivalent to the Podman --driver option
1059 Gateway=
1062 Define a gateway for the subnet. If you want to provide a gateway ad‐
1063 dress, you must also provide a subnet option.
1064 This is equivalent to the Podman --gateway option
1067 This key can be listed multiple times.
1070 Internal= (defaults to no)
1073 Restrict external access of this network.
1074 This is equivalent to the Podman --internal option
1077 IPAMDriver=
1080 Set the ipam driver (IP Address Management Driver) for the network.
1081 Currently host-local, dhcp and none are supported.
1082 This is equivalent to the Podman --ipam-driver option
1085 IPRange=
1088 Allocate container IP from a range. The range must be a either a
1089 complete subnet in CIDR notation or be in the <startIP>-<endIP> syntax
1090 which allows for a more flexible range compared to the CIDR subnet.
1091 The ip-range option must be used with a subnet option.
1092 This is equivalent to the Podman --ip-range option
1095 This key can be listed multiple times.
1098 IPv6=
1101 Enable IPv6 (Dual Stack) networking.
1102 This is equivalent to the Podman --ipv6 option
1105 Label=
1108 Set one or more OCI labels on the network. The format is a list of
1109 key=value items, similar to Environment.
1110 This key can be listed multiple times.
1113 NetworkName=
1116 The (optional) name of the Podman network. If this is not specified,
1117 the default value of systemd-%N is used, which is the same as the unit
1118 name but with a systemd- prefix to avoid conflicts with user-managed
1119 networks.
1120 Options=
1123 Set driver specific options.
1124 This is equivalent to the Podman --opt option
1127 PodmanArgs=
1130 This key contains a list of arguments passed directly to the end of the
1131 podman network create command in the generated file (right before the
1132 name of the network in the command line). It can be used to access Pod‐
1133 man features otherwise unsupported by the generator. Since the genera‐
1134 tor is unaware of what unexpected interactions can be caused by these
1135 arguments, is not recommended to use this option.
1136 The format of this is a space separated list of arguments, which can
1139 optionally be individually escaped to allow inclusion of whitespace and
1140 other control characters.
1141 This key can be listed multiple times.
1144 Subnet=
1147 The subnet in CIDR notation.
1148 This is equivalent to the Podman --subnet option
1151 This key can be listed multiple times.
1154
1157 Volume files are named with a .volume extension and contain a section
1158 [Volume] describing the named Podman volume. The generated service is a
1159 one-time command that ensures that the volume exists on the host, cre‐
1160 ating it if needed.
1161 By default, the Podman volume has the same name as the unit, but with a
1164 systemd- prefix, i.e. for a volume file named $NAME.volume, the gener‐
1165 ated Podman volume is called systemd-$NAME, and the generated service
1166 file is $NAME-volume.service. The VolumeName option allows for overrid‐
1167 ing this default name with a user-provided one.
1168 Using volume units allows containers to depend on volumes being auto‐
1171 matically pre-created. This is particularly interesting when using spe‐
1172 cial options to control volume creation, as Podman otherwise creates
1173 volumes with the default options.
1174 Valid options for [Volume] are listed below:
1177 ┌──────────────────────────┬─────────────────────────────────┐
1180 │[Volume] options │ podman volume create equivalent │
1181 ├──────────────────────────┼─────────────────────────────────┤
1182 │Device=tmpfs │ --opt device=tmpfs │
1183 ├──────────────────────────┼─────────────────────────────────┤
1184 │Copy=true │ --opt copy │
1185 ├──────────────────────────┼─────────────────────────────────┤
1186 │Group=192 │ --opt group=192 │
1187 ├──────────────────────────┼─────────────────────────────────┤
1188 │Label="foo=bar" │ --label "foo=bar" │
1189 ├──────────────────────────┼─────────────────────────────────┤
1190 │Options=XYZ │ --opt XYZ │
1191 ├──────────────────────────┼─────────────────────────────────┤
1192 │PodmanArgs=--driver=image │ --driver=image │
1193 ├──────────────────────────┼─────────────────────────────────┤
1194 │VolumeName=foo │ podman volume create foo │
1195 └──────────────────────────┴─────────────────────────────────┘
1196 Supported keys in [Volume] section are:
1198 Copy= (default to yes)
1201 If enabled, the content of the image located at the mountpoint of the
1202 volume is copied into the volume on the first run.
1203 Device=
1206 The path of a device which is mounted for the volume.
1207 Group=
1210 The host (numeric) GID, or group name to use as the group for the vol‐
1211 ume
1212 Label=
1215 Set one or more OCI labels on the volume. The format is a list of
1216 key=value items, similar to Environment.
1217 This key can be listed multiple times.
1220 Options=
1223 The mount options to use for a filesystem as used by the mount(8) com‐
1224 mand -o option.
1225 PodmanArgs=
1228 This key contains a list of arguments passed directly to the end of the
1229 podman volume create command in the generated file (right before the
1230 name of the network in the command line). It can be used to access Pod‐
1231 man features otherwise unsupported by the generator. Since the genera‐
1232 tor is unaware of what unexpected interactions can be caused by these
1233 arguments, is not recommended to use this option.
1234 The format of this is a space separated list of arguments, which can
1237 optionally be individually escaped to allow inclusion of whitespace and
1238 other control characters.
1239 This key can be listed multiple times.
1242 Type=
1245 The filesystem type of Device as used by the mount(8) commands -t op‐
1246 tion.
1247 User=
1250 The host (numeric) UID, or user name to use as the owner for the volume
1251 VolumeName=
1254 The (optional) name of the Podman volume. If this is not specified, the
1255 default value of systemd-%N is used, which is the same as the unit name
1256 but with a systemd- prefix to avoid conflicts with user-managed vol‐
1257 umes.
1258
1261 Example test.container:
1262 [Unit]
1265 Description=A minimal container
1266 [Container]
1268 # Use the centos image
1269 Image=quay.io/centos/centos:latest
1270 # Use volume and network defined below
1272 Volume=test.volume:/data
1273 Network=test.network
1274 # In the container we just run sleep
1276 Exec=sleep 60
1277 [Service]
1279 # Restart service when sleep finishes
1280 Restart=always
1281 # Extend Timeout to allow time to pull the image
1282 TimeoutStartSec=900
1283 [Install]
1285 # Start by default on boot
1286 WantedBy=multi-user.target default.target
1287 Example test.kube:
1291 [Unit]
1294 Description=A kubernetes yaml based service
1295 Before=local-fs.target
1296 [Kube]
1298 Yaml=/opt/k8s/deployment.yml
1299 [Install]
1301 # Start by default on boot
1302 WantedBy=multi-user.target default.target
1303 Example test.volume:
1307 [Volume]
1310 User=root
1311 Group=root
1312 Label=org.test.Key=value
1313 Example test.network:
1317 [Network]
1320 Subnet=172.16.0.0/24
1321 Gateway=172.16.0.1
1322 IPRange=172.16.0.0/28
1323 Label=org.test.Key=value
1324
1328 systemd.unit(5), systemd.service(5), podman-run(1), podman-network-cre‐
1329 ate(1), podman-auto-update(1)
1330 podman-systemd.unit(5)