openmediavault-restic

The openmediavault-restic plugin manages restic backups from the OMV web interface. It can:

• back up shared folders to local, S3, SFTP, Backblaze B2, REST server and rclone repositories
• schedule backup jobs with a retention policy
• browse, inspect, restore and forget the snapshots stored in a repository
• run scheduled restore tests and repository integrity checks
• serve a shared folder with the restic REST server so other machines can back up to OMV

All data is encrypted by restic before it leaves the server. The repository passphrase cannot be recovered. If it is lost, the backups are lost. Store it somewhere other than the OMV server.

Official restic documentation: https://restic.readthedocs.io/en/stable/

Install openmediavault-restic from System → Plugins. The plugin pages are under Services → Restic.

The restic REST server package (restic-rest-server) is not installed with the plugin. It is installed automatically the first time the REST server is enabled.

Services → Restic → Settings

Example default excludes:

# temporary and trash files
*.tmp
*.part
.Trash-*
.recycle

Exclude pattern syntax is described in the restic docs: Excluding files.

Services → Restic → Repositories

A repository is where restic stores backups. Create one with the + button.

Select a repository and use the toolbar buttons:

A repository cannot be deleted while a backup job or restore test still uses it.

Each repository can be checked automatically with restic check. Edit the repository and set:

A structure-only check is fast and safe to run often. Reading data verifies that the stored files are actually intact, but it downloads that data. On cloud storage this can cause egress charges. A small percentage run weekly, or 1/7 run daily (each run checks a different seventh), is a good compromise.

Repositories → select a repository → View snapshots

Lists the snapshots stored in the repository, newest first, including snapshots created by other machines. The toolbar actions work on the selected snapshot.

Forgetting a snapshot cannot be undone.

1. In the snapshot list, select the snapshot and click Restore.
2. Choose a Restore target folder, or tick Dry run to preview without writing anything.
3. Optionally set a Path filter to restore only part of the snapshot, e.g. /srv/dev-disk-by-uuid-xxxx/Documents/taxes.
4. Click Save. The restore runs in the background and shows its output as it runs.

Notes:

• Existing files in the target folder may be overwritten. Where possible, restore into an empty shared folder, check the result, then move the files into place.
• restic recreates the snapshot's original directory structure under the target. For example, a backup of /srv/dev-disk-by-uuid-xxxx/Documents restores to <target>/srv/dev-disk-by-uuid-xxxx/Documents.

Services → Restic → Backup Jobs

A backup job backs up one or more shared folders to a repository, on a schedule.

Use Run backup now to start a job immediately.

Deleting a backup job also forgets all snapshots of that job's source folders in the repository.

Services → Restic → Restore Tests

A backup is only useful if it can be restored. Restore tests restore the latest snapshot on a schedule and report failures.

Services → Restic → Environment Variables

Extra environment variables passed to restic, for one repository or for all repositories. Uses include:

• RESTIC_REST_USERNAME / RESTIC_REST_PASSWORD for a REST server, instead of putting credentials in the URL
• AWS_DEFAULT_REGION for S3
• RESTIC_COMPRESSION (auto, max, off)
• RESTIC_READ_CONCURRENCY or GOMAXPROCS to tune performance on low-end hardware

See the full list: restic environment variables.

Services → Restic → REST Server

The REST server lets other machines back up to OMV using restic's rest: backend. The restic developers recommend it over SFTP: it is faster and lighter, which suits low-end hardware.

Click Users on the REST Server page to add, edit or delete users. Only a bcrypt hash of each password is stored. When editing a user, leave the password blank to keep the current one.

Usernames may contain letters, digits, ., - and _.

On the client machine, set the repository to the OMV server. Examples use the host omv.local, port 8000 and user alice.

Repository in the root of the served folder:

restic -r rest:http://alice:PASSWORD@omv.local:8000/ init

One repository per client, in a subdirectory (required when Private repositories is enabled, where the first path component must be the username):

restic -r rest:https://alice:PASSWORD@omv.local:8000/alice/ init
restic -r rest:https://alice:PASSWORD@omv.local:8000/alice/laptop/ init

To keep the password off the command line, use environment variables:

export RESTIC_REPOSITORY=rest:https://omv.local:8000/alice/
export RESTIC_REST_USERNAME=alice
export RESTIC_REST_PASSWORD=PASSWORD
export RESTIC_PASSWORD_FILE=~/.restic-pass
restic backup ~/Documents

The same URLs work in other restic front ends such as Backrest.

A local repository created by this plugin has the same on-disk layout the REST server uses. To give remote machines access to it, select the repository's shared folder on the REST Server page. Remote clients then use rest:https://user:password@omv.local:8000/ with the same repository passphrase. The plugin can keep running backups, checks and prunes on it locally at the same time. Do not enable Private repositories in this case, because the repository sits in the root of the folder rather than under a username.

• Use TLS when login is required. Without TLS, usernames and passwords are sent in clear text on the network.
• Disabling login means anyone who can reach the port can read, add and delete repository files. The backup contents stay encrypted by restic, but an attacker could delete them. Only do this on a trusted network, and only reachable from it.
• Append-only mode protects backups from a compromised or ransomware-infected client, because the client cannot delete existing snapshots. The trade-off is that clients cannot run forget or prune themselves. They must be run on the OMV server instead. For a repository in the root of the served folder, add it under Repositories (select that folder, tick Skip initialisation, and enter its passphrase). You can then remove old snapshots with Forget in its snapshot list and free space with Prune. Automatic retention only applies to the plugin's own backup jobs, so for a client's repository run restic forget –keep-… on the OMV server, e.g. from a scheduled task.
• The service runs as root so it can share repositories with the plugin. It is confined by systemd: it can only write inside the served folder.

Scheduled backups, restore tests and repository checks log to /var/log/restic/restic.log. The log can be viewed under Diagnostics → Logs → restic.

REST server messages are in the system journal:

journalctl -u restic-rest-server

“repository is already locked” Another operation is running, or one was interrupted. Operations wait up to 5 minutes for a lock. If no restic process is running, use Unlock on the repository.

Test connection hangs or takes a long time restic keeps retrying an unreachable backend for several minutes before it gives up. Check the URI, the network, and the credentials (including any environment variables).

“wrong password or no key found” The passphrase does not match the repository. When importing an existing repository with Skip initialisation, enter the passphrase that repository was created with.

REST clients get “401 Unauthorized” Check the username and password, and that the user exists on the REST Server Users page. With Private repositories enabled, the repository path must start with /<username>/. Apply pending changes after adding users.

REST server does not start Check journalctl -u restic-rest-server. Common causes are the port already in use, or TLS enabled with a missing or invalid certificate.

Deleted files still use space Forgetting a snapshot only removes the snapshot. Run Prune on the repository, or use Forget and prune, to free the space.

https://github.com/OpenMediaVault-Plugin-Developers/openmediavault-restic