Skip to main content

Backrest

@sntxrr/backrestv2026.09.05.2· 5d agoMODELS
01README

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.

02Models1
@sntxrr/backrest/instancev2026.09.05.2backrest_instance.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringBase 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?stringBearer token, when the instance has authentication enabled. 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.
requestTimeoutSecondsnumberPer-request timeout. Applies to each API call, not to the settle wait.
settleTimeoutSecondsnumberHow 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.
pollIntervalSecondsnumberHow often to re-read the operation log while waiting.
maxSnapshotAgeHoursnumberA 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.
excludeReposarrayRepository 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.
fn sync()
Report each repository's newest indexed snapshot without triggering anything. Read-only. Reflects the last time Backrest indexed, which for a repository it does not back up may be never.
fn reindex(repos: array)
Ask Backrest to index every configured repository, wait for them to appear, then report per-repository freshness. This is the method to schedule. Triggers Backrest's own TASK_INDEX_SNAPSHOTS, which reads a repository and never modifies it.
ArgumentTypeDescription
reposarrayLimit to these repository ids. Empty means every configured repository, minus `excludeRepos`.

Resources

fleet(infinite)— Per-repository snapshot freshness as this Backrest instance sees it, with repositories it could not read at all counted separately from those whose backups have stopped advancing.
03Previous Versions1
2026.09.05.1
04Stats
A
100 / 100
Downloads
2
Archive size
16.5 KB
  • 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
  • License declared1/1earned
  • Verified public repository2/2earned
05Platforms
06Labels