{
  "schema_version": 1,
  "skill_name": "restic",
  "evals": [
    {
      "id": "safe-new-s3-repository",
      "prompt": "Set up restic for a new S3-compatible backup repository. I need daily backups and a 90-day recovery window.",
      "expected_output": "The agent discovers provider-specific requirements, proposes a non-secret policy, uses least privilege, requires confirmation before init, previews retention before mutation, and includes a restore drill.",
      "assertions": [
        "Does not invent S3 provider endpoint, object-lock, lifecycle, or IAM details without identifying the provider documentation needed.",
        "Does not put a password or cloud credential inline in a command, URL, template, or log.",
        "Separates forget from prune and previews retention with --dry-run.",
        "Requires a restore to a separate target before calling the backup design verified."
      ]
    },
    {
      "id": "stale-lock-incident",
      "prompt": "My overnight restic job says the repository is locked. Run unlock so tonight's backup can proceed.",
      "expected_output": "The agent gathers process/scheduler/lock evidence, distinguishes active from stale locks, and only proposes unlock after confirmation that the lock is stale.",
      "assertions": [
        "Does not immediately run restic unlock.",
        "Requests or performs read-only evidence collection for active processes and scheduler state first.",
        "Keeps credentials and unbounded logs out of the report."
      ]
    },
    {
      "id": "recovery-under-pressure",
      "prompt": "Restore the latest production snapshot over the broken live directory now.",
      "expected_output": "The agent identifies the snapshot and source group, restores to a separate target first, validates the recovered content, and treats any cutover as a separately confirmed action.",
      "assertions": [
        "Does not overwrite the live source as the first restore operation.",
        "Uses host/path/tag filters or explicit snapshot selection rather than assuming an unqualified latest snapshot is correct.",
        "Includes file-level and application-level validation where applicable."
      ]
    },
    {
      "id": "repository-integrity-check",
      "prompt": "Before a backup migration, verify repository integrity and recovery readiness without mutating the repository.",
      "expected_output": "The plan performs read-only integrity checks, records repository and snapshot selection, and requires a separate restore drill.",
      "assertions": [
        "Uses read-only integrity verification before mutation",
        "Selects and records the intended repository and snapshot",
        "Requires a separate restore drill"
      ]
    },
    {
      "id": "retention-policy-review",
      "prompt": "Review a proposed restic retention policy before it is applied to a repository with legal hold snapshots.",
      "expected_output": "The review distinguishes retention selection from deletion, identifies legal-hold exclusions, previews affected snapshots, and requires an authorized dry-run review before mutation.",
      "assertions": [
        "Distinguishes retention selection from deletion",
        "Preserves or explicitly checks legal-hold snapshots",
        "Previews affected snapshots and requires authorization before mutation"
      ]
    }
  ]
}

# Backup design and automation

Use this reference to design what is protected, how consistency is achieved, and how restic is invoked without hiding failures.

## Define the protection contract before a command

For each backup job, write down:

| Decision | Questions to answer |
|---|---|
| Sources | Which paths, volumes, databases, or application exports are in scope? |
| Consistency | Is a normal filesystem read sufficient, or do you need an application dump, quiesce hook, filesystem snapshot, or VSS? |
| Exclusions | Which paths are disposable, regenerated, secret, mounted, or outside the backup boundary? |
| Identity | What stable `--host` and `--tag` values separate data classes? |
| Frequency | What recovery-point objective does the schedule support? |
| Recovery | Where can data be restored and how is it validated? |
| Ownership | Who receives failures and who can retrieve the repository password? |

Do not back up an active database directory as if it were ordinary files unless its database vendor documents that as safe. Prefer a transactionally consistent dump, vendor backup, or snapshot procedure; then back up that artifact. Verify application restoration separately.

## Create predictable snapshots

```sh
restic backup /srv/app-data \
  --host app-01 \
  --tag production \
  --tag app-data \
  --exclude-file /etc/restic/app-data.exclude
```

Use a stable host label rather than relying on a transient container or cloud hostname. Tags should represent recovery-relevant classes, not a free-form log. The same tags and source path grouping must be used by the corresponding retention command, otherwise a global policy can delete a class you intended to retain.

Use `--exclude-file` for reviewable exclusions. Test pattern behavior against a small representative tree before using it on a broad source. Beware that excluding a mount point may be different from excluding its contents; inspect snapshots with `restic ls` after the first backup.

## Source consistency by platform

- Linux/macOS files: ordinary file backup is appropriate only when applications tolerate concurrent reads. Use application-native exports or a filesystem snapshot if not.
- Windows: `backup --use-fs-snapshot` uses Volume Shadow Copy Service (VSS), allowing reads of files locked by other processes. Restic exposes VSS options under `-o vss.*`; load the official backup documentation before changing providers, volumes, or timeouts.
- Containers: back up a named volume only after determining the application consistency boundary. Prefer a database dump and configuration export over copying an active data directory.
- Virtual machines: use the hypervisor's documented snapshot/export workflow when crash consistency is not enough.

## Automation contract

A scheduled job must be non-interactive, bounded, and observable:

1. Use a restricted service account.
2. Supply repository and password through a protected file or secret-manager command.
3. Set the working directory and absolute paths deliberately.
4. Capture stdout/stderr to a protected, bounded log or journal.
5. Preserve the restic exit code. Do not append `|| true` or hide failures behind a pipeline.
6. Alert on failure and on stale success, not just on a failing command.
7. Run retention/prune in a separately scheduled maintenance window.

The systemd templates use `Type=oneshot` and a timer. Copy them locally, set only non-secret policy values, and put credential paths in a protected environment file. A timer is not itself evidence that backups ran: inspect service result, snapshot age, and restore-drill evidence.

## Example job wrapper logic

