############################################################################
# REOBack - README
# $Id$
############################################################################
#
# REOBack Simple Backup Solution
# http://sourceforge.net/projects/reoback/
#
# Copyright (c) 2001, 2002 Randy Oyarzabal (techno91<at>users.sourceforge.net)
#
# Other developers and contributors:
#	 Andy Swanner	   (andys6276<at>users.sourceforge.net)
#    Richard Griswold  (griswold<at>users.sourceforge.net)
#    Nate Steffenhagen (frankspikoli<at>users.sourceforge.net)
#	 Anthony L. Awtrey, SCP Patch
############################################################################

CONTENTS

  1.  What is REOBack?
  2.  Can I copy, modify, and/or distribute it?
  3.  What files are included in the distribution and what are they for?
  4.  The backup process.
  5.  What's with the filename?
  6.  Full / incremental backup difference.
  7.  The restore process.
  8.  Remote backups.
  9.  How do I report bugs?
  10. I have a great idea for REOBack, do you care?
  11. Does REOBack have a mailing list?
  12. Possible future enhancements.

----------------------------------------------------------------------
1. What is REOBack?
----------------------------------------------------------------------

In the many years that I've been using computers, backups were the one 
essential practice that I always procrastinated with.  Mainly because 
commercial backup programs are either too complex or to much to configure.  
They always seem to do more than you want it to.  I always envisioned a 
simple solution that I can use, where all I have to do is define what I 
want to backup, schedule the program, and let it loose!

Finally early this year (2001), I was hired by a hosting company to 
develop a backup solution "that worked!".  So I started developing a 
solution I called "Easy Backup".  And the idea was really simple, 
full/incremental backups.  A few months later, the solution gradually 
leaned towards cobalt support more than anything else.  I left the company 
and the solution was stable with a couple of features left not 
implemented.

Which leads us to REOBack!  REOBack is a spin off of Easy Backup with a few 
routines added to support just about any UNIX based system. REOBack is meant 
to be a simple, and is designed to be used by administrators and users alike.

Enjoy!

----------------------------------------------------------------------
2. Can I copy, modify, and/or distribute it?
----------------------------------------------------------------------

You may copy and modify REOBack under the license terms of GNU GPL (See 
LICENSE file).  All we ask is that you keep the header information 
intact and contact us if you do so at: techno91@users.sourceforge.net.

----------------------------------------------------------------------
3. What files are included in the distribution and what are they for?
----------------------------------------------------------------------

As of version 1.0, REOBack consists of the following files:

Note: RPM installs have different locations.

TAR/GZIP INSTALL LOCATION:

file: 	reoback.pl <------- Main program.

file:	run_reoback.sh <--- 	Shell script to run main program.  Created
			    	mainly for cron execution.

dir:	docs <----------------- Documentation etc.
file:	docs/README <---------- This file
file:	docs/INSTALL <---------	What you need to do to install and start 
				using
file:	docs/CHANGES <---------	Lists changes with each released version
file:	docs/LICENSE <---------	The GNU public license


dir:	conf <----------------- Configuration files.
file:	conf/settings.conf <---	Configuration file
file:	conf/files.conf <------ Configuration file
file:	conf/log4perl.conf <--- Log4perl configuration file

dir:    data <----------------- Directory to keep data files to keep 
				track of what type of backup to run.
file:	status.dat <----------- Written after reoback run 1st time, keeps 
				track of history
file:	archive.dat <---------- written after all files archived


RPM INSTALL LOCATION:
docs: 	  /usr/share/doc/reoback-1.0/
configs:  /etc/reoback-1.0/conf/
program:  /usr/bin/

----------------------------------------------------------------------
4. The backup process
----------------------------------------------------------------------

Backups are performed by reading the user supplied configuration files and 
creating tar/gzip archives of the files defined.  REOBack is developed to 
support nightly backups runs and as such, its first run is always a full 
backup.  That is, archive every file regardless of its modification stamp.

REOBack keeps track of what type of backup to perform by storing backup 
information in the "datadir" directory defined in the configuration file. 
Therefore, deleting all files in the "datadir" directory will cause 
REOBack to perform a full backup on its next run.

