AMANDA TAPE CHANGER SUPPORT

Originally by James da Silva <jds@cs.umd.edu>
Heavily modified by various contributors

1. INTRODUCTION

This document outlines the tape changer support design of Amanda 2.2.  I
have defined a small interface for changer software to follow so that
Amanda can remain device-independent, and support the widest range of tape
software and hardware possible.

The interface is a bit simplistic, but I have been reluctant to add
complications until there is a body of field experience with the simple
version.  I am very interested in feedback on how the tape changer support
can be improved.


2. SPECIFYING A TAPE CHANGER IN AMANDA.CONF

All the 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 new "tpchanger" variable
in the amanda.conf file.  Example entry:

	tpchanger "chg-multi"	   # use multi-unit tape changer emulator
	changerfile "/etc/amanda/changer.conf"    # changer configuration

The older tapedev parameter is ignored if a tpchanger program is
specified, unless the changer program itself reads tapedev from
amanda.conf.  chg-multi 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 '/', then amanda will expect
it to reside in libexecdir, and possibly have the version suffix appended
depending on how amanda was configured.


3. DEVICE-SPECIFIC TAPE CHANGER SCRIPT

The tape changer program must support the following commands:

    <tpchanger> -slot <slot-specifier>

		changes to a particular slot
		outputs to stdout the slot name and name of the 
			device file to access the tape
		returns 0 on success, 
		returns 1 on positioning error (eg at bottom of
		    gravity stacker or slot empty)
		returns 2 any other fatal error
			error messages 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
		<none> no slot `bogus-slot'       # exitcode returned is 2


    <tpchanger> -info 
		outputs to stdout three fields: the current slot string, the
		number of slots, and whether the changer can go backwards (0
		if it can't, 1 if it can).  Same error handling as above.

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

    <tpchanger> -reset
		resets changer to known state and loads the first slot.
		Output and error handling same as "<tpchanger> -slot first".
		In the case of a gravity stacker that must be reset by hand,
		this could be run (via amtape <conf> reset) by the operator
		to inform the software that 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

    <tpchanger> -eject
		ejects the currently loaded tape, if appropriate.  Output
		and error handling are the same as the -slot command.

	Examples:
		% chg-multi -eject
		0 /dev/nrst8			# exitcode returned is 0

		% chg-multi -eject
		0 drive was not loaded		# exitcode returned is 1

For all the commands:

	An exit code of 0 implies that the operation was completely
	successful, and that the output can 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 that 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 the load of
	a different slot.

	Any other exit code is considered a fatal error and will cause
	amanda to stop attempting to talk to the tape changer.


4.  SLOT NUMBERS 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 its 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 previous one is remembered.  As an example, the
chg-multi.sh 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 specified: 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.


5. OPERATOR INTERFACE

The new amtape program is the main operator interface to Amanda's tape
changer support.  The commands supported include:

	amtape <conf> slot <slot-specifier>
		Load the tape from the specified slot into the drive
	amtape <conf> eject
		Send an eject command to the tape-changer.  Effect is changer
		specific.
	amtape <conf> reset
		Send a reset command to the tape-changer.  Effect is changer
		specific.
	amtape <conf> show
		Goes through the entire tape rack, showing the labels of all 
		amanda tapes encountered.
	amtape <conf> label <label>
		Find and load the tape with the specified label
	amtape <conf> taper
		Perform taper's scan algorithm (see below), loading the tape
		which would be picked for the next amdump run.

In addition to amtape, amlabel has been modified to allow optionally
specifying a slot:
	amlabel <conf> <label> [slot <slot-specifier>]

Amcheck also looks for the next tape in the rack the same way the taper
does.  If multiple tapes are used in one night, amcheck attempts to find
all the needed tapes in turn if the tape-changer is random access.  On a
one-way gravity stacker, amcheck just finds the first tape, since finding
the subsequent ones would put the first one out of reach of that night's
amdump run.

Amrestore does not include any tape changer support directly, as amrestore
knows nothing about the conf files or server-side databases.  This is a
deliberate decision to keep amrestore independent, so that it can be run
from any host with a tape drive, even if the original tape server host is
down.  To use amrestore in a tape-changer environment, use amtape to find
the right tape, then run amrestore giving the resulting tape device name
[yes, we need a nicer wrapper for amrestore, but I want to maintain the
independence of the low-level program].


6. HOW AMDUMP INTERACTS WITH THE TAPE CHANGER

Amanda does not require a particular tape label for a particular night's
run.  Any label that matches the labelstr regex, and is not determined to
be "active" according to the tapelist database, can be written to.
However, there is a preferred 'next' tape, the one that is next in the
cycle implied by the current tapelist.

Amdump uses two algorithms, depending on whether the tape changer can go
backwards in the rack or not.  If multiple tapes are needed in a single
run, this algorithm is repeated in turn whenever a new tape is required.

Normal tape changers:

With a full-access tape changer, Amdump now searches the entire rack for
this preferred tape label.  Usually, this tape will be found at the current
or next position, but can be located anywhere.  If the tape is found, it is
written to.  If that tape is not found, the first tape encountered that
matches the labelstr, and is not active, is picked.

Gravity stackers (anything that can not go backwards):

To avoid going all the way to the bottom of the stacker only to find that
the preferred tape isn't present and nothing can be done, Amanda now picks
the first tape (starting at the current position) that matches the
labelstr, and is not active, regardless of whether it is the preferred
tape.


7. BUILT-IN TAPE CHANGERS

chg-multi: (former chg-generic)

A tape changer script that supports several common configurations:
  - Use multiple tape drives in a single host to emulate a tape
    changer. This can also be used with a single physical drive to
    write several tape in an amanda run (check the FAQ: dumps way too big).
  - Use a gravity stacker or a real changer configured to sequentially
    load the next tape when the current one is ejected. Also supports
    a changer which cycles to the first tape after loading the last
    one.
  - Use a changer accessed through several "virtual" tape devices
    which determine which slot actually gets loaded in the tape drive.

The advantage of this changer script is that you do not need to get
into the complexity of dealing with a real changer interface. All the
action goes through the tape device interface, with standard "mt"
commands, which eases many portability issues. Many common tape
jukeboxes can be configured in a sequential or cycle mode.

chg-multi ignores `tapedev' and `changerdev', as `changerfile' may
specify several tape devices to be used.  A sample configuration file
can be found in example/chg-multi.conf.

chg-manual: (former no-changer)

This is a poor man's tape changer, as it requires the backup operator
to change tapes manually.  It expects `tapedev' to point to a valid
tape device, and stores some status data in files whose names start
with the `changerfile'.  `changerdev' is ignored.