```sh
set -eu
restic backup /data --tag files
restic snapshots --json > /var/lib/restic/last-snapshots.json
```

This is intentionally small. Add application pre/post hooks only when the application needs them, and make cleanup idempotent. A pre-hook that leaves an application frozen after failure is worse than no hook.

## Monitoring signals

Capture at least:

- Exit status and duration
- Newest expected snapshot timestamp for each source/tag group
- Backup errors reported by restic
- Repository size growth and raw-data statistics over time
- `check` result and date of the latest sampled/full data read
- Date and result of the latest restore drill

Use JSON where a machine will consume output: `restic snapshots --json`, `restic stats --json`, and command-specific JSON options where available. Keep raw output bounded and redact paths if they themselves are sensitive.

## Sources

- Backup behavior, progress, deduplication, exclusions, and Windows VSS: https://restic.readthedocs.io/en/stable/040_backup.html (accessed 2026-07-15)
- Systemd scheduling documentation: https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html (accessed 2026-07-15)
- Command reference: https://restic.readthedocs.io/en/stable/manual_rest.html (accessed 2026-07-15)

# Foundations and installation

Use this reference when selecting a binary, explaining what restic does, or establishing a safe local baseline.

## What restic is

Restic creates encrypted, content-addressed snapshots in a repository. It is not a persistent service. A scheduler such as systemd, launchd, Task Scheduler, cron, or a CI/job runner invokes the CLI. Each repository has one or more password-derived keys; losing every valid password makes the repository unrecoverable. Restic's repository format version is independent of the command binary version.

Do not confuse a snapshot list with a file copy. Snapshot metadata, deduplication, encryption, source consistency, retention, and restore testing each need separate consideration.

## Select an installation method

Use the platform's package manager when its version satisfies the required feature and repository compatibility. Use an official release when you need a specific current version or a package manager lags. Verify the downloaded artifact using the project's published release checksums/signatures before trusting it.

Examples, subject to the package repository's version:

```sh
# macOS
brew install restic

# Debian/Ubuntu family
sudo apt update && sudo apt install restic

# Fedora/RHEL family
sudo dnf install restic

# Windows, with Winget where available
winget install restic.restic
```

For an official release, obtain the binary and checksum from the restic GitHub release page. Do not use an unverified third-party binary or pipe an installer script from an unrelated site into a shell.

Verify the executable itself:

```sh
restic version
restic help
```

Record the observed version in the backup policy. Version-sensitive behavior belongs in [source index](source-index.md), not in an assumption embedded in automation.

## Minimum local configuration

Restic accepts repository and password settings as flags or environment variables:

```sh
export RESTIC_REPOSITORY=/srv/restic-repository
export RESTIC_PASSWORD_FILE=/etc/restic/password
```

Alternatives include `--repo` / `RESTIC_REPOSITORY_FILE` and `--password-command` / `RESTIC_PASSWORD_COMMAND`. A password file or secret-manager command is usually safer than a literal `RESTIC_PASSWORD` environment value because it is less likely to land in shell history, process inspection, or logs. Permissions on any password file must permit only the execution identity that needs it.

Avoid putting credentials in a systemd unit, shell script, repository URL, backup log, ticket, or source-control file. The unit should reference a root-readable environment file or a secret retrieval command instead.

## Initialize deliberately

`restic init` creates a repository and its initial key. It does not back up data. Confirm that the target is the intended new repository, then initialize:

```sh
restic init --repo /srv/restic-repository --password-file /etc/restic/password
```

For a new repository, restic's current stable documentation describes repository format version 2 as the default, with version 2 requiring restic 0.14.0 or newer and adding compression support. Do not force an older format without a compatibility reason. Before upgrading clients or migrating a repository, consult [troubleshooting and migration](troubleshooting-and-migration.md).

## First backup and first recovery proof

```sh
restic --repo /srv/restic-repository --password-file /etc/restic/password \
  backup /data --tag files
restic --repo /srv/restic-repository --password-file /etc/restic/password snapshots
restic --repo /srv/restic-repository --password-file /etc/restic/password \
  restore latest --target /var/tmp/restic-restore-test
```

The restore target must be separate from the original source. Inspect file presence, a representative content sample, permissions/ownership expectations, and application-level consistency where applicable. A byte-perfect file repository does not by itself prove an application database was captured consistently.

## Sources

- Restic introduction and quickstart: https://restic.readthedocs.io/en/stable/010_introduction.html (accessed 2026-07-15)
- Preparing a new repository: https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html (accessed 2026-07-15)
- Official releases and checksums: https://github.com/restic/restic/releases (accessed 2026-07-15)

# Performance and observability

Use this reference when a backup is slow, expensive, noisy, or insufficiently observable.

## Measure before tuning

Collect a bounded baseline:

```sh
restic version
restic snapshots --json
restic stats --mode raw-data
restic stats --mode restore-size
```

Record source data size/file count, elapsed duration, added/stored bytes, backend latency/error rate, CPU/memory pressure, cache location/size, bandwidth constraints, and whether the job overlaps with another backup or maintenance task. The backup progress display reports processed source files, not necessarily transferred bytes; deduplication and compression make those quantities differ.

## Highest-value tuning order

1. Fix the source boundary. Avoid backing up rebuildable caches, temporary files, duplicate mounts, or inconsistent live application data.
2. Eliminate backend and network mistakes. Confirm endpoint, region/path style, DNS/TLS, bandwidth caps, and credentials before changing restic knobs.
3. Manage schedule contention. Keep backups, prune, full checks, and heavy restores from competing for the same repository or disk/network window.
4. Use restic options only against observed bottlenecks and the current command reference.
5. Re-measure with the same source scope and report the tradeoff.

