% podman-volume.unit(5)

# NAME

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

# SYNOPSIS

*name*.container

# DESCRIPTION

Volume files are named with a `.volume` extension and contain a section `[Volume]` describing the
named Podman volume. The generated service is a one-time command that ensures that the volume
exists on the host, creating it if needed.

By default, the Podman volume has the same name as the unit, but with a `systemd-` prefix, i.e. 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 allows for overriding this
default name with a user-provided one.

Using volume units allows containers to depend on volumes being automatically pre-created. This is
particularly interesting when using special options to control volume creation,
as Podman otherwise creates volumes with the default options.

# FILE LOCATIONS

Place `.pod` files in one of the following:

### Rootless

- `$XDG_RUNTIME_DIR/containers/systemd/`
- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
- `/etc/containers/systemd/users/$(UID)`
- `/etc/containers/systemd/users/`

### Rootful

- `/run/containers/systemd/`
- `/etc/containers/systemd/`
- `/usr/share/containers/systemd/`

# OPTIONS

Valid options for `[Volume]` are listed below:

| **[Volume] options**                | **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 `[Volume]` section are:

@@option quadlet:module

### `Copy=` (default to `true`)

If enabled, the content of the image located at the mountpoint of the volume is copied into the
volume on the first run.

### `Device=`

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

### `Driver=`

Specify the volume driver name. When set to `image`, the `Image` key must also be set.

This is equivalent to the Podman `--driver` option.

@@option quadlet:global-args


### `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 the `image`.
It is recommended to use a fully qualified image name rather than a short name, both for
performance and robustness reasons.

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.

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.

@@option quadlet:podman-args

### `Type=`

The filesystem type of `Device` as used by the **mount(8)** commands `-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 to avoid
conflicts with user-managed volumes.

# EXAMPLE

Minimal volume unit:

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

Volume unit backed by an image:

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

# SEE ALSO

[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html),
[podman-volume-create(1)](https://docs.podman.io/en/latest/markdown/podman-volume-create.1.html),
[podman-quadlet(7)]