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 currently placed inside
  the streamer. If the tape has a valid afbackup label, then it
  is not necessary to tell the server, what tape is in the drive,
  cause it will try to read and evaluate it. If the tape is not
  labeled (e.g. if it has not been used before), the server has
  no chance to find out the number and must maintain it's own
  information about it. The server will automatically label new
  tapes, if they don't already have a valid label, the next time,
  a write operation is attempted on the tape. By issuing cartis
  after inserting an unlabeled tape you tell the server, what
  tape it should become. If you are not initially starting with
  cartridge number 1 and an unlabeled tape, you have to enter this
  command at least one time. (see: README, "BEFORE YOU START")
  if you have not labeled a tape or variable append mode is on.
  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 currently 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
  currently inside the drive, you can give the command
  $BASEDIR/client/bin/afclient -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/afclient -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 current 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> [ -rfF ] [ -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 currently loaded.
  The tape-label must be an integer number. This number is written
  to the tape currently 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.
  If it is intended to label a tape, while a server is waiting for
  another cartridge being put into the drive, the -F option must
  be used to override the lock, that is held by the server process.
  The server will be kept from probing, whether a tape is in the
  drive, while the label_tape program is running. label_tape
  should be started, before the tape to be labeled is put into the
  drive. Otherwise the server might eject it at once after probing.
  label_tape will prompt for confirmation before performing any
  tape access (if started without -f option). Thus the tape should
  be loaded after starting the command and before confirming.

   -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

   -f              Force operation without further asking

   -F              Continue regardless of a lock, probably set
                     by other running applications, especially
                     the server. This option may be used to label
                     a tape, while the server is waiting for a
                     cartridge to be put into the streamer device

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

   -r              Remove the cartridge in the drive from the
                     cartridge handling database without further
                     asking

   -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/cart_ctl

  Perform operations on tapes: move, set location, inventory, list
  locations, label several tapes in changer slots, drives, loadbays

       cart_ctl [ -ilmtefF ] [ -P [ <location> ] ] \
                  [ -s <serverconfigfile> ] \
                  [ -c <changerconfigfile> ] \
                  [ -d <changerdevice> ] [ -C <cartridges> ] \
                  [ -S [ <slots> ] ] [ -D [ <drives> ] ] \
                  [ -L [ <loadports> ] ] [ -b <blocksize> ] \
                  [ -n <comment> ]

  This command performs operations on cartridges and maintains
  the cartridge location database. This command is especially
  designed for moving cartridges around, serving as a wrapper
  for those commands, that in fact fulfil this functionality.
  cart_ctl adds the maintenance of the locations and unifies
  the command interface. E.g. the counting of slots, loadbays
  and drives always starts with 1 here. Several cartridges,
  slots, drives and loadbays can be supplied using numbers,
  dashes and commas to the respective option, e.g. -C 3-5,8 .
  The order is significant, e.g. -m -C 2-3,1 -S 5,4,3 will
  move cartridge 2 to slot 5, 3 to 4 and 1 to slot 3. This
  command evaluates the serverside configuration file and reads
  another file to configure the media changer driving commands.
  The path to this second configuration file must be given in
  the server configuration file as parameter
   Changer-Configuration-File
  See below under FILES for more details on this.
  With option -m, one or more cartridges are moved to another
  location. The location must be specified with options -S for
  slots, -D for drives, -L for loadbays and -P for a freetext
  description, if the cartridge is placed outside of any
  cartridge handling system. Thus the administrator can store
  any kind of text as reminder, where the tapes are. If there
  are no slots supplied with option -S, free slots are looked
  up and the cartridge(s) move there. The same applies for -L.
  If no drive is given with -D, the drive configured in the
  server configuration file is used. The number of the drive
  can be given, or the device name, but in the current version
  just -D is mostly suitable. If there is a tape in the drive,
  it will be unloaded to a free slot first. If occupied slots
  or loadbays are given as targets, an error message is printed
  and the move is not performed. If there is no argument given
  with -P, the user is prompted to enter a line of text, that
  is stored in the cartridge locations database. If several
  cartridges are moved outside of a robot, the text given with
  -P will be stored for all of them. If moving to loadbays is
  possible, moves to the outside will first have a loadport as
  target and the maintainer is asked to take the tape out of
  this place to it's final destination. When moving tapes in
  and there are loadbays, the maintainer is asked to put the
  cartridge into a loadbay and the robot does the rest. If
  there isn't yet any location stored for a cartridge, the
  maintainer is asked to perform the move manually, naming the
  origin location `unknown'.
  Option -S can be used, if a location of a tape changes, but
  it should not be moved by any robot. So -S just inserts or
  replaces the new location in the database. To specify the
  locations the same options can be used like when moving with
  -m, see the previous section for details.
  Option -l lists the locations of all cartridges. If -S is
  also supplied, the contents of the slots are listed. A dash
  means, that the slot is empty. A question mark means, that
  there is a cartridge in this slot, but it is unknown, which
  that might be. A dash, followed by a question mark and a
  number, all in braces, means, that the slot is empty, but the
  locations database has the given cartridge number stored for
  this slot, what means an inconsistency. Option -L together
  with -l has the respective meaning for loadbays like -S for
  slots.
  Option -i makes an inventory of the slots specified with -S.
  That is, the cartridges in these slots are loaded to drive,
  the labels are read and evaluated. If the label is recognized
  as valid for afbackup, the location database is updated. The
  cartridge will be put back to the original slot afterwards.
  Option -t can be used to label the tapes in several slots.
  The label numbers must be given using option -C and the slots
  with option -S. If the label numbers are not given, it is
  assumed, that the tapes should get the currently registered
  numbers. If it cannot be determined, which cartridges are in
  the given slots, this is an error. If the slots are not given,
  it is tried to determine them from the given cartridge numbers.
  If the given cartridges are currently not located in any slot,
  this is an error. Like with the command label_tape, a comment
  to be written to tape can be supplied with option -n.
  Option -e makes the tape in the drive to be ejected to a free
  slot. No tape number has to be supplied. Optionally the slot
  can be specified using option -S.

  Options:

    -b         override the blocksize setting in the server
                configuration file (discouraged)

    -C <cart>  specify the cartridge numbers to operate on

    -c <file>  use the given file to configure the media changer
                driving commands

    -D <drive> use the given drive as target for moves or location
                settings. The drive may be specified as number
                inside a changer system (starting with 1) or as
                device name. If no drive is given, the drive
                configured in the server configuration file is
                used

    -d <dev>   operate on the given media changer device, don't
                use the settings in the configuration file

    -F         force operations, ignore active locks on streamer
                and changer devices, if applicable

    -f         force labeling operations without further asking

    -i         inventory the cartridges in the slots specified
                with -S

    -l         list the cartridge locations, together with -S:
                list the contents of the slots (if no slots given:
                of all slots), together with -L: list the contents
                of loadports (specified or all)

    -L <loadp> specify the loadports, that should be part of the
                desired operation. If no loadports are given,
                free ones are searched for when moving

    -m         perform moves of one or more cartridges. These
                must be given using -C. Targets for the moves
                must be given using -S for slots, -L for loadbays,
                -D for drives or -P for somewhere else

    -n <comm>  use the given comment when labeling tapes with -t

    -P <place> Specify the target place for moving or just setting
                a cartridge location. If no place is given on the
                command line, the program will prompt for one

    -S <slots> Specify the slots, that should be part of the
                desired operation. If no slots are given,
                free ones are searched for when moving

    -s <file>  Use the given file as server configuration file, not
                the default one

    -t         Write labels (`tags') to the cartridges in the slots
                specified with -S

  This command can be used as the SetCartridgeCommand in the
  server configuration. Option -F is required here, cause the
  server itself is already holding a lock on the streamer device,
  thus this command needs not and should not attempt any further
  locking. The entry in the server configuration file should look
  like this:
             /path/to/cart_ctl -F -m -C %n -D

  Files:

  A configuration file to specify the media changer commands must
  be given in the server configuration with parameter
   Changer-Configuration-File
  This file must name the commands, that really perform the moves
  of the cartridges in a changer. A maximum if nine entries can
  be given to specify, how to move a cartridge from or to a slot,
  a drive or a loadbay (3 x 3 = 9). These parameters all have
  names of the form Move-<origin>-To-<target>-Command with origin
  and target being one of slot, drive and loadport, e.g.
   Move-Slot-To-Drive-Command:
  In these commands the following replacements are made:
   %d   the streamer device i.e. drive
   %D   the media changer device
   %n   the origin (e.g. slot) number, if the command starts to
        count with 1
   %m   the origin number, if counting starts with 0
   %N   the target number, if counting starts with 1
   %M   the target number, if counting starts with 0
  Commands, that are not supported for whatever reason, should
  be commented out in this configuration file.
  Two commands can be configured, that print the numbers of free
  slots/loadports to standard output. If there are loadbays, that
  should be used, the command, that lists the free ones, must be
  present. The command listing the free slots must always be
  there. The parameter names for these commands are:
  List-Empty-Slots-Command and List-Empty-Loadports-Command .
  In these commands only the pattern %D is replaced like
  explained above.

  For the most common changer driving commands (mtx and stc),
  appropriate files are included into the distribution. They can
  be used without any modifcation, just comment out the commands,
  your hardware does not support (e.g. moving from slot to slot).

  The cartridge locations database is an ASCII file in the var-
  directory of the server side called cartridge_locations .
  Like all the files there it should not be modified manually.


 $BASEDIR/server/bin/afserver [ <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 explicitly and if not found there the default files
  /etc/buserver.conf, /etc/afbuserver.conf, /etc/afserver.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

    -L <locale> Set the locale to the given string. Note, that this
                option might not be honoured due to insufficiencies
                of the gettext implementation on some systems

    -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/afmserver [ 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 -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 (see under afserver above), except for the
  following, that are understood only by afmserver:

    -d         Daemonize. Go into the background and run forever.
                This is the way, the multi stream server can be
                started without using the inetd. -p should be
                supplied when using this option

    -p <port>  The TCP port number or service name, the server
                should bind to. If started via inetd, the inetd
                binds to the port and starts the afmserver connected
                to the port. When started as daemon, the afmserver
                must be told the port to bind to. If not given,
                the service entry afmbackup is used or, if not
                found, the default port 2989


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

 $BASEDIR/client/bin/full_backup

  Run a full backup. The usage:

      full_backup [ -daG ] [ {+-}LBx ] [ <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> ] | \
                      -O <max-age-of-indexes-to-store-in-days> } ] \
                  [ -z <process-cmd> <unprocess-cmd> ] \
                  [ -Z <built-in-compress-level> ] \
                  [ -s \"<dont-process-patterns>\" ] \
                  [ -X <exclude-list-file> ] [ -l <logfile> ] \
                  [ -i <startup-info-program> ] \
                  [ -b <init-program> ] [ -e <exit-program> ] \
                  [ -k <encryption-key-file> ] \
                  [ -f <filesystem-types> ] \
                  [ -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, processing is always turned off.
  Using -R forces processing 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 explicitly, then it is searched for in the
  .../lib-directory and if not found there the files
  /etc/buclient.conf, /etc/afbuclient.conf, /etc/afclient.conf and
  /etc/afbackup/client.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 processing 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)

   -f <fs-types>   A list of filesystem types, separated by whitespace
                     and/or commas. The type names can be prefixed
                     with a plus, what is identical with no prefix,
                     with a dash - or a slash / . No prefix or a plus
                     means, that only files in filesystems of the
                     given type are saved, no others. A minus means,
                     files in a filesystem of the named type are not
                     saved, nonetheless such filesystems are traversed
                     to search for filesystems of other types probably
                     mounted underneath. The slash means, that such
                     filesystems are not even entered or traversed. If
                     the - or + prefix is used, no space is allowed
                     between option -f and it's argument, e.g. -f-nfs

   -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 processing, .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           Process 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)

   -O <maxidxage>  The maximum age of the filename list files (== index
                     files) in days, that is stored. See also option
                     -N . A floating point number is allowed here

   -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 <noproc>     A list of filename patterns, that no processing 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. This flag can also be useful
                     e.g. to explicitly store the serverside
                     var-directory, that is crucial for restore and
                     should be saved seperately after all other backup
                     clients are done
 
   -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)

   {+-}x           Write CRC32 checksums for each file to tape (+x) or
                     don't do this (-x). This option is ignored, if
                     built-in compression is selected, cause then CRC32
                     checksumming is already performed

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

   -Z <level>     If built-in compression should be used, the level
                    can be supplied here. If commands to process and
                    unprocess are also supplied with option -z, then
                    data is first processed by the process command,
                    then by built-in 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:

   Option       Client configuration file parameter name

    +B -B       ProcessBackupedFiles

    -b          InitProgram

    -C          RootDirectory

    -D          DirsToSkip

    -E          UseCTime

    -e          ExitProgram

    -F          FilesToSkip

    -f          FilesystemTypes

    -h          BackupHosts

    -I          IndexFilePart

    -i          StartupInfoProgram

    -k          EncryptionKeyFile

    -l          LoggingFile

    +L -L       ProcessLogfiles

    -N          NumIndexesToStore (*_backup), NumIndexesToScan (afrestore)

    -O          DaysToStoreIndexes (*_backup), DaysToScanIndexes (afrestore)

    -P          BackupPorts

    -S          CartridgeSets

    -s          DoNotProcess

    -V          VarDirectory

    -W          ClientIdentifier

    -X          ExcludeListFile

    -x          WriteChecksums

    -z          ProcessCmd UnprocessCmd

    -Z          BuiltinCompressLevel



 $BASEDIR/client/bin/incr_backup

  Run an incremental backup. Usage: See full_backup above.
  Additional options:
                              [ -EH ] [ -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

   -E              Use not only the modification time comparing
                     the timestamps to select filesystem entries
                     for backup, but also the inode change
                     time (ctime)

   -H              If this flag is set, all backups with a lower level
                     since the last full backup are removed from the
                     indexes and the respective tapes freed, if there
                     is no other backup data on them. In differential
                     mode (-a) a previous differential backup is also
                     removed and the tapes freed, if possible

   -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/afrestore

  The restore utility. The Usage:

       afrestore [ -nlvmi ] [ -<past-backup-no> ] [ -C <root-directory> ] \
               [ -h <backuphosts> ] [ -P <backup-ports> ] \
               [ -c <configuration-file> ] [ -W <identity> ] \
               [ -A "<after-date>" ] [ -B "<before-date>" ] \
               [ -T <tapes> ] [ -I <indexfile-part> ] \
               [ -V <var-directory> ] [ -k <encryption-key-file> ] \
               [ -z <process-cmd> <unprocess-cmd> ] \
               [ -Z <built-in-compress-level> ] [ -F <format> ] \
               [ { -N <num-indexfiles> | -O <indexfile-age-days> } ] \
               [ -p ] <path-pattern> [ [ -p ] <path-patterns> [ ... ] ]
       afrestore -a [ -nlvm ] [ -<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 <process-cmd> <unprocess-cmd> ] \
               [ -Z <built-in-compress-level> ] [ -F <format> ]
       afrestore -{ef} [ -evm ] [ -C <root-directory> ] [ -h <backuphosts> ] \
               [ -P <backup-ports> ] [ -V <var-directory> ] \
               [ -z <process-cmd> <unprocess-cmd> ] \
               [ -Z <built-in-compress-level> ] \
               [ -k <encryption-key-file> ] [ -W <identity> ] \
               [ -c <configuration-file> ] < <startup-info-file>
       afrestore -E [ -Enlvm ] [ -C <root-directory> ] [ -h <backuphosts> ] \
       	       [ -P <backup-ports> ] [ -V <var-directory> ] \
       	       [ -z <process-cmd> <unprocess-cmd> ] \
               [ -Z <built-in-compress-level> ] \
       	       [ -k <encryption-key-file> ] [ -W <identity> ] \
       	       [ -c <configuration-file> ] \
       	       [ <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 flag -e can be supplied more than one time. In
  that case the emergency restore goes back to the beginning of
  the previous full backup, if the full backup is split into
  several parts (configuration parameter NumBackupParts) and
  the last part of the current full backup has not yes run. If
  the backup parts configuration has changed after the beginning
  of the previous full backup, this option should be considered,
  as it gives additional safety, that really everything will be
  restored. 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. Like with option -e, the -E flag can be given
  several times, what has the same meaning like with option -e
  (see above). If the client's hostname has changed or restore
  should be done on another host, the original client ID must be
  supplied with the -W 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 current 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 current 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 current 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 explicitly, then it is
  searched for in the .../lib-directory and if not found there the
  files /etc/buclient.conf, /etc/afbuclient.conf, /etc/afclient.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 will be 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            In combination with -l a format string for output.
                    Default is: only the full paths of the stored
                    files are printed, one per line. The format string
                    can also contain patterns representing other file
                    attributes present in the index file(s). Possible
                    patterns are:

                     %n   The filename with full path like default

                     %b   The basename of the file, without path

                     %O   The username of the file owner

                     %o   The user-ID of the file owner (integer)

                     %m   The modification time in seconds since epoch

                     %M   The modification time in readable format

                     %t   The starting time of the backup containing
                          the file in seconds since epoch

                     %T   Like %t, but in readable format

                     %h   The hostname of the backup server, to that
                          the file has been backuped

                     %p   The port number of the backup server, to that
                          the file has been backuped

                     %c   The cartridge number on the server, the saved
                          file can be found on

                     %f   The tape file number on cartridge %c, where
                          the saved file can be found

                     %%   A percent character

                    Notes:
                    * The usual C-like backslash sequences are allowed,
                      but special characters within the filenames are
                      still printed as escape sequences, e.g. \n
                    * A newline at the end must be given explicitly as
                      backslash n (\n), otherwise no new line will start
                    * Double quotes should be written as \" within the
                      argument enclosed in single quotes
                    * To see several versions of a saved filesystem entry
                      in the indexes the option -B or -A must be given,
                      maybe with a condition, that is always true, e.g.
                      -B 23:59, what means: before today, 23:59

    -f            Restore only the filename logfiles in an emergency
                    case

    -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 current 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 processing, .z is appended

    -i            Ignore case distinctions in the filename patterns

    -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

    -m            Do not overwrite existing files (merge)

    -N <numidxs>  The maximum number of index files, that are scanned
                    for matching filenames. With each full backup, a new
                    index file is created. If time restrictions are given
                    (options -A or -B), all existing index files are
                    read, what may take a long time, if many of them are
                    kept available (see clientside configuration option
                    NumIndexesToStore or option -N of full_backup). So
                    using this parameter the scanning can be restricted
                    to a certain number of files

    -O <maxidxag> The maximum age of index files, that are scanned for
                    matching filenames, in days. See option -N . The
                    given number of days may be a floating point value

    -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 current 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

    -T <tapes>    Restore and list only files from the given list of
                    tapes. Tapes can be specified using numbers, commas
                    and dashes, e.g. 3-5,8,1

    -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 process and unprocess. If
                    a command comprises of several words, it must be
                    put in quotes

    -Z <level>    If built-in compression should be used, the level
                    can be supplied here. If commands to process and
                    unprocess are also supplied with option -z, then
                    data is first processed by the process command,
                    then by built-in 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 (or use option -m).


 $BASEDIR/client/bin/afverify

  Run a verify of a previous backup. The usage:

     afverify [ -lav ] [ -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 <process-cmd> <unprocess-cmd> ] \
              [ -Z <built-in-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 current 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. Run afverify with
  option -l, optionally -a or -<prev-total-backup> to get a list
  of backups available for verify.

    -a            Together with -l list the available backups from
                    all indexes and not only the most recent one

    -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 current 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 processing, .z is appended

    -l            Don't actually verify, but print summary information
                    about available backups, that can be verified or
                    restored from, prefixed with the arguments, that
                    may be supplied as -<past-run-no>[.<past-backup-no>]

    -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 current 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 process and unprocess. If
                    a command comprises of several words, it must be
                    put in quotes

    -Z <level>    If built-in compression should be used, the level
                    can be supplied here. If commands to process and
                    unprocess are also supplied with option -z, then
                    data is first processed by the process command,
                    then by built-in 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> ] [ -T <tmpdir> ] \
                 [ -h <source-server> ] [ -P <source-serverport> ] \
                 [ -C <source-cartridge> ] [ -F <tape-filenumber> ] \
                 [ -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 current 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

   -F <tapefilenum>  If reading and writing should not start at the
                      beginning of the tape, but at the tape file with
                      the given number. This can avoid the overhead of
                      copying entire tapes, when only some tape files
                      have been appended

   -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/update_indexes

  clean indexes from erased tapes

    update_indexes [ -v ]  [ -c <configuration-file> ]
                   [ -h <backuphosts> ] [ -P <backup-ports> ]
                   [ -I <indexfile-part> ] [ -V <var-directory> ]
                   [ -k <encryption-key-file> ] [ -W <identity> ]
                   [ -z <process-cmd> <unprocess-cmd> ]
                   [ -Z <built-in-compress-level> ]

  This command asks all the servers, which tapes are considered
  precious for the client, it is run on. If the server will tell
  fewer tapes than the client has in mind, then the tapes, that
  the server omitted, have been erased on the server side. Now
  those entries will be removed from the client's indexes, who
  list the erased tapes as backup location.
  This command may be installed setuid root, so normal users can
  start it. As it performs just a defined update operation and
  nothing else, there should not be a security problem. It might
  be a good idea to run this command before some user restore
  program (e.g. xafrestore) is started, so only those entries
  are listed to the user, that really exist on backup media and
  can be restored. When started by a normal user, all arguments
  will be ignored and only the configuration file is evaluated.

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

   -h <hostnames>    Use the given list of hosts as backup servers. 
                      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 processing, .z is appended

   -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

   -P <portnos>      The list of port numbers for the backup servers
                      either configured in the parameter file or supplied
                      with the -h option. 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 option, tell more about what is going on

   -W <id>           Identify as <id> to the server. This is needed
                      by the server to tell the client the correct
                      information about tapes, that are considered
                      crucial for this client for restore
 
   -z <z> <uz>       The commands to use for process and unprocess. If
                      a command comprises of several words, it must be
                      put in quotes

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


 $BASEDIR/client/bin/afclient

  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

      afclient -cxtd [ -[RraunOvgiIqQZwbjGK] ] \
               [ -D <destination> ] \
               [ -M <server-message> ] \
               [ -h <backup-server> ] \
               [ -z <zipcmd> <unzipcmd> ] \
               [ -T <to-extract-file/tmpdir-for-copytape> ] \
               [ -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-process-filepattern> [ -s ... ] ] \
               [ -H <header> ] \
               [ -V <statistics-report-file> ] \
               [ -A <after-time-seconds> ] \
               [ -B <before-time-seconds> ] \
               [ -W <identity> ] \
               [ <files> <directories> ... ]

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

      afclient -\?  (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 current 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
         current 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. Several
         messages can be put into the string. They must be separated
         by a real newline character or the usual C-like \n .
         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 explicitly 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

        DeleteClient: <client-identifier>
                   The tapes, that are marked as reserved for a
                   client to recover all the data in his indexes,
                   are freed. That is, the appropriate line is
                   removed from the server's precious_tapes file

  -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 processing is not applied to
          the file contents for safety reasons. With this prefix
          processing 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. If a - is supplied (no space may
                  follow -H i.e. -H-) the information is read from
                  the first line of stdin. Backslash sequences of
                  C-like style are replaced

   -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           when packing, do not keep the access time of the
                  file. By default after packing a filesystem entry
                  it's previous atime is restored

   -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>
                  In combination with -X: precede each line of
                  output received from the remotely started program
                  with the identifier of the remote host and a
                  colon, e. g.:  darkstar: Full backup finished.

   -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. If -r
                  is given more then 1 time, also let symlinks
                  originally pointing to absolute paths now point
                  to paths relative to the directory, where the
                  symlink will be created

   -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 processing on files matching the
                  given filename pattern. This parameter may
                  appear several times

   -T <file/dir> 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. In combination with
                  -D: the tape files to be copied are temporarily
                  stored in the given directory instead of the
                  default directory /tmp
  
   -u           while extracting: remove existing files with the
                  same name as found in the archive. Otherwise
                  no existing files are overwritten
  
   -U           for each packed file creating a backup in verbose
                  mode: printout the modification time of the file
                  in seconds since 1970/1/1 0:00 at the beginning
                  of the line prefixed with a tilde ~ eventually
                  behind cartridge number, file number and owner

   -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. If -v is the only given flag:
                  print out software name and version
  
   -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 process
                  files, <uz> for the corresponding unprocess.
                  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
                  built-in compression is desired, the command for
                  processing 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 built-in
                  compression is applied. An empty string has to be
                  supplied for <uz> (or any other dummy is ok), if
                  only built-in compression is desired.
                  Examples for <z>:
                   gzip       (run external command gzip),
                   "gzip -2"  (the same with an argument),
                   ". 8"      (only built-in compression level 8),
                   ". 3 __descrpt -k /my/key" (run command __descrpt
                              and apply built-in compression level 3)
  
   -Z           while printing out the contents: check those files
                  in the archive that are processed for integrity.
                  While creating an archive: write a CRC32 checksum
                  for each file, file contents or command output to
                  the backup stream
  
  
   -?           to printout this text

  The -w option reports one or more of the following states,
  separated 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 currently 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).

  The destination tape for the duplicate operation (-D) can be given
  in two ways: either with the options -h, -p, -C and -k following
  the -D immediately without space and enclosed in quotes, so that
  they appear as an own argument list in one real argument, e.g.:
    -D' -C 5 -h targethost -p targetport'
  (double quotes are of course also possible ...).
  The second format is as follows:
    [<targetcart>][@<targethost>][%targetport>][:<targetcryptkeyfile>]
  At least one of the specifiers must be present. Examples:
   5@otherhost  5%2990:/keyfile/for/target/server @otherhost%2970
  If one of the specifiers is omitted, it is assumed identical with
  the copy source specified in the normal options -h, -p, -C and -k.
  Copying a tape to itself is prevented.


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 separated 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 (separated 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 process- and unprocess commands of the client side.


 __z

  Program, that performs the same (un)compression like the built-in
  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


 __numset

  This program deals with sets of numbers and can either remove
  elements of one set in another set of merge two sets. Synopsis:

      __numset <set-1-specifier> {+|-|in} <set-2-specifier>
      __numset # <set-specifier>

  If the second argument is a +, then the two sets are merged. If
  the second argument is -, the elements in set2 are removed from
  set1. If the second argument is the word "in", then it is tested,
  whether elements of set 1 are also contained in set 2. The number
  of common elements will be the result in that case. If the first
  argument is the character # (must be escaped in shell scripts,
  e.g. write '#'), the result is the number of elements in the set
  given as second argument. Number set specifiers should not contain
  whitespace and may consist of numbers, commas and dashes. Examples
  for number set specifiers:

   3-9  4,5,9  1-3,6,9-13

  Examples how to use __numset and the results:

   prompt# __numset 1-3,5-9,14 + 10-12
   1-3,5-12,14
   prompt# __numset 1-3,5-9,14 - 5-13
   1-3,14
   prompt# __numset 3 - ""
   3
   prompt# __numset "" - 4,6,8

   prompt# __numset 3 - 3-5

   prompt# __numset # 4-9
   6
   prompt# __numset 3-6,9-12 in 10-20
   3
   prompt#

  Notes: Any argument or result might be an empty string (i.e. set)
         The numbers in the sets need not to be sorted