Chapter 8. Amanda Tape Changer Support Prev Part II. About Tapes and Changers Next ------------------------------------------------------------------------------- Chapter 8. Amanda Tape Changer Support James da Silva Original text AMANDA Core Team Stefan G. Weichinger XML-conversion;Updates AMANDA Core Team Table of Contents Introduction Specifying_a_tape_changer_in_amanda.conf Device-specific_tapechanger_script Slot_names_and_the_"current"_slot Operator_interface How_amdump_interacts_with_the_tape_changer Builtin_tape-changers chg-multi_(formerly_chg-generic) chg-manual_(formerly_no-changer) chg-mtx_(formerly_hp-changer) chg-zd-mtx chg-scsi-chio_(formerly_seagate-changer,_then_chg-chio) chg-scsi_(new_interface,_try_to_drive_a_robot_with_direct_scsi commands) chg-chio chg-chs chg-rth chg-juke chg-rait chg-disk chg-iomega chg-null Note Refer to http://www.amanda.org/docs/tapechangers.html for the current version of this document. Introduction This document outlines the tape changer support design of Amanda 2.2 and beyond. It defines a small interface for changer software to follow so that Amanda can remain device-independent but still support the widest range of tape software and hardware possible. The interface is a bit simplistic and has only had complications added when there is a body of field experience. Specifying a tape changer in amanda.conf All device-specifics are hidden by a glue program that the rest of Amanda calls to interact with the tape changer. The name of this changer program is given by the "tpchanger" variable in the file amanda.conf. Example entry: tpchanger "chg-multi" # use multi-unit tape changer emulator The tapedev parameter is ignored if a tpchanger program is specified, unless the changer program itself reads tapedev from amanda.conf. The chg-multi changer doesn't, as it reads all its configuration arguments from its own configuration file, specified as changerfile. If the tpchanger program does not begin with a '/', Amanda expects it to reside in libexecdir, and possibly have the version suffix appended depending on how Amanda was configured. Two other amanda.conf parameters are available for changer use, however their definition is left entirely up to the changer script itself. They are changerfile and changerdev. Typically changerfile will point to the configuration file specific to the changer, or be a base name of several related changer files. The changerdev variable may point to the /dev entry used to access the changer device. See the documentation with the specific changer you're interested in to see exaclty how these variables are used (if at all). Device-specific tapechanger script The tape changer script/program is always from the directory with amanda.conf. It is never passed the configuration name it is running on behalf of, but since amgetconf works without a name from the current directory, that should be sufficient. The script/program must support the following commands: * -slot If changer is loaded, unloads the current slot (if different than "slot- specifier") and puts that tape away, then loads the requested slot. See the next section for the list of valid slot requests. Outputs to stdout the slot name and name of the device file to access the tape on success, or a slot name and error text. Returns 0 on success. Returns 1 on positioning error (eg at bottom of gravity stacker or slot empty). Returns 2 any other fatal error. The slot name may be invalid, but must be present. Error message goes to stdout in place of device name. Examples: % chg-multi -slot 0 0 /dev/nrst8 # exitcode returned is 0 % chg-multi -slot 1 1 slot 1 is empty # exitcode returned is 1 % chg-multi -slot bogus-slot no slot `bogus-slot' # exitcode returned is 2 * -info Outputs to stdout three or more fields: The current slot string (required) The number of slots (required) Flag indicating whether the changer can go backwards (0 if it can't, 1 if it can). (required) Flag indicating whether the changer is searchable (optional). Shows whether the changer supports the -search and -label commands and is able to load a tape given only the Amanda label string (0 or omitted if it can't, 1 if it can). (optional) Examples: % chg-multi -info 0 10 1 # exitcode returned is 0 % chg-zd-mtx -info 0 10 1 1 * -reset Resets the changer to known state and loads the first slot. Output and error handling are the same as " -slot first" In the case of a gravity stacker that must be reset by hand, this could be run (via " amtape reset") to inform the software the stacker is positioned back at the top. Examples: % chg-multi -reset 0 /dev/nrst8 # exitcode returned is 0 % chg-multi -reset 0 slot 0 is empty # exitcode returned is 1 % chg-multi -reset 0 tape-changer not responding # exitcode returned is 2 * -eject Unloads the current slot (if loaded) and puts that tape away. Output and error handling are the same as the -slot command. Note that a tape may or may not be loaded when this command completes, depending on the hardware. Examples: % chg-multi -eject 0 /dev/nrst8 # exitcode returned is 0 % chg-multi -eject 0 drive was not loaded # exitcode returned is 1 The tape changer program MAY support the following commands: * -search Loads an Amanda tape by name (labelstr). Output and error handling are the same as the -slot command. taper, amcheck and amtape will use this command if the changer reports it is searchable. Example: % chg-zd-mtx -search DailySet005 5 /dev/nrst8 # exitcode returned is 0 - -label Associates the Amanda label with the barcode of the currently loaded (in the tape drive) tape. Outputs to stdout the current slot and tape device. amlabel will use this command if your changer is searchable to build up the barcode database. Example: % chg-zd-mtx -label DailySet006 6 /dev/nrst8 # exitcode returned is 0 For all the commands: An exit code of 0 implies that the operation was completely successful, and the output may be parsed by the Amanda code as described above. For non-zero exit codes, the first field is still the slot name, but the actual error messages are not fixed. They are just displayed and/or logged as-is by the calling Amanda program. An exit code of 1 implies the operation failed in a benign way, for example an empty slot or an attempt to go backwards in a gravity stacker. The calling Amanda program will print the error message if appropriate and continue, perhaps requesting a different slot be loaded. Any other exit code is considered fatal and will cause Amanda to stop attempting to talk to the tape changer. Slot names and the "current" slot Some tape changers, such as carousels and gravity stackers, have a hardware notion of current position. Others have no current position when no tape is loaded: all tapes are in their slots and the changer arm is docked away from the slots. Nevertheless, Amanda requires tape-changer scripts to maintain the notion of a "current" position. This is for performance reasons: as tapes tend to be loaded into the rack in order, and Amanda uses them in order, the next tape to use can be found much quicker if the position of the current one is remembered. As an example, the chg-multi script maintains the current position in a chg- multi.state file (or any other file specified in a `statefile' line in the changer configuration file). Amanda does not care how slots are available or how they are named. They could be numbered 0 to N-1, numbered 1 to N, or even designated by letter, A .. Z. The only requirement is that the names do not contain whitespace and that the names "current", "next", "prev", "first", "last" and "advance" retain their meaning as follows: current The position of the last loaded tape, as described above next The position after current, wrapping from the last slot to the first. prev The position before current, wrapping from the first slot to the last. first The first slot in the tape rack. last The last slot in the tape rack. advance The same as "next" except the next tape may not be loaded if the changer supports advancing to the next slot without putting that tape in the drive. The current position must be updated even if there is a positioning error (such as "empty slot"). This allows amanda to step through the entire tape rack by issuing successive "slot next" positioning commands. Operator interface The amtape program is the main operator interface to Amanda's tape changer support. The commands supported include: amtape slot Load the tape from the specified slot into the drive amtape eject Send an eject command to the tape-changer. Effect is changer specific. amtape reset Send a reset command to the tape-changer. Effect is changer specific. amtape show Go through the entire tape rack, showing the labels of all amanda tapes encountered. amtape label