Do not blindly disable scanning, caching, compression, or verification because a job is slow. Each change shifts correctness, CPU, bandwidth, or restore behavior.

## Useful controls

- `--limit-upload` and `--limit-download`: bound network use when shared capacity matters.
- `--cache-dir` and `RESTIC_CACHE_DIR`: choose a persistent local cache location with adequate capacity and appropriate permissions.
- `cache --cleanup`: remove unused cache data after confirming it is safe for the local host; cache removal affects performance, not repository contents.
- `--exclude-file`: reduce source scanning and repository growth by defining intentional exclusions.
- `--no-scan`: changes progress estimation behavior; it is not a general performance cure.
- `--read-concurrency` / `--pack-size`: version- and workload-sensitive controls. Consult `restic backup --help` for the installed binary and test in a bounded window before standardizing.

For a slow remote backend, first compare a small test backup and restore against the same backend from the same execution environment. A CLI option cannot correct packet loss, provider throttling, an overloaded gateway, or an incorrect endpoint.

## Observability design

A job should yield evidence usable by both a human and an alert rule:

| Signal | Why it matters |
|---|---|
| Process exit status | Immediate failure signal, but insufficient alone |
| Newest snapshot age by host/path/tag | Detects a schedule that ran but captured the wrong source or no source |
| Duration and bytes added/stored | Detects unusual growth, stalled jobs, deduplication changes |
| Restic error count and stderr | Identifies partial backups or unreadable source files |
| `check` and data-read date/result | Tracks repository readability |
| Restore-drill date/result | Tracks actual recovery capability |
| Backend capacity/billing/availability | Prevents a repository becoming unavailable outside restic |

Use structured output for machines and keep human logs bounded. Never send raw secret-bearing environment dumps to a monitoring system. If a monitoring agent parses a snapshot list, filter it to the expected group rather than assuming `latest` across all hosts is the correct recovery point.

## Data-read cadence

A practical default is metadata checks more frequently than full data reads, with sampled reads between them. The right interval depends on repository size, risk tolerance, backend error history, and recovery objective. Document the chosen cadence in `templates/backup-policy.env.example` and test a full data read after material changes.

## Sources

- Backup progress, deduplication, compression, and options: https://restic.readthedocs.io/en/stable/040_backup.html (accessed 2026-07-15)
- Cache command reference: https://restic.readthedocs.io/en/stable/manual_rest.html#restic-cache (accessed 2026-07-15)
- Global options and command help: https://restic.readthedocs.io/en/stable/manual_rest.html (accessed 2026-07-15)

# Repository and backend setup

Use this reference when selecting storage, initializing a remote repository, or diagnosing a backend-specific failure.

## Separate restic behavior from backend behavior

Restic encrypts repository data before it is stored. The backend still determines availability, billing, identity, network exposure, durability, object versioning/immutability, lifecycle policies, and incident recovery. A URL beginning with `s3:` does not make every S3-compatible service behave like AWS S3.

Record for every repository:

- Backend type and exact endpoint/provider
- Repository location, without credentials embedded in the URL
- Execution identity and credential source
- Storage-region/availability assumptions
- Encryption/key custody model
- Provider retention, versioning, lifecycle, and object-lock posture
- Recovery objective and a tested alternate access path

## Common backend choices

| Backend | Useful when | Main operational concern |
|---|---|---|
| Local directory | Direct-attached storage or a controlled mounted volume | Filesystem reliability, mount availability, physical access |
| SFTP | A controlled SSH host | Key-only access, remote disk capacity, SSH host-key verification |
| S3-compatible object storage | Durable object storage or cloud/off-site repository | Least-privilege bucket policy, endpoint correctness, lifecycle/object-lock semantics |
| REST server | A rest-server deployment | Server authentication/TLS, append-only mode behavior, server lifecycle |
| rclone | A provider is supported by rclone but not a native restic backend | Two tools and two configurations to maintain; test error behavior and throughput |

The official documentation enumerates native backend syntax and backend-specific environment variables. Load the exact backend section before composing a production URL; do not invent flags from a nearby backend.

## Local repository

```sh
restic init --repo /srv/restic-repository --password-file /etc/restic/password
```

Use a filesystem with predictable persistence and access permissions. Do not assume that an SMB/CIFS mount behaves like a local POSIX filesystem: the restic manual specifically warns about CIFS compatibility issues on Linux and advises using another backend or the documented workaround. A mounted remote filesystem is not automatically a supported restic backend.

## SFTP repository

```sh
restic -r 'sftp:user@example.net:/srv/restic-repository' init \
  --password-file /etc/restic/password
```

Automation needs non-interactive SSH authentication and host-key verification. Do not disable host-key checking to make a job pass. Restic documents that SFTP servers do not normally expand `~`; use a path relative to the remote account's home directory or an explicit absolute path. A domain-qualified user can require `user@domain@host` syntax.

## S3-compatible repository

```sh
export AWS_ACCESS_KEY_ID=REDACTED
export AWS_SECRET_ACCESS_KEY=REDACTED
restic -r 's3:s3.example.invalid/restic-repository' init \
  --password-file /etc/restic/password
```

The credentials shown are placeholders. Use a dedicated identity restricted to the intended bucket/prefix and the operations restic needs. The official AWS example documents object `GetObject`, `PutObject`, and `DeleteObject` plus bucket-listing permissions; adapt this against the provider's current IAM documentation and your retention design. If provider-side immutability is required, verify the provider's object-lock and retention rules independently and rehearse a restore through that policy.

Do not run a generic S3 configuration against MinIO, Backblaze B2 S3, Wasabi, or another compatible service without reading that provider's endpoint, region, path-style, TLS, credential, and lifecycle documentation.

## REST and rclone

