Getting Started

This guide will walk you through the basic steps to setup a new Backrest instance.

Installation

Please refer to the GitHub README for platform-specific installation instructions.

Core Concepts

Before diving into configuration, let's understand some key terminology:

• Restic Repository: The underlying storage location where your backup data is kept. While Backrest manages this for you, understanding this concept allows you to interact directly with your backups using the restic CLI if needed.
• Backrest Repository: A configuration set that defines:
  • Where your backup data is stored
  • Encryption credentials
  • Backup orchestration settings
  • Associated hooks and options
• Backup Plan: A configuration that specifies:
  • What to backup
  • When to create snapshots
  • How long to retain backups
  • When to run maintenance operations
• Key Operations:
  • Backup: Creates a new snapshot of your data
  • Forget: Marks old snapshots for deletion (without removing data)
  • Prune: Removes unreferenced data to free up storage space
  • Restore: Retrieves files from a snapshot to your local system

Initial Setup

1. Instance Configuration

Instance ID

• A unique identifier for your Backrest installation
• Used to distinguish snapshots from different Backrest instances
• Important: Cannot be changed after initial setup

Authentication

• Set your username and password during first launch
• To reset credentials: delete the "users" key from:
  • Linux/macOS: ~/.config/backrest/config.json
  • Windows: %appdata%\backrest\config.json
• Authentication can be disabled for local installations or when using an authenticating reverse proxy

2. Repository Setup

Click "Add Repo" to configure your backup storage location. You can either create a new repository or connect to an existing one.

Essential Repository Settings

1. Repository Name
   • A human-readable identifier
   • Cannot be changed after creation
2. Repository URI
   • Specifies the backup storage location
   • Common formats:
     • Backblaze B2: b2:bucket or b2:bucket/prefix
     • AWS S3: s3:bucket or s3:bucket/prefix
     • Google Cloud: gs:bucket:/ or gs:bucket:/prefix
     • SFTP: sftp:user@host:/path/to/repo
     • Local: /mnt/backupdisk/repo1
     • Rclone: rclone:remote:path (requires rclone installation)
3. Environment Variables Storage provider credentials:
   • S3: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
   • B2: B2_ACCOUNT_ID, B2_ACCOUNT_KEY
   • Google Cloud: GOOGLE_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS
4. Optional Flags Common examples:
   • SFTP key: -o sftp.args="-i /path/to/key"
   • Disable locking: --no-lock
   • Bandwidth limits: --limit-upload 1000, --limit-download 1000
5. Maintenance Policies
   • Prune Policy: Schedule for cleaning unreferenced data
   • Check Policy: Schedule for backup integrity verification

3. Backup Plan Configuration

Create a backup plan by clicking "Add Plan" and configuring these settings:

Plan Settings

1. Plan Name
   • Choose a descriptive, immutable name
   • Recommended format: [storage]-[content] (e.g., b2-documents)
2. Repository
   • Select your target repository
   • Cannot be changed after creation
3. Backup Configuration
   • Paths: Directories/files to backup
   • Excludes: Patterns or paths to skip (e.g., *node_modules*)
4. Schedule Choose one:
   • Hourly/daily intervals
   • Cron expression (e.g., 0 0 * * * for daily midnight backups)
   • Clock options:
     • UTC/Local: Wall-clock time
     • Last Run Time: Relative to previous execution
5. Retention Policy Controls snapshot lifecycle:
   • Count-based: Keep N most recent snapshots
   • Time-based: Keep snapshots by age (e.g., daily for 7 days, weekly for 4 weeks)
   • None: Manual retention management