Getting Started

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

Installation

See the Github README for installation instructions for your platform.

Terminology

• Restic Repo Backrest uses restic under-the-hood to manage backups. A restic repo is a location where restic will store your backup data, this detail is typically abstracted away from the user by Backrest but is important to understand as it means you have the option to use the restic CLI to interact with snapshots created by Backrest directly if you wish.
• Repo A Backrest repo (called a Repo from here on) is configuration data which identifies a location where your backup data will be stored (forwarded to restic), the credentials that will encrypt your backup data, hooks, and any options needed by backrest to orchestrate your backups.
• Plan A Backrest plan (called a Plan from here on) is configuration data that describes a schedule for taking snapshots, forgetting old snapshots, and running prune operations. Multiple plans can write data to the same Backrest repo.
• Operations
  • A Backup creates a restic snapshot and send it to a repo.
  • A Forget operation marks old snapshots for deletion but does not remove data from storage.
  • A Prune operation removes data from storage that is no longer referenced by any snapshot (see restic docs on forget and prune).
  • A Restore operation retrieves files from a snapshot and writes them to a location on disk.

Configuration

Instance ID

• The instance ID is a unique identifier for your Backrest instance. This is used to tag snapshots created by Backrest so that you can distinguish them from snapshots created by other instances. This is useful if you have multiple Backrest instances backing up to the same repo.
• Notably the instance ID cannot be changed after initial configuration as it is stored in your snapshots. Choose a value carefully.

Username and password

• Username and password is set on first launch of Backrest. If you lose your password you can reset it by deleting the "users" key from the ~/.config/backrest/config.json file (or %appdata%\backrest\config.json on Windows) and restarting the Backrest service.
• If you don't want to use authentication (e.g. a local only installation or if you're using an authenticating reverse proxy) you can disabled authentication.

Add a new repository

A Backrest repository is implemented as a restic repository under-the-hood (more on this later). A Repo is a configuration object which identifies a storage location and the credentials that will be used to encrypt snapshots sent to that storage. You can either add an existing repo that you created on the restic CLI or create a new one in the Backrest UI. In either case, click the "Add Repo" button in the UI to configure Backrest to use your backup location.

The primary properties of a repository are:

• Repo Name A human-readable name for the repository. This is used to identify the repository in the UI and is immutable after creation.
• Repo URI identifies the location where the repo's data is stored. This corresponds to the URI used by restic. See the restic docs for the repo types that restic supports. For common storage providers this looks like:
  • Backblaze: b2:yourbucket or b2:yourbucket/pathprefix
  • AWS S3 (or S3 compatible storage): s3:yourbucket or s3:yourbucket/pathprefix
  • SFTP e.g. sftp:user@host:/path/to/repo (note sftp:// is known to have issues in some cases, do not include a double slash prefix).
  • Local path: /mnt/backupdisk/repo1.
  • Rclone remote: rclone:remote:path. See the rclone docs for more information. To use rclone remotes, you must first install and configure rclone and ensure that the rclone config (e.g. ~/.config/rclone/rclone.conf) is available to the backrest process.
• Environment Variables environment variables provide additional configuration to restic (typically related to credentials for the storage provider). Common examples are
  • For S3 storage set: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • For B2 storage set: B2_ACCOUNT_ID and B2_ACCOUNT_KEY
• Flags additional flags to provide to restic. At the moment only presence flags are supported. Common usage might include:
  • -o sftp.args="-i /path/to/key" will pass an SSH key to restic for use with SFTP repositories.
  • --no-lock will disable the use of locks in the restic repository. This can be useful for read-only repos.
  • --limit-upload 1000 will limit the upload speed to a speed in kilobytes per second (e.g. 1000KB/s). This can be useful to avoid saturating a network connection.
  • --limit-download 1000 will limit the download speed to a speed in kilobytes per second (e.g. 1000KB/s). This can be useful to avoid saturating a network connection.
• Hooks are actions triggered by backup lifecycle events, repo hooks will apply to actions run by any plan that writes to the repo. Hooks can also be configured at the plan level. See the hooks documentation for more information.
• Prune Policy the policy that determines when prune operations will run. Prune operations clean up unreferenced data in your repo (freeing up storage in your repo over time). See the prune documentation for more information.
• Check Policy the policy that determines when check operations will run. Check operations periodically verify the integrity of your backups. See the check documentation for more information.

Configure a backup plan

A Backrest plan is a configuration object which describes a schedule for taking snapshots, retention of old snapshots, and running prune operations. Multiple plans can write data to the same Backrest repo. To create a new plan, click the "Add Plan" button in the UI and populate the plan configuration:

The primary properties of a plan are:

• Plan Name the plan name is immutable after creation, choose carefully. Organizationally it can help to choose a name that includes the type of storage or a short form of the name of the repo that will be used. E.g. to backup "Documents" directory to "b2storage" you might create a plan named "b2-documents" or similar.
• Repository the repository that this plan will operate on. This is immutable after creation.
• Paths a list of paths to include in backups.
• Excludes a list of paths to exclude from backup operations. These can be fully qualified paths (e.g. /foo/bar/baz) or wildcard paths (e.g. *node_modules*). See the restic docs on excluding files for more details. Files listed in excludes map to restic's --excludes flag.
• Schedule the schedule on which backups will run.
  • This can be specified as an interval in hours, interval in days, or as a cron providing detailed control over when backups run (e.g. 0 0 * * * for midnight every day).
  • A clock can also be configured which determines the time the schedule is checked against. UTC or Local use the current wall-clock time but will evaluate differently when using cron expressions where the timezone matters. Last Run Time evaluates the schedule relative to the last time the task ran rather than the current wall time, this can be useful for ensuring tasks aren't skipped if the schedule is missed for some reason (e.g. on a laptop that is frequently asleep).
• Retention Policy the duration that snapshots are retained for. This is enforced by running restic forget after each backup operation if a retention policy is specified. This can be set to none for append only repos or if you'd like to manage your own retention (e.g. run forget manually). Setting some retention policy is recommended to avoid the snapshot history growing without bound. Retention may be configured either based on count or bucketed by time period. See the restic docs to understand more about these policy options. Supported modes are:
  • By Count - keeps a fixed number of snapshots. E.g. keep the last 7 snapshots.
  • By Time Period - keeps snapshots in a time-based bucket. E.g. keep 1 snapshot per day for the last 7 days, 1 snapshot per week for the last 4 weeks, and 1 snapshot per month for the last 12 months.
  • None - no retention policy is enforced. This is useful for append-only repos or if you'd like to manage retention manually e.g. in an external script. Note that care should be taken not to allow snapshots to grow without bound (though Backrest will typically scale and perform well with hundreds to thousands of snapshots).
• Hooks hooks are actions that can be configured in response to backup lifecycle events. See the hooks documentation for more information and the hooks cookbook for examples.
• Backup Flags flags that are specific to the backup command (e.g. --force to force a full scan of all files rather than relying on metadata). These flags are passed directly to the restic command.
  • --one-file-system will prevent restic crossing filesystem boundaries.
  • --force will force rereading all files on each backup rather than relying on metadata (e.g. last modified time). This can be much slower.
  • --skip-if-unchanged will skip creating a new snapshot if nothing has changed on the filesystem. Note that the backup task will still appear in the 'Full Operation History' but not in the tree view. Snapshots will still be created if any file or folder metadata changes (e.g. permissions, access times, etc).