REOBack can keep backups for any number of days.  The variable 
"backupdays" in  the configuration defines this number.  For example: a 
setting of "7", will cause REOBack to keep seven days of backup.  It will 
then delete old backups after reaching the next "7" days.  Here's an 
example:

   Assume we want to keep 7 days worth of backup, that is keep a history 
   of any file for 7 days.

   backupdays = 7
   
   DAY	BACKUPTYPE	 	  |	DAY    BACKUPTYPE
   -------------------------------------------------------
   1 	Full 		          |   	 8     Full
   2	Incremental	          | 	 9     Incremental
   3	Incremental    	          |      10    Incremental
   4    Incremental               |      11    Incremental
   5	Incremental               |      12    Incremental
   6    Incremental	          |      13    Incremental
   7    Incremental (Delete 8-14) |      14    Incremental (Delete (1-7)
      
Notice that it keeps 14 days (backupdays x 2) worth of backup before it 
deletes the old backups.  That is because we don't want to delete the old 
backups until the next full backups are finished.

----------------------------------------------------------------------
5.  What's with the filename?
----------------------------------------------------------------------

Parts of the archive filename:

   DARKSTAR-mysite-full-20010818-1148AM.1.tgz     
      /       |     |       |       |   \    \
    /         |     |       |       |    \    \
  (1)        (2)   (3)     (4)     (5)    (6) (7)

   1 - Host identifier (defined in the configuration as "host")
   2 - Backup identifier
   3 - Type of backup (full or incremental)
   4 - Date of backup (YYYYMMDD format)
   5 - Time of backup
   6 - Backup day (range: backupdays - (backupdays x 2)
   7 - Extension (duh!)
   
----------------------------------------------------------------------
6. Full / incremental backup difference.
----------------------------------------------------------------------

When running a full backup, REOBack will archive ALL files and directories 
defined.  Incremental backups on the other hand only archives files that 
changes since the last full backup.  This means that if you added or 
modified files in a directory defined for backups, after the last full 
backup time, they will be picked up in every run until the next full 
backup time passes.

----------------------------------------------------------------------
7. The restore process.
----------------------------------------------------------------------


REOBack does not have any programmatic way of performing restores.  But it 
isn't really hard to do.  To restore backups follow the following steps:

   1. Choose which day you want to restore.
   2. Restore the full backup, then restore every single incremental
      backup up to the day you choose.  

   For example: to restore files as of day "11". Restore day 8,9,10 and 
   11, to get the files' state as of day "11".

   TIP: If you want to restore an individual file or directory from the 
        archives, you don't have to untar the entire archive.  You can 
        simply type the following:

        tar xpvfz DARKSTAR-myfiles-full-20010818-1148AM.1.tgz <dir or file(s)> 

        Note that you can pass many directories or files at the end of the 
        command above.  You should also omit the leading "/".

You should now have an idea of how restores are performed.

----------------------------------------------------------------------
8. Remote backups.
----------------------------------------------------------------------

Four types of remote backups are supported, NFS, FTP, SMB and SCP.  
FTP has proven to be slower compared to NFS and SCP, NFS, SCP or SMB is 
highly recommended.  However if you decide to go with the NFS route, 
make sure you read NFS documentation.  REOBack uses passwordless 
connections only, so be sure to see SCP-INFO file.  Due to a limitation
in the SCP Perl module, REOBack is unable to do auto-deletions of 
files backed up via SCP.

Note that REOBack simply needs the NFS mount-point to do NFS transfers.  
REOBack automatically mounts and unmounts the mount-point.  Therefore, if 
your NFS mount is already pre-mounted, I suggest you change the 
configurations to NOT perform remote backups and simply keep local 
backups as NFS mount-points are simply represented as a local directory.

----------------------------------------------------------------------
9. How do I report bugs?
----------------------------------------------------------------------

Please use the bug tracking feature at sourceforge to report any 
bugs.  The URL is:
     http://sourceforge.net/projects/reoback/

----------------------------------------------------------------------
10. I have a great idea for REOBack, do you care?
----------------------------------------------------------------------

Of course we do!  Please send all ideas, suggestions, or comments to:
     techno91@users.sourceforge.net


----------------------------------------------------------------------
11. Does REOBack have a mailing list?
----------------------------------------------------------------------

Yes. The address is: reoback-discussion@lists.sourceforge.net
To subscribe/unsubscribe to list, visit our project page at 
http://sourceforge.net/projects/reoback/

----------------------------------------------------------------------
12. Possible future enhancements.
----------------------------------------------------------------------

   - Web configuration interface
   - Mail notifications
   
   If you have a feature request, make sure to add them to our source 
   forge project page at: http://sourceforge.net/projects/reoback/