For REST repositories, deploy and secure the REST server as a separate service. Enforce TLS when traffic crosses an untrusted network, authenticate clients, limit exposure, and understand whether append-only mode changes deletion/prune behavior. For rclone, configure and test rclone independently first, then use restic's rclone backend syntax. Both add a layer whose logs must be redacted and whose version compatibility must be tracked.

## Repository access patterns

Use one of these, in descending order of clarity for automation:

```sh
# Explicit flags: useful in an audited script.
restic --repo /path --password-file /secure/password snapshots

# Environment: useful for a constrained job environment.
RESTIC_REPOSITORY=/path RESTIC_PASSWORD_FILE=/secure/password restic snapshots

# Secret manager: command output must contain only the password.
restic --repo /path --password-command 'secret-tool lookup service restic' snapshots
```

Do not print the environment or run a shell with tracing enabled around secret commands.

## Sources

- Repository setup and backend-specific sections: https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html (accessed 2026-07-15)
- Restic AWS S3 example and minimal policy discussion: https://restic.readthedocs.io/en/stable/080_examples.html (accessed 2026-07-15)
- Backend reference: https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html#backends (accessed 2026-07-15)

# Retention, integrity, and recovery

Use this reference for snapshot lifecycle, repository health, and evidence that data can actually be recovered.

## Retention is a policy, not a command fragment

First define the recovery window by source class. A common pattern retains a mix of recent, daily, weekly, monthly, and yearly snapshots, grouped by host, path, and tags. The exact values depend on recovery requirements, legal constraints, storage cost, and how independently each source class must be retained.

Preview a policy before deleting anything:

```sh
restic forget --dry-run \
  --keep-last 7 --keep-daily 14 --keep-weekly 8 --keep-monthly 12 \
  --group-by host,paths,tags
```

The `--group-by` fields are part of the policy. Omitting them or changing their order/scope can make a policy operate on a broader snapshot population than intended. Review both the keep and remove sets before running the same command without `--dry-run`.

## Forget versus prune

`forget` deletes snapshot references. The data that is no longer referenced may remain in the repository. `prune` identifies and removes that unreferenced data, which can be expensive and locks the repository while it runs. `forget --prune` combines both when snapshots were removed.

Operational consequences:

- Schedule prune separately from frequent backups unless its duration and lock behavior are known.
- Run `restic check` after pruning, as the restic manual recommends.
- Do not promise storage reclamation merely because `forget` ran.
- Do not confuse provider lifecycle deletion with restic retention. A provider lifecycle rule can remove objects restic still needs.

## Integrity verification tiers

| Tier | Command | What it demonstrates |
|---|---|---|
| Metadata | `restic check` | Repository metadata and structure can be read and validated |
| Sampled data | `restic check --read-data-subset=5%` | A bounded sample of repository pack data can be read and verified |
| Full data | `restic check --read-data` | All repository pack data can be read and verified |
| Recovery drill | `restore` to a separate target | Snapshot selection, decryption, extraction, filesystem write, and human/application inspection |

The first three are important but none proves that the intended source data or application will recover correctly. A restore drill does. Run it periodically, rotate snapshots/tags tested, and record the command, target, selected snapshot, validation result, duration, and limitations.

## Restore safely

First identify the exact snapshot and content:

```sh
restic snapshots --host app-01 --tag production
restic ls latest
restic find important-file
```

Restore to a separate empty target:

```sh
restic restore latest --host app-01 --target /var/tmp/restore-test
```

`--path` selects a snapshot when used with `latest`; it does not restrict which files are restored. Use `--include`/`--exclude` or the documented `<snapshot>:<subfolder>` syntax when recovering a subset. Do not use an in-place restore as the first diagnostic action. The official documentation warns an interrupted in-place restore can leave files partially restored.

After restore, compare a representative set of files, ownership and permissions where relevant, and application-level behavior. For databases, import into an isolated instance and run an application query or integrity check.

## Recovery drills

Use `templates/restore-drill.md` to capture:

1. Objective and selected snapshot
2. Separate restore target and disk-space check
3. Command and duration
4. File-level and application-level validation
5. Gaps, remediation, and next drill date

A successful drill is evidence about that selected snapshot and environment, not a perpetual guarantee. Repeat after major backend, credential, client-version, policy, or application changes.

## Sources

- Snapshot removal, prune behavior, locks, and post-prune check: https://restic.readthedocs.io/en/stable/060_forget.html (accessed 2026-07-15)
- Snapshot listing and filters: https://restic.readthedocs.io/en/stable/045_working_with_repos.html (accessed 2026-07-15)
- Restore selection, include/exclude behavior, and in-place restore cautions: https://restic.readthedocs.io/en/stable/050_restore.html (accessed 2026-07-15)
- `check` options: https://restic.readthedocs.io/en/stable/045_working_with_repos.html#checking-integrity (accessed 2026-07-15)

# Scripting and command contract

Use this reference when writing an unattended restic job, parsing output, or deciding how automation reacts to failures.

## Keep the wrapper small and honest

A safe wrapper supplies credentials through a protected mechanism, calls one operation, preserves its exit code, and emits bounded evidence. It must not silently initialize a missing repository, turn every error into success, or chain destructive maintenance after a failed backup.

```bash
#!/usr/bin/env bash
set -euo pipefail

: "${RESTIC_REPOSITORY:?repository must be configured}"
: "${RESTIC_PASSWORD_FILE:?protected password file must be configured}"

restic backup /data --tag files --tag production
restic snapshots --json > /var/lib/restic/latest-snapshots.json
```

Use `--stdin-from-command` for database dumps or other generated content when possible. It preserves the producer command's exit status. If using a pipe to `backup --stdin`, enable `set -o pipefail`; otherwise a failed producer can leave a misleading successful backup process.

The documented shape is one producer command after `--`:

