Volumes

To enable data persistence and to obtain better performance, application data must reside in Podman volumes. A volume, passed via podman run --volume parameter can be of these types:

Local directory, bind-mounted into the container filesystem.
Single local file, copied into the container filesystem when podman run is invoked.
Podman named volume.

The following example shows how multiple volumes can be defined for a service in the Systemd dovecot.service unit:

[Service]
...
ExecStart=/usr/bin/podman run \
    ...
    --volume=dovecot-data:/var/lib/vmail \
    --volume=./tls-certs:/etc/ssl/dovecot:z \
    --volume=dovecot-dict:/var/lib/dovecot/dict:z \
    --volume=dovecot-lmtp:/var/lib/umail:z \
    --volume=dovecot-custom:/etc/dovecot/local.conf.d:z \
    ${MAIL_DOVECOT_IMAGE}

The above podman run arguments define:

Four named volumes: dovecot-data, dovecot-dict, dovecot-lmtp, and dovecot-custom. Named volumes are typically used to store application data persistently. In some cases, they are shared between containers—for example, to enable communication through a Unix-domain socket.
One bind-mounted directory: ./tls-certs. This directory, located under the current working directory when podman run is invoked, is bind-mounted to the container’s /etc/ssl/dovecot. This approach is often used to pass configuration files—or TLS certificates, in this case—to the container. A third option, single-file volumes, is described in the Podman documentation.

Note the :z flag, present in some volume definitions: it configures the SELinux volume label in “shared” mode (type container_file_t), which is the recommended choice for rootless containers. Since the label is recursively checked when the container is started, the volume dovecot-data that may contain many files is exempted to avoid long startup times. If you copy files from external sources into a volume, ensure the label type is container_file_t to avoid file access errors. Refer to podman run man page for differences between volume flags.

Inspect Podman named volumes with:

podman volume ls

Suggest volume assignment to additional disks

When an application is created in NS8, or when a service is started for the first time, named volumes are created under a Podman predefined directory. You can check its path with:

podman system info --format='{{.Store.VolumePath}}'

The path depends on whether the command is executed by root (for rootful modules) or by a normal user (for rootless modules).

The default path resides under the root filesystem. It is possible to mark one or more application volumes to be presented for optional assignment to additional disks, present in the NS8 installation node.

The org.nethserver.volumes image label is managed by the application developer. Define this application label like:

 org.nethserver.volumes = dovecot-data

When the Mail application is installed in a NS8 cluster, this label triggers an UI modal window asking the Sysadmin where to store its data, provided the destination node has an additional disk already configured. If not, the volume is created in the default disk.

The label value syntax is a list of words separated by spaces. Each word must correspond to a named volume. List only the volumes you consider suitable for additional disks.

Assume that additional disks are slower than the root disk, but have bigger size.

Configure volume assignments for a node

The system administrator can configure a NS8 node to assign specific application volumes to custom base directories. These assignments are stored in /etc/nethserver/volumes.conf and evaluated during module creation.

Assignments defined in volumes.conf can extend beyond the volume names declared by the app developer with the org.nethserver.volumes image label explained in the previous section. However, settings collected from the UI take precedence over those in volumes.conf.

The volumes.conf file uses a Windows-INI–like format, where section names correspond to applications and key-value pairs define named volume assignments with their system mount points. It can be edited manually with a text editor or managed through the volumectl command.

This is a brief list of volumectl invocations for different scenarios.

List available base directories (filesystem mountpoints). For each directory the mounted disk label, size and used space are printed.
```
# volumectl list-base-paths
/srv/disk00 (MYDISK) size=2.0G used=46.6M
```

Assign base path for dovecot-data volume of mail applications.

# volumectl add-volume dovecot-data --target /mnt/disk00 --for mail
Added volume target for [mail]: dovecot-data → /mnt/disk00

Similar to the previous example, but limits the assignment only to the next Nextcloud installation.

# volumectl add-volume nextcloud-app-data --target /mnt/disk01 --for nextcloud --next-only
Added volume target for [nextcloud4]: nextcloud-app-data → /mnt/disk01
# volumectl add-volume nextcloud-app-data --target /mnt/disk00 --for nextcloud
Added volume target for [nextcloud]: nextcloud-app-data → /mnt/disk00

Remove an existing volume assignment.

# volumectl remove-volume nextcloud-app-data --for nextcloud
(command has no output on success)

Look at /etc/nethserver/volumes.conf to check the current settings:

   cat /etc/nethserver/volumes.conf

Output example:

[mail]
dovecot-data = /mnt/disk00

[nextcloud4]
nextcloud-app-data = /mnt/disk01

[nextcloud]
nextcloud-app-data = /mnt/disk00

This configuration file example shows how specific volume targets apply to different applications. It will store nextcloud-app-data data volume of nextcloud4 application under /mnt/disk01, whilst data of other Nextcloud applications will reside under /mnt/disk00.

Move a volume of an installed application

Assignments in volumes.conf are evaluated only when a volume is created. To move the data of an existing volume to another disk, use volumectl move-volume. It works only with rootless applications.

The move has two steps, to keep the application downtime short:

Sync. Copy the volume data to the target base path, while the application is running. The first copy can take a long time: run it as many times as needed, each run copies only the changes since the previous one.
```
# volumectl move-volume dovecot-data --for mail1 --target /mnt/disk00 --sync
```
Finalize. Stop the application, copy the last changes, recreate the volume at the new location and start the application again. Run it right after a sync, so the last copy is short.
```
# volumectl move-volume dovecot-data --for mail1 --target /mnt/disk00
```

The target is one of the base paths printed by volumectl list-base-paths, or the mountpoint of the default disk (for example /) to move the volume back to it. Data is copied preserving numeric ownership, permissions, ACLs, extended attributes (including SELinux labels), hard links and sparse files. Both steps check the target has enough free space.

During the finalize step the whole user session of the application is stopped: all its services, timers and its agent. If the agent is running a task, the command refuses to stop it. Retry later, or add --force to stop the agent anyway: the running task is interrupted and never returns a result to its caller.

If finalize fails, or it is interrupted with Ctrl-C, the original volume is restored and the application is started again. When finalize completes, the old data is removed in background by a transient Systemd unit, volumectl-trash-*. Its name is printed by the command, to check its progress with journalctl -u.

Until finalize runs, the original volume is untouched. To cancel a move, remove the copied data from the target base path, for example:

rm -rf /mnt/disk00/mail1/dovecot-data

When the target is the default disk, the copy is under the application home directory, for example /home/mail1/.local/share/volumectl-staging/dovecot-data.