AMANDA-CHANGERS(7)

📦
version 3.5.4 · 8 versions
, in ubuntu stonking

💖 amanda-changers 💖

okay bestie, this is AMANDA-CHANGERS(7) — the Amanda changers page — and it's a long one, so it comes in three parts. This is part 1. Buckle in. 🎀

🌸 NAME 🌸

amanda-changers — configuring and using Amanda changers. That's the whole vibe, short and sweet. 💅

✨ DESCRIPTION ✨

okay so Amanda uses changers to arbitrate access to devices (peep amanda-devices(7)) and data volumes. Changers give you an abstraction of tape robots, but bestie, they're used to manage non-tape media too, not just tapes. Amanda communicates with changers through the Changer API.

This manpage contains a user-level overview of the API, and does not address details that are only of concern to developers. For that purpose, consult the Amanda source code and http://wiki.zmanda.com. 🫶

🌈 TRANSITION 🌈

The Amanda Changer API version 1.0 is no longer supported. rip babe. 💀

The Amanda Changer API version 2.0 is composed of perl objects that can manage parallel access to multiple devices and other complexity. At this point, all Amanda programs use the new Changer API directly. slay.

The Changer API strives to treat all changers identically, so that Amanda's behavior is independent of the changer in use. However, some parts of Amanda operate differently depending on whether a changer can efficiently search for a volume with a given label. This distinction is really only apparent with tape libraries: those with barcode readers can quickly find a desired tape, while those without may fall back to an inefficient scan of each volume. The capability to perform quick searches is called "fast-search", and each changer is annotated below to indicate its support. iykyk. 👑

🌸 SPECIFYING CHANGERS 🌸

Changer specifications are strings like chg-disk:/my/vtapes. The chg- prefix serves to differentiate changers from devices (see amanda-devices(7)). The next portion (disk, in this case) identifies the particular changer driver to use, and everything that follows the : is interpreted by the driver. Note that the : character is required, even when nothing follows it. no cap.

A name which does not match this pattern is treated as an Amanda device, and is wrapped by the single-device changer, e.g., chg-single:tape:/dev/rmt/0.

Changers which require additional parameters can also be described in amanda.conf(5) with "changer" sections. Such a changer definition creates a changer "alias", in this case named hp-robot, which can then be named where an application expects a changer — for example, the target of the amvault command or in a global tpchanger parameter.

🛠️ CONFIGURATION 🛠️

The preferred method of specifying configuration for a changer is as a "changer" section in amanda.conf(5). The tapedev parameter then indicates, by name, the changer that will be used by default by most Amanda programs. For example:

define changer hp-robot {
    tapedev "chg-robot:/dev/sg1"
    property "tape-device" "0=tape:/dev/nst0"
    property append "tape-device" "1=tape:/dev/nst1"
    device-property "BLOCK_SIZE" "512k"
}
# ...
tapedev "hp-robot"

Several changer drivers accept changer properties which control the behavior of the changer. These properties must be specified in a changer definition, as in the hp-robot example, above.

Devices, too, can take properties to control their behavior (see amanda-devices(7)). Device properties can come from four places: implicit device properties (from tapetype parameters), global device properties (from global device-property parameters), properties in device definitions, and properties in changer definitions. Properties are applied in this order, with later properties taking priority. periodt.

There are only three implicit properties: MAX_VOLUME_USAGE is set based on the tapetype length parameter, READ_BLOCK_SIZE is set if readblocksize is set, and BLOCK_SIZE is set based on the blocksize parameter.

Global device properties always apply. If the changer specifies a device by alias, then device properties from the definition apply. If the changer is specified by an alias, then properties from that definition applied.

👑 CHANGER DRIVERS 👑

This section lists the changer drivers included with Amanda, and basic instructions for using them. For complete How-To information, consult the Amanda wiki at http://wiki.zmanda.com. 🦋

chg-aggregate:changer

define changer robot0 {
  tpchanger "chg-robot:/dev/sg0"
  property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
}
define changer robot1 {
  tpchanger "chg-robot:/dev/sg1"
  property "tape-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
}
define changer single {
  tpchanger "chg-single:/dev/rmt/4"
}
define changer aggregate {
  tpchanger "chg-aggregate:{robot0,robot1,single}"
  property "state-filename" "/etc/amanda/CONF/aggregate.state"

}
tpchanger "aggregate"

