autorestic Documentation

The following community-driven projects are available to help integrate or deploy autorestic. Note that these are not officially affiliated with the autorestic project:

• SystemD Units: For running autorestic as a systemd service.
• Docker Image: For running autorestic within a containerized environment.
• Ansible Roles: For automating autorestic configuration and deployment via Ansible.

autorestic provides several features to enhance the restic backup experience:

• YAML Configuration: Manage all settings via YAML files instead of complex CLI arguments.
• Incremental Backups: Uses restic's incremental capabilities to ensure minimal space is used.
• Multi-Backend Support: Back up data to multiple different storage backends.
• Snapshot Management: Define snapshot policies and pruning rules.
• Security: All backups are fully encrypted.
• Automation Hooks: Execute custom commands before or after a backup runs.
• Exclusions: Support for exclude patterns and specific files.
• Scheduled Backups: Compatible with cron jobs for automatic execution.
• Docker Integration: Ability to backup and restore Docker volumes.
• Shell Completions: Generated completions available for bash, zsh, fish, and powershell.

When specifying a location via the -l or --location flag, you can use the location@backend syntax to target a specific backend associated with that location instead of the default one.

autorestic backup -l location@backend

The execution order of hooks follows this lifecycle:

1. prevalidate hook
2. Check backup location (validates to and from)
3. before hook
4. Run backup
5. after hook
6. Result-based execution:
   • success hook (if no errors found)
   • failure hook (if at least one error encountered)

Note on failures: If prevalidate or before hooks encounter errors, the backup and after hooks are skipped, and only the failure hook runs.

In autorestic, a location represents the input to the backup process, typically a folder or a set of folders. Locations are defined under the locations key in your configuration file.

Important Requirement: Location names MUST be in lower case.

A single location can be configured to back up to multiple backends, ensuring data redundancy across different servers.

version: 2

locations:
  my-location-name:
    from: path/to/backup
    to:
      - name-of-backend
      - also-backup-to-this-backend

When configuring restic flags, autorestic resolves conflicts using a hierarchical priority system. If the same flag is defined in multiple places, the more specific definition wins.

The order of priority (from highest to lowest) is:

1. Location options (highest priority)
2. Backend options
3. Global options (lowest priority)

In version 1.5, Autorestic transitioned from referencing backups by their file path to using native Restic tags.

Consequences:

• The restore and prune commands will no longer automatically recognize or include backups created before this change (pre-1.5).
• To use old backups with the new system, you must manually tag them.

To manually tag an old backup so it can be referenced by name, use the autorestic exec command with the --tag --add flags. Note that this specific command format is intended for scenarios where you have only one location.

autorestic exec -va -- tag --add ar:location:LOCATION_NAME # Only if you have only one location

When configuration values are defined in multiple places, autorestic resolves them using the following order of precedence (highest to lowest):

1. Env Variables (System environment variables)
2. Env File (.autorestic.env)
3. Config file (.autorestic.yaml)

Backends define the output locations for your backup process. Every backup configuration must include at least one backend.

Important: Backend names must be written in lower case.

version: 2

backends:
  name-of-backend:
    type: local
    path: /data/my/backups

To avoid repetition in advanced configurations, you can use YAML aliases. Define reusable snippets under the global extras key in your .autorestic.yml file. You can then inject these snippets into locations using the & (anchor) and * (alias) syntax, or the << (merge) operator.

Common use cases include sharing hooks (prevalidate, before, after) or options: forget policies across multiple locations.

version: 2

extras:
  hooks: &foo
    prevalidate:
      - echo "Wake up!"
    before:
      - echo "Hello"
    after:
      - echo "kthxbye"
  policies: &bar
    keep-daily: 14
    keep-weekly: 52

backends:
  # ...
locations:
  a:
    from: /data/a
    to: some
    hooks:
      <<: *foo
    options:
      forget:
        <<: *bar
  b:
    from: data/b
    to: some
    hooks:
      <<: *foo
    options:
      forget:
        <<: *bar