Provided by: amanda-common_3.3.6-4.1_amd64 bug

NAME

       amanda-changers - Configuring and Using Amanda Changers

DESCRIPTION

       Amanda uses changers to arbitrate access to devices (amanda-devices(7)) and data volumes.
       Changers provide an abstraction of tape robots, but are used to manage non-tape media,
       too. 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 is in transition from version 1.0 - driven by shell scripts invoked
       for each changer operation - to version 2.0, 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, although 1.0 changer scripts are still fully
       supported via chg-compat.

       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.

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. This is an easy way to distinguish new changer specifications from
       old.

       A name which does not match this pattern, but which matches an old changer script (e.g.,
       chg-zd-mtx), invokes the backward-compatibility changer driver as e.g.,
       chg-compat:chg-zd-mtx. If the name does not match an old changer, then it 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 defininition 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.

       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 (new)
       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 to use two or more changers or standalone drive in sequence.

   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 (new)
       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-disk (old)
       tapedev "file:/u01/vtapes"
       tpchanger "chg-disk"
       changerfile "chg-disk.conf"     # optional file

       This changer script supports sequential access to vtapes stored in directories named slotN
       in the directory specified by the tapedev parameter. The configuration file parameter is:

       LASTSLOT=number    # The number of slots, default to tapecycle setting.

       This changer is not fast-search capable.

   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.

   chg-multi (old)
       tpchanger "chg-multi"
       changerfile "chg-multi-state"

       This script simply round-robins a number of distinct device names, as specified in its
       configuration file. It is useful when all volumes for a configuration have different
       device names -- for example, with S3 devices. The changerfile need not exist; it is used
       as a prefix for filenames of state files.

       The configuration file has simple lines with a parameter and its value separated by a
       space. The # character introduces a comment. The configuration parameters are:

       multieject
           If this is 1, use an 'mt offline' command to change to the next tape, or multiple such
           commands for skipping several tapes at a time.

       needeject
           This option is incompatible with 'multieject'. This should be 1 for changers accessed
           through several virtual tape devices, when the changer needs the current tape to be
           ejected before changing to another device.

       gravity
           Set this to 1 if the changer/stacker is unable to loop back to the first tape after
           unloading the last one, or if you don't want amanda to go through the tape stack
           looking for the exact tape it wants instead of using the first acceptable one.

       slot X
           The configuration file should list as many 'slot X' statements as the number of slots
           supported by the changer or the number of separate tape drives used.

       This changer is not fast-search capable.

   chg-manual
       tpchanger "chg-manual"
       changerfile "chg-manual.conf"

       This script simply provides distinct device names in a round-robin fashion, as specified
       in its configuration file. It is useful when all volumes for a configuration have
       different device names -- for example, with S3 devices. The configuration file parameters
       are (as listed in the script):

       resend_mail=900       # resend mail every __ seconds
       timeout_mail=604800   # time out after this many seconds (default 7 days)
       request="[type]"      # How to request a new tape (default "tty_email")
         request="tty"       # Use the tty to ask the user to change tape.
                             # Can't be use by cron
         request="email"     # Send an email to ask the user to change tape.
         request="tty_email" # Use the tty if it exist or send an email.

       This changer is not fast-search capable.

   chg-zd-mtx (old)
       tpchanger "chg-zd-mtx"
       changerdev "/dev/sg0"         # used with 'mtx -f'
       changerfile "chg-zd-mtx.conf"
       tapedev "tape:/dev/nst0"

       This script interfaces with a tape drive using the Zubkoff/Dandelion version of mtx.
       That's the version that takes a device specifier with the -f option and has subcommands
       like status. The configuration file parameters are (as listed in the script itself):

       firstslot=?                 #### First storage slot (element)
       lastslot=?                  #### Last storage slot (element)
       cleanslot=-1                #### Slot with cleaner tape -- default is "-1"
                                   #### Set negative to indicate no cleaner available
       driveslot=0                 #### Drive slot number.  Defaults to 0
                                   #### Use the 'Data Transfer Element' you want
       autoclean=0                 #### Set to '1' or greater to enable
       autocleancount=99           #### Number of access before a clean.
       havereader=0                #### If you have a barcode reader, set to 1.
       offline_before_unload=0     #### Does your robot require an
                                   #### 'mt offline' before mtx unload?
       poll_drive_ready=NN         #### Time (seconds) between tests to see if
                                   #### the tape drive has gone ready (default: 3).
       max_drive_wait=NN           #### Maximum time (seconds) to wait for the
                                   #### tape drive to become ready (default: 120).
       initial_poll_delay=NN       #### initial delay after load before polling for
                                   #### readiness
       slotinfofile=FILENAME       #### record slot information to this file, in
                                   #### the line-based format "SLOT LABEL\n"

       This changer is fast-search capable if and only if havereader is true.

   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)).

       Chg-rait does not require that all of the child changers have the same slot names:
       compound slot names are created by combining the slot names supplied by the child changers
       using the same shell-like syntax. For example, if the child changers return slots "top",
       "strange", and "3", then the RAIT changer will return "{top,strange,3}". This makes it
       possible to, for example, mirror data on tapes in slots 1-10 to tapes in slots 11-20 of
       the same robot, using two chg-zd-mtx child changers (and, naturally, two tape drives). In
       this arrangement, the first slot would be named {1,11}.

       As a convenience to the user, the RAIT changer will also accept un-braced slot names, and
       supply the same name to each child changer. Thus with a 4-device RAIT changer, "17" is
       equivalent to "{17,17,17,17}".

       Drive names are parsed in a similar fashion, for operations that take drive names (clean
       and eject).

       This changer is fast-search capable only if all of its child changers are fast-search
       capable.

           Note
           The old chg-rait script is no longer supported nor shipped with Amanda, although the
           old script will continue to function via chg-compat, giving users time to upgrade
           their configuration.

   chg-null:
       tpchanger "chg-null:"

       This changer always provides the device "null:". It is 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"

       This changer drives a robotic tape library using the operating system's mtx command. It
       replaces the ancient chg-zd-mtx script. The changer uses all of the information available
       to operate as efficiently as possible. Even without a barcode reader, the changer can
       usually load a tape immediately, without resorting to a sequential scan of many tapes. It
       is capable of sharing state across multiple Amanda configurations, avoiding conflicts and
       optimally tracking the contents of the library.

       This changer does not accept a changerdev parameter, but the changerfile parameter can be
       used to specify a filename at which it should store its state. Ordinarily, this state is
       stored in a file named after the changer device under $localstatedir/amanda, e.g.,
       /var/amanda/chg-robot-dev-sg0. 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.

       With a barcode reader present, it is possible for chg-robot to track the state of the
       library reliably, even recognizing tapes that are removed and later re-inserted (by
       remembering their barcodes). Without barcodes, the changer can still remember the slot in
       which it last saw the tape with a particular label, although this information can become
       stale if the tapes are rearranged by an operator. 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, use the amtape(8) subcommand update.

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

       There is a shell script in the contrib/ directory of Amanda's source distribution which
       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
       A number of special operations are available for chg-robot 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 unload the volume in the given drive, ejecting first if the
       changer properties dictate. Note that, despite the subcommand name, the changer attempts
       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.

       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.

   Properties
       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, thus preferring 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 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 defaults to 0 seconds.  It is only used if EJECT-BEFORE-UNLOAD is true.  See
           "Timing", below.

       FAST-SEARCH

           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 is 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 wait 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 correspondance 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 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 any any subsequent
           operation.  The default value is 0 seconds.  See "Timing", below.

       USE-SLOTS

           This property, if specifies, 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, and in many cases will 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 are: 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 do not 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.

       Each of the times specified in these properties may be given as integers with the optional
       suffix s for seconds (the default) or m for minutes.

   chg-ndmp:HOST[:PORT]@SCSIDEV
           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"

       This changer is very similar to chg-robot, but controls a tape changer on an NDMP server
       instead of a local device. The HOST in the tpchanger should be the hostname of the NDMP
       server. The PORT is optional. The SCSIDEV should specify the SCSI device on the NDMP
       server which controls the changer. The format of this parameter is
       implementation-specific.

       The appropriate authentication properties will be automatically set on any devices created
       by this changer.

   Properties
       This changer supports all of the properties supported by chg-robot, although the value of
       MTX is ignored. The following properties are also recognized:

       NDMP_AUTH

           Authentication method to use to connect to the NDMP server.  One of "md5" (default),
           "text", "none" (for an empty authentication attempt) or "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, enables the NDMJOB library's verbose (packet-level) debugging.

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

       This changer is for use with standalone drive, it can work with any device. The device
       (tape:/dev/nst0) must be set in the tpchanger definition.

       The chg-single changer has no property.

   Unmaintained Changers
       Amanda has many other changer scripts and programs beyond those described here (see the
       changer-src/ in the source directory), but most of these scripts are unmaintained and
       undocumented, and will be removed when the new changer API is fully implemented.

SEE ALSO

       amanda(8), amanda.conf(5), amanda-devices(7)

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

AUTHOR

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