This changer driver allow the use of two or more changers or standalone drives in sequence. literally stacking them one after another. 🔥

Properties

  • LOCK-TIMEOUT — The time in seconds amanda wait to lock the statefile (default: 1000)
  • STATE_FILENAME — The name of the state file (default: "$CONFIG_DIR/$changer_name.state").

chg-disk:VTAPEROOT

tpchanger "chg-disk:/var/mnt/vtapes"
property "num-slot" "10"
property "auto-create-slot" "yes"
property "removable" "yes"
property "mount" "yes"
property "umount" "yes"
property "umount-lockfile" "/etc/amanda/conf/vtapes-lock"
property "umount-idle" "1"

This changer driver replaces the old chg-disk, supporting parallel access to vtapes stored in directories named slotN in the directory specified after chg-disk:. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots. This changer is fast-search capable. 💅

The current slot can be accessed using the device name file:VTAPEROOT. This is useful for the amrestore(8) command line.

Properties

  • AUTO-CREATE-SLOT — If a slotN directory in the range 1 to NUM-SLOT does not already exist, and this property is true, then the changer will create the directory.
  • LOCK-TIMEOUT — The time in seconds amanda wait to lock the statefile (default: 1000)
  • MOUNT — If this property is true, the changer try to mount the removable disk if nothing is mounted. The system must be configured to allow the amanda user to mount it.
  • NUM-SLOT — The minimum number of slots in the changer, where the first slot is slot1. If additional slot directories exist, they will also be used.
  • REMOVABLE — If this property is true, then the changer will verify that the changer directory (e.g., /var/mnt/vtapes) is on a different filesystem from its parent directory (e.g., /var/mnt). This is useful for removable disks, as it will prevent Amanda from creating slot directories when the removable disk is not mounted.
  • UMOUNT — If this property is true, the changer try to umount the removable disk when it exit. The system must be configured to allow the amanda user to umount it.
  • UMOUNT-LOCKFILE — If UMOUNT is set, it require a lockfile outside of the mount point to prevent race.
  • UMOUNT-IDLE — If set, the changer try to umount the removable disk when it is not in use. The umount-idle value is a delay in second to wait before doing the umount. A value >= 1 is required to prevent useless mount/umount.

chg-diskflat:VTAPEROOT

tpchanger "chg-diskflat:/var/mnt/vtapes-flat"
property "num-slot" "10"
property "auto-create-slot" "yes"
property "removable" "yes"
property "mount" "yes"
property "umount" "yes"
property "umount-lockfile" "/etc/amanda/conf/vtapes-flat-lock"
property "umount-idle" "1"

This changer driver can be used only with the diskflat device, supporting parallel access to vtapes stored in files named with the label in the directory specified after chg-diskflat:. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots. This changer is fast-search capable. 🔥

Properties

Have the same properties as the chg-disk changers. 🎀

chg-multi:DEVICE-LIST

tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
changerfile "chg-multi-state"

This script simply round-robins a number of distinct device names, as specified in the tpchanger setting. It is useful when all volumes for a configuration have different device names — for example, if you have many standalone drive. The changerfile must exist; it is used to save the state file.

The child devices are specified using the same syntax as for the RAIT device (see amanda-changers(7)). The range specification can be especially useful here:

tpchanger "chg-multi:s3:mycompany-backups/tape-{001..100}"

This changer is not fast-search capable. 😭

Properties

  • FIRST-SLOT — This property gives the number of the first slot. The default value is "1".
  • LOCK-TIMEOUT — The time in seconds amanda wait to lock the statefile (default: 1000)

Special Operations

A number of special operations are available for chg-multi via amtape(8) subcommands.

The reset subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer.

The eject subcommand will eject the volume in the given drive.

The clean subcommand is not yet implemented. 💀

The update subcommand instructs the changer to update its state database. Given no arguments, the changer will scan all available slots, loading each tape and reading its label. Especially for large libraries, this can take a long time. If only a few slots have changed, they can be listed on the command line:

amtape CONFIG update 1-3,9

In this case, the changer will only scan the stated slots. Finally, the changer will not scan at all if it is given the tape label for the slot:

amtape CONFIG update 2=DailySet-028

In this case, the changer updates its state to indicate that DailySet-028 is in slot 2, without trying to load the tape.

amtape CONFIG update 1-3,9=

In this case, the changer marks the stated slots as an unknown state.

amtape CONFIG update error=

In this case, the changer marks all slot in error as an unknown state.

chg-rait:{CHILD1,CHILD2,..}

define changer vtape {
    tpchanger "chg-disk:/path/to/vtape"
}
define changer robot {
    tpchanger "chg-robot:/dev/sg0"
    tapedev "tape:/dev/nst0"
}
tpchanger "chg-rait:{vtape,robot}"

This changer script constructs RAIT devices out of the devices provided by several "sub-changers". The sub-changers are specified using the same shell-like syntax as the RAIT device (see amanda-devices(7)).

So bestie, chg-rait is not out here demanding that every one of its child changers use the same slot names. It builds compound slot names by smooshing together the slot names from each child, using that same shell-like brace syntax. Like, if the child changers hand back the slots "top", "strange", and "3", then the RAIT changer gives you {top,strange,3}. 💅 Which means you can do things like mirror data on tapes in slots 1-10 onto tapes in slots 11-20 of the same robot, using two chg-zd-mtx child changers (and, naturally, two tape drives). In that arrangement the first slot is named {1,11}.

And as a lil treat for you, the RAIT changer also accepts un-braced slot names, and just hands the same name to every child changer. So with a 4-device RAIT changer, "17" is literally equivalent to "{17,17,17,17}". ✨

Drive names get parsed the same way, for the operations that take drive names (clean and eject).

Heads up though: this changer is fast-search capable only if every single one of its child changers is fast-search capable. No exceptions, no shortcuts. 🫶

chg-null: 🌸

tpchanger "chg-null:"

This changer always provides the device null:. That's the whole job, bestie. It's sometimes useful in conjunction with chg-rait:. 💜

chg-robot:DEVICE 👑

define changer robot {
    tpchanger "chg-robot:/dev/sg0"
    property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
    property "eject-before-unload" "yes"
    property "use-slots" "1-5,11-20"
}
tpchanger "robot"

Okay so this one drives a robotic tape library using your operating system's mtx command. It is the glow-up replacement for the ancient chg-zd-mtx script, periodt. It uses all of the information available to operate as efficiently as possible. Even with no barcode reader, it can usually load a tape immediately, without resorting to a sequential scan of many tapes. And it's capable of sharing state across multiple Amanda configurations, so it avoids conflicts and optimally tracks what's actually in the library. 🌈

This changer does not accept a changerdev parameter, but the changerfile parameter can be used to specify a filename where it should store its state. Ordinarily, that state lives in a file named after the changer device under $localstatedir/amanda, e.g., /var/amanda/chg-robot-dev-sg0. And listen: there should be a single such statefile for each distinct tape library attached to the Amanda server, even if multiple Amanda configurations reference that library. One library, one statefile, iykyk. 🙈

With a barcode reader present, chg-robot can track the state of the library reliably, even recognizing tapes that get removed and later re-inserted (by remembering their barcodes). Without barcodes, the changer can still remember the slot where it last saw the tape with a particular label — although that info can become stale if an operator rearranges the tapes. But in any case, the changer will never "hunt" for a tape by repeatedly loading slots and checking labels. If the changer's state is inaccurate, just use the amtape(8) subcommand update. 🌸

This changer is fast-search capable even without a barcode reader. For such libraries, it's the responsibility of the operator to update the changer when tapes are added to or removed from the library. 👑

There's a shell script in the contrib/ directory of Amanda's source distribution that can help you convert a chg-zd-mtx configuration into a chg-robot configuration. Just give it your Amanda configuration name:

sh contrib/convert-zd-mtx-to-robot.sh $config

The script can be downloaded at http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh. ✨

Special Operations 💫

There are a bunch of special operations available for chg-robot via amtape(8) subcommands. Let's go through them one by one, bestie.

  • The reset subcommand changes the current slot to the first available slot, but it does not erase any stored state maintained by the changer.
  • The eject subcommand unloads the volume in the given drive, ejecting first if the changer properties dictate that. And note this: despite the subcommand name, the changer tries to avoid the state where a volume has been ejected from the drive but not unloaded back to a storage slot. 🫶
  • The clean subcommand is not yet implemented. Never was, never will be (for now, anyway).
  • The update subcommand tells the changer to update its state database. Given no arguments, the changer scans all available slots, loading each tape and reading its label. Especially for large libraries, this can take a long time. 😭

If only a few slots have changed, you can list them on the command line:

amtape CONFIG update 1-3,9

In this case, the changer will only scan the stated slots. And finally, the changer won't scan at all if you give it the tape label for the slot:

amtape CONFIG update 2=DailySet-028

In this case, the changer updates its state to indicate that DailySet-028 is in slot 2, without even trying to load the tape. 💅

amtape CONFIG update 1-3,9=

In this case, the changer marks the stated slots as an unknown state.

amtape CONFIG update error=

In this case, the changer marks all slots in error as an unknown state. 🌸

Properties 🎀

BROKEN-DRIVE-LOADED-SLOT

Set this boolean property to true if mtx doesn't return correctly which slot is loaded in a drive.

DRIVE-CHOICE

This property controls the algorithm used to select a drive in which to load a tape. If set to the default ("lru"), the changer attempts to use the least recently used drive, resulting in a round-robin behavior. The "firstavail" algorithm selects the first available drive, so it prefers the first drive specified via the TAPE-DEVICE property. 👑

EJECT-BEFORE-UNLOAD

Set this boolean property to true if the library requires an offline operation to be performed on the tape drive before it can be unloaded. If set, then mt will be invoked to perform this operation. Most libraries do not require this workaround.

EJECT-DELAY

This is the time between ejecting a tape and unloading the volume to a storage slot, and it defaults to 0 seconds. It is only used if EJECT-BEFORE-UNLOAD is true. See "Timing", below. ⏳

This boolean property indicates whether the changer advertises the ability to find volumes without sequential scanning. The traditional taperscan algorithm alters its behavior based on this flag, so it's sometimes necessary to adjust it — although the changer will always search for a desired tape using the most efficient means available. The default value is true.

IGNORE-BARCODES

If this boolean property is true, then chg-robot will ignore any barcode information that the library provides. This property is probably only useful when the library returns incorrect barcodes, for example due to a malfunction in the barcode reader. 💀

LOAD-POLL

This property specifies the timing of Amanda's polling for the tape drive to be ready after loading a new tape. See "Timing", below.

The script "polls" by trying to open the tape device repeatedly until no error is encountered. The property specifies the time to wait before the first poll (D), the frequency at which to poll and retry on errors (P), and the time after which it should give up (U). The format is

"D [poll P [until U]]"

For a simple delay with no polling, use e.g.,

property "load-poll" "13s"

To delay and then poll, use e.g.,

property "load-poll" "13s poll 5s"

and to add a maximum total time, use e.g.,

property "load-poll" "0s poll 5s until 2m"

The default value is "0s poll 3s until 2m". ✨

LOCK-TIMEOUT

The time in seconds amanda waits to lock the statefile (default:1000).

MTX

The path to the mtx binary. The default value is defined at compile time.

STATUS-INTERVAL

This is the minimum time between invocations of mtx status to determine the state of the changer library. The default value, 2 seconds, avoids back-to-back status invocations but ensures that the metadata is up to date. For operating systems or libraries where the mtx status takes a considerable time to complete, this value should be increased. See "Timing", below.

TAPE-DEVICE

This property describes the correspondence of drive numbers in the library to Amanda devices, in the format DRIVE=DEVICE. The property can be specified multiple times to describe multiple devices. The device will usually be a tape device name starting with tape:, but it may also refer to a device alias (see amanda-devices(7)). As a shortcut, if the tapedev parameter is specified in the changer definition, then it is assumed to be the device name for drive 0. 💅

UNLOAD-DELAY

This specifies the minimum time between an unload operation and any subsequent operation. The default value is 0 seconds. See "Timing", below.

USE-SLOTS

This property, if specified, enumerates the slots to which this changer should limit itself. The slots are specified as a comma-separated list of ranges, e.g., "1-5,11-15,19,22". The property can be specified more than once, and the resulting sets will be combined. The changer will refuse to load tapes not found in these slots, except for import/export purposes. 🚫

Timing ⏰

Tape libraries are fickle, bestie, and in many cases they'll report that an operation is complete when it is still in progress. Chg-robot takes several timing-related properties to accommodate such behavior.

A typical sequence of operations performed during a load is: get library status, eject a tape, unload the tape back to a storage slot, load a new tape, and read the label on that tape to ensure the drive is ready. 🌸

On most systems, the library status check is nearly instantaneous — the changer library provides its cached state to the host without initiating any robot motion. In order to keep its metadata up-to-date, chg-robot runs this command very frequently, but this frequency can be reduced (at the cost of potentially stale metadata) by setting the STATUS-INTERVAL property to a larger value.

Some tape libraries don't integrate the eject operation (performed by the embedded tape drive) with the unload operation (performed by the library robot), and can actually cause physical damage by attempting to remove the tape before the ejection is complete. 😭 For such changers, set the EJECT-DELAY property to allow enough time for the eject to complete.

Once a tape is unloaded, if the library needs time to "quiesce" before processing another command, add that time to the UNLOAD-DELAY parameter. No other operations will be performed on the library until this delay has elapsed. 🫶

Once a tape has been loaded, chg-robot waits until the drive is ready before allowing Amanda to use the volume, as described for LOAD-POLL, above. 💜

🦋 chg-ndmp:HOST[:PORT]@SCSIDEV 🦋

ok so imagine chg-robot but the changer isn't plugged into your local box bestie, it lives on an NDMP server ✨

tpchanger "chg-ndmp:filer.company.com@/dev/sg0"
property        "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"
property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"
property "use-slots" "1-12"
property "ndmp-auth" "text"
property "ndmp-username" "luke"
property "ndmp-password" "leia"

So like, this one is very similar to chg-robot — same energy, different address 💅 — except instead of poking a tape changer on a local device, it controls one that's sitting on an NDMP server.

  • the HOST in the tpchanger line = the hostname of the NDMP server, that's literally it
  • the PORT is optional, she's not required bestie
  • the SCSIDEV = the SCSI device on the NDMP server that runs the changer. and the format of this parameter is implementation-specific — so don't come at me asking for one true format, it depends on your setup 🫶

Also, adorable: the appropriate authentication properties get set on any devices this changer creates, automatically, no extra work from you 💖

Properties

This changer supports all of the properties supported by chg-robot — big slay, full inheritance — with one thing: the value of MTX is ignored. Like fully ignored. Not a vibe, just a fact 🙈

And these extra properties are recognized too:

NDMP_AUTH

Authentication method for connecting to the NDMP server. Pick one:

  • "md5" — the default, iconic, use this unless you have a reason
  • "text" — plain text auth
  • "none" — for an empty authentication attempt
  • "void" — for no authentication attempt at all

NDMP-PASSWORD

The password for the NDMP server 🔐

NDMP-USERNAME

The username for the NDMP server 🪪

VERBOSE

If true, it turns on the NDMJOB library's verbose (packet-level) debugging. so much output. every packet. absolutely unhinged amounts of information, but sometimes that's exactly what you need to figure out what's going on 😭

🎀 chg-single:DEVICE 🎀

tpchanger "chg-single:tape:/dev/nst0"

This changer is for use with a standalone drive — and honestly it can work with any device, she's flexible like that ✨ The device (tape:/dev/nst0) has to be set in the tpchanger definition though, non-negotiable.

And the plot twist? The chg-single changer has no property. That's it. That's the whole thing. Minimalist queen 👑

💀 Unmaintained Changers 💀

Amanda has a whole pile of other changer scripts and programs beyond the ones described here (peep the changer-src/ in the source directory if you're curious 👀), but ngl most of these scripts are unmaintained and undocumented, and they're getting removed once the new changer API is fully implemented. So like… don't get attached bestie, they're on their way out 🫠

🔥 SEE ALSO 🔥

The Amanda Wiki: : http://wiki.zmanda.com/ 🌈

👑 AUTHOR 👑

Dustin J. Mitchell <dustin@zmanda.com> Zmanda, Inc. (http://www.zmanda.com)

and that's a wrap on the whole page babes 🫶 this one was Amanda 3.5.4, dated 08/26/2026, filed under AMANDA-CHANGERS(7) — go forth and change some tapes, you've got this 💖✨🎀

📦 where this page comes from