intro

一套客户/服务器模式的备份系统代码,跨平台,支持linux,AIX, IRIX, FreeBSD, Digital Unix (OSF1), Solaris and HP-UX.

in a filesystem on the client. It serves for determining, where
the data for restore can be found on the server and to determine,
whether a user is allowed to restore the corresponding file, if
this possibility is configured (see HOWTO.FAQ.DO-DONT Q7).
Each time a full backup is done, a new filelist is started.
Incremental backups result in appending lines to this file.
The filelist files are identified by the number of the full
backup, that is increased continuously each full backup.
A configurable number of such filelist files is kept for later
use. The restore utility needs these lists when certain files
are requested for restore. If these filelists get lost, you are
in trouble. You should use the mechanism described in the next
section to avoid this.

Minimum restore information

The minimum information to restore everything (the stored data
and the filelists) is on which cartridges and in which tape files
the data can be found. At each start of a full or incremental
backup this information is passed to a configurable program that
can read this information (a line of a special format) as the
standard input. This program should write this to a place where
it is safe from crashes of the local machine. One possibility
is a NFS-mounted directory, another one is to send this
information via email. This minimum information can be passed
to the restore utility for restoring either everything or only
the filelist files. The minimum restore information is not
cumulative i.e. only the latest one is required. Without this
minimum restore information, a tape scan is necessary to
do emergency recovery (get everything back after a complete
loss). This takes notably longer and can be avoided having
this little string available when needed.
If it is required to restore older backups or filelists that have been
deleted, because they fell out of the configurable number of indexes
to keep, the older minimum restore information can be used.
So it is not a bad idea to store it together with the
current date. This possibility requires, of course, that the
tapes with the older backups have not been overwritten.

Levels of Disaster / data loss

There are several stages of recovery from loss of data depending
on what information is still abailable and usable.
* saved filesystem entries are lost on a client, but indexes
  (filelists) are intact:
    - (x)afrestore without options -e, -E
    - uses index
    - end user restore possible, if configured
* index(es) lost, minimum restore information at hand:
    - afrestore with option -e (probably first -f, if desired)
    - pipe the minimum restore string into the program
    - must be done by administrator (superuser)
    - the minimum restore info is NOT (in) an index file,
      it's the string starting with @@@===--->>>
* index(es) lost, minimum restore information lost:
    - afrestore with option -E
    - supply number(s) of tapes probably having the most
      recent minimum restore information
    - must be done by administrator (superuser)
    - if afbackup -E does not find anything: try to find the
      minimum restore info on tape using dd(1), strings(1)
      and grep for @@@===--->>> (in quotes, please) on the
      tape
* server broken:
    - same procedure like for the client
    - the server's latest version of the var-directory must
      be restored before doing anything else
See also HOWTO Q24 and the DO-DONT section for more details.


Client-side program structure

There is a three-layer program hierarchy on the client side. The
program "afclient" in the client's binary directory performs
the packing, unpacking and the communication with the server
side. It does not read the configuration file and does not
maintain the filelists described above. This is done by programs
with higher functionality, that in turn call the "afclient" program
setting it into different modes. The entry "afbackup" in the same
directory is identical with "afclient". These higher level programs
are full_backup, incr_backup, afrestore, afverify and a few more.
afrestore in turn is used by the X11-frontend xafrestore. See HOWTO
Q41 for more information about the architecture.


How to use it
-------------

First a short summary, which program serves for what purpose,
in order of estimated interest:

client side:

full_backup     runs a backup of all configured files/directories
incr_backup     runs an incremental or level-X backup i.e. only
                things modified since one of the previous backups
                are saved
afrestore       restore files/directories whose names are matching
                given arguments
xafrestore      an X11-frontend for afrestore
afverify        compare the latest or an older backup with the
                current status of the files/directories
update_indexes  remove entries from the online file index, whose
                corresponding tapes have been erased on the
                server(s)
copy_tape       make an identical copy of one tape to another
                assigning a different secondary label number
clientconfig    program to modify the client configuration
                interactively, online help available
xclientconfig   ditto, but as X11-program

server side:

afserver        the server program operating the tape and serving
                one client at a time
afmserver       the multiplexing frontend for afserver, possibly
                serving several clients in parallel
label_tape      to put a valid afbackup label to a tape or read it
cart_ctl        in combination with a changer: handle tapes and
                maintain their locations
cartis          to change the writing position on tape manually
                (use carefully !)
cartready       to give manual hints to the server when requested
                to perform some administrative action
serverconfig    program to modify the client configuration
                interactively, online help available
xserverconfig   ditto, but as X11-program
xserverstatus   displays the current status of the server and the
                most recent entries of the serverside log