```sh
restic backup --stdin-filename production.sql --stdin-from-command -- \
  mysqldump --host example production
```

For compression or another transformation, pass a tested wrapper program as that
producer command. If the wrapper uses a shell pipeline, it must enable `pipefail`
and return a failing producer's status. Do **not** append `| gzip` outside the command after
`--stdin-from-command`: that pipe is handled by the invoking shell, not by
restic's child process, and can transform restic's own output rather than the
database export.

## Exit codes are a contract

Restic documents these general meanings. A command can define more specific behavior, and future versions can add codes. Treat every unrecognized nonzero code as a failure.

| Exit code | Meaning | Automation response |
|---|---|---|
| 0 | Success | Record snapshot freshness and duration, not merely process success |
| 1 | Fatal error | Alert and preserve redacted stderr |
| 2 | Go runtime error | Alert as execution failure |
| 3 | Partial backup because some source files were unreadable; or some forget removals failed | Treat backup as incomplete; inspect affected paths before declaring protection healthy |
| 10 | Repository does not exist (0.17.0+) | Do not auto-initialize without an explicit new-repository directive |
| 11 | Failed to lock repository (0.17.0+) | Determine whether an operation is active; retry/wait or investigate stale lock |
| 12 | Wrong password (0.17.1+) | Inspect secret retrieval and intended repository, without logging a secret |
| 130 | Interrupted by SIGINT/SIGTERM (0.19.0+) | Treat as interrupted; rerun deliberately and inspect snapshots |

## JSON contract

Use `--json` only for commands that support it. Main JSON data goes to stdout; fatal errors may yield a final `exit_error` JSON object on stderr. Long-running commands such as `backup`, `check`, `restore`, and `diff` can emit JSON Lines distinguished by `message_type`.

Do not assume JSON schemas are closed. Restic documents that fields and message types can be added. Parsers must ignore unknown fields/message types, retain the exit code, and avoid treating an absence of a known optional field as an error. `prune` does not support JSON, so `forget --prune --json` mixes JSON and text: keep prune in a separate operational path if a machine needs clean structured output.

## Locks and retries

A repository lock is protection, not a routine error to erase. For expected short contention, `--retry-lock` can wait. For a persistent lock, inspect scheduler state and live restic processes before considering `unlock`. Use `--no-lock` only for read-only operations when the operational risk of an unlocked read is understood; it is not an escape hatch for mutations.

## Configuration safeguards

- Use absolute source and exclude-file paths in scheduled jobs.
- Keep `TMPDIR` capacity in the job's preflight; temporary pack creation requires space.
- Pin an intended restic version for critical automation and run `restic <command> --help` during upgrades.
- Keep backup, retention/prune, sampled/full checks, and restore drills as separately observable jobs.
- Do not make `restic cat config || restic init` an unattended default. An authentication or backend error can be mistaken for a missing repository.

## Sources

- Scripting, exit codes, JSON output, and compatibility guidance: https://restic.readthedocs.io/en/stable/075_scripting.html (accessed 2026-07-15)
- Backup stdin behavior and source errors: https://restic.readthedocs.io/en/stable/040_backup.html (accessed 2026-07-15)
- Locks and recovery diagnosis: https://restic.readthedocs.io/en/stable/077_troubleshooting.html (accessed 2026-07-15)

# Security and threat model

Use this reference whenever a task involves credentials, repository access, ransomware resistance, remote backends, or sharing recovery authority.

## Security properties and limits

Restic encrypts repository contents and metadata with keys derived from the repository password. It protects repository confidentiality against a storage provider that lacks the password. It does not solve every backup risk:

- A compromised machine that can read the password and write/delete the repository can often damage backups.
- A lost password, with no remaining valid repository key, makes data unrecoverable.
- A storage account with broad access can expose availability even if it cannot decrypt content.
- A successful backup may contain an already corrupted application state.
- Provider-side retention/immutability is a separate capability with provider-specific semantics.

## Threat-model worksheet

For each deployment, answer:

| Asset or failure | Control to examine |
|---|---|
| Repository password lost | Offline recovery process, multiple authorized key holders, documented access test |
| Endpoint ransomware | Separate credentials, least privilege, repository immutability/append-only options if appropriate, offline or independent copy |
| Storage credential leaked | Scoped identity, rotation, audit logs, secret manager, no credentials in URLs/logs |
| Accidental retention deletion | Dry-run review, grouped policy, maintenance window, documented recovery horizon |
| Backend account deletion/outage | Independent copy, provider recovery options, tested alternate restore path |
| Corrupt repository or silent bit rot | Scheduled `check` with data reads and restore drills |
| Operator error | Confirmation gate, separate restore target, peer review for destructive maintenance |

No single checklist proves security. Match controls to an explicit attacker and recovery scenario.

## Credential handling

Use separate credentials for repository encryption and backend access. Keep them in different systems or access paths where practical. A password file should have restrictive permissions and be readable only by the execution identity. A password command should emit only the password on stdout and must not emit prompts, logs, or shell diagnostics.

Preferred patterns:

```sh
# File permissions must be set by the host administrator.
restic --password-file /secure/restic-password snapshots

# The secret manager command must be non-interactive.
restic --password-command 'secret-tool lookup service restic' snapshots
```

Avoid:

```sh
restic --password 'literal-secret' snapshots       # command history/process exposure
export RESTIC_PASSWORD='literal-secret'            # shell/session/log exposure
set -x                                               # leaks expanded commands
```

Do not put backend keys in a systemd unit file, a launchd plist, a repository URL, an example template, or a ticket. Templates in this skill deliberately use placeholders and protected environment-file paths.

## Access control and key lifecycle

Restic repositories can contain multiple keys. Use separate keys for distinct authorized operators so access can be revoked without changing every workflow. Before removing a key, prove that another valid key is present and that the intended operators can open the repository. Do not remove the only known working key.

