banshee/services-collection/services/restic/ssh/snapshots

restic snapshots, by SSH

Returns, for each restic repository a server backs up to, whether restic reads it, and the age of its newest snapshot, read by restic on that server over SSH. A backup that failed leaves no snapshot: the age grows, and says it. Three watches are offered, each one set on the probe. No secret leaves the server.

Versions

restic with the global options --repository-file, --password-file, --no-lock, --no-cache and --json, as its current documentation gives them. restic 0.17.0 and later tell a missing repository by its exit code (10), 0.17.1 and later a wrong password (12); the older ones by their message. Generic: no folder of version.

How it works

Each repository is given by two files on the server, which restic reads itself: the file of its location and the file of its password. For each line of restic:repositories, the collector runs:

restic snapshots --json --no-lock --no-cache --repository-file /etc/restic/nas.repository --password-file /etc/restic/nas.password

the two paths going as arguments, each quoted apart. The password never leaves the server, and is never written on a command line. restic answers every snapshot of the repository, its time in RFC 3339:

[{"time": "2026-10-26T01:00:03.123456789+01:00", "hostname": "www", "paths": ["/srv"], "id": "…", "short_id": "4bd2b1c5"}]

A repository is named by the path of its location file: /etc/restic/nas.repository. The location itself is never returned.
status is ok; empty for a repository without any snapshot; wrong-password; not-found for a repository that does not exist; unreadable for any other failure (a file unreadable, the storage unreachable, restic missing). Run the same command by hand, as the SSH account, to read why.
age is the time since the newest snapshot, in hours, against the poller's clock; it is only returned for a repository read.
--no-lock makes restic read without writing a lock in the repository, and without waiting for a backup or a prune that holds one; --no-cache makes it write no cache in the account's home. Nothing is written, neither in the repository nor on the server.

Prerequisites

An SSH account for monitoring, without write rights (monitoring below), on the server that runs the backups, with restic in its path.
For each repository, two files that account reads, owned by it, mode 0400: - the location file, one line: sftp:backup@nas.example:/srv/restic/www; - the password file, one line: the password. Any key of a restic repository opens all its data: rather than share the backups' own password, give the monitoring account a key of its own, which can be removed alone (restic key add, then restic key remove <id> to revoke it).

install -m 0400 -o monitoring /dev/null /etc/restic/nas.password
editor /etc/restic/nas.password

The storage behind the repository must let the account in by itself: for sftp:, an SSH key of the account and its ~/.ssh/config.
No sudo.
The fingerprint of the server's host key, set in protocol:ssh:fingerprint (not needed when the Security settings trust the first SSH fingerprint presented).

Variables

Name	Label	Says	Default
`restic:repositories`	Repositories	one line per repository: the path of its location file, a space, the path of its password file	—

Outputs

Name	Label	Unit	Per instance
`status`	Repository read	—	yes, per repository
`age`	Age of the newest snapshot	h	yes, per repository

Watches

Name	Title	Kind	Defaults	Checked by default
`unreadable`	Repository unreadable or empty	expected value, on `status`	critical when anything but `ok`	yes
`old`	Newest snapshot too old	above a threshold, on `age`	warning above 30 h, critical above 54 h: a daily backup missed once, then twice	yes
`missing`	Repository missing	expected instances, on `status`	no name given: it raises nothing until names are set on the probe	no

Limits

A storage whose keys restic takes from environment variables (S3, B2, Azure, Google Cloud Storage) is not served: no environment is given to restic. Whether restic finds the keys of S3 in the account's own ~/.aws/credentials is not checked.
Every snapshot is listed at each run: a repository that keeps thousands makes a long answer.
The age is that of the newest snapshot of the whole repository: a repository shared by several hosts stays young while one of them no longer backs up. Give each host its own repository, or its own probe.
Whether a snapshot is complete, and whether the repository is sound (restic check), is not read here: check reads the data, and takes a lock.
The restic version that first took --no-lock for snapshots is not documented; a restic that does not know it stops with unreadable.
Not checked against a restic: the options, exit codes and JSON are those of the restic documentation ("Scripting", "Working with repositories", the global flags of restic --help).