borgbackup

Table of Contents

1. Description
2. Setup - The basics of getting started with borgbackup
   • Backup server
   • Backup client
3. Usage - Configuration options and additional functionality
4. Development - Guide for contributing to the module

Description

This module is intended to facilitate a backup scheme based on borg with the following security properties:

• compromise of a node cannot escalate to compromise of backups
• compromise of the backup server cannot escalate to compromise of nodes

To accomplish this, the backup server is assumed to be managed masterless and nodes are restricted to append-only access.

This has a number of downsides:

• access to the backupserver has to be configured manually and cannot be automated with exported resources.
• purging of old backups will have to be done manually.

If you are looking for a backup solution with as little configuration effort as possible, you are probably better off with the Vox Populi module.

Setup

Important: to be able to recover from backups, you will need access to the following three:

• the BORG_PASSPHRASE, set is borgbackup::client::borgpassphrase
• ssh access to the backup server
• the client's keyfile, stored in /root/.config/borg/keys

This module does not arrange these requirements for you! Make sure you have local copies of the BORG_PASSPHRASE as well as the clients' keys on the machine you want to use for recovery.

Backup server

The backup server can be configured as follows:

include borgbackup::server

To grant nodes access to write backups, fill your hiera with something like:

borgbackups::server::clients:
  hostname1:
    type: ssh-rsa
    data: AAAAgnove41...
  hostname2:
    type: ssh-rsa
    data: AAAAnbor0ve..

This will create users named hostname1, hostname2, etc. You will need to make sure you provide yourself (or anyone who needs access to the backups) with ssh access to these accounts.

Backup client

All requirements for running backup jobs can be installed as follows:

include borgbackup::client

This class is included in the backup_lv and backup_fs defined types, so there is no strict need to do so explicitly in your own manifests.

You will need to provide the BORG_PASSPHRASE variable in hiera (preferably using eyaml):

borgbackup::client::borgpassphrase: supersecret

Usage

This module supports two types of backup jobs:

• backing up logical volumes through backup_lv
• backing up data from filesystem through backup_fs

Backing up logical volumes

A systemd timer that ensures a weekly backup run can be created like this:

borgbackup::backup_lv { 'backstuffup':
  excludes     => ['/var/log','/tmp'],
  backupserver => 'backups.example.org',
  vg           => 'myvolume',
  lv           => 'stuff',
}

This assumes the logical volume to contain a paritioned disk image. In case the logical volume directly contains a filesystem, add the rawdisk parameter:

borgbackup::backup_lv { 'backstuffup':
  excludes     => ['/var/log','/tmp'],
  backupserver => 'backups.example.org',
  vg           => 'myvolume',
  lv           => 'stuff',
  rawdisk      => true,
}

Backing up from filesystem

To create a weekly backup of (part of) your filesystem, you can apply:

borgbackup::backup_fs { 'backstuffup':
  backupserver => 'backups.example.org',
  mountpoint   => '/home',
}

Development

Merge requests are welcome. If you wish to share any security issues, please contact tails-sysadmins@boum.org. Our PGP fingerprint is: D113CB6D5131D34BA5F0FE9E70F4F03116525F43

Reference

Table of Contents

Classes

• borgbackup: Installs borgbackup
• borgbackup::client: Configures a backup client
• borgbackup::server: Configures a backup server

Defined types

• borgbackup::backup_fs: Sets up a weekly backup job for a filesystem
• borgbackup::backup_lv: Sets up a weekly backup job for a logical volume

Classes

borgbackup

This class installs borgbackup.

Examples

include borgbackup

borgbackup::client

This class deploys the required scripts and dependencies to run backup jobs on a node.

Examples

class { 'borgbackup::client':
  borgpassphrase => 'supersecret',
}

Parameters

The following parameters are available in the borgbackup::client class.

borgpassphrase

Data type: String

The BORG_PASSPHRASE environment variable (for more info, see: https://borgbackup.readthedocs.io/en/stable/usage/general.html)

borgbackup::server

This class ensures borgbackup is installed and that for every client:

• there is a user, named after the client, with a homedirectory
• the client has ssh access to write backups append-only

Examples

class { 'borgbackup::server':
  clients => {
    host1 => {
      type => 'ssh-rsa',
      data => 'AAAAB3NzaC1yc2EAAA...',
    },
  },
}

Parameters

The following parameters are available in the borgbackup::server class.

clients

Data type: Hash

A hash containing all the names of all the nodes that need to make backups and their respective root users' ssh public key.

Defined types

borgbackup::backup_fs

Creates a systemd timer that calls the backup script for backing up a filesystem. Defaults to backing up everything, this can be adjusted by setting the mountpoint parameter.

Examples

borgbackup::backup_fs { 'backstuffup':
  excludes     => ['/var/log','/tmp'],
  backupserver => 'backups.example.org',
}

Parameters

The following parameters are available in the borgbackup::backup_fs defined type.

backupserver

Data type: String

The server backups are written to.

mountpoint

Data type: String

The point in our filesystem from where we want to back up, defaults to / to provide full backups.

Default value: '/'

backupuser

Data type: String

The username on the backupserver, defaults to the client's hostname.

Default value: $trusted['hostname']

basedir

Data type: String

The directory on the backupserver in which our borg repository resides.

Default value: "/home/${backupuser}"

repo

Data type: String

The name of our borg repository.

Default value: $title

dow

Data type: String

The day of the week in which we want the backup job to run.

Default value: 'Sun'

rnd

Data type: String

The random time offset (from midnight) on which the backup job is run.

Default value: '24h'

excludes

Data type: Array[String]

An array of patterns for paths to exclude from backups (see: https://borgbackup.readthedocs.io/en/stable/usage/create.html)

Default value: []

borgbackup::backup_lv

Creates a systemd timer that calls the backup script for backing up logical volumes. The volume can contain either a partitioned disk image or a filesystem. In the latter case, rawdisk should be set to true.

Examples

borgbackup::backup_lv { 'backstuffup':
  excludes     => ['/var/log','/tmp'],
  backupserver => 'backups.example.org',
  vg           => 'myvolume',
  lv           => 'stuff',
}

Parameters

The following parameters are available in the borgbackup::backup_lv defined type.

backupserver

Data type: String

The server backups are written to.

vg

Data type: String

The volume group in which the logical volume to back up resides.

lv

Data type: String

The logical volume to back up.

backupuser

Data type: String

The username on the backupserver, defaults to the client's hostname.

Default value: $trusted['hostname']

basedir

Data type: String

The directory on the backupserver in which our borg repository resides.

Default value: "/home/${backupuser}"

repo

Data type: String

The name of our borg repository.

Default value: $title

dow

Data type: String

The day of the week in which we want the backup job to run.

Default value: 'Sun'

rnd

Data type: String

The random time offset (from midnight) on which the backup job is run.

Default value: '24h'

excludes

Data type: Array[String]

An array of patterns for paths to exclude from backups (see: https://borgbackup.readthedocs.io/en/stable/usage/create.html)

Default value: []

rawdisk

Data type: Boolean

A boolean describing whether the logical volume directly contains a filesystem (as opposed to a partitioned disk image).

Default value: false

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.2

Bugfixes

Fixes typo in systemd service.

Release 0.1.1

Features

Added a parameter to set the randomised delay at which a backup job runs and changed the default from 4 to 24 hours to remove bias towards particular timezones.

Release 0.1.0

Features

Weekly backups of logical volumes and/or filesystem

Bugfixes

none

Known Issues

none