X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=man%2Fxml-source%2Famanda-changers.7.xml;h=9846a12066e2e942acc5ae0fcfbb6523f3202b37;hb=fd48f3e498442f0cbff5f3606c7c403d0566150e;hp=4d68e2c8354f7f7e5367d9239d5c9db26adac6cf;hpb=96f35b20267e8b1a1c846d476f27fcd330e0b018;p=debian%2Famanda
diff --git a/man/xml-source/amanda-changers.7.xml b/man/xml-source/amanda-changers.7.xml
index 4d68e2c..9846a12 100644
--- a/man/xml-source/amanda-changers.7.xml
+++ b/man/xml-source/amanda-changers.7.xml
@@ -3,7 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
-
+
%global_entities;
]>
@@ -28,7 +28,7 @@
DESCRIPTION
Amanda uses changers to arbitrate access to devices
-(amanda-devices7)
+()
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
@@ -43,11 +43,18 @@ http://wiki.zmanda.com.
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. When this transition is complete, Amanda devices will, in general,
-be specified via a changer, which will provide the necessary device specifier
-to access a requested volume. In the interim, support for the "new" changer
-syntax is limited to the experimental
-amvault8.
+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.
@@ -56,40 +63,78 @@ syntax is limited to the experimental
Changer specifications are strings like
chg-disk:/my/vtapes. The
chg- prefix serves to differentiate changers
-from devices (see
-amanda-devices7).
-The next portion (disk, in this case)
-identifies the particular changer driver to use, and everything that follows
-the : is interpreted by the driver.
+from devices (see ). 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
+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 &amconf; with "changer" sections, for example,
+Changers which require additional parameters can also be described in
+&amconf; 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 &amconf;. 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 "drives" "0=/dev/nst0;1=/dev/nst0"
- property "slots" "1-10"
+ 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 ). 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.
-(note that "chg-robot" is not yet implemented, so this is hypothetical). 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.
+
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 (new)
+chg-disk:VTAPEROOT (new)
tpchanger "chg-disk:/u01/vtapes"
@@ -98,7 +143,11 @@ tpchanger "chg-disk:/u01/vtapes"
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.
+"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 command line.
@@ -106,15 +155,90 @@ supporting parallel access to vtapes stored in directories named
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.
+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
+ 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
+chg-multi (old)
tpchanger "chg-multi"
changerfile "chg-multi-state"
@@ -127,6 +251,34 @@ 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:
+
+
+multiejectIf 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.
+
+
+needejectThis 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.
+
+
+gravitySet 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 XThe 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
@@ -150,9 +302,11 @@ request="[type]" # How to request a new tape (default "tty_email")
+This changer is not fast-search capable.
+
-chg-zd-mtx
+chg-zd-mtx (old)
tpchanger "chg-zd-mtx"
changerdev "/dev/sg0" # used with 'mtx -f'
@@ -188,25 +342,334 @@ slotinfofile=FILENAME #### record slot information to this file, in
+This changer is fast-search capable if and only if
+havereader is true.
+
-chg-rait
+chg-rait:{CHILD1,CHILD2,..}
-tpchanger "chg-rait"
-changerfile "chg-rait.conf"
+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 configuration file specifies nchangers, the number of
-subchangers, and then provides tpchanger, changerdev_N, changerfile_N, and tpchanger_N for each sub-changer, 1 through N.
+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
+).
+
+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.
+
+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
+chg-null:
-tpchanger "chg-null"
+tpchanger "chg-null:"
-This changer always provides the device "null:". It is sometimes useful in conjunction with chg-rait.
+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
+ 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
+ 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 ). 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.
+
+
+
+
+
@@ -221,12 +684,10 @@ will be removed when the new changer API is fully implemented.
-SEE ALSO
-
-amanda8,
-amanda.conf5,
-amanda-devices7,
-
+
+,
+,
+
+
-