Changer API (1.0)

This is a developer-level description of the current Changer API. It is intended for authors of changer scripts.

Model

The changer script is treated as a source of device names, used to access volumes stored in numbered slots. The scripts assume that all devices are unused when they are invoked; that is, Amanda never invokes a changer script while it is still using a device. Thus, a script may operate with a single "drive", into which it "inserts" volumes on request. For a typical tape robot, this is the natural mode. Other changers (e.g., chg-disk) emulate this behavior.

Invocation

The tape changer script/program is always run from the config directory (the one containing amanda.conf(5)). It is never passed the configuration name it is running on behalf of, but since amgetconf(8) works without a name from the current directory, that is minimally sufficient. Note that changer scripts do not have access to command-line config overwrites (e.g., -o tapedev=/dev/nst3).

Input to a script comes on its command line. The output is a line written to stdout and an exit code.

In general, exit codes are as follows:

0

the operation was completely successful, and the output will be parsed as described for the command

1

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.

2

the operation produced a fatal error, and Amanda will no longer access the changer device.

The line written standard output is a "new" slot name followed by a space and an arbitrary string, e.g.,

13 slot 13 is bad luck

On a fatal error, the slot is often a dummy string such as <none>.

Note that the word "line" above refers to all output from the changer script, regardless of newline characters. That is, multiline responses are completely acceptable.

Commands

The script/program must support the following commands:

-slot

<tpchanger> -slot <slot-specifier>

If the changer is loaded, unload the current volume and load the volume in the requested slot. See Slot Specifiers, below, for the list of valid slot requests.

Output to stdout is the slot name and the name of the device file to access the tape on success (exit code 0 or 1), or a slot name and error text (exit code 2).

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
<none> no slot `bogus-slot'	# exitcode returned is 2

-info

<tpchanger> -info

Outputs to stdout three or more fields:

• The current slot string (required)
• The number of slots (required; -1 if this value is unavailable)
• Flag indicating whether the changer can go backward (0 if it can't, 1 if it can). (required)
• Flag indicating whether the changer is searchable (optional)

The final field 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).

Examples:

% chg-multi -info
0 10 1				# exitcode returned is 0

% chg-zd-mtx -info
0 10 1 1

-reset

<tpchanger> -reset

Resets the changer to known state and loads the first slot.

Output and error handling are the same as the -slot command. Output of only a slot name is also valid, if no volume is loaded.

In the case of a gravity stacker that must be reset by hand, this can be run (via " amtape <conf> 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 				# no device; 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

<tpchanger> -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 

-search

<tpchanger> -search <labelstr>

Loads an Amanda tape by name (labelstr).

Output and error handling are the same as the -slot command. taper, amcheck(8) and amtape(8) will use this command if the changer reports it is searchable.

The tape changer program may support this command, as indicated by the result of -info:

Example:

% chg-zd-mtx -search DailySet005
5 /dev/nrst8			# exitcode returned is 0

-label

<tpchanger> -label <labelstr>

Associates the Amanda label <labelstr> 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.

The tape changer program may support this command, as indicated by the result of -info:

Example:

% chg-zd-mtx -label DailySet006
6 /dev/nrst8			# exitcode returned is 0 

Slot Specifiers

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.