
     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
<jds@amanda.org>

Stefan G. Weichinger

XML-conversion;Updates
AMANDA Core Team
<sgw@amanda.org>
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:

* <tpchanger> -slot <slot-specifier>

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


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


* <tpchanger> -reset

Resets the changer to known state and loads the first slot.
Output and error handling are the 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") 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


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

The tape changer program MAY support the following commands:

* <tpchanger> -search <labelstr>

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

-<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.
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 <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 Go 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.
amtape <conf> clean If a cleaning tape is defined by the changer, load it in
the drive and put it away when done.
amtape <conf> device Output the current tape device name.
amtape <conf> current Display the contents of the current slot.
amtape <conf> update Scan the entire tape rack and update the barcode database.
See the amtape(8) man page for more details.
In addition to amtape, amlabel has been modified to allow optionally specifying
a slot:
amlabel <conf> <label> [slot <slot-specifier>]
amcheck 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 only finds the first tape, since finding the subsequent ones
would put the first one out of reach of that night's amdump run.
amrestore and amrecover do not yet include any tape changer support directly,
as amrestore knows nothing about the amanda.conf files or server-side
databases. This is a deliberate decision to keep amrestore independent, so 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.

 How amdump interacts with the tape changer

Amanda does not require a particular tape label for a run. Any label that
matches the labelstr regex and is determined to be "inactive" according to the
tapelist database, may 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 (those that can go backwards):
With a full-access tape changer, amdump searches the entire rack for the
preferred tape label. This tape will usually be found at the current or next
position, but might be located anywhere. If the tape is found, it is used. If
it 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 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.

 Builtin tape-changers


 chg-multi (formerly chg-generic)

This tape changer script supports several common configurations:

* Using 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 tapes in an
  Amanda run.


* Using 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.


* Using 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' because `changerfile' may specify
several tape devices to be used. A sample configuration file may be found in
example/chg-multi.conf.

 chg-manual (formerly no-changer)

This is a poor man's tape changer that requires the backup operator to change
tapes manually. It expects `tapedev' in amanda.conf 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 (formerly hp-changer)

An mtx-based tape changer script. `changerdev' must specify the tape device
controlled by the mtx program, and `tapedev' must point to the 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. It will maintain files named `changerfile'/
changer-clean and `changerfile'/changer-access. 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 the Zubkoff/Dandelion
version of mtx. EricParticularly, paging and registry files usually present problems. Backing up
page files is pointless, but registry files are quite important to back up. It
is possible to create regular files that contain registry information by using
the Regback utility, from the Windows NT Resource Kit. Unfortunately, it is not
part of the Windows NT standard distribution, you have to purchase it
separately. Thanks to Ernie Oporto <ernie_oporto@mentorg.com> for the tip.

 Mac OS X

For notes on how to setup Amanda under Apple's OS X, please refer to http://
web.brandeis.edu/pages/view/Bio/AmandaMacOSXCompileNotes, written by Steven
Karel<karel@brandeis.edu>. Thanks to Jose L.Hales-Garcia <jose@stat.ucla.edu>
for the tip.
-------------------------------------------------------------------------------

Prev                   Up                                   Next
Part I. Installation  Home  Chapter 2. Amanda Installation Notes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           ./usr/share/amanda/tapechangers.txt                                                                 0000644 0000000 0000000 00000070172 10533157660 016267  0                                                                                                    ustar   root                            root                                                                                                                                                                                                                   
     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
<jds@amanda.org>

Stefan G. Weichinger

XML-conversion;Updates
AMANDA Core Team
<sgw@amanda.org>
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:

* <tpchanger> -slot <slot-specifier>

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


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


* <tpchanger> -reset

Resets the changer to known state and loads the first slot.
Output and error handling are the 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") 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


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

The tape changer program MAY support the following commands:

* <tpchanger> -search <labelstr>

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

-<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.
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 <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 Go 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.
amtape <conf> clean If a cleaning tape is defined by the changer, load it in
the drive and put it away when done.
amtape <conf> device Output the current tape device name.
amtape <conf> current Display the contents of the current slot.
amtape <conf> update Scan the entire tape rack and update the barcode database.
See the amtape(8) man page for more details.
In addition to amtape, amlabel has been modified to allow optionally specifying
a slot:
amlabel <conf> <label> [slot <slot-specifier>]
amcheck 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 only finds the first tape, since finding the subsequent ones
would put the first one out of reach of that night's amdump run.
amrestore and amrecover do not yet include any tape changer support directly,
as amrestore knows nothing about the amanda.conf files or server-side
databases. This is a deliberate decision to keep amrestore independent, so 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.

 How amdump interacts with the tape changer

Amanda does not require a particular tape label for a run. Any label that
matches the labelstr regex and is determined to be "inactive" according to the
tapelist database, may 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 (those that can go backwards):
With a full-access tape changer, amdump searches the entire rack for the
preferred tape label. This tape will usually be found at the current or next
position, but might be located anywhere. If the tape is found, it is used. If
it 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 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.

 Builtin tape-changers


 chg-multi (formerly chg-generic)

This tape changer script supports several common configurations:

* Using multiple tape drives in a single host to emulate a tape changer. This
  can also be used with a single physical drive to write se