borgbackup

Backups using borg

Project URL RSS Feed Report issues

Module Stats

483 downloads

136 latest version

5.0 quality score

Version information

released Aug 23rd 2023

This version is compatible with:

Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
Puppet >= 5.5.0 < 8.0.0

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'tails-borgbackup', '0.1.3'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add tails-borgbackup

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install tails-borgbackup --version 0.1.3

Documentation

tails/borgbackup — version 0.1.3 Aug 23rd 2023

borgbackup

Description
Setup - The basics of getting started with borgbackup
- Backup server
- Backup client
Usage - Configuration options and additional functionality
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

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

Modules

Discover

Contribute

Resources

About Forge

Getting Started

borgbackup

Version information

This version is compatible with:

Start using this module

Documentation

borgbackup

Table of Contents

Description

Setup

Backup server

Backup client

Usage

Backing up logical volumes

Backing up from filesystem

Development

Reference

Table of Contents

Classes

Defined types

Classes

borgbackup

Examples

borgbackup::client

Examples

Parameters

borgpassphrase

borgbackup::server

Examples

Parameters

clients

Defined types

borgbackup::backup_fs

Examples

Parameters

backupserver

mountpoint

backupuser

basedir

repo

dow

rnd

excludes

borgbackup::backup_lv

Examples

Parameters

backupserver

vg

lv

backupuser

basedir

repo

dow

rnd

excludes

rawdisk

Changelog

Release 0.1.2

Release 0.1.1

Release 0.1.0

`borgbackup`

`borgbackup::client`

`borgpassphrase`

`borgbackup::server`

`clients`

`borgbackup::backup_fs`

`backupserver`

`mountpoint`

`backupuser`

`basedir`

`repo`

`dow`

`rnd`

`excludes`

`borgbackup::backup_lv`

`backupserver`

`vg`

`lv`

`backupuser`

`basedir`

`repo`

`dow`

`rnd`

`excludes`

`rawdisk`