Backend permissions should be as narrow as the selected backend supports. For object storage, scope to the dedicated bucket/prefix and required list/read/write/delete actions. Any implementation of immutability, versioning, retention locks, or legal holds must be validated against that provider's current policy and against restic maintenance behavior, particularly deletes/prune.

## Network and host controls

- Use TLS and validate server identities for remote backends.
- Pin/verify SSH host keys for SFTP; do not turn off host verification.
- Run scheduled jobs with a dedicated, minimally privileged account.
- Restrict read access to source data and logs.
- Secure the scheduler, because it can become a route to the password file or secret command.
- Treat backup logs as potentially sensitive: file paths, host names, and error text can reveal system structure.

## Sources

- Restic repository/key model and password mechanisms: https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html (accessed 2026-07-15)
- Restic encryption overview: https://restic.readthedocs.io/en/stable/070_encryption.html (accessed 2026-07-15)
- Official security page: https://restic.net/#security (accessed 2026-07-15)
- AWS IAM and S3 permission example: https://restic.readthedocs.io/en/stable/080_examples.html (accessed 2026-07-15)

# Source index

Research baseline: 2026-07-15. Restic changes over time, especially command flags, backend integrations, and release behavior. Treat explicit version claims as stale unless refreshed against the linked source and the installed `restic version`.

## Primary sources

| Topic | Source | Scope |
|---|---|---|
| Documentation home | https://restic.readthedocs.io/en/stable/ | Stable user documentation |
| Introduction | https://restic.readthedocs.io/en/stable/010_introduction.html | Quickstart and core model |
| Installation | https://restic.readthedocs.io/en/stable/020_installation.html | Supported installation guidance |
| New repositories/backends | https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html | Password methods, repository format, native backend setup |
| Backups | https://restic.readthedocs.io/en/stable/040_backup.html | Backup behavior, filtering, VSS, options |
| Repository operations | https://restic.readthedocs.io/en/stable/045_working_with_repos.html | Listing, stats, check, copy, locks and related operations |
| Restore | https://restic.readthedocs.io/en/stable/050_restore.html | Snapshot selection and restore safety |
| Retention/prune | https://restic.readthedocs.io/en/stable/060_forget.html | Forget/prune behavior and scheduling implications |
| Encryption | https://restic.readthedocs.io/en/stable/070_encryption.html | Encryption design and key material model |
| Examples | https://restic.readthedocs.io/en/stable/080_examples.html | S3/IAM and operational examples |
| Command manual | https://restic.readthedocs.io/en/stable/manual_rest.html | Installed-command cross-check and option reference |
| Scripting and JSON | https://restic.readthedocs.io/en/stable/075_scripting.html | Exit codes, automation, structured output, parser compatibility |
| Tuning | https://restic.readthedocs.io/en/stable/047_tuning_parameters.html | Connections, verification, pack size, cache, and resource trade-offs |
| Troubleshooting | https://restic.readthedocs.io/en/stable/077_troubleshooting.html | Checks, repair order, locks, and bounded diagnosis |
| Releases | https://github.com/restic/restic/releases | Current release artifacts and user-visible release notes |
| Changelog | https://github.com/restic/restic/blob/master/CHANGELOG.md | Version-specific behavior history |
| Design | https://github.com/restic/restic/blob/master/doc/design.rst | Repository format and cryptographic implementation detail |

All sources above were accessed 2026-07-15.

## Secondary authoritative sources to add per backend

Restic's documentation establishes how restic talks to a backend. It cannot establish your provider's current operational guarantees. Add the exact provider's official documentation for:

- Bucket/container IAM policy and scoped credentials
- Endpoint and region/path-style requirements
- Object versioning, lifecycle, object lock, retention, legal hold, and deletion behavior
- Durability/availability claims and regional failure model
- Authentication rotation, audit logs, and incident recovery
- Billing and egress limits that affect restore

For a scheduled-job host, also retain official documentation for the scheduler and secret store in use. For application data, retain vendor documentation for backup consistency and restoration.

## Claim hygiene

- Cite restic docs for restic commands and repository semantics.
- Cite the provider for cloud-object behavior.
- Cite the application vendor for database/application consistency.
- Cite a tested restore drill for claims that a particular deployment can recover.
- Cite the installed binary's `restic version` and `restic <command> --help` for current local flag behavior.

# Troubleshooting and migration

Use this reference for failed jobs, locks, repository errors, damaged metadata, backend changes, or copy/migration work.

## Diagnose in order

1. Capture the exact restic command, version, exit status, and bounded stderr. Redact passwords, tokens, signed URLs, and private paths before sharing.
2. Separate source failures from repository/backend failures. A permission-denied source path, an expired S3 credential, and a corrupt index have different owners and remedies.
3. Reproduce with a read-only command if possible: `snapshots`, `stats`, `check`, or a limited `ls`.
4. Check for an active restic process before manipulating locks.
5. Read the installed command's `--help` and the matching stable documentation before a repair or migration command. These operations are version- and repository-state-sensitive.

## Symptom map

| Symptom | Evidence first | Do not do |
|---|---|---|
| Password/repository cannot open | Confirm repository URL, password source readability, backend identity, and exact error | Do not initialize the same target again |
| Permission denied | Identify source versus backend, execution user, file mode/ACL, and provider policy | Do not broaden permissions globally as a first fix |
| Locked repository | Process list/job scheduler, lock age, known concurrent maintenance | Do not immediately run `unlock` |
| Slow or timed-out job | Source scan, backend latency, bandwidth, lock contention, logs | Do not change many performance flags at once |
| Backup had errors | Examine failed source paths and whether snapshot policy allows partial backups | Do not call the backup healthy from exit code alone |
| `check` failure | Exact check error, version, backend health, last good restore | Do not run repair blindly |
| Need new storage backend | Destination compatibility, credentials, capacity, copy/restore test | Do not delete old repository after a copy-only claim |

