Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

borg

Simple puppet module to configure backups with borg.
Project URLRSS FeedReport issues

14,042 downloads

1,537 latest version

4.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.1.2 (latest)
  • 1.1.1
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Nov 20th 2019
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x
  • Puppet 5.X

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'baldurmen-borg', '1.1.2'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add baldurmen-borg
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install baldurmen-borg --version 1.1.2

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

baldurmen/borg — version 1.1.2 Nov 20th 2019

borg

Table of Contents

  1. Description
  2. Setup
  3. Usage
  4. Reference
  5. Limitations

Description

This module configures a backup script using borg and setups a cron job accordingly.

The design of this module is modular: you can call the borg::backup define as many times you want to create different backup schemes.

Setup

This module takes for granted that:

  • You have already created a borg archive somewhere using borg init.
  • The user you backup with has access to the relevant files to backup from and to the borg archive to backup to, be it locally or through ssh.

Be aware that the backup script created will contain your archive encryption passphrase. This file is only readable by the user running the backup job.

Usage

The simplest way to use this module is this way:

include borg

borg::backup {
  'root':
    archive_path => 'webserver',
    archive_path => '/data/borg/my-backup',
    passphrase   => '12345-super-strong',
    type         => 'borg';
}

An advanced example might look like:

include borg

borg::backup {
  'kvm':
    backup_path           => '/',
    archive_path          => 'kvm',
    archive_path          => 'foo@bar:/data/borg/kvm',
    passphrase            => '12345-super-strong',
    exclude               => [ '/proc', '/sys', '/var/lib/libvirt/images', '/mnt' ],
    prune                 => true,
    compression           => 'lzma,6',
    daily                 => 7,
    weekly                => 4,
    monthly               => 0,
    log                   => true,
    type                  => 'sshfs',
    sshfs_mount           => '/data/foobar',
    cron_time             => '0 2 * * *',
    envvar_relocated_repo => true,
    envvar_unknown_repo   => true;

  'mnt':
    backup_path  => '/mnt',
    archive_path => 'server-number-42',
    archive_path => '/data/borg/kvm-mnt',
    passphrase   => '12345-super-strong',
    type         => 'borg',
    prune        => false,
    user         => 'mounty-mounter';
}

If you want to use this module using Hiera, you will have to add a create_ressources statement somewhere in your manifests. You can use something like this:

$borg_backup = hiera_hash('borg::backup',{})
create_resources('borg::backup',$borg_backup)

A simple Hiera syntax for a backup definition would look like this:

borg::backup:
  'root':
    archive_name: webserver
    archive_path: /data/borg/my-backup
    passphrase: 12345-super-strong
    type: borg

Reference

Classes

Public classes

  • borg: Main class. Used for installs and directory creation.

Private classes

  • borg::backup: Handles the creation of backup scripts and cron jobs.

Parameters

The following parameters are available in the borg::backup class:

backup_path

Optional.

Data type: String.

Path to the files to backup.

Default value: /.

archive_name

Data type: String.

Name of the borg archive.

Default value: undef.

archive_path

Data type: String.

Path to the borg archive to backup to. Can either be a local path or an ssh remote path.

Default value: undef.

passphrase

Optional.

Data type: String.

Passphrase for the borg archive. If not set, it is taken from granted the borg archive was created without a passphrase.

Default value: undef.

exclude

Optional.

Data type: Array.

Paths to exclude from the backup.

Default value: '/proc', '/sys'.

prune

Optional.

Data type: Boolean.

Using this parameter will prune your backups at the rate set by the daily, weekly, monthly and yearly values.

Default value: true.

compression

Optional.

Data type: String.

This will set the compression on the backups.

Default value: auto.

daily

Optional.

Data type: Integer.

Numbers of days to keep a backup before pruning.

Default value: 7.

weekly

Optional.

Data type: Integer.

Numbers of weeks to keep a backup before pruning.

Default value: 4.

monthly

Optional.

Data type: Integer.

Numbers of months to keep a backup before pruning.

Default value: 6.

yearly

Optional.

Data type: Integer.

Numbers of years to keep a backup before pruning.

Default value: 0.

log

Optional.

Data type: Boolean.

This parameter is used to log the exit code of the last backup run. If the prune parameter is set, it will also log the exit code of the last prune run.

This is useful if you want to monitor the success of your backup runs in multiple ways, like check_borg does.

Log files will be written to /var/log/borg/borg-${name}.log and will look like:

create: 0
prune: 0

Default value: false.

type

Optional.

Data type: Enum.

Two types of backups are supported: borg and sshfs.

If the former is used, the backup run takes for granted borg is installed on the endpoint and can server the files, either locally or through ssh.

If the latter is used, the archive path will be mounted on the path specified by the sshfs_mount parameter with sshfs. In that case, the mounting point will be unmounted at the end of the backup run.

sshfs_mount

Optional.

Data type: String.

The mounting point to used when sshfs is set as the backup type.

Default value: /mnt.

user

Optional.

Data type: String.

The user to run the backup as.

Default value: root.

cron_time

Optional.

Data type: String.

When the cron job will run. This should respect the cron time format.

Default value: 0 1 * * *.

envvar_relocated_repo

Optional.

Data type: Boolean.

Sets the BORG_RELOCATED_REPO_ACCESS_IS_OK environment variable.

Default value: false.

envvar_unknown_repo

Optional.

Data type: Boolean.

Sets the BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK environment variable.

Default value: false.

Limitations

This module was developed for Debian Stretch and Puppet 4. Compatibility on other OS or Puppet versions is not guaranteed.