Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

backupninja

Installs, configures, and manages backupninja
Project URLRSS FeedReport issues

9,486 downloads

322 latest version

5.0 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.1.0 (latest)
  • 4.0.4
  • 4.0.3
  • 4.0.2
  • 4.0.1
  • 4.0.0
released Mar 21st 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
  • , , , , Archlinux

Start using this module

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

Add this module to your Puppetfile:

mod 'smash-backupninja', '4.1.0'
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.1.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

Documentation

smash/backupninja — version 4.1.0 Mar 21st 2023

backupninja

Table of Contents

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

Description

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

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 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:

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

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

Usage

Configure backupninja

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

class { 'backupninja':
  when          => 'everyday at 04',
  reportemail   => 'admin@example.net',
  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 backup.example.org
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 client.example.org
class { 'backupninja':
  account_host          => 'backup.example.org',
  server_backupdir      => '/data/backups',
  account_sshkey_source => "puppet:///modules/profiles/ssh_keys/${::fqdn}/root_id_ed25519.pub",
}
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 client.example.org
class { 'backupninja':
  account_host           => 'backup.example.org',
  server_backupdir       => '/data/backups',
  account_sshkey         => $::ssh_keys_users['root']['id_ed25519.pub']['key'],
  account_sshkey_type    => $::ssh_keys_users['root']['id_ed25519.pub']['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.

Multiple server FQDNs

If the backupserver is reachable by multiple FQDNs for the same backupserver, with the clients deciding which FQDN to use, then be sure to collect the resources for the accounts with the additional FQDNs, eg. on the server:

    # this will realize resources exported to this server's $::fqdn
    class { 'backupninja':
      server => true
    }

    # if it's reachable via other FQDNs, you want to realize those extra ones with a statement as below
    Backupninja::Server::Account <<| tag == 'backup-private.example.net' |>>

And then on the clients:

    # on node clientA:
    class { 'backupninja':
      account_host => 'backup.example.net'
    }

    # on node clientB:
    class { 'backupninja':
      account_host => 'backup-private.example.net'
    }

Reference

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.

Limitations

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

Development

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 0xacab.org