chg-mtx: (former hp-changer)

A mtx-based tape changer script.  `changerdev' must specify the tape
device controlled by the mtx program, and `tapedev' must point to
no-rewind tape device to be used.  More than likely, both `changerdev'
and `tapedev' will reference the same device file.  `changerfile' must
specify a prefix for status files maintained by this script.  If
`changerfile' is defined as `/usr/adm/amanda/csd/changer', this script
will maintain files named `changer-clean' and `changer-access' in the
log directory.  You may have to edit the script to specify which slot
contains a cleaning tape (cleanslot).

The `mtx' program must support commands such as `-s', `-l' and `-u'.
If the one you've got requires `status', `load' and `unload', you
should use chg-zd-mtx instead, see below.

chg-zd-mtx:

Based on chg-mtx, but modified in order to support Zubkoff/Dandelion
version of mtx.  Eric DOUTRELEAU <Eric.Doutreleau@int-evry.fr>, who
contributed this script, reported that it works on a Solaris/sparc box
with a HP 1557A stacker.

In addition to the `changerfile'-clean and the `changerfile'-access
files, it will maintain a `changerfile'-slot that indicates the
currently loaded slot.

chg-scsi-chio: (former seagate-changer, then chg-chio)

A C program that relies on scsi tape-changer interfaces.  It may
either use the tape changer interface specified in chio.h (Gerd Knor's
SCSI media changer driver, a Linux kernel loadable module), or it may
use built-in tape changer interfaces available on HPUX, Solaris 2.5,
IRIX and possibly others, but only the chio and HPUX interfaces are
currently implemented .  `tapedev' specifies the tape device to be
used; `changer_dev' is the device used to talk to the kernel module
(for chio, usually /dev/ch0), and `changerfile' specifies a filename
in which the current slot number will be stored.

