Provided by: afbackup_3.3.8.1final-1_i386 bug

NAME

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

SYNOPSIS

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

DESCRIPTION

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

       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.

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

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

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

       -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

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

       -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

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

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

NOTES

       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

       /usr/server/lib/server.conf
              Server configuration file

       /usr/server/lib/changer.conf
              The media changer driver configuration.
              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, stc, chio and
              mover/sch),    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).

       /var/lib/afbackup
              Some internal state information of the server.

       /var/lib/afbackup/cartridge_locations
              The ASCII file containing the cartridge locations database

SEE ALSO

       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)

AUTHOR

       afbackup was written by Albert Fluegel (af@muc.de)