backrest/docs/content/1.introduction/1.getting-started.md

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

::alert{type="info"} Once backrest is installed, you can access the web interface at http://localhost:9898 (or the port you configured). Backrest will immediately prompt you to configure a default user and password (or you may disable authentication if you prefer). Once this is done, you can go on to configure your installation. ::

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
  • 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.ssh_argument="-i /path/to/key" will pass an SSH key to restic for use with SFTP repositories.
  • --force will force rereading all files on each backup rather than relying on metadata (e.g. last modified time). This can be much slower.
  • --one-file-system will prevent restic crossing filesystem boundaries.

• 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.

::alert{type="info"} Once you've added your repo you're ready to import snapshots (click Index Snapshots) if you have existing data. Go on to configure a backup plan to start creating new snapshots. ::

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 is expressed in cron format (configurable visually in the webui).

• 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 page of the wiki for more details.

::alert{type="success"} Success! Now that Backrest is configured you can sit back and let it manage your backups. You can monitor the status of your backups in the UI and restore files from snapshots as needed. ::

::alert{type="warning"} Make sure that you save a copy of your repo credentials and any encryption keys (e.g. the password) in a safe place. If you lose these you will not be able to restore your data. It can be a good idea to store your entire Backrest config (typically located at ~/.config/backrest/config.json) in a secure location e.g. a password manager or encrypted storage. ::