create README.md

README.md

@@ -1,76 +1,263 @@
 # rsnapshot
 
-[![Build Status](https://travis-ci.org/OpenConceptConsulting/puppet-rsnapshot.svg?branch=master)](https://travis-ci.org/OpenConceptConsulting/puppet-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)
-4. [Usage - Configuration options and additional functionality](#usage)
+    * [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
 
-This puppet module manages rsnapshot configuration. It's a barebones module, as it doesn't deal with managing ssh keys or cron rules to trigger rsnapshot.
+The rsnapshot module installs, configures and manages rsnapshot on a dedicated backup server.
-
-At the moment, this module has been tested with Puppet 3.x and Ubuntu 12.04, 14.04 and Debian 6. If you have another OS/Puppet version you want to include, please submit a pull request!
 
 ## 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)
 
-This module is a barebones rsnapshot installation and configuration system. It came into existing because we needed an rsnapshot module but didn't want to have it generate cron rules or setup ssh keys (rsnapshot only needs to generate local backups for us).
+### 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.
-It is relatively trivial to then add a `cron` rule to trigger rsnapshot, and managing ssh keys can be done through `ssh_authorized_key`.
 
 ## Setup
 
 ### What rsnapshot affects
 
-* `rsnapshot` package and its dependencies
+* This module will install the rsnapshot package on your system
-* `/etc/rsnapshot.conf` (by default)
+* This module will manage the rsnapshot config on your system
+* This module will manage cron entries for your configured nodes
 
-## Usage
+### Setup Requirements
 
-You only need to declare the rsnapshot class, and configure the parameters you need.
+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.
-The class will default to sane values for your OS if you don't override some parameters.
+It will create repeatable random cron entries from a configurable timerange for all hosts.
 
-While you can include the class as is, it wont be useful unless you specify `backups` or `backup_scripts`.
+### 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
 
-### backups
+### Classes
-A hash backup locations. The key is the source, the value is the destination.
 
-```
+#### Public Classes
-class { 'rsnapshot':
+* rsnapshot: Main class, includes all other classes.
-  backups => {
+
-    '/home/' => 'localhost/',
+####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,
-If you want the backup stanza to have overriden configuration options, add them to the destination, separated by a tab character:
-
-```
-class { 'rsnapshot':
-  backups => {
-    '/home/' => 'localhost/	one_fs=1',
   }
+  {...}
 }
-```
+### rsnapshot configuration variables
-
+Please read up on the following in the [rsnapshot manpage](http://linux.die.net/man/1/rsnapshot)
-### backup_scripts
+####`$cmd_cp`
-Exactly like [backups](#backups), except that they generate `backup_script` stanzas.
+####`$cmd_rm`
-
+####`$cmd_rsync`
-## Limitations
+####`$cmd_ssh`
-
+####`$cmd_logger`
-The module has been tested/used in production with Puppet 3.x.
+####`$cmd_du`
-
+####`$cmd_rsnapshot_diff`
-On the OS side, the module currently only works on Debian-family OSes, but we'd love to get a patch to add support for more families/operating systems.
+####`$cmd_preexec`
-
+####`$cmd_postexec`
-## Development
+####`$use_lvm`
-
+####`$linux_lvm_cmd_lvcreate`
-Development is happening on [github](https://github.com/OpenConceptConsulting/puppet-rsnapshot), and we welcome pull requests!
+####`$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`

manifests/config.pp

@@ -3,6 +3,7 @@
 # manage host configs
 class rsnapshot::config (
   $hosts          = $rsnapshot::hosts,
+  $cron_dir       = $rsnapshot::cron_dir,
 ) {
   # these are global settings, no point in setting them per host
   $config_version         = $rsnapshot::params::config_version
@@ -15,7 +16,9 @@ class rsnapshot::config (
   file { $lockpath:
     ensure => 'directory',
   }
-
+  file { $cron_dir:
+    ensure => 'directory',
+  }
   # custom function, if only a hostname is given as a param, this is an empty hash
   # the next loop would break as puppet does not allow to reassign variables
   # the function checks $hosts for elements like: 

manifests/params.pp

@@ -7,6 +7,7 @@ class rsnapshot::params {
   $config_backup_user                   = 'root'
   $package_name                  = 'rsnapshot'
   $package_ensure                = 'present'
+  $cron_dir                      = '/tmp/rsnapshot.d/cron'
   $config_backup_levels          = [ 'daily', 'weekly', ]
   $config_backup_defaults        = true
   $config_version                = '1.2'

metadata.json

@@ -10,12 +10,32 @@
   "tags": [
     "rsnapshot",
     "backup",
+    "rsync",
   ],
   "requirements": [
     { "name": "pe", "version_requirement": ">= 3.0.0" },
     { "name": "puppet", "version_requirement": ">= 3.0.0" }
   ],
   "dependencies": [
-    { "name": "puppetlabs-stdlib","version_range": ">= 1.0.0" }
+    { "name": "puppetlabs-stdlib","version_range": ">= 1.0.0" },
+    { "name": "stahnma-epel","version_range": ">= 1.0.0" }
+  ],
+  "operatingsystem_support": [
+    {
+    "operatingsystem":"CentOS",
+    "operatingsystemrelease":[ "5", "6", "7" ]
+    },
+    {
+    "operatingsystem":"Debian",
+    "operatingsystemrelease":[ "6", "7", "8" ]
+    },
+    {
+    "operatingsystem": "Ubuntu",
+    "operatingsystemrelease": [ "12.04", "10.04", "14.04" ]
+    },
+    {
+    "operatingsystem": "Fedora",
+    "operatingsystemrelease": [ "17", "18", "19", "20", "21", "22", "23", "24" ]
+    },
   ]
 }