Man Linux: Main Page and Category List


       cart_ctl - perform operations on cartridges, e.g. moves


       cart_ctl [ -ilmtefFrN ] [ -P [ <location> ] ] [ -s <serverconfigfile> ]
       [ -c <changerconfigfile> ] [ -d <changerdevice> ] [ -C <cartridges> ] [
       -S  [  <slots>  ]  ]  [  -D  [ <drives> ] ] [ -L [ <loadports> ] ] [ -b
       <blocksize> ] [ -a [ <cartridge-attribute-specs> ] ] [ -n <comment> ] [
       <cartridge-descriptions> ... ]


       This  command  performs  operations  on  cartridges  and  maintains the
       cartridge location, label, attributes and description  databases.   One
       major  functionality is to move cartridges around, serving as a wrapper
       for those commands, that are actually  fulfilling  this  functionality.
       cart_ctl  adds  the  maintenance  of  other  data  in  the  context  of
       cartridges and unifies the command  interface.  E.g.  the  counting  of
       slots,  loadports  and  drives  always  starts  with  1  here.  Several
       cartridges, slots, drives and loadports 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 a different
       location. The location must be  specified  using  the  options  -S  for
       slots,  -D  for  drives,  -L  for  loadports  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 no slots are given  with  option  -S,
       free  slots are searched and the cartridge(s) are moved 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  simply  -D  is
       mostly  suitable.  If  there  is  a tape in the drive, it will first be
       unloaded to a free slot. If slots or loadports  are  given  as  targets
       that appear to be occupied, 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 assigned to all of them. When
       moving to a loadport is possible, moves to the outside  will  first  be
       targeted to a loadport 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  loadports,  the  maintainer  is  asked to put the cartridge into a
       loadport 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 -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.


       Option -P can be used, if a location of a tape changes, but  it  should
       not  be  moved  by  any  robot.  So -P 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, so please see the previous section
       for details.


       Option -l displays  information  about  cartridges.  Without  modifying
       options,  the  locations  of  cartridges  are  listed.  When -S is also
       supplied, the contents of the slots are listed (if no slots  given:  of
       all  slots).  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  loadports  like -S for slots. The options -a, -r, -N and -i modify
       the operation  mode  of  -l  in  terms  of  the  information,  that  is
       displayed.  All listings can be limited to certain cartridges using the
       option -C like explained above. Some listings can be limited  to  slots
       giving  -S,  to  loadports  using  -L  or  to  drives  passing  -D,  if

       With -a some attributes of cartridges are displayed. They  include  the
       quantity of data on the tapes, indicates, whether they are full, set to
       read-only, how often they have become full  and  when  they  have  been
       written  the  last  time.  Futhermore  it shows, whether a cartridge is
       permitted to be overwritten completely. This is true, if no client  has
       reserved  the  cartridge for restore. This information is stored in the
       file "precious_tapes" in the server’s var-directory.

       With -a some attributes of cartridges are displayed. They  include  the
       quantity of data on the tapes, indicates, whether they are full, set to
       read-only, how often they have become full  and  when  they  have  been
       written  the  last  time.  Futhermore  it shows, whether a cartridge is
       permitted to be overwritten completely. This is true, if no client  has
       reserved  the  cartridge for restore. This information is stored in the
       file "precious_tapes" in the server’s var-directory.

       Together with -i the hardware inventory is run  (without  updating  the
       stored  information about barcodes or locations) and shows a listing of
       these informations including the optionally assigned  description  (see
       option  -N ). If option -N is given additionally, the cartridge numbers
       resulting from the stored assignments are listed, too. This only  gives
       the proper result, if the status of the hardware (i.e. the locations of
       cartridges in the robot) is  in  sync  with  the  data  stored  by  the
       afbackup  server. Synchronizations can be performed using the option -i
       , see below. The listings performed with -l (except together with -i  -
       hardware  inventory)  can  be  run  by  normal  users  as  well, if the
       respective files in the server’s var directory are  readable.  If  some
       required  files cannot be read, the program issues warnings indicating,
       what file lacks read permission.


       Option -i makes an inventory of the slots specified  with  -S.  If  the
       cartridges  in  the  slots have barcode labels known to the server side
       (can be listed with -lN ), the cartridge location assignment is updated
       without  reading  the  label  from the media (except, when option -F is
       given, see below). If the barcode is unknown or  no  barcode  could  be
       figured  out,  the  label  written to the cartridge media must be read.
       This can be enforced overriding the knowledge about barcode - cartridge
       assignments  using  option  -F . That is, the cartridges in these slots
       are loaded to drive, the labels are read from media 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.  If  a  barcode  has been recognized, it is assigned to the
       cartridge.  That  is,  a  respective  line  is  written  to  the   file
       "cartridge_names"  in  the  var-directory  of the server and can now be
       listed using options -lN . Together with  -N  the  funcionality  of  -i
       changes notably. In this mode not the location data is updated, but the
       barcode information. Using -iN the user tells  the  program,  that  the
       location  information  is  correct  and  the  barcode  information  has
       changed. Thus the program will look up the  barcodes  by  querying  the
       hardware,  check with the location data (listable with option -l alone)
       and assigns the barcodes according to these informations. This ( -iN  )
       has  to  be done, if the barcodes on the cartriges have been changed or
       new cartridges with new barcodes are to be introduced, that the  server
       has  never  seen  yet.  Usually before running this program with -iN it
       must be run with -P -S ... -C ... telling the  server,  what  cartriges
       have  been  positioned  in  what  place,  otherwise  -iN  cannot obtain
       sufficient information to make the assignments.


       Option -t can be used to write a media label to 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, the program tries to figure them out using
       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.  If  option  -r  is  not given, the user will be asked, whether the
       labeled cartridges should  be  marked  overwritable.  To  achieve  this
       without  further  asking,  the  option  -r  must  be  given. If barcode
       information could be read from the hardware,  it  is  assigned  to  the
       cartridge and can be displayed with options -lN .


       Using  option  -N  freetext comments or descriptions can be assigned to
       cartridges. They can be displayed using  the  options  -lN  .   Several
       descriptions  can be assigned passing several cartridge numbers with -C
       . The descriptions are  specified  in  additional  arguments,  one  per
       cartridge.  Descriptions  may contain whitespace and must then be given
       enclosed in quotes as usual in a shell interpreted context. When  there
       are  more  cartridges  specified  than  descriptions,  the  last  given
       description is assigned to all the remaining cartridges. The  token  %C
       can be used within descriptions and will be replaced with the number of
       the cartridge. E.g. try:
        cart_ctl -N -C 1-3 "Tape %C"


       With option -a certain attribute values can be set for cartridges.  The
       format is:


       <cartridge-set>  has  the  same format like with option -C (see above).
       <attribute-name> is one of:

       r      read-only. Cartridges set to read-only are not subject of  write
              operations any more

       o      overwrite. When this flag is set to yes, the entire cartridge is
              allowed to be overwritten. That  means,  no  client  request  to
              protect this cartridge from overwriting is in effect any more

       f      full-counter. A counter is maintained reflecting, how often each
              cartridge has became full during it’s lifetime

       The attributes r  and  o  can  be  set  simply  specifying  it  without
       assignment and unset prefixing it with a bang ! Alternatively the value
       yes or no can be assigned. Example:

        cart_ctl -a 4-5:r,6:!o,8:f=0

       This means: Set cartridges 4 and 5 to read-only,  protect  cartridge  6
       from overwriting and assign a full-counter of 0 to cartridge 8.


       *      To list the current settings, run this program with options -la

       *      In csh and friends the bang must be prefixed with a backslash to
              protect it from shell-history interpretation.

       *      4-5:r can be written as 4-5:r=yes

       *      6:!o can be written as 6:o=no

       *      Setting a cartridge to overwrite removes all  reservations  from
              clients (see file precious_tapes in the server’s var-directory)

       *      Setting  a  cartridge  to o=no adds a line to the precious_tapes
              file, that is not specific to any client and thus has the effect
              of  a  general  write  protection,  what  is quite the same like
              setting it to read-only.


       For detailed usage and functionality see above

       -a <attribute-assignment>
              change  the  values  of  some  settable  cartridge   attributes.
              Together with -l (see there): list cartridge attributes

       -b <blocksize>
              override  the blocksize setting in the server configuration file

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

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

       -D <drives>
              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 <device>
              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.  Together with -i :  Do  read  the  tape
              label  from  media  though  the  cartridge  is possibly known by

       -f     force labeling operations without further asking.

       -i     inventory the cartridges  in  the  slots  specified  with  -S  .
              Together  with  -l  (see  there): List the cartridges as queried
              from the hardware

       -l     Without other options: list the  locations  of  cartridges.   In
              combination  with  -l  several  other options lose their meaning
              while selecting special list modes:

              -a     list some of the stored attributes of cartridges

              -i     list the information obtainable from  the  hardware  e.g.
                     barcodes, cartridge locations, if applicable

              -N     list  the  stored  barcode  labels  of the cartridges (if
                     applicable) and  optionally  assigned  freetext  comments
                     (see option -N )

              -r     list   the   cartridges   reserved  i.e.  protected  from
                     overwriting by clients and by which clients

       -L <loadports>
              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 loadports, -D for drives or -P for somewhere else

       -N <description> [ <descriptions...> ]
              set freetext descriptions for cartridges given with -C .  %C  is
              replaced  with  the  cartridge’s  number.  Together with -l (see
              there): list barcode labels and descriptions

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

       -r     Together with option -t: delete the labeled cartridges from  the
              cartridge  database  without  further  asking,  so  they will no
              longer be protected from overwriting.   Together  with  -l  (see
              there):  list  reservations  of  cartridges  i.e.  requests from
              clients to protect from overwriting

       -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 <serverconfigfile>
              Use the given file as server configuration file, not the default

       -t     Write labels (‘tags’) to the cartridges in the  slots  specified
              with -S


       A  configuration  file  to  specify  the media changer commands must be
       given in the server configuration with parameter

       This file must name the commands, that actually operate e.g.  move  the
       cartridges  in  a  changer.  A  maximum of nine entries can be given to
       specify, how to move a cartridge from or  to  a  slot,  a  drive  or  a
       loadport  (3  *  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.

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

       If barcode label  support  is  desired,  some  more  commands  must  be
       configured.  The  maintainer  has  the  choice whether to configure one
       command for all 3 types of locations in  a  changer  (slot,  drive  and
       loadport),  or  whether to configure 3 commands. If only one command is
       configured, it must  be  given  as  List-Tape-Labels-Command  and  must
       produce  a minimum of 3 fields of output, separated by whitespace.  The
       first column must be one of the words  "slot",  "drive"  or  "loadport"
       (may  be  upper  or  lowercase),  the second field must be the instance
       number starting with 1, the rest of the line must contain the text form
       of  the  barcode  label.  If three commands are wished to be configured
       separately, their  names  are  List-Tapelabels-in-Slots-Command,  List-
       Tapelabels-in-Drives-Command  and List-Tapelabels-in-Loadports-Command.
       Their output must be similar like with the single command, but omitting
       the  first  field containing the location type. Configuring one command
       for all usually has the advantage of faster execution,  but  is  a  bit
       harder to code.

       For  the  most  common  changer  driving  commands  (mtx, stc, chio and
       mover/sch), appropriate files are included into the  distribution  (but
       may  be incomplete due to lack of experience). They can be used without
       any modifcation, just comment out the commands, your hardware does  not
       support (e.g. moving from slot to slot).


       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


              Server configuration file

              The  media changer driver configuration, see above under CHANGER

              Some internal state information of the server.

              The ASCII file containing the cartridge locations database

              The ASCII file containing the number of bytes and files  on  the
              tapes,  the  flag,  whether  a  tape is full and the most recent
              writing time.

              The file containing the list of the numbers of the tapes set  to
              read-only mode

              The  ASCII file containing the information, what cartridges have
              been requested to be protected from overwriting by clients

              ASCII file containing the  determined  barcode  labels  and  the
              freetext comments assigned to the cartridges

              ASCII  file  containing  information,  how often a cartridge has
              become full during it’s lifetime


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


       afbackup was written by Albert Fluegel (