Man Linux: Main Page and Category List

NAME

       afclient - controls the client functions of the afbackup package

SYNOPSIS

       afclient   -cxtd   [-[RraunlOUvgIiqQZwbjGK]]   [-D  <destination>]  [-M
       <message>]  [-m  <message-poll-interval>]  [-h   <backup-server>]   [-z
       <proccmd>  <unproccmd>]  [-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 -?
       afclient -usage

       The  first form is similar to tar (1), 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:

              afclient -X full_backup -h <some-host>
              afclient -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 configuration file under "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.
       One of the following flags has always 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: <client-id> <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. The list  is
                     assigned  to the client with the given client identifier,
                     regardless of an id suppied with option -W .  These tapes
                     will not be overwritten until it is explicitly permitted.
                     This message is  sent  automatically  by  full_backup  or
                     incr_backup 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,  -d,  -X,  -D,  -I and -m 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.

       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     don’t enter buffering mode

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

       -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.  If given twice, the current directory is assumed to be
              the relative root directory for the symbolic  link  target.   If
              given  three times, the root directory of the current process is
              used as the relative root directory of the symbolic link targets

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

       -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. If -v is the
              only given flag: print out software name and version

       -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

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  applies,  when
       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

STATUS REPORTS

       The  -w  option  reports  one 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).

DESTINATION

       The  destination  tape  for the duplicate operation 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.

FILES

       /etc/afbackup/client.conf
              Client configuration file

       /var/log/afbackup
              The directory for logging the client backups

       /var/lib/afbackup
              Some internal state information of the client backups.

SEE ALSO

       afclientconfig(8), xafclientconfig(8), full_backup(8),  incr_backup(8),
       afverify(8),  afrestore(8),  xafrestore(8),  afserver(8), afmserver(8),
       copy_tape(8),  afclient.conf(8),  afserver.conf(8),  update_indexes(8),
       tar(1)

AUTHOR

       afbackup  was  written  by Albert Fluegel (af@muc.de). This manpage was
       extracted  from  the  text  docs  by  Christian  Meder  (meder@isr.uni-
       stuttgart.de).