Forge Home


Installs, configures, and manages backupninja




6,314 latest version

5.0 quality score

Version information

  • 4.0.4 (latest)
  • 4.0.3
  • 4.0.2
  • 4.0.1
  • 4.0.0
released Mar 31st 2018
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 6.0.0
  • RedHat
    , Archlinux

Start using this module

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

Add this module to your Puppetfile:

mod 'smash-backupninja', '4.0.4'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add smash-backupninja
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install smash-backupninja --version 4.0.4

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.



smash/backupninja — version 4.0.4 Mar 31st 2018


Table of Contents

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


This module manages your backups using the backupninja program, with the option of creating remote accounts on a designated server for storing backup data.

It installs and configures backupninja, including its cron job. It can be used to deploy configurations for the various backup handlers it supports, such as MySQL, PostgreSQL, duplicity and rsync along with the package dependencies, if any, of these backup tools. It can also export user, ssh key and file resources to a backup server, creating a remotely accessible storage space allowing clients to upload their backups on a remote server.


Setup Requirements

This module depends on the puppetlabs-stdlib module.

Users upgrading from the pre-4.0.0 version of this module should refer to the UPGRADING file which describes the changes introduced in this new release.

Getting started

class { 'backupninja': } will install backupninja with a default configuration, along with an hourly cron job. It won't actually do any backups until a backup action is configured. This is accomplished declaring one or more of the the backupninja::action defined types.

For example, this will install a backup action in /etc/backup.d which will create compressed SQL dumps of all MySQL/MariaDB databases present on this node:

class { 'backupninja::action::mysql':
  sqldump => true

By default, backup actions are run every day at 1 AM.


Configure backupninja

In the example below, backupninja will be configured to run every night at 4 AM, sending an email report to ''.

class { 'backupninja':
  when          => 'everyday at 04',
  reportemail   => '',
  reportsuccess => true,

Refer to the backupninja manpage for details regarding how to correctly format values for the when parameter.

Scheduling backups

By default, backupninja checks whether to run jobs once every hour, on the hour, via its cron job. Therefore, if you specify minutes in the when parameter value (eg. 'everyday at 04:30'), it will be considered valid but the minutes compoment will be ignored and backupninja will run at 4 AM.

The examples below illustrate alternative ways to organize backup scheduling using backupninja.

Fixed time

This will run backupninja every day at 3:45 AM.

class { 'backupninja':
  when         => 'manual',
  cron_minute  => '45',
  cron_hour    => '3',
  cron_command => "${backupninja::executable} --now"

To have different fixed times per node, you may, for example, derive the minute component from the fqdn_rand(59) function.

Random delay

This action will add a random delay of up to one hour at the beginning of the backup run. Useful if you want to avoid clients hitting the backup server all at once.

class { 'backupninja':
  when => 'everyday at 04',
backupninja::action::sh { 'delay':
  priority => 0,
  content => 'perl -e "sleep int(rand(3600))"',

Backup accounts

This module allows you to provision backup accounts on a node designated as a backup server, using exported resources. A user, home directory and SSH public key will be deployed on the server allowing the automated backups from the client.

Of these, the SSH public key needs special consideration, as this module does not automatically generate the required keys. If you do not already manage user SSH keys with Puppet, there are generally two ways to go about it, the manual way and the automated way.

In a nutshell, the manual way requires you to generate an SSH key pair on each backup client and copy the public keys to a central directory on the server, while the automated way uses the Puppet agent and the voxpupuli/puppet-ssh_keygen module to generate the key pair, along with the $ssh_keys_users fact provided by the shared-puppet-modules-group/sshd module to make the public key available in your manifests. See below for examples.

First, define a node as the backup server:

# on node
class { 'backupninja':
  server           => true,
  server_backupdir => '/data/backups',

Then, on the backup client, declare the backupninja class along with a remote backup action. Notice that the public SSH public key will be retrieved from the Puppet server.

# on node
class { 'backupninja':
  account_host          => '',
  server_backupdir      => '/data/backups',
  account_sshkey_source => "puppet:///modules/profiles/ssh_keys/${::fqdn}/",
backupninja::action::rdiff { 'main':
  include => [ '/root', '/home' ],
  exclude => [ '/home/*/.cache' ],
  type    => 'remote',

If you use a module that provides the $ssh_keys_users fact, you can declare the backupninja class as below. Notice this method allows more flexibility since it makes use of the ssh_authorized_key native type.

# on node
class { 'backupninja':
  account_host           => '',
  server_backupdir       => '/data/backups',
  account_sshkey         => $::ssh_keys_users['root']['']['key'],
  account_sshkey_type    => $::ssh_keys_users['root']['']['type'],
  account_sshkey_options => [ 'restrict' ],

If the SSH keypair for the root account is being generated using the ssh_keygen module, the $ssh_keys_users fact will not contain the root public key on the very first Puppet agent run. To work around this, wrap the class declaration in a if has_key($::ssh_keys_users, 'root') statement.


The full reference documentation for this module may be found at on GitLab Pages.

Alternatively, you may build yourself the documentation using the puppet strings generate command. See the documentation for Puppet Strings for more information.


  • Puppet 4 or later is required.
  • Debian was used for testing, but the module should work on any system for which backupninja is packaged.
  • Configuration parameters related to vservers are not implemented.

Known issues

This module does not verify your backups, check that everything you need is actually in there, or even check whether the data can actually be restored. You need to regularly test your backups.

I cannot stress this enough: do not wait until disaster strikes, TEST YOUR BACKUPS.


This module's development is tracked on GitLab. Please submit issues and merge requests on the shared-puppet-modules-group/backupninja project page.

Upstream backupninja development happens at riseuplabs/backupninja on