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

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

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

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

/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

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)

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