README for backup.pl (v 1.9 22/6/2010)
 --------------------------------------

 backup.pl (c) 2003-2010 th(at)bogus.net is a small utility that uses rsync to 
 make backup copies securely over the network.


 usage
 =====

 $Id: backup.pl,v 1.9 2010/06/22 09:11:11 torh Exp $
 usage: ./backup.pl [-v|-h] [-r] [-d] [-t] [-p] [-c <config>] [-e <filename>]
  -v : print version
  -h : print this help
  -d : turn on debugging
  -p : enable --partial (resume files that have grown or failed)
  -e : do not execute unless <file> exists (for mounted directories)
  -r : don't delete files that don't exist on source
  -t : only test, don't actually run rsync
  -c : configuration file (default: /etc/backup.conf)

 most of the above options should be quite self-explanatory.
 
 new in version 1.9 is the addition of including an option to enable --partial which
 will resume any files that failed (or have grown) during the last backup.
 
 worth mentioning is the -e option, which will ensure that the backup only takes place
 if a given file exists. this can be useful if you run your backups to e.g. NFS or SMB
 mounted directories. by adding a ".mounted" in the root of the mounted file system,
 you can check for the existence of this file before the backup runs, so:

 ./backup.pl -c /etc/backup.conf -e /nfs_export/backups/.mounted


 preparation
 ===========

 in order to make it work, you will need to install rsync on the machines you
 wish to make backups of. 

 you can find rsync at http://samba.anu.edu.au/rsync/.

 you also need ssh installed, and you will also need to enable passphrase-less 
 dsa (or rsa) authentication. to do this, you should ideally familiarise 
 yourself with ssh-keygen(1):

   man ssh-keygen

 but here is a quick start tutorial in order to get you started. first, on 
 the machine where you wish to keep your backups, run:

   su -
   ssh-keygen -t dsa

 when you are prompted for a password, press return ("enter"). after the key
 has been generated, it will be located in (usually) /root/.ssh/id_dsa.pub. copy 
 this key to every host's "root" authorized_keys file, e.g. do:

   echo "ssh-dss AA.[truncated].o6Q== user@localhost.localdomain" >> /root/.ssh/authorized_keys

 on all the hosts you wish to make backups.


 if you plan to backup windows files
 ===================================

 you will need to install Cygwin (which is a really easy affair), and 
 make sure you include sshd and rsync in the install dialogue.

 when this is installed, you will need to generate the sshd host keys by
 typing:

   ssh-host-config

 and you will also need to create your ssh keys, etc. you'd be smart to 
 create a "backup" user.


 configuring
 ===========

 the default path for the configuration file is /etc/backup.conf; you will 
 have to edit the backup.pl file if you wish to change this.

 the configuration file is constructed as follows. all lines starting with
 # or ; (including any white space preceding these characters) are 
 considered comments. the variable DESTROOT can be used to change the default 
 destination root directory for all the hosts you wish to backup. currently,
 the destination root is "/export/backup".

 it is also possible to have per-host DESTROOT's, as long as DESTROOT is 
 defined within the host definition block (see example configuration file).

 backups will be organised under this directory so:

           /export/backup
                 |
       +---------+---------+--- .. ---+
       |         |         |          |
     host1     host2     host3    user@hostN

 any file/directory you do NOT want to include in the backup should be preceded
 by - and whitespace, e.g.

	/home
 -	/home/mrbig

 will backup everything in /home, but not mrbig's directory.

 you organise hosts in the configuration file using the following structure;

   www.bogus.net {
     /etc
     /var/www
     /home
   - /home/ftp
   }
   ftp.bogus.net {
     /etc
     /local
   - /local/src
   - /local/obj
     /home
   - /home/ftp
   }
   me@myuniversity.edu {
     /home/me
   }

 if the host portion of the configuration block is 'localhost', this will
 instruct the script to send the files _to_ a remote server - ensure your
 DESTROOT reflects this, e.g.:

   localhost 512 {
     DESTROOT=www.example.com:/local/myremotebackup
     /etc
     /home
   }

  the above will bandwidth limit a backup _from_ the local machine to a 
  remote server.

 see the backup.conf file supplied for some more examples.

 
 special note for windows hosts
 ==============================

 any file that recides on a windows box can be backed up so:

   backup@windows.host.here {
     /cygdrive/c/My Documents
     /cygdrive/c/Documents and Settings/myuser
   }


 running
 =======

 after you have decided what is necessary to keep a backup of, test it by 
 running backup.pl with no arguments. after the program has finished running, 
 verify that your files have been transferred, and then (e.g.) add the 
 following to your /etc/daily.local (or similar!):

   if [ -x /usr/local/bin/backup.pl ]; then
        echo "running backup.pl"; /usr/local/bin/backup.pl&
   fi

 enjoy!


 a word or two on restore
 ========================

 (this is completely left up as an exercise to the unfortunate user!)