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