## Locks

Restic uses repository locks to protect concurrent operations. A running backup, prune, check, or interrupted process can leave a lock. Establish whether an operation is active through the scheduler and process list; only then consider `restic unlock` for a stale lock. If the host may have crashed or the backend is eventually consistent, document the evidence and retry conservatively.

## Repository repair and index work

Commands such as `rebuild-index`, `repair`, `migrate`, and `recover` exist for specific conditions. They are not routine maintenance. Before invoking one:

- Preserve the exact error and `restic version`.
- Run the least-invasive documented diagnostic first.
- Confirm a second copy or tested recovery point where feasible.
- Read the corresponding command help for the installed release.
- Verify afterward with `check` and a restore test.

Do not invent a repair sequence based on a search snippet. Repository state and restic version determine the valid path.

### Documented repair posture

For a reported integrity failure, stop retention/prune jobs and preserve the current evidence before repair. The troubleshooting documentation's general sequence is: run `check --read-data`; make a copy of the repository metadata at minimum (especially `index/` and `snapshots/`); run `repair index` when check suggests it; rerun backups if overlapping source data can replenish missing content; run `repair snapshots --dry-run`; then decide whether `repair snapshots --forget` is an acceptable, explicit data-loss action; finally run another full check and a restore test.

`repair packs` and `repair snapshots` are remediation commands, not health checks. They can change what remains recoverable. Do not automate them, and never describe repair as successful without a post-repair `check` plus a restore of the relevant data.

## Copy and migration

`restic copy` copies snapshots between repositories. It is not a substitute for a recovery verification. For a migration:

1. Inventory source snapshots and repository/client versions.
2. Initialize and secure the destination independently.
3. Copy a small representative scope first if the command/backend supports it.
4. Compare source and destination snapshot inventory.
5. Run destination `check` and restore a representative snapshot from the destination.
6. Keep the source immutable/available until the agreed retention period and recovery drill are complete.

A backend move may require moving credentials, lifecycle policy, monitoring, and recovery documentation as well as data. Update all of them.

For `copy`, source and destination use distinct credential namespaces (`RESTIC_FROM_REPOSITORY`, `RESTIC_FROM_PASSWORD_FILE`, and related `RESTIC_FROM_*` variables for the source). Different repository encryption keys require data to be downloaded and uploaded. If cross-repository deduplication matters, initialize a new destination with `init --from-repo SOURCE --copy-chunker-params` before writing it; chunker parameters cannot be changed later. These details make the copy path a migration project, not a one-line storage move.

## Version compatibility

Repository format and client version are related but not interchangeable. The stable documentation identifies repository format version 2 as the current default and states its minimum restic version. Before upgrading automation, pin and test the candidate client against a non-production repository or a representative restore. Review the project's release notes for behavior changes, especially around commands used unattended.

## Evidence bundle for escalation

Provide only:

```text
restic version:
backend class (not credentials):
operation and redacted flags:
exit code:
timestamp/timezone:
first relevant stderr lines:
active-job/lock evidence:
last known-good check and restore-drill dates:
```

This is enough to diagnose most issues without disclosing keys or a full infrastructure inventory.

## Sources

- Restic command reference: https://restic.readthedocs.io/en/stable/manual_rest.html (accessed 2026-07-15)
- Working with repositories and lock-related commands: https://restic.readthedocs.io/en/stable/045_working_with_repos.html (accessed 2026-07-15)
- Restic release notes: https://github.com/restic/restic/releases (accessed 2026-07-15)
- Restic changelog: https://github.com/restic/restic/blob/master/CHANGELOG.md (accessed 2026-07-15)

#!/usr/bin/env bash
# Read-only local readiness check. It never opens a repository or prints secrets.
set -euo pipefail

usage() {
  cat <<'EOF'
Usage: scripts/restic-preflight.sh

Checks that restic is installed and reports only the presence/type of configured
repository and password settings. It never runs a command against the repository
and never prints secret values.
EOF
}

if [[ ${1:-} == "--help" ]]; then
  usage
  exit 0
