podman-volume.unit(5)

okay so bestie, welcome to podman-volume.unit(5) — it lives in the File Formats Manual section, and it's literally the glow-up guide for systemd unit files that manage container volumes with Podman Quadlet 🦋

---

✨ NAME ✨

podman-volume.unit — systemd unit files for managing container volumes using Podman Quadlet 💅

---

🌸 SYNOPSIS 🌸

name.volume

---

🎀 DESCRIPTION 🎀

So here's the tea: volume files are named with a .volume extension, and they contain a section called [Volume] that describes the named Podman volume. The generated service is a one-time command that makes sure the volume exists on the host — creating it if needed. Slay, honestly. ✨

By default, the Podman volume has the same name as the unit, but with a systemd- prefix. Like, for a volume file named $NAME.volume, the generated Podman volume is called systemd-$NAME, and the generated service file is $NAME-volume.service. The VolumeName option lets you override this default name with one you provide yourself, no big deal 💁

Using volume units is lowkey iconic because it lets containers depend on volumes being automatically pre-created. It's especially interesting when you're using special options to control volume creation — because otherwise Podman just creates volumes with the default options, and we don't want that, bestie 😭

---

🧚 USAGE SUMMARY 🧚

The .volume file is parsed by the podman-system-generator at boot or reload, generating a systemd .service that runs podman volume create. That's it. That's the whole vibe. 💜

---

👑 OPTIONS 👑

Valid options for [Volume] are listed below — here's your lil mapping cheat sheet, where each [Volume] option gets matched up with its podman volume create equivalent 🫶

• ContainersConfModule=/etc/nvd.conf → --module=/etc/nvd.conf
• Copy=true → --opt copy
• Device=tmpfs → --opt device=tmpfs
• Driver=image → --driver=image
• GlobalArgs=--log-level=debug → --log-level=debug
• Group=192 → --opt group=192
• Image=quay.io/centos/centos:latest → --opt image=quay.io/centos/centos:latest
• Label="foo=bar" → --label "foo=bar"
• Options=XYZ → --opt "o=XYZ"
• PodmanArgs=--driver=image → --driver=image
• Type=type → Filesystem type of Device
• User=123 → --opt uid=123
• VolumeName=foo → podman volume create foo

Supported keys in the [Volume] section are:

🍓 ContainersConfModule=module

Load the specified containers.conf(5) module. Fr fr, that's it.

This option can be listed multiple times 💫

🍓 Copy=bool (defaults to true)

If enabled, the content of the image located at the mount point of the volume is copied into the volume on the first run. One-time copy, no cap.

🍓 Device=

The path of a device which is mounted for the volume.

🍓 Driver=

Specify the volume driver name. Heads up bestie: when set to image, the Image key must also be set.

This is equivalent to the Podman --driver option.

🍓 GlobalArgs=

This key contains a list of arguments passed directly after the podman command in the generated file. It can be used to access Podman features that are otherwise unsupported by the generator. But like… since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option 🙈

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

🍓 Group=

The host (numeric) GID, or group name to use as the group for the volume.

🍓 Image=

Specifies the image the volume is based on when Driver is set to image. It is recommended to use a fully qualified image name rather than a short name — both for performance and robustness reasons. Do it, bestie, your future self will thank you 💖

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version. Periodt.

Special case:

• If the name of the image ends with .image, Quadlet will use the image pulled by the corresponding .image file, and the generated systemd service contains a dependency on the $name-image.service (or the service name set in the .image file). Note: the corresponding .image file must exist.

🍓 Label=

Set one or more OCI labels on the volume. The format is a list of key=value items, similar to Environment.

This key can be listed multiple times.

🍓 Options=

The mount options to use for a filesystem as used by the mount(8) command -o option.

🍓 PodmanArgs=

This key contains a list of arguments passed directly to the end of the podman command in the generated file. It can be used to access Podman features that are otherwise unsupported by the generator. Again though — since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option 💀

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

🍓 Type=

The filesystem type of Device as used by the mount(8) command's -t option.

🍓 User=

The host (numeric) UID, or user name to use as the owner for the volume.

🍓 VolumeName=

The (optional) name of the Podman volume. If this is not specified, the default value is the same name as the unit, but with a systemd- prefix — i.e. a $name.volume file creates a systemd-$name Podman volume, so there's no conflict with user-managed volumes. Clever, right? 💅

---

🌈 EXAMPLE 🌈

Minimal volume unit, cute and to the point:

[Volume]
VolumeName=mydata
Label=app=data
User=1000
Group=1000

Volume unit backed by an image — this one's giving main character energy:

[Volume]
VolumeName=html
Driver=image
Image=quay.io/centos/centos:latest
Copy=true

---

🦋 SEE ALSO 🦋

systemd.unit(5), podman-systemd.unit(5), podman-volume-create(1)

---

and that's the whole page, bestie — mwah 💋 this lil sign-off is brought to you by podman-volume.unit(5), iykyk 🎀✨