#file: README
 $Id: README,v 1.2 2002/04/20 07:35:08 rkeech Exp $

		The rkbackup system
		===================

Introduction

This file describes the rkbackup system, which is a set of shell
scripts which provide for a well-controlled and simple way of using
dump for system backups.


The files included in the system are as follows:

abortbu		Abort a running backup.
bulogrotate	Perform log rotation.
checkbu		Check backup status.
checkbu-run	Determine if a backup is currently running.
rkbackup	Perform a backup.
tapefile	Determine the current tape file.
backup-test.conf Test backup configuration.


(man pages)

abortbu.8
backup.conf.4
backup.post.4
backup.pre.4
bulogrotate.8
checkbu-run.8
checkbu.8
rkbackup.8
tapefile.8


Layout and naming.

Files are normally laid out as follows:

	scripts in /usr/sbin

	configuration files in /etc/rkbackup

	log files in /var/log/backup

	man pages in /usr/man/man{8,4}

Log files are named based on the configuration from which the
corresponding backup derives.

configuration	config file name	logfile
------------------------------------------------------------------
(default)	backup.conf		backup-default.19980828
test		backup-test.conf	backup-test.19980828



Set up

Configuration.  The backup system uses configurations.  Before a
backup can be performed, as a bare minimum, a default configuration
file "backup.conf" must be created.  This can be modelled of the
prototype provided with the package "backup-test.proto".  The default
configuration will normally comprise the whole system.  It is
recommended to have a test configuration (a single small file system)
and an operating-system-only (root and usr, et cettera) configuration.

Accompanying actions.  The backup can execute scripts before and after
the main part of the backup.  By default the scripts executed are
backup.post and backup.pre in /usr/sbin.  The use of these will
be site- and system-specific.

File modes. It is important that all configuration files and
accompanying-action scripts have their ownership and modes set
correctly, or the backup will not run as a security precaution.  This
is because if unauthorised access to a file is gained, it would be
possible for actions to be exectuted with root privilege.


Running

The main executable is "rkbackup"  when run without arguments it runs
the default configuration (backup.conf).  It can use alternate
configurations using the "-c" flag, eg "rkbackup -c test".  If a
backup is to be run without the accompanying pre- and post-backup
actions, then the "-s" (suppress) flag can be used.  

Log file.  When running, the log file is placed in /var/tmp, and only
moved to /var/log/backup when complete.  This is done to minimise the
risk of corrupting a backup of the root file systems due to files
changing during the backup (of course if /var/tmp is in the root file
system then this is no help).

PID file.  A file called backup-<configuration>.pid (eg
backup-test.pid) is created during the backup.  This helps in
determining the running status of the backup and is interpreted by
checkbu-run.

Status.  The running or historical status can be determined using the
checkbu command.

Dump level.  The rkbackup system only supports level-0 dumps.

Cron.  Following is an example fragment from /etc/crontab on a Red Hat 
Linux system:
----
03 04 * * 1,2,4,5 root /usr/sbin/rkbackup -c data
03 04 * * 3       root /usr/sbin/rkbackup -c weekly   
----

In this example, weekly backups are done on a Wednesday, and data-only
backups are down on Monday, Tuesday, Thursday and Friday.


Diagnostics

The checkbu command give a number of useful ways of checking the
backups.  A typical use might be as per the following example:

1. Look at the success/failure status of the last ten default backups.

# checkbu -S -m 10
10:1998-08-17: success
9:1998-08-17: success
8:1998-08-18: success
7:1998-08-19: success
6:1998-08-20: success
5:1998-08-21: failure
4:1998-08-24: success
3:1998-08-25: success
2:1998-08-26: success
1:1998-08-27: success


Note the number in the first column of the output is a sequence number
used in the next step.

2.  Examine the reason for failure of the backup that failed above.

# checkbu -s -d 5
Log file: backup-default.19980821.

Summary:
WARNING: backup failures detected on tapefile(s) 5 5.
No pre- or post-backup actions were performed.
Backup duration 0 hour(s), 53 minute(s).
Log file closed at 21:59.


3.  Examine the complete log output from the failed backup.

# checkbu -l -d 5

This prints out the entire log file.


Disabling backups

Where backups are normally scheduled automatically, rkbackup allows for
backups to be disabled (ie not run) if the need arises for operational
reasons.  This can be done without removing the associated
cron entry.  To provide this the rkbackup script will not perform backups if 
it is called from cron and the following file exists:

/etc/rkbackup/backup-<configuration>.disable 
(eg backup-test.disable).

This disable action can be performed from the operations menu.  The
disable flag file is ignored when the rkbackup script is called from
the command line.


Useful extras

Offlining. By default, the tape is taken offline (ejected) at the end
of a backup.  If this is not required, the following line should be
added to the associated configuration file:

	NO_OFFLINE=true

This can be useful in test configurations.

Auto suppress.  While the accompanying actions (pre- and post-backup)
can be suppressed from the command line, they can also be blanket
suppressed for a configuration by setting the following in the
configuration file:

	accompanying_actions=suppressed

This can be useful in test configurations.

Abort on failure.  By default, if a single tape file dump fails, the dumps
of the remaining tape files will be attempted and the post-backup
actions will be performed.  In some cases it is desrable to abort the
whole backup if a dump fails.  If this is the case then set the
following in the configuration file:

	ABORT_ON_FAILURE=true


Design and philosophy

The rkbackup system is designed to be as portable as possible.  For
this reason it is implemented in Bourne Shell, and in such a way as to
be as generic as possible.  Local and system-specific changes should
be restriced to configuration files and pre- and post-backup action
scripts.
