Provided by: amanda-common_3.1.0-1_i386 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-disk:VTAPEROOT (new)
       tpchanger "chg-disk:/u01/vtapes"

       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.

   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.

       This changer is not fast-search capable.

   Properties
       FIRST-SLOT

           This property gives the number of the first slot. The default value
           is "1".

   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 {
           tpcanger "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".

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

   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)