Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

borg

installs, configures, and manages borg
Project URLRSS FeedReport issues

12,042 downloads

272 latest version

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

Version information

  • 4.2.0 (latest)
  • 4.1.0
  • 4.0.0
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.4.0
  • 2.3.1
  • 2.3.0
  • 2.2.0
  • 2.1.2
  • 2.1.1
  • 2.1.0
  • 2.0.0
  • 1.6.0
  • 1.5.0
  • 1.4.0
  • 1.3.1
  • 1.3.0
  • 1.0.1
  • 1.0.0
released Oct 12th 2023
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 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
  • Puppet >= 7.0.0 < 9.0.0
  • Archlinux, Gentoo, , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'puppet-borg', '4.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

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

Manually install this module globally with Puppet module tool:

puppet module install puppet-borg --version 4.2.0

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
Tags: backup, restore, borg, borgbackup

Documentation

puppet/borg — version 4.2.0 Oct 12th 2023

puppet-borg

Build Status Release Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores puppetmodule.info docs AGPL v3 License

Table of contents

Borg Setup

Borg is a client that creates local backups, encrypts them, and saves them at a given location. A possible location is the local filesystem, a mount of a remote storage (like CIFS), certain storage protocols it directly can interact with or another borg binary. The latter is the preferred option. You can place the borg binary on a remote linux system and create an ssh account that cannot allocate a PTY and has ForceCommand set to borg serve. Such u user can only send and receive backups to the binary via ssh. A possible configuration for the sshd server looks like this (won't be handled by this module):

# /etc/ssh/sshd_config
AcceptEnv LANG LC_*
ChallengeResponseAuthentication no
PasswordAuthentication no
PrintMotd no
Subsystem sftp /usr/libexec/sftp-server
UsePAM yes
X11Forwarding yes
Match Group borgusers
    AllowAgentForwarding no
    AllowTcpForwarding no
    AuthorizedKeysFile %h/%u/.ssh/authorized_keys
    ForceCommand borg serve
    PasswordAuthentication no
    PermitTTY no
    PermitUserRC no
    X11Forwarding no

This module will provide a borg backup script that works with such a setup. We will also configure a systemd service and a timer to execute it on a regular basis. Borg doesn't automatically prune old backups, our script has parameters for this.

Please have a look at our REFERENCE.md. All parameters are documented in that file.

Examples

The only parameter you really need to set is FQDN of the remote server:

class{'borg':
  backupserver => 'myawesomebackupmachine.org'
}

We assume that your ssh username is the hostname from the client. You maybe want to overwrite this assumption:

class{'borg':
  backupserver => 'myawesomebackupmachine.org',
  username => 'notmyhostname',
}

We need to tell the script what we want to do with every mountpoint, backup it or ignore it. We can also exclude specific paths. The defaults are stored in the manifests/init.pp with os-specific overrides in data/.

Restore Script

Figuring out from which backup archive you want to restore a certain file can be quite time-consuming with just borg alone. When listing the contents of each backup archive, the client will talk to the remote server a lot during the generation of the list. To speed this up, Florian Pritz developed a helper. This will be executed after every backup. The script talks to the server and fetches a list of all files from the last backup. The information are stored in a local sqlite database. You can do restores directly via this script. You can find the upstream documentation (including examples) at metacpan.org

Prometheus Exporter

More and more people use prometheus. We vendor a bash script that can provide you metrics about your backups in the prometheus format. They are written to disk and the node_exporter can collect them.

Facts

This module provides you a structed fact, named borgbackup. It currently only lists the borgbackup version. It's a structured so it can easily be extended without breaking changes and without further topscope pollution.

# puppet facts show borgbackup
{
  "borgbackup": {
    "version": "1.2.1"
  }
}

Limitations

On CentOS 8, the PowerTools repository needs to be enabled by the user. Packages from EPEL8 require the repository but it's disabled by default. For more information see:

borgbackup before 1.1.17 didn't depend on packages from PowerTools so this worked by accident.

Tests

This module has several unit tests and linters configured. You can execute them by running:

bundle exec rake test

Detailed instructions are in the CONTRIBUTING.md file.

Contributions

Contribution is fairly easy:

  • Fork the module into your namespace
  • Create a new branch
  • Commit your bugfix or enhancement
  • Write a test for it (maybe start with the test first)
  • Create a pull request

Detailed instructions are in the CONTRIBUTING.md file.

License and Author

This module was originally written by Tim Meusel. It's licensed with AGPL version 3.