
Programs of AF's backup system
==============================


Programs of the server side
---------------------------

 $BASEDIR/server/bin/cartis

  Administration of the cartridge numbers. Usage:

      cartis <number>

      cartis -i <ins-cart> <ins-file> [ -S <cartset> ]

  The first form of this command is used to give the backup
  server a hint, which cartridge number is actually placed inside
  the streamer. Normally it has no chance to find out the number
  and must maintain it's own information about it. If you are not
  initially starting with cartridge number 1, you have to enter
  this command at least on time (see: README, "BEFORE YOU START").
  The second form instructs the server to write the next backup
  data stream to cartridge number <ins-cart>, starting at file
  number <ins-file>. This is useful, if for some reason you want
  to take the cartridge actually lying inside the drive out and
  continue on a different tape or at the beginning of the tape
  you have put in instead. Note, that it usually causes problems,
  if you try to write at a tape position, that is not at the end
  of the last file, that has been written to tape. So set the
  <ins-file> number only to a value different from 1, if you
  really know, that this is the end of the used tape area. In
  other words, if n files are on tape, set <ins-file> to n+1. So
  if you don't know n, you're better off starting to write at the
  beginning of a new tape entering the appropriate cartis-command.
  To find out, what the server is thinking, which cartridge is
  actually inside the drive, you can give the command
  $BASEDIR/client/bin/client -q  on any client. If the value, that
  is printed out, does not reflect the reality, you have to inform
  the backup server about this fact via this command entering both
  forms of this command. The first form with the real cartridge
  number and the second one with the next cartridge number and a 1
  as file number. Then the next backup goes to the next cartridge.
  You may also set the next backup writing position to the current
  file number on the correct cartridge. To find out, where the
  server side intents to write the next backup, enter the command
  $BASEDIR/client/bin/client -Q  on any client.
  It makes sense to check the consistency from time to time, if
  the backup server has the right idea of the actual cartridge.

   -S <cartset>    The cartridge set to use, where <cartset> is the
                     number of a valid cartridge set on the server
                     side. Default is 1


 $BASEDIR/server/bin/cartready

  (No arguments evaluated)
  If you have no cartridge handling system, a human must put the
  next cartridge into the drive, if necessary. Then the backup-
  server must get a hint, when the maintainer has done it. This
  is achieved entering this command on the backup server host,
  after the new cartridge is inserted. Nonetheless the server
  process waits a certain timespan, until it accesses the drive
  the next time (See: "Cart-Insert-Gracetime" in CONFIG).


 $BASEDIR/server/bin/label_tape

  Write a label to tape or display it. Usage:

       label_tape <label-number> [ -c <configfile> ] \
                  [ -S <sec-label-number ] [ -n <comment> ] \
                  [ -d <devicename> ] [ -b <blocksize> ] \
                  [ -s <set-file-cmd> ] [ -C <num-cartridges> ]
       label_tape -q [ -c <configfile> ] [ -d <devicename> ] \
                  [ -b <blocksize> ] [ -s <set-file-cmd> ]

  The first form writes a label to the tape, the second form shows
  the label on the tape, that is actually loaded.
  The tape-label must be an integer number. This number is written
  to the tape actually in the drive and identifies it uniquely. It
  must be in the range from 1 to the number of cartridges given in
  the configuration file. This label is written at the beginning
  of the tape, so all data on tape will be lost. Due to that fact
  the user is always prompted, if he really wants to do this.
  <config-file> can be a different configuration file than the one
  the server process is started with. Normally it makes no sense
  to use this option, but in extremely pathological cases the
  program might not be able to find out the full path to the
  configuration file. Then is has to be supplied at the command
  line.
  The normal case is to use this command without options, but the
  settings in the serverside configuration file can be overridden,
  if necessary.

   -b <blocksize>  The blocksize of the device to use

   -C <num-carts>  The total number of handled cartridges

   -c <configfile> A different configuration file to use

   -d <devicename> The device to use

   -n <comment>    A comment to include into the tape label
                     (256 characters max)

   -S <sec-label>  The secondary label number, the server will
                     accept, if the primary label number does
                     not match

   -s <setf-cmd>   The command to reel the tape to a given
                     file position


 $BASEDIR/server/bin/server [ <options> ] [ <configuration-file> ]

  The server program. It must be started by the inetd-superdaemon.
  The configuration-file is read as $BASEDIR/server/lib/backup.conf
  if not given explicitely and if not found there the default files
  /etc/buserver.conf and /etc/afbackup/server.conf are tried.

  Options:

    -b         Turns off buffering mode. This reduces performance
                but seems to be necessary on some OSes

    -S         Run in slave mode. This option should is used, when
                the program is started as backend for the multi-
                stream server and should not be configured for
                normal startup

  Options for debugging purposes only:

    -D         Enter an infinite loop at startup to be caught
                using a debugger or continue, when a USR1 signal
                is sent to the process

    -s         Don't use secure mode for client requests. No
                authentication is performed

    -l <file>  Use a different logfile than set in the config
                file (see: Parameter Logging-File)

    -x <dir>   Use a different directory for remotely startable
                programs (see: Parameter Program-Directory)


 $BASEDIR/server/bin/mserver [ options ] [ <configuration-file> ]

  The multi-stream server able to serve several clients in parallel.
  This program works as a protocol multiplexing frontend for the
  normal server, that in turn is started as backend in slave mode.
  For the client side this server looks exactly like the normal
  single stream server, so for them there is nothing special contac-
  ting the multi stream server.
   The clients must pass a unique identifier to the multi stream
  server. Otherwise it cannot distinguish the clients, especially
  when dispatching the data on tape to the clients. By default this
  identifier is the official hostname of the client, that is
  determined from the connection. A client may pass a different
  identifier after having connected and authenticated successfully.

  The options are identical to those of the server program except
  for option -S, that is not applicable here, cause the multi-stream
  server doesn't know a slave mode. The other options are passed to
  the server backend.


