man cart_ctl (8): 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.

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

AUTHOR

afbackup was written by Albert Fluegel ([email protected])