moved all to trunk

1 files changed, 147 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..1b8bd66
--- /dev/null
+++ b/README
@@ -0,0 +1,147 @@
+
+                                          |\_
+                 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