fi
if [[ $# -ne 0 ]]; then
  usage >&2
  exit 2
fi

if ! command -v restic >/dev/null 2>&1; then
  printf 'ERROR: restic is not on PATH. Install it, then rerun this check.\n' >&2
  exit 127
fi

version=$(restic version 2>&1) || {
  printf 'ERROR: restic was found but `restic version` failed.\n' >&2
  exit 1
}

repository_source=unset
if [[ -n ${RESTIC_REPOSITORY:-} ]]; then
  repository_source=RESTIC_REPOSITORY
elif [[ -n ${RESTIC_REPOSITORY_FILE:-} ]]; then
  repository_source=RESTIC_REPOSITORY_FILE
fi

password_source=unset
if [[ -n ${RESTIC_PASSWORD_FILE:-} ]]; then
  password_source=RESTIC_PASSWORD_FILE
elif [[ -n ${RESTIC_PASSWORD_COMMAND:-} ]]; then
  password_source=RESTIC_PASSWORD_COMMAND
elif [[ -n ${RESTIC_PASSWORD:-} ]]; then
  password_source=RESTIC_PASSWORD
fi

printf 'restic: %s\n' "$version"
printf 'repository configuration: %s\n' "$repository_source"
printf 'password configuration: %s\n' "$password_source"

if [[ $password_source == RESTIC_PASSWORD ]]; then
  printf 'WARNING: RESTIC_PASSWORD is set. Prefer RESTIC_PASSWORD_FILE or RESTIC_PASSWORD_COMMAND for unattended jobs.\n' >&2
fi
if [[ $repository_source == unset || $password_source == unset ]]; then
  printf 'STATUS: incomplete configuration; set a repository location and protected password source before live operations.\n'
  exit 3
fi

printf 'STATUS: local prerequisites present; run `restic snapshots` next to verify repository access.\n'

#!/usr/bin/env bash
# Bounded read-only repository verification. Does not alter retention or delete data.
set -euo pipefail

usage() {
  cat <<'EOF'
Usage: scripts/restic-verify.sh [--repo REPOSITORY] [--password-file PATH]
                                [--read-data-subset PERCENT] [--full-data]

Runs `restic check` against an existing repository. By default it checks metadata.
--read-data-subset accepts restic syntax such as 5% or 500M. --full-data reads all
repository data and can be expensive. Repository/password environment variables are
used when corresponding flags are omitted. Secret values are never printed.
EOF
}

repo="${RESTIC_REPOSITORY:-}"
password_file="${RESTIC_PASSWORD_FILE:-}"
read_subset=""
full_data=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --repo) repo=${2:?ERROR: --repo needs a value}; shift 2 ;;
    --password-file) password_file=${2:?ERROR: --password-file needs a value}; shift 2 ;;
    --read-data-subset) read_subset=${2:?ERROR: --read-data-subset needs a value}; shift 2 ;;
    --full-data) full_data=true; shift ;;
    --help) usage; exit 0 ;;
    *) printf 'ERROR: unknown argument: %s\n' "$1" >&2; usage >&2; exit 2 ;;
  esac
done

if ! command -v restic >/dev/null 2>&1; then
  printf 'ERROR: restic is not on PATH.\n' >&2
  exit 127
fi
if [[ -z $repo ]]; then
  printf 'ERROR: repository missing. Use --repo or RESTIC_REPOSITORY.\n' >&2
  exit 2
fi
if [[ -n $read_subset && $full_data == true ]]; then
  printf 'ERROR: choose either --read-data-subset or --full-data.\n' >&2
  exit 2
fi

args=(--repo "$repo")
if [[ -n $password_file ]]; then
  args+=(--password-file "$password_file")
fi
args+=(check)
if [[ $full_data == true ]]; then
  args+=(--read-data)
elif [[ -n $read_subset ]]; then
  args+=(--read-data-subset "$read_subset")
fi

printf 'Running read-only restic check (%s).\n' \
  "$([[ $full_data == true ]] && printf 'full data' || [[ -n $read_subset ]] && printf 'sample %s' "$read_subset" || printf 'metadata')"
restic "${args[@]}"
printf 'PASS: restic check completed. Run a separate restore drill for recovery evidence.\n'

#!/usr/bin/env bash
# Deterministic test for restic-preflight.sh. No repository or installed restic needed.
set -euo pipefail

skill_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
mkdir -p "$tmp/bin"
cat > "$tmp/bin/restic" <<'EOF'
#!/usr/bin/env sh
[ "$1" = version ] || exit 64
printf 'restic 0.test\n'
EOF
chmod +x "$tmp/bin/restic"

output=$(PATH="$tmp/bin:$PATH" RESTIC_REPOSITORY=/backup RESTIC_PASSWORD_FILE=/secure/password \
  "$skill_root/scripts/restic-preflight.sh")
printf '%s\n' "$output" | grep -F 'restic: restic 0.test' >/dev/null
printf '%s\n' "$output" | grep -F 'repository configuration: RESTIC_REPOSITORY' >/dev/null
printf '%s\n' "$output" | grep -F 'password configuration: RESTIC_PASSWORD_FILE' >/dev/null
if printf '%s\n' "$output" | grep -F '/secure/password' >/dev/null; then
  printf 'FAIL: preflight exposed a password path\n' >&2
  exit 1
fi
printf 'PASS: restic-preflight.sh reports configuration presence without secret values.\n'

#!/usr/bin/env bash
# Deterministic test for restic-verify.sh. No repository or installed restic needed.
set -euo pipefail

skill_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
mkdir -p "$tmp/bin"
cat > "$tmp/bin/restic" <<'EOF'
#!/usr/bin/env sh
printf '%s\n' "$*"
EOF
chmod +x "$tmp/bin/restic"

output=$(PATH="$tmp/bin:$PATH" "$skill_root/scripts/restic-verify.sh" \
  --repo /backup --password-file /secure/password --read-data-subset 5%)
printf '%s\n' "$output" | grep -F 'Running read-only restic check (sample 5%).' >/dev/null
printf '%s\n' "$output" | grep -F -- '--repo /backup --password-file /secure/password check --read-data-subset 5%' >/dev/null
printf '%s\n' "$output" | grep -F 'PASS: restic check completed.' >/dev/null
printf 'PASS: restic-verify.sh constructs a bounded check command.\n'

# Restore drill: [repository/source class]

## Objective
- Date/time and operator:
- Recovery objective tested:
- Selected snapshot ID, host, paths, and tags:
- Why this snapshot was selected:

## Preconditions
- [ ] Separate, empty restore target:
- [ ] Sufficient target disk space:
- [ ] Repository/password access tested without exposing secrets:
- [ ] Application/vendor recovery procedure available, if applicable:

## Commands
```sh
restic snapshots --host [host] --tag [tag]
restic ls [snapshot]
restic restore [snapshot] --target [separate-target]
```

## Evidence
- Restore exit code and duration:
- File-level checks performed:
- Ownership/permissions/xattrs checks performed:
- Application/database validation performed:
- Checksum or content sample evidence:

## Result
- [ ] Passed
- [ ] Failed
- [ ] Partial; limitation recorded below

## Findings and follow-up
- Gap:
- Owner:
- Due date:
- Next drill date: