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


Programs on 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. Usage:

      label_tape [ -f <config-file> ] <tape-label>

  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. 


 $BASEDIR/server/bin/server [ <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.


Programs on the client side
---------------------------

 $BASEDIR/client/bin/full_backup

  Run a full backup. The usage:

      full_backup [ -S <cartset> ] [ -d ] [ -c <config-file> ]

  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. It writes
  a log into the specified file, that usually resides on a local
  filesystem, but can also be NFS-mounted. 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.

   -c <configfile> A different configuration file to use

   -d              Detach from the terminal when starting

   -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/client/bin/incr_backup

  Run an incremental backup. The usage:

      incr_backup [ -S <cartset> ] [ -d ] [ -c <config-file> ]

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

   -c <configfile> A different configuration file to use

   -d              Detach from the terminal when starting

   -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/client/bin/restore

  The restore utility. The Usage:

       restore  [ -nl ] [ -<past-backup-no> ] [ -R <root-directory> ] \
                [ -h <backuphost> ] [ -c <configuration-file> ] \
                [ -A "<after-date>" ] [ -B "<before-date>" ] \
		[ -p ] <path-pattern> [ [ -p ] <path-patterns> [ ... ] ]

       restore  -a [ -<past-backup-no> ] [ -R <root-directory> ] \
                [ -h <backuphost> ] [ -c <configuration-file> ]

       restore  -{ef}  [ -R <root-directory> ] [ -h <backuphost> ] \
                [ -c <configuration-file> ] < <startup-information-file>

  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). 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

    -n   Do not restore anything, just printout a message,
         how many files and/or directories fit the supplied
         path-part(s)

    -l   Do not restore anything, just list the names of
         the files and/or directories, that fit the supplied
         path-part(s)

    -A   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   Restore files modified before the given date. See
         -A for the valid date formats

    -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

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

    -h   restore from the given backuphost instead of the one
         specified in the client side configuration file

    -c   Use the given file for configuration information

  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 [ -c <configuration-file> ] [ -<past-backup-specifier> ]

  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 in-
  creased 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 pre-
  vious 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   Use the given file for configuration information

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

  The main program of the client side. Here's the usage, that
  can be printed out entering:  client -usage

       client -cxtd [ -RraunOvgiqQZb ]
               [ -h <backup-server> ]
               [ -z <zipcmd> <unzipcmd> ]
               [ -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 ... ] ]
               [ -V <statistics-report-file> ]
               [ <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
  
  -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, filenames have to be seperated by whitespace. If a name
  is containing whitespace, it has to be enclosed in double
  quotes ("). If a name contains double quotes or backslashes,
  each has to be preceded by a backslash (so backslashes become
  double backslashes).
  
  
  More options in alphabetical order:
  
   -a           in combination with -x: extract all files and
                  directories in the archive
  
   -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 <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

   -k <file>    use the contents of the given file as encryption
                  key for authenticating to the server
  
   -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 seperated 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
  
   -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
  
   -Z           while printing out the contents: check those files
                  in the archive that are compressed for integrity
  
  
   -?           to printout this text


 $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> ]

  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.

