cart_ctl

CART_CTL(8)                 System Manager's Manual                CART_CTL(8)



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)



Debian Project                  2000 October 9                     CART_CTL(8)