For detailed information about the programs see the PROGRAMS file,
the manual pages, and the HOWTO-FAQ, e.g. FAQ Q41

Now a typical case is described. Individual needs can be
satisfied by reading the rest of the documentation. Below are
hints to configuration files for some typical cases that
come with the distribution.

Let us assume, you have a DAT-cartridge handler with 12 tapes
connected to some machine without the possibility to set a
cartridge directly via commandline interface. The first
thing to do is set the robot to sequential mode. It is no bad
idea to make this machine "fetch" the backup from the clients
using a small script that is started via crond. Thus the
first step is to setup this backup server. Unpack the
distribution, run the Install script and select installation
option number 1 for installing and configuring the server side.
The last question to be answered is whether to run the
serverside configuration program. Answer with yes, because we
should do this now. Most entries can be accepted as they are,
using the default value. You must know yourself Which device
should be used (you have, of course, already done some archiving
with tar to the connected streamer!). The blocksize can be looked
up usually in the man-pages of rmt or tar. Set the parameter
"CartridgeHandler" to 1 and the number of cartridges to 12.
Because you must use the robot sequential mode, clear
the "SetCartridgeCommand", if not already done entering the
parameter number and a single space for the value. Set the
"ChangeCartridgeCommand" to a command, that ejects a tape from
the drive (usually mt -f %d rewoffl - the %d stands for the
configured devicename, just for convenience, so that it need
not to be typed in several times). The UserToInform-parameter
should be set to some administrator, or group of administrators,
that should receive important informations. The rest of the para-
meters are quite self-explanatory. Use the online-help, the
CONFIG and the HOWTO.FAQ.DO-DONT, if you don't know what they
mean. Especially the CONFIG should provide valuable hints.
Finish the server configuration by entering "ok".
Now make the robot have cartridge number 1 present inside
the streamer. If you do not want to do this or can't convince
the device to do what you desire, run the following command:
/the/path/to/server/bin/cartis <cartno>
where <cartno> is the integer number specifying the cartridge
currently present in the drive.

Now install the client side on each client, that should do
backups to the server. Again, unpack the distribution and
run the Install script, choosing the installation option
number 3 for client with remote start possibility. Again, all
defaults should be ok, so the last question, whether to run
the clientside configuration program can be confirmed.
Reasonable defaults are present for each parameter. What you
have to configure in any case are the files and directories,
that are to be stored. Furthermore, the startup information
program should be configured to a reasonable command (see above
under "Minimum restore information" for details). If you
are upgrading to a newer version and some of the parameters
are not set, see the client.config (or server.config, respec-
tively) of the current distribution for the defaults, that I
consider sufficient for normal cases. This also might give you
better ideas about what the parameters are good for.

Finally write small scripts starting the backup one after the
other on the clients (the server may off course also be a
client). An example script is provided in the HOWTO.FAQ.DO-DONT
under Q2. Just replace the list of hosts in the shell-variable
BACKUPCLIENTS. Now add entries to root's crontab-file. Entering
crontab -l > my_crontab
as root writes the current crontab to the file my_crontab. E.g. to
run a full backup each Friday evening and incremental
backups each evening from Monday to Thursday (all at 8 pm), add
these two lines:

0 20 * * 5   /usr/backup/client/bin/full_backup_cycle
0 20 * * 1-4 /usr/backup/client/bin/incr_backup_cycle

assuming the named programs are the scripts you wrote according
to the above description. Then run the command
 crontab my_crontab
to install the modified crontab file.

That's it. Maybe, you want to start the first full backup manually
to see whether everything is correctly installed and working.
In this case just start the script yourself and watch, what
happens. Especially watch the client- and server-side logfiles in
/path/to/client/var/backup.log and /path/to/server/var/backup.log.


Sample configuration files (Linux)

server.conf.manual
    For a streamer on /dev/nst0 without a changer, so tapes must be
    changed manually

server.conf.changer
    For a streamer on /dev/nst0, changer on /dev/sg0 (run scsicheck
    to find correct device), stacker has 7 slots, no loadport, copy
    changer.conf.mtx to /path/to/server/lib/changer.conf

server.conf.dir
    For writing the backup to a filesystem (directory /var/backup)
    using the directory option of (see:) HOWTO Q 3

server.conf.dirsl
    For writing the backup to a filesystem (directory /var/backup)
    using the symlink option of (see:) HOWTO Q 3

client.conf
    client side configuration file, appropriate for many cases
    (server hostname or alias must be backuphost, do adapt the
    parameter DirsToBackup to what is really appropriate)


----

If this introduction together with the rest of the documentation
is not sufficient, please let me know, but PLEASE give me
instructive hints regarding what you are missing or what should
be clarified.

Albert Fluegel

December 8, 2001