Programs of the client side
---------------------------

 $BASEDIR/client/bin/full_backup

  Run a full backup. The usage:

      full_backup [ -daG ] [ {+-}LB ] [ <files> <directories> ... ] \
                  [ -C <root-directory> ] [ -F \"<files-to-skip>\" ] \
                  [ -D \"<directories-to-skip>\" ] \
                  [ -c <configuration-file> ] [ -W <identity> ] \
                  [ -h <backuphosts> ] [ -P <backup-ports> ] \
                  [ -I <indexfile-part> ] \
                  [ -N <num-indexes-to-store> ] \
                  [ -z <compress-cmd> <uncompress-cmd> ] \
                  [ -Z <builtin-compress-level> ] \
                  [ -s \"<dont-compress-patterns>\" ] \
                  [ -X <exclude-list-file> ] [ -l <logfile> ] \
                  [ -i <startup-info-program> ] \
                  [ -b <init-program> ] [ -e <exit-program> ] \
                  [ -k <encryption-key-file> ] \
                  [ -V <var-directory> ] [ -S <cartridge-sets> ]

  This program reads the client-side configuration file and runs
  (eventually a part of) a full backup of all files and directories
  specified in the configuration file or on the commandline. It is
  recommended to setup everything in the configuration file and run
  this command without any arguments (same applies for incr_backup).
  If files and/or directories are supplied on the commandline, those
  specified in the configuration file are overridden. Furthermore
  the program then behaves slightly different: If backup parts are
  configured, they are ignored. The timestamp, that is evaluated
  during incremental backup to determine, whether files have been
  modified, is not changed. This behaviour reflects the assumption,
  that supplying files or directories on the commandline is done
  for testing or other temporary purposes. Modifying the timestamp
  would confuse the normal regularly running backup mechanism. In
  these temporary cases the -a option should make sense, see below
  for details. Be also aware of the -C option's meaning. If the name
  of a file is preceded with -r, the contents of the file is stored,
  but not the characteristics of the inode. This is useful for
  saving raw devices. By default, compression is always turned off.
  Using -R forces compression of the contents. Preceding a directory
  name with -m the recursive descent into this directory is limited
  to the filesystem, where the directory resides.
  The names of the files and directories, that are stored, are
  written into logfiles, that comprise of the indexfile-part (-I)
  and the current total backup counter. This counter is incremented
  each time a full backup (part 1) starts. A minimum information
  required to restore after a hard crash having lost everything is
  piped into the startup-info-program (-i). 
  Whether only a part of a full backup is run depends on the setting
  of the parameter NumBackupParts (See: CONFIG). If the configuration
  file is not supplied explicitely, then it is searched for in the
  .../lib-directory and if not found there the files
  /etc/buclient.conf /etc/afbackup/server.conf are tried.
  Commandline options generally override configuration file settings.
  Every option described below (except -c) has a corresponding
  entry in the configuration file, but there are more possible
  settings in the config file.

   -a              Append mode. Do not increment the total backup
                     counter. (See -N)

   {+-}B           Perform per-file compression on the stored files
                     (+B) or not (-B) (See: -F)

   -b <initprog>   Run the given program before attempting a backup.
                     If the command returns an exit status unequal
                     to 0, no backup is performed (see: -e). Not to
                     be mixed up with option -i

   -C <rootdir>    Change to the given directory before starting the
                     backup climbing down into the directories to be
                     stored

   -c <configfile> A different configuration file to use

   -D <skip-dirs>  A list of directory name patterns separated by
                     whitespace to ignore for backup. Several must be
                     put into quotes (See: -F and -X)

   -d              Detach from the terminal when starting

   -e <exitprog>   Run the specified program after finishing. If the
                     command comprises of several words separated by
                     whitespace, it must be put into quotes (See: -i)

   -F <skip-files> A list of filename patterns separated by whitespace
                     to ignore for backup. Several must be put into
                     quotes (See: -D and -X)

   -G              To request a new cartridge. If the current writing
                     position is already at the beginning of a new or
                     reused tape, nothing happens

   -h <backuphosts> The names of the hosts, where a backup server side
                     lives. The list can be separated by commas and/or
                     whitespace. If whitespace is present, quotes are
                     necessary. The hosts are tested for service
                     availability. If a backup server is not ready,
                     the next one is tried. If all are busy, the program
                     waits for a minute and tries again

   -I <idx-prefix> The first part of the filename, the names of the
                     stored files and directories are written to. The
                     current total backup number is appended (that
                     increments each start of a full backup). If these
                     files undergo compression, .z is appended

   -i <info-prog>  The command to save startup information. A minimum
                     information to recover from a hard crash is piped
                     into this program (at stdin). If the command
                     comprises of several words, it must be put into
                     quotes. Not to be mixed up with option -b

   -k <file>       Use the contents of the given file as encryption
                     key for authenticating to the server

   {+-}L           Compress the filename list files (+L) or not (-L)
                     (See: -I)

   -l <logfile>    Write loggings into the given logfile. A dash -
                     means: no logging, only write to stderr

   -N <num-idxes>  The number of filename list files, that is stored
                     over time. A new list is begun at each start of
                     a full backup (except -a is supplied)

   -P <portnos>    The port numbers, that are tried to connect at the
                     servers. They must be supplied positionally according
                     to the configured or (with the -h option) given
                     backup servers. The list may be separated by whitespace
                     and/or commas. If whitespace is present, quotes are
                     necessary

   -S <cartsets>   The cartridge sets to use, where <cartsets> is a
                     number of a valid cartridge set on the appropriate
                     server side. Default is 1. These must be supplied
                     positionally according to the configured or (with
                     the -h option) given backup servers. The list may
                     be separated by whitespace and/or commas. If
                     whitespace is present, quotes are necessary

   -s <nocompr>    A list of filename patterns, that no compression is
                     attempted on, what can save time significantly.
                     The list should always be enclosed in quotes

   -V <var-dir>    The directory, where varying files are put

   -v              be verbose

   -W <id>         Identify as <id> to the server. This is needed when
                     connecting a multi-stream server to distinguish
                     between the clients. Default is the official
                     hostname of the client. If the client should fake
                     to be a different one than it is in fact, this
                     option must be used
 
   -X <excl-file>  The name of a file, that may exist in any directory
                     containing a list of filename patterns, one per
                     line. All files and directories in that directory
                     matching one of the patterns are exluded from
                     backup (See: -D and -F)

   -z <z> <uz>    The commands to use for compress and uncompress. If
                    a command comprises of several words, it must be
                    put in quotes

   -Z <level>     If builtin compression should be used, the level can
                    be supplied here. If commands to compress and
                    uncompress are also supplied with option -z, then
                    data is first processed by the compress command,
                    then by builtin compression. During uncompress it
                    works the other way round


  A table of corresponding command line options and configuration
  file entries, (subsets) accepted by full_backup, incr_backup,
  restore, verify, print_errors:

   Option       Client configuration file parameter name

    +B -B       CompressBackupedFiles

    -b          InitProgram

    -C          RootDirectory

    -D          DirsToSkip

    -e          ExitProgram

    -F          FilesToSkip

    -h          BackupHosts

    -I          IndexFilePart

    -i          StartupInfoProgram

    -k          EncryptionKeyFile

    -l          LoggingFile

    +L -L       CompressLogfiles

    -N          NumIndexesToStore

    -P          BackupPorts

    -S          CartridgeSets

    -s          DoNotCompress

    -V          VarDirectory

    -W          ClientIdentifier

    -X          ExcludeListFile

    -z          CompressCmd UncompressCmd

    -Z          BuiltinCompressLevel



 $BASEDIR/client/bin/incr_backup

  Run an incremental backup. Usage: See full_backup above.
  Additional option:
                              [ -Q <backup-level> ]

  This program reads the client-side configuration file and runs
  an incremental backup, i.e. all files and directories are saved,
  whose modification time is later than the moment the previous
  backup (full or incremental) has started. The options and their
  meanings are exactly the same as for full_backup, except for the
  -a option, see below. The total backup counter is not increased.

   -a              Differential mode. The timestamp storing the
                     time of the last backup is not modified

   -Q <level>      The backup level. All files modified since the
                     most recent backup with a level equal or
                     higher are saved. The higher this number, the
                     more files are redundantly saved again.
                     <level> can be an arbitrary number from 0
                     up to 2147483646 (== MAXINT - 1). Default: 0.
                     A full backup has an implicit backup level of
                     2147483647 (== MAXINT)


 $BASEDIR/client/bin/restore

  The restore utility. The Usage:

       restore [ -nlv ] [ -<past-backup-no> ] [ -C <root-directory> ] \
               [ -h <backuphosts> ] [ -P <backup-ports> ] \
               [ -c <configuration-file> ] [ -W <identity> ] \
               [ -A "<after-date>" ] [ -B "<before-date>" ] \
               [ -I <indexfile-part> ] [ -V <var-directory> ] \
               [ -k <encryption-key-file> ] \
               [ -z <compress-cmd> <uncompress-cmd> ] \
               [ -Z <builtin-compress-level> ] \
               [ -p ] <path-pattern> [ [ -p ] <path-patterns> [ ... ] ]
       restore -a [ -v ] [ -<past-backup-no> ] [ -C <root-directory> ] \
               [ -h <backuphosts> ] [ -P <backup-ports> ] \
               [ -c <configuration-file> ] [ -W <identity> ] \
               [ -I <indexfile-part> ] [ -V <var-directory> ] \
               [ -k <encryption-key-file> ] \
               [ -z <compress-cmd> <uncompress-cmd> ] \
               [ -Z <builtin-compress-level> ]
       restore -{ef} [ -v ] [ -C <root-directory> ] [ -h <backuphosts> ] \
               [ -P <backup-ports> ] [ -V <var-directory> ] \
               [ -z <compress-cmd> <uncompress-cmd> ] \
               [ -Z <builtin-compress-level> ] \
               [ -k <encryption-key-file> ] [ -W <identity> ] \
               [ -c <configuration-file> ] < <startup-info-file>
       restore -E [ -nlv ] [ -C <root-directory> ] [ -h <backuphosts> ] \
       	       [ -P <backup-ports> ] [ -V <var-directory> ] \
       	       [ -z <compress-cmd> <uncompress-cmd> ] \
               [ -Z <builtin-compress-level> ] \
       	       [ -k <encryption-key-file> ] [ -W <identity> ] \
       	       [ -c <configuration-file> ] [ -H <orig-host> ] \
       	       [ <cartridge-number> | <cartridge-range> ] ... ]

  The first form can be used for restoring selected pieces of
  a certain previous backup run. If no option of the type
  -<past-backup-no> is supplied (e.g. -2 ), the most recently
  made backup is accessed. If an option like this is given,
  the backup system tries to extract the files from the backup
  before ( -1 ) or even an earlier one. This requires, that
  enough file- and directory-name-logging is provided. This
  can be done with the client-side configuration parameter
  NumIndexesToStore (See: CONFIG). The parameters <path-pattern>
  indicate, which files and directories should be restored. An
  asterisk is implicitely put before and after the <path-pattern>,
  so it is assumed to be a substring of the path. This can be
  prevented preceding the <path-pattern> with the option -p.
  These may be wildcards for the full path name leading to the
  file relative to the directory, to that the client changes
  before starting any backup or restore (See under the parameter
  RootDirectory in CONFIG). Note, that you have to put these into 
  quotes, if you are using wildcards to prevent substutition. It
  is a bad idea to restore a total backup entering: restore "*"
  This leads to a huge filelist to be processed by the client,
  what might plug up memory and/or temporary space in some
  filesystem. Instead you should use the second form with the
  option -a, what restores a total backup. The third form
  restores without looking for filename log files. Instead it
  reads the standard input for information, where to extract
  from. The format expected at standard input is the same as
  produced by incr_backup or full_backup, if the configuration
  option StartupInfoProgram is used. The given program is then
  supplied with the appropriate information and should write
  it to some place outside the local host, so that it will not
  be affected by a hard crash (see: StartupInfoProgram in
  CONFIG). The fourth form scans the cartridges (if supplied)
  on the given servers (if supplied, eventually with alternate
  given port numbers - see below for the format, how to specify
  cartridge/host/port-triples) for backups done from the host,
  where the restore program is started and restores everything
  it finds. The functionality is similar to -e, but no input has
  to be supplied. If the client's hostname has changed or restore
  should be done on another host, the original hostname must be
  supplied with the -H option. Otherwise nothing or the wrong
  stuff will be restored. Scanning the cartridges can take a lot
  of time, but it should be several minutes, not hours.
  Cartridges can be supplied in three forms as arguments: simple
  numbers, ranges (e. g. as 3-5 without spaces), and ranges
  relative to the actual backup writing position (e. g. as -3).
  In the latter case -0 means the cartridge, that will be written
  to next time i.e. that holds the actual writing point. -2 stands
  for the latest 3 cartridges. To indicate, that a cartridge is
  located at a certain backup server, maybe with a special port
  number (if there are several backup servers), the cartridge
  number or range can be followed by the at-character @, optionally
  followed by the percent character % and the port number, e. g.
  3-5@buhost%2989 . No whitespace is allowed in such a specifier.
  If no port is given, the default port is assumed (2988). If no
  hostname is given, the default backup server is used. Default
  backup server is the first one in the list, that is configured
  in the parameter file or overriden by the option -h. Any number
  of ranges or numbers can be supplied, overlapping duplicates are
  ignored. If no cartridge numbers are given, the program searches
  backward from the actual writing position on each configured
  backup server until it thinks, it has enough backups found, or
  all cartridges on that server have been tried. The found backups
  are sorted in the correct order (using the stored backup time)
  and afterwards everything found is restored. This form of the
  command needs no information at all for an emergency restore. If
  the configuration file is not supplied explicitely, then it is
  searched for in the .../lib-directory and if not found there the
  files /etc/buclient.conf and /etc/afbackup/client.conf are tried.

  Flags

    -A <date>     Restore files modified after the given date. The
                    date should be put into quotes, cause it usually
                    contains whitespace. Valid formats are e.g.:
                      MM/DD/YYYY hh:mm:ss
                      DD.MM.YYYY hh:mm:ss
                    or the formats produced by ctime(3) or date(1).
                    The year may be supplied in two digits or in the
                    non-US-formats be omitted, then the current year
                    is assumed. The seconds may also be omitted
                    (hh:mm), the whole time may be left off, then
                    00:00 is assumed. Thus the shortest valid format
                    is DD.MM

    -B <date>     Restore files modified before the given date. See
                    -A for the valid date formats

    -C <root-dir> Change to the given root-directory before restoring
                    files instead of the one specified in the client
                    side configuration file. If this directory does
                    not exist, it is created

    -c <conffile> Use the given file for configuration information

    -e            Restore all files from the previous backup in an
                    emergency case without looking for the filename
                    logfiles, which are also restored

    -f            Restore only the filename logfiles in an emergency
                    case

    -H <orighost> (in combination with -E) Restore everything saved
                    from the given host, if different from the one,
                    where the program is running. Domainnames or
                    anything behind (and including) a dot in this
                    hostname is ignored

    -h <hostnames> Use the given list of hosts as backup servers. This
                    list is used only, if no hostname information can
                    be found as associated with the actual filesystem
                    entry, that should be restored. The first host in
                    this list is the default server, if no hostname
                    information at all can be found. If -E is given
                    and no cartridge number is supplied at all, all
                    hosts in this list are tried one after the other.
                    The hostnames in this list can be separated by
                    whitespace and/or commas

    -I <idx-prefix> The first part of the filename, the names of the
                    stored files and directories are written to. The
                    current total backup number is appended (that
                    increments each start of a full backup). If these
                    files undergo compression, .z is appended

    -k <file>     Use the contents of the given file as encryption
                    key for authenticating to the server

    -l            Do not restore anything, just list the names of
                    the files and/or directories, that fit the supplied
                    path-part(s); in combination with -E: just scan the
                    given tape(s) and printout the minimum restore info,
                    that can be read by restore -e

    -n            Do not restore anything, just printout a message,
                    how many files and/or directories fit the supplied
                    path-part(s); in combination with -E: just scan the
                    given tape(s) and printout, what backups have been
                    written there

    -P <portnos>  The list of port numbers for the backup servers
                    either configured in the parameter file or supplied
                    with the -h option. This list is used only, if no
                    port number information can be found as associated
                    with the actual filesystem entry, that should be
                    restored. The port numbers supplied here are asso-
                    ciated with the backup server names by position.
                    The port numbers in this list can be separated by
                    whitespace and/or commas

    -V <var-dir>  The directory, where varying files are put

    -v            be verbose

    -W <id>       Identify as <id> to the server. This is needed when
                    connecting a multi-stream server to distinguish
                    between the clients. Default is the official
                    hostname of the client. If the client should fake
                    to be a different one than it is in fact, this
                    option must be used
 
    -z <z> <uz>   The commands to use for compress and uncompress. If
                    a command comprises of several words, it must be
                    put in quotes

    -Z <level>    If builtin compression should be used, the level can
                    be supplied here. If commands to compress and
                    uncompress are also supplied with option -z, then
                    data is first processed by the compress command,
                    then by builtin compression. During uncompress it
                    works the other way round

  I suggest to run restore with the -l option before really going
  to restore anything. So you see, what files will be generated,
  maybe overwriting existing ones unintendedly.


 $BASEDIR/client/bin/verify

  Run a verify of a previous backup. The usage:

       verify [ -v ] [ -c <configuration-file> ] \
              [ -<past-run-no>[.<past-backup-no>] ] \
              [ -h <backuphosts> ] [ -P <backup-ports> ] \
              [ -C <root-directory> ] [ -S <cartridge-sets> ] \
              [ -I <indexfile-part> ] [ -V <var-directory> ] \
              [ -k <encryption-key-file> ] [ -W <identity> ] \
              [ -z <compress-cmd> <uncompress-cmd> ] \
              [ -Z <builtin-compress-level> ]

  Without any arguments, this program runs a verify over the
  previously written backup. This may either be a full or an
  incremental backup, only the contents of the very previous
  run are used. All found differences are reported.
   Though it is not considered to make too much sense, it is
  also provided, that files and directories saved during a run
  before the previous one can be checked. This can be done
  supplying the <past-backup-specifier>. If this is a simple
  number, it counts back from the previous full or incremental
  backup of the same total backup number (this number is increased
  each run of the full_backup-command, not by subsequent
  incremental backups). -1 means, that the backup before the
  previous one is checked and so on. If the contents of a previous
  total backup run should be checked, the following form may
  be used: -<previous-run>.<previous-total-backup>, where
  <previous-total-backup> counts back from the actual total backup
  number and <previous-run> counts back from the last backup
  (incremental or full) run among the previous total. previous-run
  may be 0 here. E.g. verify -0.1 checks the files saved during
  the last run of the previous total backup.

    -C <root-dir> Change to the given root-directory before verifying
                    files instead of the one specified in the client
                    side configuration file.

    -c <conffile> Use the given file for configuration information

    -h <hostnames> Use the given list of hosts as backup servers. This
                    list is used only, if no hostname information can
                    be found as associated with the actual filesystem
                    entry, that should be verified. The first host in
                    this list is the default server, if no hostname
                    information at all can be found. The hostnames in
                    this list can be separated by whitespace and/or
                    commas

    -I <idx-prefix> The first part of the filename, the names of the
                    stored files and directories can be found. The
                    current total backup number is appended (that
                    increments each start of a full backup). If these
                    files undergo compression, .z is appended

    -k <file>     Use the contents of the given file as encryption
                    key for authenticating to the server

    -P <portnos>  The list of port numbers for the backup servers
                    either configured in the parameter file or supplied
                    with the -h option. This list is used only, if no
                    port number information can be found as associated
                    with the actual filesystem entry, that should be
                    verified. The port numbers supplied here are asso-
                    ciated with the backup server names by position.
                    The port numbers in this list can be separated by
                    whitespace and/or commas

    -V <var-dir>  The directory, where varying files are put

    -v            Verbose mode: print information records on tape and
                     the names of the checked files during operation

    -W <id>       Identify as <id> to the server. This is needed when
                     connecting a multi-stream server to distinguish
                     between the clients. Default is the official
                     hostname of the client. If the client should fake
                     to be a different one than it is in fact, this
                     option must be used
 
    -z <z> <uz>   The commands to use for compress and uncompress. If
                    a command comprises of several words, it must be
                    put in quotes

    -Z <level>    If builtin compression should be used, the level can
                    be supplied here. If commands to compress and
                    uncompress are also supplied with option -z, then
                    data is first processed by the compress command,
                    then by builtin compression. During uncompress it
                    works the other way round

  In my opinion a verify makes only sense immediately following
  an incremental or full backup with the purpose to check, whether
  the files and directories did not get corrupt on the storage
  media. If you want to do this (via cron or however), keep in
  mind, that the verify takes at least the same time as the
  backup itself. If you have a huge amount of data to save, the
  additional verify might run you into time consumtion problems.


 $BASEDIR/client/bin/copy_tape

  Make a duplicate of a tape. The usage:

     copy_tape [ -v ] [ -c <configuration-file> ] [ -l <logfile> ] \
                 [ -h <source-server> ] [ -P <source-serverport> ] \
                 [ -C <source-cartridge> ] \
                 [ -k <source-encryption-key-file> ] \
                 [ -D \
                  [ -h <target-server> ] [ -P <target-serverport> ] \
                  [ -C <target-cartridge> ] \
                  [ -k <target-encryption-key-file> ] ]

  This command connects to one or two backup servers and makes
  an identical copy of a tape to another one. The tape label
  is rewritten, so that the destination tape keeps it's primary
  cartridge number, but gets the number of the source tape as
  secondary number. Thus it can be used instead of the tape
  with that primary number. In fact both numbers are accepted
  for backup, restore or other operations except the copy_tape
  operation itself. Recursively copying an already duplicated
  tape does not further change the secondary cartridge number,
  so e.g. any copy of cartridge number 3 will be usable as such.
  Copying cartridge 3 to cartridge 5 and then 5 to 8 does not
  make cartridge number 8 usable as cartridge 5, but still as
  cartridge number 3. When the backup server sees a cartridge
  with the wrong primary number, but the correct secondary
  number, this cartridge is accepted, but a warning is written
  to the serverside log. The defaults for the copying source are
  taken from the client side configuration file. Default source
  cartridge is the one currently loaded in the drive on the
  server, that will be asked for this information. If no target
  parameters are supplied, they get the values of the appropriate
  source parameters as default. So if no arguments are supplied,
  the actual tape would be copied to itself, what is prevented
  while printing an error message. Target (or: destination)
  parameters must always be following the -D option, source
  parameters must be supplied in an earlier position. If the
  source tape is operated by a different server than the target,
  copying goes straight from one to the other. As two servers
  (with a different port number) can reside on one host, this
  process does not necessarily imply a network connection.
  If source and target tape are handled by the same server, the
  data to be copied must be stored somewhere inbetween. For this
  purpose a temporary directory is created on the client, where
  this program is started, usually in /tmp or /var/tmp (see:
  tmpnam(3)). The filesystem, where this directory lives, must
  have a free capacity of at least the largest occurring tape
  file. This maximum tape file size is configured on the server
  side by the parameter MaxBytesPerFile (see: afserver.conf(8)).
  If there is not enough space, the duplication of the tape
  fails. The copying program writes as many tape files to disk
  as it can, while a certain amount will remain free. Then it
  ejects the source cartridge and loads the target cartridge.
  Now the files in the temporary directory are written to the
  target tape while immediately removing files, that are no
  longer needed. The more space is available in the temporary
  directory, the fewer cartridge loads/ejects are necessary.

   -C <cartridge>    The number of the cartridge to use as copying
                      source or target (depends on argument position:
                      before or behind -D).

   -c <configfile>   Use the given file for configuration information

   -h <hostname>     The name of the backup server host, where the
                       source or target cartridge is handled,
                       respectively

   -k <file>         Use the contents of the given file as encryption
                      key for authenticating to the server, where the
                      source or target cartridge is handled,
                      respectively

   -l <logfile>      A file to write log information to

   -P <portnum>      The port number of the backup server on the
                      backup server host, where the source or target
                      cartridge is handled

   -v                Verbose option, tell more about what is going on


 $BASEDIR/client/bin/client

  The main program of the client side. This program does not read
  configuration files or filelists nor does it maintain any other
  persistently stored information. It's just the workhorse providing
  the functionality, that is required by the higher level programs.
  Here's the usage, that can be printed out typing:  client -usage

       client -cxtd [ -[RraunOvgiIqQZwbjG] ] \
               [ -M <server-message> ] \
               [ -h <backup-server> ] \
               [ -z <zipcmd> <unzipcmd> ] \
               [ -Z <builtin-compress-level> ] \
               [ -T <to-extract-filename> ] \
               [ -C <cartridge-number> ] \
               [ -F <filenumber-on-tape> ] \
               [ -f <archive-filename> ] \
               [ -e <errorlog-filename> ] \
               [ -p <server-port-number> ] \
               [ -N <newer-than-filename> ] \
               [ -o <user-ID> ] \
               [ -k <encrption-key-file> ] \
               [ -s <dont-compress-filepattern> [ -s ... ] ] \
               [ -H <header> ] \
               [ -V <statistics-report-file> ] \
               [ -A <after-time-seconds> ] \
               [ -B <before-time-seconds> ] \
               [ -W <identity> ] \
               [ <files> <directories> ... ]

       client -X <program> \
               [ -h <backup-client> ]

       client -\?  (to get help)

  The first form is similar to tar, except that it contacts a
  backup server, if the -f option is not supplied.

  The second form is used to start a program remotely on
  another host. In most cases this will be one of:

  client -X full_backup -h <some-host>
  client -X incr_backup -h <some-host>

  Normally this host is a backup client and a backup is started
  this way. Only programs can be started, that reside in the
  directory, that is configured in the backup server's configu-
  ration file unter "Program-Directory".

  The third form produces the following help text:

  Description
  ===========
  
  This program is used to maintain archives on a backup server
  host or in a file. Archives can be created, extracted or their
  contents be listed. Almost one of the following flags has to
  be supplied:
  
   -c  to create an archive
  
   -x  to extract from an archive
  
   -t  to list the contents of an archive
  
   -d  to verify (compare) the contents of an archive

   -C  to set a certain cartridge on the backup server
        (makes only sense extracting or listing with -x or
         -t, the writing position can't be changed by clients)

   -F  to set a certain file on the backup server's tape
        (same applies as for -C)

   -q  to printout the actual cartridge and tape file number
         on the backup server
  
   -Q  to printout the cartridge and tape file number for the
         the next write access on the backup server

   -X  followed by the full path name of a program to be started on
         the client. This can be used to trigger a backup remotely.
         If the program needs arguments, the command together with
         the arguments has to be enclosed by quotes
  
   -I  to  printout an index of the backups written to the
         actual cartridge

   -w  to check the status of the streamer on the server side, e.g.
         whether it is ready and waiting for requests to service,
         see below for possible states

   -G  to request a new cartridge for the next writing operation.
         If the current writing position is already at the beginning
         of a new or reused tape, nothing happens

   -D <destination> to make an exact copy of a tape to another one
         (duplicate). See below how to specify the destination tape.
         Duplication can be either from one cartridge to another on
         the same server, or from one server to another one. When
         copying to the same server chunks of data are stored in a
         temporary directory on the client, where the command is
         started, what should preferably be the source server

   -M <message> send a message to the server. Messages will in the
         most cases contain whitespace, so they should be enclosed
         in quotes. Server messages should be sent to the single
         stream server (port), the multi stream server might hang
         receiving a message due to systematical reasons.
         The following messages are currently supported:

        PreciousTapes: <list-of-tapes>
                   The list of tapes is inserted into the table
                   with the tapes, that are crucial for clients
                   to restore all files, that are listed in all
                   existing index files. These tapes will not be
                   overwritten until explicitely permitted. This
                   message is generated automatically and should
                   not be used in other user contexts

        ReuseTapes: <list-of-tapes>
                   The opposite of PreciousTapes. Sending this
                   message permits the server to overwrite the
                   listed tapes, though they are crucial for
                   some client

        TapesReadOnly: <list-of-tapes>
                   The list of tapes is inserted into the file
                   listing the files, that should not be written
                   any more for whatever reason

        TapesReadWrite: <list-of-tapes>
                   This reverts the status of tapes set read-only
                   to read-write, the opposite of TapesReadOnly

        CartridgeReady
                   When an operator is requested to do something
                   the server is waiting for, this message can be
                   sent to trigger the server to proceed. This
                   message has the same effect as the cartready
                   command


  -c, -x, -t and -X are mutual exclusive. The other options can
  be supplied as needed. To set the cartridge and/or the tape file
  on the backup server is only making sense when not creating
  an archive. The serial order of writing to tape is handled by
  the server machine independently of the client.
  
  
  Filenames
  
  The names of the files and directories, that have to be put
  into or extracted from an archive are by default read from the
  standard input. If you supply filenames in the command line or
  enter the -a flag when extracting, standard input is not read.
  The same is valid, if filenames are read from a file with the
  -T option. When reading the names from a file or from standard
  input, they must be given one per line. If a name contains
  special characters (like newline or nonprintable ones), they
  have to be specified using backslash-sequences like in C-code,
  e.g. \n for newline.
  In save mode (-c) filenames can be prefixed with character
  sequences, that have special meanings (no space between prefix
  and filename):

   /../   The file is not saved with all attributes present in
          the inode, but only the contents are saved. This might
          be useful for saving raw-devices
   //../  With /../ the configured compression is not applied to
          the file contents for safety reasons. With this prefix
          compression can be forced nonetheless
   |||    and a mandatory space character indicates, that the
          following characters up to (but not including) another
          triple bar ||| should be interpreted as a shell command,
          that is started and whose standard output is written to
          the backup. At restore time the command following the
          second triple bar is started and the data stream read
          at backup time is written to it's standard input. This
          might be useful for saving e.g. databases. The second
          command may be terminated by a triple sharp ###, that
          starts an optional comment. Example:
         ||| pg_dumpall ||| psql db_tmpl ### Store Postgres DBs


  More options in alphabetical order:
  
   -            in combination with -c: read standard input and
                  write it to tape, in combination with -x: read
                  tape and write it to standard output

   -A <time>    process files (save or extract) modified after
                  the given time in seconds since 1.1.1970 00:00

   -a           in combination with -x: extract all files and
                  directories in the archive
  
   -B <time>    process files (save or extract) modified before
                  the given time in seconds since 1.1.1970 00:00

   -b           don't enter buffering mode

   -e <errlog>  Use the file <errlog> to write error messages to
                  instead of the standard error output
  
   -f <file>    write to or read from a file instead of querying
                  the backup server
  
   -g           while extracting/reading: ignore leading garbage,
                  suppress error messages at the beginning. This
                  is useful when extracting from tape files, that
                  are not the first ones of a whole archive.
  
   -H <header>  put the supplied informational header to the begin
                  of the backup

   -h <host>    use the backup server with the name <host>
                  default host is the machine with the name
                  backuphost
  
   -i           while extracting: ignore the stored ownership and
                  do not restore it

   -j           when starting to write: request starting a new
                  tape file

   -k <file>    use the contents of the given file as encryption
                  key for authenticating to the server
  
   -l           for each packed or unpacked filename, if sending
                  to or receiving from a backup server in verbose
                     mode in combination with -n:
                  printout server name and port number at the
                  beginning of the line, e.g.: orion%2988!

   -N <file>    while archiving: ignore files with a modification
                  time before the one of the given file, only save
                  newer files or such with the same age in seconds

   -n           for each packed or unpacked filename, if sending
                  to or receiving from a backup server in verbose
                     mode:
                  printout cartridge and tape file number at the
                  beginning of the line, e. g.: 7.15: <filename>

   -O           for each packed file creating a backup in verbose
                  mode: printout the user-ID of the file owner at
                  the beginning of the line prefixed with a bar |
                  eventually behind cartridge and file number

   -o <uid>     archive or extract only files owned by the user
                  with the given user-ID (an integer)
  
   -p <portno>  use a different port number for communicating with
                  the backup server. Default is TCP-Port 2988
  
   -R           pack or extract directories recursively with all
                  of their contents
  
   -r           use filenames relative to the current directory,
                  whether they start with a slash or not

   -S <cartset> The cartridge set to use, where <cartset> is the
                  number of a valid cartridge set on the server
                  side. Default is 1. This option makes sense only
                  when creating backups with -c

   -s <filepat> do not attempt compression on files matching the
                  given filename pattern. This parameter may
                  appear several times

   -T <file>    read the filenames to process from the <file>.
                  The filenames must be separated by whitespace.
                  If whitespace is part of a filename, it has to
                  be enclosed by double quotes. Double quotes or
                  backslashes within the filename have to be
                  preceded by a backslash
  
   -u           while extracting: remove existing files with the
                  same name as found in the archive. Otherwise
                  no existing files are overwritten
  
   -V <file>    write a report containing statistics at the end of
                  a backup to the <file>

   -v           verbose mode: print the filenames while creating
                  or extracting, be a little more verbose while
                  listing contents
  
   -W <id>      identify as <id> to the server. This is needed when
                  connecting a multi-stream server to distinguish
                  between the clients. Default is the string
                  "<client-program>"
 
   -z <z> <uz>     use <z> as the command, that is used to compress
                     files, <uz> for the corresponding uncompress.
                     The command has to read from stdin and to write
                     to stdout. If arguments have to be supplied to
                     <z> and/or <uz>, don't forget to use quotes. If
                     builtin compression is desired, the command for
                     compression has to start with a dot (.), followed
                     by a space and a number ranging from 1 to 9, that
                     specifies the compression level. If an additional
                     external command should process the data, it may
                     follow, separated from the compression level by
                     whitespace. The order of processing is: First the
                     external program processes the data, then builtin
                     compression is applied. An empty string has to be
                     supplied for <uz> (or any other dummy is ok), if
                     only builtin compression is desired.
                     Examples for <z>:
                      gzip       (run external command gzip),
                      "gzip -2"  (the same with an argument),
                      ". 8"      (only builtin compression level 8),
                      ". 3 __descrpt -k /my/key" (run command __descrpt
                                 and apply builtin compression level 3)
  
   -Z           while printing out the contents: check those files
                  in the archive that are compressed for integrity
  
  
   -?           to printout this text

  The -w option reports one or more of the following states,
  seperated by the plus character + :

    READY     the device is not in use by any program and the
              server side is ready to service requests

    BUSY      the device is in use and actually operated by the
              afbackup service

    DEVINUSE  the streamer device is in use by some program, that
              is not part of the afbackup service

    UNAVAIL   the streamer device is not accessible or in some
              other way occupied

    UNLOADED  the device is not busy, but there is no tape loaded

    CHANGEABLE when reported together with UNLOADED, a tape can be
              loaded quickly e.g. using the afclient command with
              option -C <cartno>. It is not considered quickly,
              if a human operator must put the cartridge into the
              drive, so in this case only UNLOADED is reported.
              When reported with READY, the tape can be changed
              quickly (same understanding as before).


 $BASEDIR/client/bin/print_errors

  A utility to extract error messages from the actual filename
  logging file besides those appearing in the configured logfile
  of the client side. Usage:

       print_errors [ -c <configuration-file> ] [ -<past-backup-no> ] \
                    [ -I <indexfile-part> ] [ -V <var-directory> ] \
                    [ -N <num-indexes-to-store> ] \
                    [ -z <compress-cmd> <uncompress-cmd> ] \
                    [ -Z <builtin-compress-level> 

  If no option of the type -<past-backup-no> is supplied (e.g. -2 ),
  the most recently made backup is accessed. If an option like this
  is given, the backup system tries to extract the errors from the
  backup before ( -1 ) or even an earlier one. This requires, that
  enough file- and directory-name-logging is provided. This can be
  done with the client-side configuration parameter NumIndexesToStore 
  (See: CONFIG). A different configuration file can be supplied with
  the -c option.

  Options in alphabetical order:

    -c            Use the given file for configuration information

    -I <idx-prefix> The first part of the filename, the names of the
                    stored files and directories can be found. The
                    current total backup number is appended (that
                    increments each start of a full backup). If these
                    files undergo compression, .z is appended

   -N <num-idxes>  The number of filename list files, that is stored
                     over time. A new list is begun at each start of
                     a full backup (except -a is supplied)

   -V <var-dir>    The directory, where varying files are put

   -z <z> <uz>     The commands to use for compress and uncompress. If
                     a command comprises of several words, it must be
                     put in quotes

   -Z <level>      If builtin compression should be used, the level can
                     be supplied here. If commands to compress and
                     uncompress are also supplied with option -z, then
                     data is first processed by the compress command,
                     then by builtin compression. During uncompress it
                     works the other way round


Helper programs
---------------

  The names of all the following programs are starting with two
  underscores __ to indicate, that they don't have a functionality,
  which refers directly to any backup or restore operations. They
  can be used to achieve additional functionality or for further
  convenience. They are listed in alphabetical order regardless of
  usefulness or importance.


 __descrpt

  Program to encrypt data using a DES-algorithm. Usage:

    __descrpt { -e | [ -d ] } [ -w ] [ -k <cryptkeyfile> ]

  This program en- or decrypts the standard input to standard output.
  The used key is derived from the string supplied at compile time or
  read from the given cryptkeyfile. If -d is not supplied, data will
  be encrypted, otherwise decrypted. -e is optional i.e. the default.
  By default 128 Bit DES encryption is active. With the flag -w this
  is reduced to weaker 64 Bit DES encryption, what is much less secure
  but notably faster. If -w is supplied when encrypting, it must also
  be given for decrypt.
  This program can only be built, if the Eric Young's DES library is
  available. The command  make __descrpt  in the source distribution
  directory will compile and link it.


 __inc_link

  Script to modify a symlink to point to the next file, counted
  by the trailing number. Usage:

    __inc_link [ -s ] <symlink> <increment>

  It will be determined, to what the given symlink points. The
  integer number at the end of this filesystem entry will be
  increased by the given increment (may be negative). The symlink
  will be removed and a new one created pointing to the resulting
  filesystem entry. If no filesystem entry with the resulting name
  exists, an error message is printed. If the new symlink cannot
  be created or the old one cannot be removed, error messages are
  printed. If everything works fine and the -s flag (silent) is
  not supplied, the name of the filesystem entry, to that the new
  symlink points, is printed. If any error occurs, the original
  symlink remains unchanged. E.g. if  ls -l  reports (among others):

  lrwxrwxrwx  1  af  user  13  Oct  8 14:00  the_link -> file.number.4

  and the command  __inc_link the_link 2  is entered, the result
  of a following  ls -l  will be:

  lrwxrwxrwx  1  af  user  13  Oct  8 14:00  the_link -> file.number.6

  and some more (file.number.6 must exist)


 __mt

  Wrapper script for mt on systems, where the count 0 for subcommands
  like fsf leads to an error. Same usage applies for both __mt and mt.


 __packpats

  Auxiliary script used by xafrestore. The functionality of this
  program is not important to any user or administrator. It's main
  intention is to speed up the index scanning, cause otherwise the
  Tcl/Tk-Script must do the entire evaluation, what is a real CPU
  hog.


 __piper

  Program to create command pipes without the overhead of shells.
  Usage:

    __piper [ command [ args ] [ '|' command [ args ] [ '|' ... ] ] ]

  This program simply gets one or more commands seperated by the pipe
  symbol | as arguments. When called from a shell commandline or in
  any situation, where the whole command is interpreted by a shell,
  the bar | has to be escaped from interpretation, either by preceding
  it with a backslash or putting it into single quotes.
   The arguments are chained (seperated by single spaces each) and
  then separated at word boundaries. If an argument should contain
  whitespace, it must be double-quoted. The whole command pipeline may
  be put into one single argument, so in a shell the following is ok:

    __piper 'echo "Hello    lots of space" | sed "s/ts of/st in/g"'

  Double quotes, the pipe symbol and the backslash itself may be
  escaped by a preceding backslash \.
  The advantage using this program instead of a shell with the -c
  option should be a much faster startup of the whole pipeline. This is
  useful in the compress- and uncompress commands of the client side.


 __z

  Program, that performs the same (un)compression like the builtin
  compression. The synopsis of this program is:

      __z [ -{123456789|d} ]

     __z [ -123456789 ]  compresses standard input to standard out
                         using the given compression level

     __z -d              uncompresses standard in to standard out

