Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

tarsnap

a module to install and configure tarsnap
Project URLRSS FeedReport issues

13,132 downloads

7,130 latest version

4.3 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

  • 2.0.1 (latest)
  • 1.0.0
  • 0.4.6
  • 0.4.4
  • 0.4.3
  • 0.2.1
  • 0.1.0
released Dec 2nd 2016
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.5.0 < 5.0.0
  • Ubuntu, Debian, RedHat, CentOS, FreeBSD

Start using this module

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

Add this module to your Puppetfile:

mod 'brainsware-tarsnap', '2.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add brainsware-tarsnap
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install brainsware-tarsnap --version 2.0.1

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

brainsware/tarsnap — version 2.0.1 Dec 2nd 2016

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with tarsnap
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

this module helps install and configure tarsnap.

It does not, and cannot help you create keys for servers. You have to do that manually

Setup

The tarsnap module assumes that you have a package named tarsnap in your package repositories. You can override this expectation by either changing the $package_name, or by setting it to undef if you have other means of installing it.

PPA

For Ubuntu, I have created a PPA which builds the latest version of tarsnap for all Ubuntu LTS. If you're interested in helping with that, you can also join that team on launchpad.

Keys

In order for tarsnap to be fully functional, and thus for this module to be, you must setup the key. Please follow the instructions of the official documentation

As I'd rather not be responsible for making your backups inaccessible through a puppet hickup, keys are, as of yet, not created automatically (and thus cannot be re-created automatically ;).

Usage

To install tarsnap from the package all that is needed is:

include tarsnap

We can change basic parameters such as the package name:

class { 'tarsnap':
  package_name => 'acme-tarsnap',
}

if the configuration file or the root key are not in the default locations, we can change those as well:

class { 'tarsnap':
  configfile => '/usr/local/etc/tarsnap.conf',
  keyfile    => '/secure/tarsnap.key',
}

Many option that can be set in tarsnap.conf can be set through the base class. The most important one is $cachedir. All boolean options (those that can be prefaced with no- in tarsnap.conf) can be set to true/false.

class { 'tarsnap':
  cachedir               => '/var/backups/tarsnap',
  aggressive_networking  => false,
}

n.b.: this module will guarantee that $cachedir exists as directory and is root:root owned.

The easiest way to use tarsnap is from cron:

cron { 'tarsnap-etc-daily':
  command => "/usr/bin/tarsnap -c -f etc.`date +%Y%m%d` /etc /usr/local/etc /opt/etc",
  user    => 'root',
  hour    => 2,
  minute  => fqdn_rand(60),
}

if we want to only keep the last 30 days, we can follow this up with:

cron { 'dailiy-tarsnap-etc-trim-30':
  command => "/usr/bin/tarsnap --list-archives | grep 'etc\.' | sort -n | head -n +30 | xargs -n 1 /usr/bin/tarsnap -d -f"
  user    => 'root',
  hour    => 3,
  minute  => fqdn_rand(60),
}

We provide a convenience wrapper around those two expressions:

tarsnap::periodic { 'etc':
  dirs => [ 'etc', '/usr/local/etc', '/opt/etc' ],
  hour => 3,
}

Often if we have a lot of periodic jobs, randomizing will still lead to overlapping runs, which doesn't work with tarnsap. For this purpose we provide a the class tarsnap::batch. It can also be directly configured through tarsnap:

class { 'tarsnap':
  batch_enable => false,
  locations    => {
    'etc'       => '/etc',
    'home'      => [ '/home/me/pix', '/home/me/src', '/home/me/txt' ],
    '.dotfiles' => [ '/home/me/.gnupg', '/home/me/.config', '/home/me/.ssh' ],
    'blog'      => [ '/home/me/blog/src', '/home/me/blog/pix' ],
  }
}

Reference

tarsnap

  • package_name: Name of tarsnap package. If tarsnap is installed by other means, set this to undef (Default: tarsnap)
  • package_ensure: Ensure tarsnap package is in this version, absent, present or latest. (Default: present)
  • configfile: Path to tarsnap's configuration file. (Default: /etc/tarsnap.conf)
  • path: Path to tarsnap. (Default: /usr/bin/tarsnap)
  • archive_path: Path to tarsnap-archive script. (Default: /usr/local/bin/tarsnap-archive)
  • rotate_path: Path to tarsnap-rotate script. (Default: /usr/local/bin/tarsnap-rotate)
  • batch_path: Path to tarsnap-batch script. (Default: /usr/local/bin/tarsnap-batch)
  • cachedir: Path to tarsnap's cachedir. This directory will be created by puppet. (Default: /var/backups/tarsnap)
  • keyfile: Path to tarsnap's keyfile for this machine. (Default: /root/tarsnap.key)
  • nodump: Honor the nodump file flag. (Default: true)
  • print_stats: Print statistics when creating or deleting archives. (Default: true)
  • checkpoint_bytes: Create a checkpoint once per X of uploaded data (Default: 1G)
  • aggressive_networking: Use multiple TCP connections when writing archives. (Default: undef)
  • batch_enable: Whether or not to include the batch-proccessing class. (Default: false)
  • locations: Hash of directory arrays to archive in a batch job. (Default: {})

tarsnap::periodic

  • name: base-name of this archive
  • ensure: Ensure presence or absence of cron jobs. (Default: present)
  • dirs: Array of dirs to backup (Default: [])
  • exclude: Array of patterns to exclude from archives (Default: [])
  • keep: How many archives to keep. If this is set to 0 no archives will be deleted. (Default: 30)
  • hour: Hour when to run. (Default: fqdn_rand(24, $title), i.e.: between 00:xx and 23:xx)
  • minute: Minute when to run. (Default: fqdn_rand(60, $title), i.e.: between xx:00 and xx:59)
  • month: Month of year to run. (Default: undef)
  • monthday: The day of the month on which to run. (Default: undef)
  • offset: Offset (in hours) when to run the cleanup job. (Default: 1)
  • weekday: The weekday on which to run. (Default: undef)

tarsnap::batch

  • enable: Ensure presence or absence of batch script and cron job. (Default: true)
  • keep: How many archives to keep. If this is set to 0 no archives will be deleted. (Default: 30)
  • hour: Hour when to run. (Default: fqdn_rand(6, $title), i.e.: between 00:xx and 06:xx)
  • minute: Minute when to run. (Default: fqdn_rand(60, $title), i.e.: between xx:00 and xx:59)
  • locations: Hash of directory arrays. (Default: $::tarsnap::locations)

Limitations

While it is possible to configure tarsnap on a per-user basis, tarsnap::config currently is a class. If you think it's useful to change that, please contribute!

Development

Please use the github issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.