Operations Guide

This guide details the core operations available in Backrest and how to configure them effectively.

Restic Integration

Backrest executes operations through the restic backup tool. Each operation maps to specific restic commands with additional functionality provided by Backrest.

Binary Management

  • Location: Backrest searches for restic in:
    1. Data directory (typically ~/.local/share/backrest)
    2. /bin/ directory
  • Naming: Binary must be named restic-{VERSION}
  • Auto-download: If no binary is found, Backrest downloads a verified version from GitHub releases
  • Verification: Downloads are verified using SHA256 checksums signed by restic maintainers
  • Override: Set BACKREST_RESTIC_COMMAND environment variable to use a custom restic binary

Command Execution

  • Environment: Repository-specific environment variables are injected
  • Flags: Repository-configured flags are appended to commands
  • Logging:
    • Error logs: Last ~500 bytes (split between start/end if longer)
    • Full logs: Available via View Logs in the UI, truncated to 32KB (split if longer)

Scheduling System

Backrest provides flexible scheduling options for all operations through policies and clocks.

Schedule Policies

PolicyDescriptionUse Case
DisabledOperation will not runTemporarily disable operations
CronStandard cron expression timingPrecise scheduling (e.g., 0 0 * * * for daily midnight)
Interval DaysRun every N daysRegular daily+ intervals
Interval HoursRun every N hoursRegular sub-daily intervals

Schedule Clocks

ClockDescriptionBest For
LocalLocal timezone wall-clockFrequent operations (hourly+)
UTCUTC timezone wall-clockCross-timezone coordination
Last Run TimeRelative to previous executionInfrequent operations, preventing skips
Scheduling Best Practices
  • Backup Operations (Plan Settings):
    • Hourly or more frequent: Use "Local" clock
    • Daily or less frequent: Use "Last Run Time" clock
  • Prune/Check Operations (Repo Settings):
    • Run infrequently (e.g., monthly)
    • Use "Last Run Time" clock to prevent skips

Operation Types

Backup

Restic Documentation

Creates snapshots of your data using restic backup.

Process Flow:

  1. Start
    • Triggers CONDITION_SNAPSHOT_START hooks
    • Applies hook failure policies if needed
  2. Execution
    • Runs restic backup
    • Tags snapshot with plan:{PLAN_ID} and created-by:{INSTANCE_ID}
  3. Completion
    • Records operation metadata (files, bytes, snapshot ID)
    • Triggers appropriate hooks:
      • Error: CONDITION_SNAPSHOT_ERROR
      • Success: CONDITION_SNAPSHOT_SUCCESS
      • In both cases: CONDITION_SNAPSHOT_END
  4. Post-processing
    • Runs forget operation if retention policy exists

Snapshot Tags:

  • plan:{PLAN_ID}: Groups snapshots by backup plan
  • created-by:{INSTANCE_ID}: Identifies creating Backrest instance

Forget

Restic Documentation

Manages snapshot retention using restic forget --tag plan:{PLAN_ID}.

Retention Policies:

  • By Count: --keep-last {COUNT}
  • By Time Period: --keep-{hourly,daily,weekly,monthly,yearly} {COUNT}

Prune

Restic Documentation

Removes unreferenced data using restic prune.

Configuration:

  • Scheduled in repo settings
  • Appears under _system_ plan
  • Parameters:
    • Schedule timing
    • Max unused percent (controls repacking threshold)
Optimization Tips:
  • Run infrequently (monthly recommended)
  • Use higher max unused percent (5-10%) to reduce repacking
  • Consider storage costs vs. cleanup frequency

Check

Restic Documentation

Verifies repository integrity using restic check.

Configuration:

  • Scheduled in repo settings
  • Appears under _system_ plan
  • Parameters:
    • Schedule timing
    • Read data percentage
A value of 100% for read data% will read/download every pack file in your repository. This can be very slow and, if your provider bills for egress bandwidth, can be expensive. It is recommended to set this to 0% or a low value (e.g. 10%) for most use cases.
Edit this page on GitHub
Table of Contents