omv8:omv8_plugins:restic [omv-extras.org]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== openmediavault-restic ======

===== Summary =====

The openmediavault-restic plugin manages [[https://restic.net|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/]]

===== Installation =====

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.

===== Settings =====

**Services -> Restic -> Settings**

^ Field ^ Description ^
| Cache directory | Local restic cache (default ''/var/cache/restic''). Speeds up operations, especially on remote repositories. Leave blank to disable caching (not recommended). |
| Exclude patterns | Default exclude patterns applied to **every** backup job, one per line. Lines starting with ''#'' are comments. These are added to each job's own excludes. |
| Exclude cache directories | Skips any directory containing a ''CACHEDIR.TAG'' file (restic ''--exclude-caches''). |

Example default excludes:

<code>
# temporary and trash files
*.tmp
*.part
.Trash-*
.recycle
</code>

Exclude pattern syntax is described in the restic docs: [[https://restic.readthedocs.io/en/stable/040_backup.html#excluding-files|Excluding files]].

===== Repositories =====

**Services -> Restic -> Repositories**

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

^ Field ^ Description ^
| Repository name | Name used within the plugin. Spaces are replaced with underscores. |
| Passphrase | Encryption passphrase. It cannot be changed from the plugin after creation; use ''restic key passwd'' on the command line if it must be rotated. |
| Type | Backend type (see below). |
| Shared Folder | Local repositories only: the shared folder that holds the repository. |
| Remote path / URI | Remote repositories only: see the table below. |
| Account ID / Access key \\ Account key / Secret key | S3 and B2 only. |
| Skip initialisation | Tick to import an existing repository instead of creating a new one. The passphrase must match the existing repository. |

==== Repository types ====

^ Type ^ Remote path / URI example ^ Notes ^
| Local | (select a shared folder) | Best on a different disk from the data being backed up. |
| S3 compatible | ''bucket-name'' (AWS) \\ ''https://host:port/bucket'' (other providers, MinIO, ...) | Enter the access key and secret key. |
| SFTP | ''user@host:/path/to/repo'' | SSH key authentication must be set up for root beforehand. Password prompts are not supported. |
| Backblaze B2 | ''bucket-name'' or ''bucket-name:path'' | Uses the native B2 API. Enter the account/key ID and application key. |
| REST server | ''http://host:8000/'' \\ ''https://user:password@host:8000/repo/'' | Credentials can be placed in the URL or supplied via environment variables. |
| rclone | ''remote:path'' | The rclone remote must be configured beforehand with ''rclone config''. |

==== Repository actions ====

Select a repository and use the toolbar buttons:

^ Action ^ restic command ^ Description ^
| View snapshots | ''snapshots'' | Opens the list of snapshots stored in the repository (see [[#snapshots|Snapshots]]). |
| Test connection | ''cat config'' | Confirms the repository is reachable and the passphrase is correct. |
| Unlock | ''unlock'' | Removes stale locks left by an interrupted operation. |
| Statistics | ''stats'' | Shows the repository size. |
| Check | ''check'' | Verifies the repository structure. |
| Prune | ''prune'' | Removes data no longer referenced by any snapshot. |

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

==== Scheduled integrity check ====

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

^ Field ^ Description ^
| Schedule | Disabled, Daily (03:00), Weekly (Sunday 03:00) or Monthly (1st, 03:00). |
| Read data subset | Optional. Also downloads and verifies part of the stored data. Accepts a percentage (''5%''), a fraction (''1/7'') or a size (''500M''). Leave blank to only check the repository structure. |
| Send email | Never, Only on error, or Always. The output is emailed to root, which requires notifications to be configured under **System -> Notification**. |

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.

===== Snapshots =====

**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.

^ Action ^ Description ^
| Restore | Restores the snapshot to a shared folder (see [[#restoring|Restoring]]). |
| Inspect | Shows the snapshot metadata (''restic cat snapshot'') and its restore size and stored size (''restic stats''). |
| List files | Lists every file in the snapshot with size, owner and date (''restic ls --long''). Large snapshots produce a lot of output. |
| Forget | Removes the snapshot from the repository. The data it referenced stays in the repository until it is pruned. |
| Forget and prune | Removes the snapshot, then prunes unreferenced data. Frees the space immediately but can take a long time on large repositories. |

**Forgetting a snapshot cannot be undone.**

===== Restoring =====

  - In the snapshot list, select the snapshot and click **Restore**.
  - Choose a **Restore target folder**, or tick **Dry run** to preview without writing anything.
  - Optionally set a **Path filter** to restore only part of the snapshot, e.g. ''/srv/dev-disk-by-uuid-xxxx/Documents/taxes''.
  - 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''.

===== Backup Jobs =====

**Services -> Restic -> Backup Jobs**

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

^ Field ^ Description ^
| Enabled | Disabled jobs are not scheduled. |
| Job name | Optional name. |
| Source folders | Shared folders to back up. All selected folders go into the same snapshot. |
| Repository | Destination repository. |
| Tags | Comma-separated tags added to each snapshot (e.g. ''daily,offsite''). |
| Exclude patterns | Comma-separated patterns for this job only. The default excludes from Settings are also applied. |
| Time of execution | Hourly, daily, weekly, monthly, yearly, at reboot, or a custom schedule. |
| Keep last / daily / weekly / monthly / yearly | Retention policy applied after each backup (''restic forget --prune''). ''0'' disables that rule. Only snapshots of this job's source folders are affected, so several jobs can share one repository safely. |
| Send command output via email | Emails the output of each scheduled run to root. |
| Send email on error only | Only emails when the run fails. |

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.

===== Restore Tests =====

**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.

^ Field ^ Description ^
| Repository | The latest snapshot in this repository is tested. |
| Mode | **Dry run**: reads only snapshot metadata and writes nothing. Fast, and suitable for frequent runs. \\ **Verify**: performs a full restore and checks every restored file against the snapshot. Reads all the data and needs free disk space. |
| Verify target folder | Verify mode only. Data is restored into a ''restic-restoretest-<id>'' subdirectory of this shared folder. |
| Clean up after verify | Deletes that subdirectory when the test finishes. Nothing else in the folder is touched. |
| Path filter | Test only part of the snapshot. |
| Schedule / email | Same as backup jobs. Enable **Send email on error only** to be alerted when a backup cannot be restored. |

===== Environment Variables =====

**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: [[https://restic.readthedocs.io/en/stable/040_backup.html#environment-variables|restic environment variables]].

===== REST Server =====

**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.

==== Settings ====

^ Field ^ Description ^
| Enabled | Installs ''restic-rest-server'' (if needed) and starts it when the changes are applied. Disabling stops the service; the package stays installed. |
| Shared folder | Folder served by the REST server. Each client can use its own subdirectory as a separate repository. |
| Port | Listening port (default ''8000''). It must not be in use by another service. |
| Require login | Enabled by default. Clients must authenticate as a user from the **Users** page. |
| Private repositories | Each user can only access repositories under a path named after their username. |
| Append-only | Clients can add snapshots but cannot delete or modify existing data. |
| TLS enabled / Certificate | Serves HTTPS using a certificate from **System -> Certificates -> SSL**. |

==== Users ====

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 ''_''.

==== Connecting a client ====

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:
<code>
restic -r rest:http://alice:PASSWORD@omv.local:8000/ init
</code>

One repository per client, in a subdirectory (required when **Private repositories** is enabled, where the first path component must be the username):
<code>
restic -r rest:https://alice:PASSWORD@omv.local:8000/alice/ init
restic -r rest:https://alice:PASSWORD@omv.local:8000/alice/laptop/ init
</code>

To keep the password off the command line, use environment variables:
<code>
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
</code>

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

==== Serving an existing local repository ====

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.

==== Security ====

  * **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.

===== Logs =====

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:
<code>
journalctl -u restic-rest-server
</code>

===== Troubleshooting =====

**"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.

===== Source Code =====

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