README

   1
   2                                           |\_
   3                  B A C K U P N I N J A   /()/
   4                                          `\|
   5
   6       a silent flower blossom death strike to lost data.
   7
   8 Backupninja allows you to coordinate system backup by dropping a few
   9 simple configuration files into /etc/backup.d/. Most programs you
  10 might use for making backups don't have their own configuration file
  11 format. Backupninja provides a centralized way to configure and
  12 coordinate many different backup utilities.
  13
  14 Features:
  15  - easy to read ini style configuration files.
  16  - secure, remote, incremental filesytem backup (via rdiff-backup).
  17    incremental data is compressed. permissions are retained even
  18    with an unpriviledged backup user.
  19  - backup of mysql databases (via mysqlhotcopy and mysqldump).
  20  - backup of ldap databases (via slapcat and ldapsearch).
  21  - passwords are never sent via the command line to helper programs.
  22  - you can drop in scripts to handle new types of backups.
  23  - backup actions can be scheduled
  24  - you can choose when status report emails are mailed to you
  25    (always, on warning, on error, never).
  26  - works with linux-vservers
  27
  28 The following options are available:
  29 -h, --help           This usage message
  30 -d, --debug          Run in debug mode, where all log messages are
  31                      output to the current shell.
  32 -f, --conffile FILE  Use FILE for the main configuration instead
  33                      of /etc/backupninja.conf
  34 -t, --test           Run in test mode, no actions are actually taken.
  35 -n, --now            Perform actions now, instead of when they
  36                      might be scheduled.
  37 --run FILE           runs the specified action FILE (e.g. one of the /etc/backup.d/ files)
  38
  39 CONFIGURATION FILES
  40 ===================
  41
  42 The general configuration file is /etc/backupninja.conf. In this file
  43 you can set the log level and change the default directory locations.
  44 You can force a different general configuration file with "backupninja
  45 -f /path/to/conf".
  46
  47 To preform the actual backup, backupninja processes each configuration
  48 file in /etc/backup.d according to the file's suffix:
  49
  50   .sh      --  run this file as a shell script.
  51   .rdiff   --  this is a configuration for rdiff-backup
  52   .maildir --  this is a configuration to backup maildirs
  53   .dup     --  this is a configuration for duplicity
  54   .mysql   --  mysql backup configuration
  55   .ldap    --  ldap backup configuration
  56   .sys     --  general system reports
  57
  58 Support for additional configuration types can be added by dropping
  59 bash scripts with the name of the suffix into /usr/share/backupninja.
  60
  61 The configuration files are processed in alphabetical order. However,
  62 it is suggested that you name the config files in "sysvinit style."
  63
  64 For example:
  65         00-disabled.ldap
  66         10-runthisfirst.sh
  67         20-runthisnext.mysql
  68         90-runthislast.rdiff
  69
  70 Typically, you will put a '.rdiff' config file last, so that any
  71 database dumps you make are included in the filesystem backup.
  72 Configurations files which begin with 0 (zero) are skipped.
  73
  74 Unless otherwise specified, the config file format is "ini style."
  75
  76 For example:
  77
  78    # this is a comment
  79
  80    [fishes]
  81    fish = red
  82    fish = blue
  83
  84    [fruit]
  85    apple = yes
  86    pear = no thanks \
  87    i will not have a pear.
  88
  89
  90 SCHEDULING
  91 ==========
  92
  93 By default, each configuration file is processed everyday at 01:00 (1
  94 AM). This can be changed by specifying the 'when' option in a config
  95 file.
  96
  97 For example:
  98
  99   when = sundays at 02:00
 100   when = 30th at 22
 101   when = 30 at 22:00
 102   when = everyday at 01            <-- the default
 103   when = Tuesday at 05:00
 104
 105 A configuration file will be processed at the time(s) specified by the
 106 "when" option. If multiple "when" options are present, then they all
 107 apply. If two configurations files are scheduled to run in the same
 108 hour, then we fall back on the alphabetical ordering specified above.
 109 If two configurations files are scheduled close to one another in
 110 time, it is possible to have multiple copies of backupninja running if
 111 the first instance is not finished before the next one starts.
 112
 113 These values for 'when' are equivalent:
 114
 115   when = tuesday at 05:30
 116   when = TUESDAYS at 05
 117
 118 These values for 'when' are invalid:
 119
 120   when = tuesday at 2am
 121   when = tuesday at 2
 122   when = tues at 02
 123
 124
 125 REAL WORLD USAGE
 126 ================
 127
 128 Backupninja can be used to impliment whatever backup strategy you
 129 choose. It is intended, however, to be used like so:
 130
 131 (1) First, databases are safely copied or exported to /var/backups.
 132     Typically, you cannot make a file backup of a database while it
 133     is in use, hence the need to use special tools to make a safe copy
 134     or export into /var/backups.
 135
 136 (2) Then, vital parts of the file system, including /var/backups, are
 137     nightly pushed to a remote, off-site, hard disk (using
 138     rdiff-backup). The local user is root, but the remote user is not
 139     priviledged. Hopefully, the remote filesystem is encrypted.
 140
 141 There are many different backup strategies out there, including "pull
 142 style", magnetic tape, rsync + hard links, etc. We believe that the
 143 strategy outlined above is the way to go because: (1) hard disks are
 144 very cheap these days, (2) pull style backups are no good, because then
 145 the backup server must have root on the production server, and (3)
 146 rdiff-backup is more space efficient and featureful than using rsync +
 147 hard links.
 148
 149
 150 SSH KEYS
 151 ========
 152
 153 In order for rdiff-backup to sync files over ssh unattended, you must
 154 create ssh keys on the source server and copy the public key to the
 155 remote user's authorized keys file. For example:
 156
 157   root@srchost# ssh-keygen -t dsa
 158   root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost
 159
 160 Now, you should be able to ssh from user 'root' on srchost to
 161 user 'backup' on desthost without specifying a password.
 162
 163 Note: when prompted for a password by ssh-keygen, just leave it
 164 blank by hitting return.
 165
 166
 167 INSTALLATION
 168 ============
 169
 170 Requirements:
 171   apt-get install bash gawk
 172
 173 Recommended:
 174   apt-get install rdiff-backup gzip hwinfo
 175
 176 Files:
 177   /usr/sbin/backupninja        -- main script
 178   /etc/cron.d/backupninja      -- runs main script nightly
 179   /etc/logrotate.d/backupninja -- rotates backupninja.log
 180   /etc/backup.d/               -- directory for configuration files
 181   /etc/backupninja.conf        -- general options
 182   /usr/share/backupninja       -- handler scripts which do the actual work
 183
 184 Installation:
 185   There is no install script, but you just need to move files to the
 186   correct locations. All files should be owned by root.
 187
 188   # tar xvzf backupninja.tar.gz
 189   # cd backupninja
 190   # mv backupninja /usr/sbin/backupninja
 191   # mv etc/logrotate.d/backupninja /etc/logrotate.d/backupninja
 192   # mv etc/cron.d/backupninja /etc/cron.d/backupninja
 193   # mkdir /etc/backup.d/
 194   # mv etc/backupninja.conf /etc/backupninja.conf
 195   # mv handlers /usr/share/backupninja