Now there is another way, to get the chg-scsi a little bit more
flexible.  If you use only one digit in the `tapedev' parameter, the
chg-scsi expects that changerfile points to a real configuration file,
not only a counting file.  In this configuration file you may specify
that the tapedrive needs an eject command and an optional waittime,
necessary after inserting the tape into the drive.  You are also able
to configure a range of slots which should be used by your
configuration.  The idea behind this is, that you don't want amanda to
cycle all the tapes if amanda searches exactly one tape.  If you have
a library which supports more than one drive you can also specify
which drive to use.  For each configuration (there should be at least
one) you have to specify a file, where amanda remembers which tape is
actually in the drive.  For future use there is also some stuff for
cleaning the drives.

In amanda.conf:

tapedev "x"       with x between 0 and 9, selects the configuration to use
changerfile "filename"            specifies the changer configuration file

In the changer-config-file the following could be set:
number_configs x	x between 0 and 9 	number of configurations
						defined. This should be
						the first parameter in the
						config-file.
eject	x		x 0 or 1		1 means that the drives need
						an eject command, before the 
						robot can handle the tape.
sleep	x		x between 0 and MAX_INT specifies the seconds to wait
						before the drive could be used
						after inserting a tape. 5
						should be OK.
cleanmax x		x some positive int	How many cleanings does a 
						cleaning tape survive
changerdev  <device>				The device for the robot

And then there come some configuration sections, separated by the word `config`
followed by the ordinal of that configuration (0 to 9). In each configuration
section you should specify:

drivenum x		x between 0 and the number of drives in the library
						This one specifies the drive to
						use with this configuration
dev	<device>				The device for the tapedrive
startuse    x		x between 0 and maximum slotnumber of your library
						Starting here we may use the tapes
enduse	 x		x between start and maximum slotnumber
						This is the last tape we may use
						in this configuration. If we reach
						this one the next will be start..
statfile <filename>				Here we remember the last used
						slot for this configuration
cleancart	x	x between 0 and maximum slotnumber 
						In this slot we find the 
                                                cleaning tape
cleanfile <filename>				Here we will remember how 
						often we used the cleaning tape
usagecount <filename>				This points to a file which is
						deleted after cleaning the drive
						e.g. the usagetime of the drive
											 
Comments begin with an '#' until end of line.
Allowed separators are TAB and SPACE. 

chg-scsi: (new interface, try to drive a robot with direct scsi commands)
The config and the sysntax is the same as for chg-scsi-chio. New
is the config type 

scsitapedev <devicename>

This device is used to control the tape, read status infos etc.

tapestatus <filename>

If this option is given on every eject/move the log pages of the tape
device will be dumped in this file. There are 2 log pages were you
can see how many read/write errors (corrected) are processed by the tape

labelfile <filename>

This file is used for the mapping from barcode labels to amanda volume labels.
It is used if the changer has a barcode reader. To initialize run amtape show,
this will add the mapping for the tapes in the magazine.

eject > 1

Use the mtio ioctl to eject the tape, use only if the standard (1) does
not work, and send the debug output (/tmp/amanda/chg-scsi.debug) to
th@ant.han.de

changerident <ident>

With this it is possible to specify which internal driver to use for 
controlling/error handling of the robot

tapeident <ident>

Some as above but for the tape.


New command line option:
-status [all|types|robot|sense|ModeSenseRobot|ModeSenseTape|fd]

<all> will show the result form all options.
<types> will list the known driver types.
<robot> will show the status of all elements (tape/robot/slots..)
<sense> will show the result from a request sense
<ModeSenseRobot> will show the sense page from the robot
<ModeSenseTape> will show the sense page from the tape
<fd> will show the devices which are open, and some info about it.


At the moment changer with tape and robot on the same SCSI id (
but on different luns) will run on the following plattforms
HP_UX 10.20	
IRIX 6.x
Solaris
Linux
AIX
FreeBSD

Tape and robot on different IDs run native on
Linux
HP-UX 10.20
Irix 6.x
FreeBSD

Tape and robot on different IDs with special modules run on
Solaris	with sst kernel module. See in the contrib/sst directory

For HP you have to create the special device files for the pass throu
interface. Check if the ctl driver is installed.
Example:
# lsdev -C ctl
    Character     Block       Driver          Class
      203          -1         sctl            ctl

Next check on which bus your drives are connected. (ioscan)

with the Character device num form the lsdev and the card instance from
ioscan create the special file.
Example:
mknod /dev/scsi/1 c 203 0x001000
                          ||||
                          ||| LUN of device
                          ||SCSI ID of the device
                          2 digit instance number from ioscan

On Linux you need either sg (generic scsi) as module or it must be compiled
into the kernel. If the sg driver doses not work try to use the ioctl interface.
For that you have to undef the LINUX_CHG define in changer-src/scsi-linux.c
Also you have to change the NORMAL_TIMEOUT in /usr/src/linux/drivers/scsi/scsi_ioctl.c
from (10 * HZ) to (5 * 60 * HZ).
On linux it does not run if you are using an aha1542 SCSI controller. The
driver can not handle the extended request sense.

On IRIX you find the SCSI pass through interfaces for every device in /dev/scsi

chg-scsi has been tested/run with the following devices
Exabyte 10h and eliant tape
HP-Surestore 1200e and C1553A tape
BreeceHill Q2.15 (EXB-120) and DLT7000 tape
Powerstor L200 and DLT7000 
ARCHIVE Python 28849-XXX 
TANDBERG TDS 1420
ADIC VLS DLT Library

It is now possible with a changer that has barcode reader to load tapes faster.
Also amdump will find tapes faster. Every time a tape is labeled the information
in the labelfile will be updated. To initialize the label mapping you can also
do an amtape config show. This will put the mapping for all tapes in the magazine
into the mapping file.

For all problems please contact th@ant.han.de. Please include in your
mail the debug file. (/tmp/amanda/chg-scsi.debug)


chg-chio: (new perl script, that replaces the original chg-chio written in C)

This script is based on the FreeBSD version of chio, a program to
communicate with the jukebox.  This script has for the moment only
been test with FreeBSD and is likely not to work on any other system.
Let me know if this is the case and send me the output of the chio
program for your version of chio.

It does not restrict the number of tapes, except that if there is only
one tape in the juke, it is supposed to be in max_slot and not in slot 1.

[This is the first version of the changer script and I would
appreciate all comments on it, at nick.hibma@jrc.it.  It has been
tested only with FreeBSD 2.2.5 and the accompanying chio program.]

chg-chs: (former chs-changer)

A tape changer script very similar to chg-multi, that uses the `chs'
program to change tapes.  As in chg-multi, `tapedev' is ignored.
`changerfile' names its configuration file, similar to chg-multi.conf.
`changerdev' will be passed to CHS in a -f command-line switch, unless
it is set to an empty string or "/dev/null" (watch out for default
values!)

chg-rth: (former rth-changer)

A perl5 script that controls an HPc1553 tape drive via a Peripheral
Vision Inc. SCSI control subsystem that interprets commands sent on
the SCSI bus.  It expects `tapedev' to specify the tape device to be
used.  `changerfile' and `changerdev' are ignored.