From d39e3136d852a338bd01d9dc3cfabcbda4996967 Mon Sep 17 00:00:00 2001 From: Atlas Date: Wed, 15 Apr 2026 21:07:10 -0700 Subject: [PATCH] Create: reference/autorestic.md --- reference/autorestic.md | 392 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 reference/autorestic.md diff --git a/reference/autorestic.md b/reference/autorestic.md new file mode 100644 index 0000000..dc2e881 --- /dev/null +++ b/reference/autorestic.md @@ -0,0 +1,392 @@ +--- +created: '2026-04-16T04:07:10+00:00' +id: 34f7f22e-f842-40e8-bbc2-1dff12c1b87e +keywords: +- autorestic +- restic +- YAML +- backup +- automation +- cron +- hooks +- Docker volumes +- snapshot copy +- retention policy +- multi-backend +- cupcakearmy +links: [] +modified: '2026-04-16T04:07:10+00:00' +summary: Reference for Autorestic — a config-driven CLI wrapper around restic that + simplifies backup management via YAML configuration, multi-backend orchestration, + hooks, cron scheduling, and Docker volume support. +tags: +- backup +- restic +- autorestic +- automation +- CLI +- YAML +- reference +title: Autorestic Reference +--- + +--- +id: autorestic +title: Autorestic Reference +created: 2025-07-10 +modified: 2025-07-10 +tags: + - backup + - restic + - autorestic + - automation + - CLI + - YAML + - reference +links: + - reference/restic.md + - reference/docker-compose.md +--- + +# Autorestic — Config-Driven CLI for Restic + +**URL:** https://autorestic.vercel.app/ +**GitHub:** https://github.com/cupcakearmy/autorestic +**License:** MIT +**Platforms:** Linux, macOS (Windows NOT supported) + +## Overview + +Autorestic is a high-level CLI wrapper around restic that simplifies backup management through YAML configuration files. While restic is powerful, its CLI becomes unwieldy when managing many backup locations across multiple backends. Autorestic provides: + +- **YAML config files** — no complex CLI flags +- **Multiple backends per location** — backup to several destinations simultaneously +- **Snapshot policies** — retention/forget rules per location +- **Before/after hooks** — run commands around backups +- **Cron job scheduling** — built-in automatic scheduling +- **Docker volume support** — backup/restore Docker volumes +- **Copy optimization** — copy snapshots between backends without re-reading source +- **Generated shell completions** — bash, zsh, fish, powershell + +## Installation + +### Script (Recommended) + +```bash +curl -s https://raw.githubusercontent.com/cupcakearmy/autorestic/master/install.sh | bash +``` + +Requires `bash`, `wget`, and `bzip2`. + +### Package Managers + +| Platform | Command | +|---|---| +| macOS | `brew install autorestic` | +| Fedora | `dnf install autorestic` | +| Arch Linux | AUR package | + +### Docker + +```bash +docker pull cupcakearmy/autorestic +``` + +### Manual + +Download binary from GitHub releases to `/usr/local/bin` (autoupdates still work). + +## Configuration + +Autorestic uses a YAML config file. Default locations: + +- `~/.autorestic.yml` +- `$PWD/.autorestic.yml` + +Custom location: `-c path/to/config.yml` + +### Config Structure + +```yaml +version: 2 + +global: # Optional global settings + forget: # Default retention policy + keep-daily: 30 + keep-weekly: 52 + +backends: # Backend definitions + local: + type: local + path: /tmp/backups + key: some-secret-password + b2: + type: b2 + path: my-bucket + key: another-secret + s3: + type: s3 + path: s3.amazonaws.com/bucket + key: s3-secret + env: # Custom environment variables + AWS_ACCESS_KEY_ID: key + AWS_SECRET_ACCESS_KEY: secret + +locations: # Backup locations + home: + from: /home/user + to: # Single or multiple backends + - local + - b2 + hooks: + before: echo "Starting backup" + after: echo "Done!" + success: echo "Success!" + failure: echo "Failed!" + cron: "0 3 * * *" # Cron expression for scheduling + forget: prune # Auto-forget after backup (use "yes" to forget without prune) + options: + forget: + keep-last: 10 + keep-daily: 14 + backup: + exclude: + - '*.tmp' + exclude-file: .gitignore + docker-volumes: + from: docker-volumes:/ # Docker volume syntax + to: local +``` + +### Backend Names + +Names MUST be lower case. If no key is defined, autorestic auto-generates one and writes it back to the config. To prevent this, set `requireKey: true`. + +### Location Names + +Names MUST be lower case. Location names are used with `-l` flags. + +## Locations + +The `from` field is the source (can be a single string or an array of strings). Paths can be absolute, relative to the config file, or use `~` for home directory. + +The `to` field is one or more backends (defined in the `backends` section). + +### Location@Backend Syntax + +Select a specific backend for a location: + +```bash +autorestic backup -l location@backend +``` + +## Hooks + +Five hook stages available: + +1. **prevalidate** — before checking if backup location is valid (e.g., to mount filesystem) +2. **before** — after validation check, before backup runs +3. **after** — after backup completes (success or failure) +4. **success** — only on successful backup +5. **failure** — only on failed backup + +**Flow:** `prevalidate` → check location → `before` → backup → `after` → `success`/`failure` + +If `prevalidate` or `before` fails, backup and `after` are skipped, only `failure` runs. + +### Environment Variables in Hooks + +- `AUTORESTIC_LOCATION` — location name (all hooks) +- After/success hooks additionally get per-backend metadata: + - `AUTORESTIC___` where N is the backend execution order + +Available metadata: `SNAPSHOT_ID`, `PARENT_SNAPSHOT_ID`, `FILES_ADDED`, `FILES_CHANGED`, `FILES_UNMODIFIED`, `DIRS_ADDED`, `DIRS_CHANGED`, `DIRS_UNMODIFIED`, `ADDED_SIZE`, `PROCESSED_FILES`, `PROCESSED_SIZE`, `PROCESSED_DURATION` + +## Location Options + +Pass native restic flags per command: + +```yaml +locations: + my-location: + from: /data + to: backend + options: + backup: + tag: + - foo + - bar + one-file-system: true + forget: + keep-last: 5 +``` + +**Priority:** location > backend > global + +## Copy Optimization + +Instead of backing up to multiple backends separately, copy snapshots between backends: + +```yaml +locations: + my-location: + from: /data + to: + - fast-backend # backup here + - slow-backend # backup here + copy: + fast-backend: + - slow-backend # copy from fast to slow (no re-read of source) +``` + +## Excluding Files + +```yaml +locations: + my-location: + from: /data + to: my-backend + options: + backup: + exclude: + - '*.nope' + - '*.abc' + exclude-file: .gitignore +``` + +## Forget/Retention Policies + +```yaml +locations: + etc: + from: /etc + to: local + forget: prune # auto-forget after backup + options: + forget: + keep-last: 5 + keep-hourly: 3 + keep-daily: 4 + keep-weekly: 1 + keep-monthly: 12 + keep-yearly: 7 + keep-within: "14d" +``` + +Global defaults: + +```yaml +global: + forget: + keep-daily: 30 + keep-weekly: 52 +``` + +## Cron Jobs + +Add a `cron` expression to any location: + +```yaml +locations: + home: + from: /home/user + to: local + cron: "0 3 * * *" # daily at 3 AM +``` + +Then install the cron runner (once, regardless of number of locations): + +```bash +# In crontab (trigger every 5 minutes recommended): +*/5 * * * * autorestic --ci cron +# or: +*/5 * * * * autorestic -c /path/to/config.yml --ci cron +``` + +Manual backups with `autorestic backup` don't affect the cron timeline. + +## Docker Volumes + +Backup Docker volumes using special `from` syntax: + +```yaml +locations: + db-volume: + from: docker-volumes:my_volume_name + to: local +``` + +## CLI Reference + +### General + +```bash +autorestic info # show config summary +autorestic check # verify config and initialize backends +autorestic -c config.yml ... # use custom config file +``` + +### Backup + +```bash +autorestic backup -a # backup all locations +autorestic backup -l home # backup specific location +autorestic backup -l home -l etc # backup multiple locations +autorestic backup -l home@b2 # backup location to specific backend +``` + +### Restore + +```bash +autorestic restore -l home --to /path/where/to/restore +autorestic restore -l home --to /path --force # overwrite existing data +``` + +If a location has multiple backends, autorestic uses the first one. Default snapshot is `latest`. + +### Forget/Prune + +```bash +autorestic forget -a # apply retention policy to all +autorestic forget -l home # apply to specific location +autorestic forget -a --dry-run # preview only +autorestic forget -a --prune # also prune (free disk space) +``` + +### Exec (Run Native Restic Commands) + +```bash +autorestic exec -a -- snapshots # list all snapshots +autorestic exec -av -- snapshots # verbose +autorestic exec -b local -- snapshots # specific backend +autorestic exec -a -- check --read-data # any restic command +``` + +### Other Commands + +| Command | Description | +|---|---| +| `autorestic cron` | Run cron-triggered backups | +| `autorestic unlock` | Remove stale locks | +| `autorestic upgrade` | Update autorestic | +| `autorestic install` | Install restic binary | +| `autorestic uninstall` | Uninstall restic binary | +| `autorestic completion` | Generate shell completions | + +## Relationship to Restic + +Autorestic is purely a wrapper — all actual backup/restore/encryption work is done by restic. Autorestic adds: + +- YAML configuration management +- Multi-backend orchestration +- Hook execution +- Cron scheduling +- Snapshot copy optimization +- Simplified CLI for common operations + +For all restic concepts (encryption, deduplication, backends, etc.), see the [Restic Reference](reference/restic.md). + +## See Also + +- [Restic Reference](reference/restic.md) +- [Docker Compose Reference](reference/docker-compose.md) \ No newline at end of file