Changer API
This is a developer-level description of Changer API v. 2.0, which was introduced in Amanda-2.6.1. For the old (pre-2.6.1) changer API, see Changer API (1.0).
Links
Detailed documentation of the Changer API is available directly in the source code, in the form of perldoc. See Amanda::Changer.
Motivation for the Change
The previous Changer API (1.0) had a few design deficiencies which made it incompatible with the needs of future versions of Amanda.
- All changer invocations are synchronous - Amanda stops to wait for the changer operation to complete.
- There is no mechanism to mark a device as "in use." Amanda has historically handled this by only allowing one process with access to the drive to run at any time, but modern users demand more concurrency than this.
- There is no mechanism to operate multiple, independent changers simultaneously - nor even to configure them. Tape-changer configuration is done with global Amanda parameters, and most scripts fetch their configuration using amgetconf(8).
- The exiting interface requires callers to handle four semantically distinct types of changers: no changer at all (tpchanger=), gravity changers, unsearchable changers, and searchable changers.
- The exiting interface does not support advanced operations such as importing or exporting tapes or moving them from slot to slot.
Operational Overview
The changer API is a collection of perl modules with the common prefix Amanda::Changer. Changers are represented as objects, with (among others) a sophisticated load() method which loads a volume and returns a reservation object. The caller has exclusive use of the underlying device until the reservation is explicitly released. Other parts of the same application, or other processes entirely, can reserve other volumes, assuming that the necessary resources are available (drives, SCSI IDs, whatever).
All operations are asynchronous, meaning that other activities such as file transfers can continue while the changer is performing an operation. As a result, the caller must be running an Amanda::MainLoop, and the resulting Perl contains a lot of anonymous subs serving as callbacks.
Slots
To support older functionality in Amanda, this version of the API has inherited a vague notion of "slot" from the 1.0 API. Note that this concept is ill-defined for *all* changers!
- for chg-zd-mtx, when e.g., slot "6" is loaded, the tape is actually physically located in the drive (perhaps slot 0), and the changer hardware/driver merely "remembers" that the tape came from slot 6. The user could certainly move another tape to slot 6 in the interim, which would leave chg-zd-mtx at a loss when it tried to unload the tape from the drive.
- for chg-multi, a slot is the same as a drive, and media is never moved in or out of drives
- for chg-disk, a slot is a substring of a subdirectory name, but only the "current" slot is accessible (via symlink)
- for chg-rait, a slot is defined by the slots of the sub-changers
Within the 2.0 API, this concept is still present, mostly to support the taperscan algorithm and to allow users to perform administrative tasks via amtape. Slots are arbitrary user-displayable strings meaning only "a place to look for a volume". A changer must maintain a "current" slot, and must pass along a "next" slot with each reservation. No further meaning is expected of slots, and new uses of the API should avoid reference to the concept as much as possible.
Bits and Pieces
(stuff I need to put somewhere)
Configuration Matrix
What follows is an exhaustive list of the combinations of configuration options for a changer, and the resulting interpretation of the "default" changer.
| global tapedev | global tpchanger | tpchanger in changer def'n | result |
|---|---|---|---|
| - | - | - | invalid |
| - | dev uri | - | chg-single with dev |
| - | dev alias | - | chg-single with dev |
| - | changer uri | - | given changer with no config |
| - | changer alias | changer uri | given changer with config from def'n |
| - | changer alias | changer script | chg-compat with config from def'n |
| - | changer script | - | chg-compat with global config |
| dev uri | - | - | chg-single with dev |
| dev uri | dev uri | - | invalid |
| dev uri | dev alias | - | invalid |
| dev uri | changer uri | - | invalid |
| dev uri | changer alias | changer uri | invalid |
| dev uri | changer alias | changer script | invalid |
| dev uri | changer script | - | chg-compat with global config |
| dev alias | - | - | chg-single with dev |
| dev alias | dev uri | - | invalid |
| dev alias | dev alias | - | invalid |
| dev alias | changer uri | - | invalid |
| dev alias | changer alias | changer uri | invalid |
| dev alias | changer alias | changer script | invalid |
| dev alias | changer script | - | chg-compat with global config |
| changer uri | - | - | changer with global config |
| changer uri | dev uri | - | invalid |
| changer uri | dev alias | - | invalid |
| changer uri | changer uri | - | invalid |
| changer uri | changer alias | changer uri | invalid |
| changer uri | changer alias | changer script | invalid |
| changer uri | changer script | - | invalid |
| changer alias | - | changer uri | changer with config from def'n |
| changer alias | - | changer script | chg-compat with config from def'n |
| changer alias | dev uri | changer uri | invalid |
| changer alias | dev uri | changer script | invalid |
| changer alias | dev alias | changer uri | invalid |
| changer alias | dev alias | changer script | invalid |
| changer alias | changer uri | changer uri | invalid |
| changer alias | changer uri | changer script | invalid |
| changer alias | changer alias | changer uri | invalid |
| changer alias | changer alias | changer script | invalid |
| changer alias | changer script | changer uri | invalid |
| changer alias | changer script | changer script | invalid |