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