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