Backrest
Keep a Backrest server's snapshot index current for restic repositories it does not itself back up, and report how fresh each one is. Backrest indexes snapshots only for repositories it runs backups for; one that is merely configured — the normal shape when restic runs from systemd timers on each host and Backrest is only the console — is never indexed at all, and reports no error while doing so. The repository simply stays empty in the UI, which reads as no backups for a host whose backups are in fact current. sync reads the operation log and reports each repository's newest indexed snapshot. reindex triggers Backrest's own TASK_INDEX_SNAPSHOTS for every configured repository, waits for them to appear, and reports the same shape; it reads repositories and never creates, forgets or prunes a snapshot, so it is safe to schedule. Four server behaviours shape the implementation because each one silently produces a wrong answer if ignored. GetOperations' repoId selector does not filter — a selector matching nothing returns the ENTIRE operation log rather than an empty set, so a per-repository query makes every repository report the whole fleet's totals; operations are therefore fetched once and grouped on each operation's own repoId. A failed index task leaves no trace in the operation log, only successes being recorded, so a repository the server cannot read is indistinguishable through the API from one whose task has not run yet — both are reported as unindexed with the reason named as the server log rather than invented. The task queue is serial, so triggering N repositories enqueues N tasks behind each other and one whose credentials were revoked does not fail fast but retries with exponential backoff for six minutes or more while everything behind it waits, which is why the wait is a deadline over the whole set rather than a per-task timeout. And a repository with no indexed snapshot at all is a different failure from one whose snapshots have stopped advancing — the first is a credential this server holds that no longer exists, the second is a backup that has stopped running — so they are counted separately as unindexed and stale instead of being folded into one unhelpful total. Because it reaches repositories through the server's own stored credentials rather than the ones the backup hosts use, disagreement with a host-side view is informative: it means exactly one of the two credential sets has gone bad.
Declare SPDX license (MIT) in manifest.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Base URL of the Backrest API, e.g. http://backrest.internal:9898. No trailing slash needed. Prefer an address reachable directly; a URL fronted by an SSO proxy answers with an HTML login page rather than JSON. |
| apiKey? | string | Bearer token, when the instance has authentication enabled. Backrest issues only JWTs from its Login call, which expire after seven days, so for anything scheduled prefer `username` and `password`. Omit for an instance with auth disabled. Supply it from a vault rather than inline — marking it sensitive keeps it out of logs, but the stored model config still holds whatever literal you pass. |
| username? | string | Backrest user to authenticate as with HTTP Basic, which Backrest checks on every request — no login call and no token to expire. Set together with `password`; mutually exclusive with `apiKey`. Give each automated caller its own user so it can be rotated and revoked on its own. |
| password? | string | Password for `username`. Supply it from a vault rather than inline, for the same reason as `apiKey`. |
| requestTimeoutSeconds? | number | Per-request timeout. Applies to each API call, not to the settle wait. |
| settleTimeoutSeconds? | number | How long `reindex` waits for every repository to appear before reporting. A repository Backrest cannot read never appears, so it consumes this whole budget on every run — repair its credentials or add it to `excludeRepos` rather than shortening this, which would only start cutting off healthy repositories too. |
| pollIntervalSeconds? | number | How often to re-read the operation log while waiting. |
| maxSnapshotAgeHours? | number | A repository whose newest indexed snapshot is older than this is reported `stale`. The default allows a full missed daily backup plus most of a second day, so a single late run does not read as a failure. |
| excludeRepos? | array | Repository ids to leave alone. Use for repositories Backrest backs up itself — it already indexes those on its own schedule — and for any it is known to be unable to read. |
| allowPlaintextCredentials? | boolean | Silence the warning logged when a credential is sent to a non-loopback `http://` apiUrl. Set it only when that traffic cannot leave the machine or a trusted segment — for example a container calling its own host's address — since Basic sends the password, merely base64-encoded, on every request. |
| Argument | Type | Description |
|---|---|---|
| repos? | array | Limit to these repository ids. Empty means every configured repository, minus `excludeRepos`. |
Resources
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned