Changer API

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)
Revision as of 20:07, 1 January 2011 by Dustin (talk | contribs) (add glossary link)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

This page is about the "new", Perl Changer API, which was introduced in Amanda-2.6.1. For the old (pre-2.6.1) changer API, see Changer API (1.0).

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.


The Changer API is the only means by which Amanda applications can get access to volumes. Simple changers are available to handle trivial cases such as a single tape drive. This means that, outside the changer implementations, no part of the Amanda codebase needs to distinguish one changer type from another.


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. Note that, through use of 'amtape advance', it's possible that the current slot isn't even loaded in 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, with a similar definition. Slots are arbitrary user-displayable strings meaning only "a place to look for a volume". "Loaded" volumes are still considered to be in a slot, and chg-robot takes some effort to maintain this illusion. A changer must also maintain a "current" slot, and must pass along a "next" slot with each reservation. No further meaning is expected of slots.


When an Amanda process needs to access a volume, it acquires a "reservation" from the changer. Until this reservation is released, the process is guaranteed access to the volume, and that access is exclusive (unless the device itself supports concurrent access).


All new changers support searching for a volume by label, although this operation may be more or less efficient depending on the details of the configuration. For example, chg-disk can always find a label by inspecting the slot subdirectories, but chg-robot may need to load and examine several tapes to find its target (although it tries to avoid this!).


  • Detailed documentation of the Changer API is available directly in the source code, in the form of perldoc. See Amanda::Changer.
  • The details of changer configuration

Motivation for the Change

This API is a complete rewrite of the previous Changer API (1.0). The older version 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 old API requires callers to handle four semantically distinct types of changers: no changer at all (tpchanger=""), gravity changers, unsearchable changers, and searchable changers.
  • The old API does not support advanced operations such as importing or exporting tapes or moving them from slot to slot.