cart_ctl.8.in

一套客户/服务器模式的备份系统代码,跨平台,支持linux,AIX, IRIX, FreeBSD, Digital Unix (OSF1), Solaris and HP-UX.

.TH CART_CTL 8 "2000 October 9" "Debian Project"
.SH NAME
cart_ctl \- perform operations on cartridges, e.g. moves
.SH SYNOPSIS
.B cart_ctl
[ -ilmtefFr ] [ -P [ <location> ] ] \
[ -s <serverconfigfile> ] \
[ -c <changerconfigfile> ] \
[ -d <changerdevice> ] [ -C <cartridges> ] \
[ -S [ <slots> ] ] [ -D [ <drives> ] ] \
[ -L [ <loadports> ] ] [ -b <blocksize> ] \
[ -n <comment> ]
.SH 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.
.PP
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'.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.TP
.B -b
override the blocksize setting in the server
configuration file (discouraged)
.TP
.B -C <cartridges>
specify the cartridge numbers to operate on
.TP
.B -c <config-file>
use the given file to configure the media changer
driving commands
.TP
.B -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
.TP
.B -d <device>
operate on the given media changer device, don't
use the settings in the configuration file
.TP
.B -F
force operations, ignore active locks on streamer
and changer devices, if applicable
.TP
.B -f
force labeling operations without further asking
.TP
.B -i
inventory the cartridges in the slots specified
with -S
.TP
.B -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)
.TP
.B -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
.TP
.B -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
.TP
.B -n <comment>
use the given comment when labeling tapes with -t
.TP
.B -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
.TP
.B -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
.TP
.B -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
.TP
.B -s <serverconfigfile>
Use the given file as server configuration file, not
the default one
.TP
.B -t
Write labels (`tags') to the cartridges in the slots
specified with -S
.SH 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
.SH FILES
.IP @serverlibdir@/@serverconf@
Server configuration file
.IP @serverlibdir@/changer.conf
The media changer driver configuration.
.br
A configuration file to specify the media changer commands must
be given in the server configuration with parameter
 Changer-Configuration-File
.br
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:
.br
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
.br
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.
.br
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).
.IP @servervardir@
Some internal state information of the server.
.IP @servervardir@/cartridge_locations
The ASCII file containing the cartridge locations database
.SH 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) 
.SH AUTHOR
.B afbackup 
was written by Albert Fluegel ([e-mail])