README

                                          |\_
                 B A C K U P N I N J A   /()/
                                         `\|
                         
      a silent flower blossom death strike to lost data.

Backupninja allows you to coordinate system backup by dropping a few
simple configuration files into /etc/backup.d/. Most programs you
might use for making backups don't have their own configuration file
format. Backupninja provides a centralized way to configure and
coordinate many different backup utilities. 

Features:
 - easy to read ini style configuration files.
 - secure, remote, incremental filesytem backup (via rdiff-backup).
   incremental data is compressed. permissions are retained even
   with an unpriviledged backup user.
 - backup of mysql databases (via mysqlhotcopy and mysqldump).
 - backup of ldap databases (via slapcat and ldapsearch).
 - passwords are never sent via the command line to helper programs.
 - you can drop in scripts to handle new types of backups.

The following options are available:
-h         This help message
-d         Run in debug mode, where all log messages are output
           to the current shell.
-f <file>  Use <file> for the main configuration instead of
           /etc/backupninja.conf
 
CONFIGURATION FILES
===================

The general configuration file is /etc/backupninja.conf. In this file
you can set the log level and change the default directory locations.
You can force a different general configuration file with "backupninja
-f /path/to/conf".

To preform the actual backup, backupninja processes each configuration
file in /etc/backup.d according to the file's suffix:
 
  .sh      --  run this file as a shell script.
  .rdiff   --  this is a configuration for rdiff-backup
  .maildir --  this is a configuration to backup maildirs
  .mysql   --  mysql backup configuration
  .ldap    --  ldap backup configuration

Support for additional configuration types can be added by dropping
bash scripts with the name of the suffix into /usr/share/backupninja. 

The configuration files are processed in alphabetical order. However,
it is suggested that you name the config files in "sysvinit style." 

For example:
	00-disabled.ldap
	10-runthisfirst.sh
	20-runthisnext.mysql
	90-runthislast.rdiff

Typically, you will put a '.rdiff' config file last, so that any
database dumps you make are included in the filesystem backup. 
Configurations files which begin with 0 (zero) are skipped.

Unless otherwise specified, the config file format is "ini style."

For example:

   # this is a comment
   
   [fishes]
   fish = red
   fish = blue

   [fruit]
   apple = yes
   pear = no thanks \
   i will not have a pear.

REAL WORLD USAGE
================

Backupninja can be used to impliment whatever backup strategy you
choose. It is intended, however, to be used like so:

(1) First, databases are safely copied or exported to /var/backups.
    Typically, you cannot make a file backup of a database while it
    is in use, hence the need to use special tools to make a safe copy
    or export into /var/backups.
     
(2) Then, vital parts of the file system, including /var/backups, are
    nightly pushed to a remote, off-site, hard disk (using
    rdiff-backup). The local user is root, but the remote user is not
    priviledged. Hopefully, the remote filesystem is encrypted. 

There are many different backup strategies out there, including "pull
style", magnetic tape, rsync + hard links, etc. We believe that the
strategy outlined above is the way to go because: (1) hard disks are
very cheap these days, (2) pull style backups are no good, because then
the backup server must have root on the production server, and (3)
rdiff-backup is more space efficient and featureful than using rsync +
hard links. 

SSH KEYS
========

In order for rdiff-backup to sync files over ssh unattended, you must
create ssh keys on the source server and copy the public key to the
remote user's authorized keys file. For example:

  root@srchost# ssh-keygen -t dsa
  root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost 

Now, you should be able to ssh from user 'root' on srchost to
user 'backup' on desthost without specifying a password.

Note: when prompted for a password by ssh-keygen, just leave it
blank by hitting return.

INSTALLATION
============
   
Requirements:
  apt-get install bash gawk

Suggested:
  apt-get install rdiff-backup gzip

Files:
  /usr/sbin/backupninja        -- main script
  /etc/cron.d/backupninja      -- runs main script nightly
  /etc/logrotate.d/backupninja -- rotates backupninja.log
  /etc/backup.d/               -- directory for configuration files
  /etc/backupninja.conf        -- general options 
  /usr/share/backupninja       -- handler scripts which do the actual work

Installation:
  There is no install script, but you just need to move files to the
  correct locations. All files should be owned by root.
 
  # tar xvzf backupninja.tar.gz
  # cd backupninja
  # mv backupninja /usr/sbin/backupninja
  # mv etc/logrotate.d/backupninja /etc/logrotate.d/backupninja
  # mv etc/cron.d/backupninja /etc/cron.d/backupninja
  # mkdir /etc/backup.d/
  # mv etc/backupninja.conf /etc/backupninja.conf
  # mv handlers /usr/share/backupninja