vh/VuongKB

Fork 0

Files

T

Atlas d39e3136d8 Create: reference/autorestic.md

2026-04-15 21:07:10 -07:00

9.4 KiB

Raw Blame History

created, id, keywords, links, modified, summary, tags, title

created

keywords

links

modified

summary

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)

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

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

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:

autorestic backup -l location@backend

Hooks

Five hook stages available:

prevalidate — before checking if backup location is valid (e.g., to mount filesystem)
before — after validation check, before backup runs
after — after backup completes (success or failure)
success — only on successful backup
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_<METADATA>_<BACKEND>_<N> 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:

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:

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

locations:
  my-location:
    from: /data
    to: my-backend
    options:
      backup:
        exclude:
          - '*.nope'
          - '*.abc'
        exclude-file: .gitignore

Forget/Retention Policies

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:

global:
  forget:
    keep-daily: 30
    keep-weekly: 52

Cron Jobs

Add a cron expression to any location:

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):

# 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:

locations:
  db-volume:
    from: docker-volumes:my_volume_name
    to: local

CLI Reference

General

autorestic info              # show config summary
autorestic check             # verify config and initialize backends
autorestic -c config.yml ... # use custom config file

Backup

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

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

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)

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.

9.4 KiB Raw Blame History