# rsnapshot #### Table of Contents 1. [Overview](#overview) 2. [Module Description - What the module does and why it is useful](#module-description) * [Notes](#notes) 3. [Setup - The basics of getting started with rsnapshot](#setup) * [What rsnapshot affects](#what-rsnapshot-affects) * [Setup requirements](#setup-requirements) * [Getting started with rsnapshot](#getting-started) 4. [Configuration - options and additional functionality](#configuration) * [Examples](#examples) * [More Options](#more-options) 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference) 5. [Limitations - OS compatibility, etc.](#limitations) 6. [Development - Guide for contributing to the module](#development) 7. [Editors](#editors) 8. [Contributors](#contributors) ## Overview The rsnapshot module installs, configures and manages rsnapshot on a dedicated backup server. ## Module Description The rsnapshot module installs, configures and manages rsnapshot on a dedicated backup server. It allows to set up a centralized Backup Server for all your nodes. For the cron setup, the module will pick random time entries for the crons from an Array or a Range of time. For how to configure this, [please see below](#more-options) ### Notes This module is best used with an ENC like hiera. It will make your config much easier to read and to maintain. Check the examples to see what I mean. ## Setup ### What rsnapshot affects * This module will install the rsnapshot package on your system * This module will manage the rsnapshot config on your system * This module will manage cron entries for your configured nodes ### Setup Requirements On CentOS Systems this module requires the stahnma-epel module. Also you will need to have rsync installed on all nodes to be backed up. It will create repeatable random cron entries from a configurable timerange for all hosts. ### Getting Started You will need to pass the nodenames to be backed up at least. This will pickup all defaults and add localhost to the backups: ```puppet class { '::rsnapshot': hosts => { 'localhost' => {}, } } ``` ## Configuration Here are some more elaborate examples of what you can do with this module. ### Examples This will backup localhost with defaults. It will disable the default backup locations for example.com and just backup '/var' for example.com. ```puppet class { '::rsnapshot': hosts => { 'localhost' => {}, 'example.com' => { backup_defaults => false, backup => { '/var/' => './' } } } } ``` The same in hiera: ```yaml --- classes: rsnapshot rsnapshot::hosts: localhost: example.com: backup_defaults: false backup: '/var/': './' ``` A more complete hiera example: ```yaml --- classes: - rsnapshot # override default backup dirs for all hosts: rsnapshot::default_backup: '/etc': './' '/usr/local': './' '/home': './' # configure hosts to be backed up rsnapshot::hosts: # pick all defaults for localhost localhost: # add futher backups for node foo.example.com (additional to default_backup) and use a different snapshot root foo.example.com: backup: '/foo': './' '/bar': './' '/baz': './misc' snapshot_root: '/tmp/rsnapshot' # all defaults foo1.example.com: foo2: # disable default backup dirs and just backup /var for node bar1 # also set the minute to 0-10 for daily cron (note: this is not particularly useful, it's just meant to document the features) # lastly set the range of hours to pick a random hour from (the cron for bar1 will have hour set to something between 1 and 5) bar1: backup_defaults: false backup: '/var': './var' cron: 'daily': 'minute': '0-10' 'hour': '1..5' ``` ### More options The defaults are pretty reasonable, I hope. However, you may override pretty much anything. Available parameters are discussed below. #### Specials As mentioned, this module will generate random time entries for your hosts. The random number generator is hashed with hostname and backup_level, so the randomness will be repeatable per host.level. This is important so puppet won't override the crons with each run. You may specify time ranges as follows: * default cron syntax (1-10, '*/5', 5) * an array with allowed values, for example, if you want the backup for a host to run between 1am and 5am, you would override the hours setting for the host in question. in hiera this would look like: (Explanation see below) ```yaml rsnapshot::hosts: example.com: cron: 'daily': 'minute': '1' 'hour': '1..5' ``` This will create the rsnapshot config using defaults from params.pp, but set the minute of the daily backup to '1' and the hour to something random between 1 and 5. So it would look something like: ``` 1 4 * * * foo daily ``` or maybe ``` 1 2 * * * foo daily ``` ## Reference ### Classes #### Public Classes * rsnapshot: Main class, includes all other classes. ####Private Classes * rsnapshot::install: Handles the packages. * rsnapshot::config: Handles configuration and cron files. * rsnapshot::params: default values. ### Functions ####`assert_empty_hash` Sets an empty value to a hash (we need this so a loop doesn't break if just a hostname is given to pick up all defaults. ####`pick_undef` Like pick but returns undef values. ####`rand_from_array` Takes an Integer, a String or an Array as input, and returns a random entry from the array (or just the String/Integer) ### Parameters The following parameters are available in the `::rsnapshot` class: ####`$hosts` Hash containing the hosts to be backed up and optional overrides per host ####`$conf_d` The place where the configs will be dropped (Default: /etc/rsnapshot (will be created if it doesn't exist)) ####`$config_backup_user` The user to run the backup scripts as (Default: root, also the user used for ssh connections, if you change this make sure you have proper key deployed and the user exists in the nodes to be backed up.) ####`$package_name` Default: rsnapshot ####`$package_ensure` Default: present ####`$cron_dir` Directory to drop the cron files to. Crons will be created per host. (Default: /etc/cron.d) ####`$backup_levels` Array containing the backup levels (hourly, daily, weekly, monthly) Configure the backup_levels (valid per host and global, so you may either set: rsnapshot::backup_levels for all hosts or override default backup_levels for specific hosts) ####`$backup_defaults` Boolean. Backup default backup dirs or not. ####`$cron` Hash. Set time ranges for different backup levels. Hash is of the form: cron =>{ daily => { minute => param, hour => param, } weekly => { minute => param, hour => param, } {...} } ### rsnapshot configuration variables Please read up on the following in the [rsnapshot manpage](http://linux.die.net/man/1/rsnapshot) ####`$cmd_cp` ####`$cmd_rm` ####`$cmd_rsync` ####`$cmd_ssh` ####`$cmd_logger` ####`$cmd_du` ####`$cmd_rsnapshot_diff` ####`$cmd_preexec` ####`$cmd_postexec` ####`$use_lvm` ####`$linux_lvm_cmd_lvcreate` ####`$linux_lvm_cmd_lvremove` ####`$linux_lvm_cmd_mount` ####`$linux_lvm_cmd_umount` ####`$linux_lvm_snapshotsize` ####`$linux_lvm_snapshotname` ####`$linux_lvm_vgpath` ####`$linux_lvm_mountpath` ####`$logpath` ####`$logfile` ####`$lockpath` ####`$snapshot_root` ####`$no_create_root` ####`$verbose` ####`$loglevel` ####`$stop_on_stale_lockfile` ####`$rsync_short_args` ####`$rsync_long_args` ####`$ssh_args` ####`$du_args` ####`$one_fs` ####`$retain` ####`$interval` ####`$include` ####`$exclude` ####`$include_file` ####`$exclude_file` ####`$link_dest` ####`$sync_first` ####`$rsync_numtries` ####`$use_lazy_deletes` ####`$default_backup` ####`$backup_scripts`