NAME
cart_ctl - perform operations on cartridges, e.g. moves
SYNOPSIS
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> ... ]
DESCRIPTION
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.
MOVING CARTRIDGES
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.
PLACING CARTRIDGES
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.
LISTING CARTRIDGE INFORMATION
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
applicable.
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.
TAKING INVENTORY OF CARTRIDGES
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.
LABELING CARTRIDGES
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 .
ASSIGNING DESCRIPTIONS
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"
SETTING ATTRIBUTE VALUES
With option -a certain attribute values can be set for cartridges. The
format is:
<cartridge-set>:[!]<attribute-name>[=<attribute-value>][,...]
<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.
Notes:
* 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.
OPTIONS OVERVIEW
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
(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. Together with -i : Do read the tape
label from media though the cartridge is possibly known by
barcode
-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
one
-t Write labels (‘tags’) to the cartridges in the slots specified
with -S
CHANGER CONFIGURATION FILE
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 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.
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 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).
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, see above under CHANGER
CONFIGURATION FILE
/var/lib/afbackup
Some internal state information of the server.
/var/lib/afbackup/cartridge_locations
The ASCII file containing the cartridge locations database
/var/lib/afbackup/bytes_on_tape
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.
/var/lib/afbackup/readonly_tapes
The file containing the list of the numbers of the tapes set to
read-only mode
/var/lib/afbackup/precious_tapes
The ASCII file containing the information, what cartridges have
been requested to be protected from overwriting by clients
/var/lib/afbackup/cartridge_names
ASCII file containing the determined barcode labels and the
freetext comments assigned to the cartridges
/var/lib/afbackup/tape_uses
ASCII file containing information, how often a cartridge has
become full during it’s lifetime
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)