scroll-backup

📜 scroll backup system v0.5.2 'TERMINUS EST'

scroll is a configurable backup system with support for multiple backends. It features:

• restic support
• rsync support
• robocopy support for Windows
• Configurable compound commands called plans
• Support for email reports
• scroll is multi-platform. Currently tested under Linux and Windows.

Overview

scroll is simple to use. To backup all targets to all backends:

# Dots are wildcards
scroll backup . .

To backup two targets (docs,art) to a single backend (remote):

# Multiple targets or backends are seperated with a comma
scroll backup docs,art remote

To restore a target (docs) from a backend (remote) to a local path (/):

scroll restore docs remote /

To trim all targets in all restic backends according to the policy of each target:

scroll trim . .

The list command lists snapshots in restic backends:

scroll list . remote         # List all snapshots for this host in `remote`
scroll host:. ls . remote    # List all snapshots for all hosts in `remote`
scroll h:Corinth ls . remote # List all snapshots for another host in `remote`

More example commands:

# Create frozen snapshots that will be ignored by the `trim` command:
scroll freeze docs local docs-phase-1
scroll frozen . . # List all frozen snapshots
# Run a plan (compound preconfigured commands defined in the configuration file):
scroll plan weekly
# Find all snapshots containing a given path:
scroll find art remote /home/user/art/sketch/2024-01-23.png
# Check the integrity of all restic backends:
scroll check .
# Remove a stale lock:
scroll unlock local

Installation

npm install -g scroll-backup

NB: on Windows, first run scroll init after installation.

After installation, edit your config file and key file, if you plan to use restic backends.

Config File

• Linux: /etc/scroll/scroll.yaml
• Windows %ALLUSERSPROFILE%\scroll\scroll.yaml

Read more about this file and see a commented example in the Configuration section below.

Key File

• Linux: /etc/scroll/key
• Windows %ALLUSERSPROFILE%\scroll\key

Place the password used to encrypt and decrypt your restic repos here.

Scheduling

Note that scroll currently has no built-in scheduling; to run backup operations automatically you'll need to use whatever facilities your system provides for that (cron, systemd timers, Windows' Task Scheduler). In the future scroll may provide a scheduling daemon to be more system-agnostic.

Configuration

Scroll is configured using YAML.

• Under Linux, the default configuration file is located at /etc/scroll/scroll.yaml
• Under Windows its path is %ALLUSERSPROFILE%\scroll\scroll.yaml
  (typically C:\ProgramData\scroll\scroll.yaml)

Backends

Backends are locations where backups are stored. scroll supports multiple backend types; currently these are snap backends which use restic and sync backends. sync backends use rsync where available and robocopy under windows. When performing backup and restore operations the backend type determines which tool will be used.

Type Syntax

scroll uses a special syntax to specify the type of a backend. It looks like TYPE::. For example:

backends:
  example-a: snap::/backups/repo
  example-b: sync::ssh://[e-mail]:2222/backups

Valid types are:

• snap: A restic backend. This is the default type if none is given.
• sync: An rsync/robocopy backend.

restic

restic backends are the default backend type. Configuration example:

backends:
  # These are both restic backends with the `snap` type
  local-a: /backups/repo-a
  local-b: snap::/backups/repo-b
  # Any location restic supports will work:
  remote-a: sftp:[e-mail]:/backups/repo
  remote-b: sftp://[e-mail]:2222//srv/restic-repo
  remote-c: rest:https://user:[e-mail]:8000

rsync

rsync/robocopy backends are specified with the sync type. Configuration example:

backends:
  # Any location rsync supports will work:
  local-b: sync::/backups/sync
  remote-a: sync::rsync://[e-mail]:9999/backups/sync
  # When using ssh use URL syntax:
  remote-b: sync::ssh://[e-mail]:9999/backups/sync

Example Configuration

Below is an example configuration with commentary:

# Backends are named locations that store backups.
backends:
  # By default, scroll uses restic backends. These may use any path or URL
  # supported by restic.
  local: /backups/scroll/repo
  remote: rest:http://user:[e-mail]:3333/backups/repo
  # Using the `MODE::` syntax, you can specify the backend type.
  # `sync::` is used here to create rsync backends:
  local-sync: sync::/backups/scroll/sync
  remote-sync: sync::ssh://[e-mail]:7777/backups/scroll/sync
# Targets are named locations to be backed up.
targets:
  docs:
    # A target may include multiple paths:
    path:
      - /home/user/docs
      - /home/user/records
    # Paths may be excluded from the target:
    exclude: /home/user/docs/temp
    policy: --keep-daily 7
  art:
    path: /home/user/art
    # Policies are used with restic backends to control how many snapshots are
    # kept when the `trim` command is run.
    policy: --keep-daily 7
  movies:
    # If you don't plan to store a target in any restic backend, you don't need
    # to specify any trim policy.
    path: /home/user/movies
  music:
    path: /home/user/music
# Plans are configurable compound commands, allowing you to run multiple scroll
# commands as one, or to configure arguments for a single commands:
plan:
  # The default plan is named `main`
  # This could be run with either `scroll plan main` or just `scroll plan`
  main:
    - "backup docs,art local,remote"
    - "backup music local-sync,remote-sync"
  # Run this with `scroll plan weekly`
  weekly:
    - "backup movies local-sync,remote-sync"

Commands

help / h [COMMAND]

Print help information. If no COMMAND is given, print all help information.

list / ls [TARGET] [REPO]

List snapshots for the given target and repo, or all repos and targets if these are not given.

plan / p [NAME]

Run a plan by NAME. If no name is given, run the default plan.

backup / b [TARGET] [REPO] [TAG...]

Backup TARGET to REPO, with optional TAGs.

freeze TARGET REPO TITLE [TAG...]

Take frozen snapshot of TARGET to REPO, with a TITLE and optional TAGs. Frozen snapshots are ignored by the trim command.

frozen [TARGET] [REPO]

List frozen snapshots for the given target and repo.

init

Perform initial setup.

trim / t [TARGET] [REPO]

Forget and prune snapshots for TARGET in REPO.

find / f TARGET REPO [PATH...]

Search for snapshots containing one or more PATHs in the given TARGET and REPO.

restore / r TARGET REPO PATH

Restore the given TARGET from REPO to PATH.

unlock / u [REPO]

Unlock REPO, or all repos.

check / c [REPO] [ARG...]

Check the integrity of REPO, or all repos.

x [REPO] [ARG...]

Execute arbitrary restic commands for the given REPO.

backends

List all configured backends.

targets

List all configured targets.

show

Show configuration details.

report [LONG]

Send a report if mailing is configured.

License

Copyright 2020-2024 0E9B061F
Available under the terms of the Mozilla Public License Version 2.0.