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  - you can drop in scripts to handle new types of backups.
  17  - backup actions can be scheduled
  18  - you can choose when status report emails are mailed to you
  19    (always, on warning, on error, never).
  20  - console-based wizard (ninjahelper) makes it easy to create
  21    backup action configuration files.
  22  - passwords are never sent via the command line to helper programs.
  23  - works with Linux-Vservers (http://linux-vserver.org/)
  24
  25 Backup types:
  26  - secure, remote, incremental filesytem backup (via rdiff-backup).
  27    incremental data is compressed. permissions are retained even
  28    with an unpriviledged backup user.
  29  - backup of mysql databases (via mysqlhotcopy and mysqldump).
  30  - backup of ldap databases (via slapcat and ldapsearch).
  31  - basic system and hardware info
  32  - encrypted remote backups (via duplicity).
  33  - backup of subversion repositories.
  34
  35 The following options are available:
  36 -h, --help           This usage message
  37 -d, --debug          Run in debug mode, where all log messages are
  38                      output to the current shell.
  39 -f, --conffile FILE  Use FILE for the main configuration instead
  40                      of /etc/backupninja.conf
  41 -t, --test           Test run mode. This will test if the backup could run, without actually
  42                      preforming any backups. For example, it will attempt to authenticate
  43                      or test that ssh keys are set correctly.
  44 -n, --now            Perform actions now, instead of when they might be scheduled.
  45                      No output will be created unless also run with -d.
  46 --run FILE           Runs the specified action FILE (e.g. one of the /etc/backup.d/ files).
  47                      Also puts backupninja in debug mode.
  48
  49 NINJAHELPER
  50 ===========
  51
  52 Ninjahelper is an additional script which will walk you through the process of
  53 configuring backupninja. Ninjahelper has a menu driven curses based interface
  54 (using dialog).
  55
  56 To add an additional 'wizard' to ninjahelper, follow these steps:
  57
  58 (1) to add a helper for the handler "blue", create the file
  59     blue.helper in the directory where the handlers live.
  60     (ie /usr/share/backupninja).
  61
  62 (2) next, you need to add your helper to the global HELPERS variable
  63     and define the main function for your helper (the function name
  64     is always <helper>_wizard). for example, blue.helper:
  65        HELPERS="$HELPERS blue:description_of_this_helper"
  66        blue_wizard() {
  67          ... do work here ...
  68        }
  69
  70 (3) look at the existing helpers to see how they are written. Try to re-use
  71     functions, such as the dialog functions that are defined in easydialog.sh,
  72     or the vserver functions defined in lib/vserver.
  73
  74 (4) test, re-test, and test again. Try to break the helper by going backwards,
  75     try to think like someone who has no idea how to configure your handler
  76     would think, try to make your helper as simple as possible. Walk like a cat,
  77     become your shadow, don't let your senses betray you.
  78
  79
  80 CONFIGURATION FILES
  81 ===================
  82
  83 The general configuration file is /etc/backupninja.conf. In this file
  84 you can set the log level and change the default directory locations.
  85 You can force a different general configuration file with "backupninja
  86 -f /path/to/conf".
  87
  88 To preform the actual backup, backupninja processes each configuration
  89 file in /etc/backup.d according to the file's suffix:
  90
  91   .sh      --  run this file as a shell script.
  92   .rdiff   --  filesystem backup (using rdiff-backup)
  93   .dup     --  filesystem backup (using duplicity)
  94   .mysql   --  backup mysql databases
  95   .ldap    --  backup ldap databases
  96   .pgsql   --  backup PostgreSQL databases
  97   .sys     --  general hardware, partition, and system reports.
  98   .svn     --  backup subversion repositories
  99   .maildir --  incrementally backup maildirs (very specialized)
 100
 101 Support for additional configuration types can be added by dropping
 102 bash scripts with the name of the suffix into /usr/share/backupninja.
 103
 104 The configuration files are processed in alphabetical order. However,
 105 it is suggested that you name the config files in "sysvinit style."
 106
 107 For example:
 108         00-disabled.ldap
 109         10-runthisfirst.sh
 110         20-runthisnext.mysql
 111         90-runthislast.rdiff
 112
 113 Typically, you will put a '.rdiff' config file last, so that any
 114 database dumps you make are included in the filesystem backup.
 115 Configurations files with names beginning with 0 (zero) or ending with
 116 .disabled (preferred method) are skipped.
 117
 118 Unless otherwise specified, the config file format is "ini style."
 119
 120 For example:
 121
 122    # this is a comment
 123
 124    [fishes]
 125    fish = red
 126    fish = blue
 127
 128    [fruit]
 129    apple = yes
 130    pear = no thanks \
 131    i will not have a pear.
 132
 133
 134 SCHEDULING
 135 ==========
 136
 137 By default, each configuration file is processed everyday at 01:00 (1
 138 AM). This can be changed by specifying the 'when' option in a config
 139 file.
 140
 141 For example:
 142
 143   when = sundays at 02:00
 144   when = 30th at 22
 145   when = 30 at 22:00
 146   when = everyday at 01            <-- the default
 147   when = Tuesday at 05:00
 148
 149 A configuration file will be processed at the time(s) specified by the
 150 "when" option. If multiple "when" options are present, then they all
 151 apply. If two configurations files are scheduled to run in the same
 152 hour, then we fall back on the alphabetical ordering specified above.
 153 If two configurations files are scheduled close to one another in
 154 time, it is possible to have multiple copies of backupninja running if
 155 the first instance is not finished before the next one starts.
 156
 157 Make sure that you put the "when" option before any sections in your
 158 configuration file.
 159
 160 These values for 'when' are equivalent:
 161
 162   when = tuesday at 05:30
 163   when = TUESDAYS at 05
 164
 165 These values for 'when' are invalid:
 166
 167   when = tuesday at 2am
 168   when = tuesday at 2
 169   when = tues at 02
 170
 171
 172 REAL WORLD USAGE
 173 ================
 174
 175 Backupninja can be used to implement whatever backup strategy you
 176 choose. It is intended, however, to be used like so:
 177
 178 (1) First, databases are safely copied or exported to /var/backups.
 179     Typically, you cannot make a file backup of a database while it
 180     is in use, hence the need to use special tools to make a safe copy
 181     or export into /var/backups.
 182
 183 (2) Then, vital parts of the file system, including /var/backups, are
 184     nightly pushed to a remote, off-site, hard disk (using
 185     rdiff-backup). The local user is root, but the remote user is not
 186     priviledged. Hopefully, the remote filesystem is encrypted.
 187
 188 There are many different backup strategies out there, including "pull
 189 style", magnetic tape, rsync + hard links, etc. We believe that the
 190 strategy outlined above is the way to go because: (1) hard disks are
 191 very cheap these days, (2) pull style backups are no good, because then
 192 the backup server must have root on the production server, and (3)
 193 rdiff-backup is more space efficient and featureful than using rsync +
 194 hard links.
 195
 196
 197 SSH KEYS
 198 ========
 199
 200 In order for rdiff-backup to sync files over ssh unattended, you must
 201 create ssh keys on the source server and copy the public key to the
 202 remote user's authorized keys file. For example:
 203
 204   root@srchost# ssh-keygen -t dsa
 205   root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost
 206
 207 Now, you should be able to ssh from user 'root' on srchost to
 208 user 'backup' on desthost without specifying a password.
 209
 210 Note: when prompted for a password by ssh-keygen, just leave it
 211 blank by hitting return.
 212
 213 The included helper program "ninjahelper" will walk you through creating
 214 an rdiff-backup configuration, and will set up the ssh keys for you.
 215
 216
 217 Amazon Simple Storage Service (S3)
 218 ==================================
 219
 220 Duplicity can store backups on Amazon S3 buckets, taking care of encryption.
 221 Since it performs incremental backups it minimizes the number of request per
 222 operation therefore reducing the costs. The boto Python interface to Amazon
 223 Web Services is needed to use duplicity with S3 (Debian package: python-boto).
 224
 225
 226 VSERVERS
 227 ========
 228
 229 If you are using Linux-Vservers (http://linux-vserver.org/) there are some
 230 special capabilities that different handlers have to make vserver
 231 backups easier.
 232
 233 Set the variable "vservers" to be "yes" in /etc/backupninja.conf and see the
 234 example configuration files for each handler to configure the vserver specific
 235 variables.
 236
 237 Additional vserver variables that can be configured in /etc/backupninja.conf,
 238 but they probably don't need to be changed:
 239
 240 VSERVERINFO (default: /usr/sbin/vserver-info)
 241 VSERVER (default: /usr/sbin/vserver)
 242 VROOTDIR (default: `$VSERVERINFO info SYSINFO |grep vserver-Rootdir | awk '{print $2}'`)
 243