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