"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
<!-- entities files to use -->
- <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
+ <!ENTITY % global_entities SYSTEM 'global.entities'>
%global_entities;
]>
<refsect1><title>DESCRIPTION</title>
<para>Amanda uses changers to arbitrate access to devices
-(<citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+(<manref name="amanda-devices" vol="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 <emphasis>user-level</emphasis> overview
<para>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
-<citerefentry><refentrytitle>amvault</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+complexity. At this point, all Amanda programs use the new Changer API directly,
+although 1.0 changer scripts are still fully supported via <code>chg-compat</code>.
+</para>
+
+<para>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.</para>
</refsect1>
<para>Changer specifications are strings like
<computeroutput>chg-disk:/my/vtapes</computeroutput>. The
<computeroutput>chg-</computeroutput> prefix serves to differentiate changers
-from devices (see
-<citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
-The next portion (<computeroutput>disk</computeroutput>, in this case)
-identifies the particular changer driver to use, and everything that follows
-the <computeroutput>:</computeroutput> is interpreted by the driver.</para>
+from devices (see <manref name="amanda-devices" vol="7"/>). The next portion
+(<computeroutput>disk</computeroutput>, in this case) identifies the particular
+changer driver to use, and everything that follows the
+<computeroutput>:</computeroutput> is interpreted by the driver. Note that the
+<computeroutput>:</computeroutput> character is required, even when nothing
+follows it. This is an easy way to distinguish new changer specifications from
+old.</para>
<para>A name which does not match this pattern, but which matches an old
changer script (e.g., <computeroutput>chg-zd-mtx</computeroutput>), invokes the
-backward-compatibility changer driver as
+backward-compatibility changer driver as e.g.,
<computeroutput>chg-compat:chg-zd-mtx</computeroutput>. 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.,
<computeroutput>chg-single:tape:/dev/rmt/0</computeroutput>.</para>
-<para>Changers which require additional parameters can also be described in &amconf; with "changer" sections, for example,
+<para>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 <emphasis>hp-robot</emphasis>, which can
+then be named where an application expects a changer - for example, the target
+of the <command>amvault</command> command or in a global
+<command>tpchanger</command> parameter.</para>
+
+<refsect2><title>CONFIGURATION</title>
+
+<para>The preferred method of specifying configuration for a changer is as a
+"changer" section in &amconf;. The <emphasis>tapedev</emphasis> parameter
+then indicates, by name, the changer that will be used by default by most
+Amanda programs. For example:
<programlisting>
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"
</programlisting>
+</para>
+
+<para>Several changer drivers accept <emphasis>changer properties</emphasis> which
+control the behavior of the changer. These properties must be specified in a
+changer definition, as in the <emphasis>hp-robot</emphasis> example, above.</para>
+
+<para>Devices, too, can take properties to control their behavior (see <manref
+name="amanda-devices" vol="7" />). Device properties can come from four
+places: implicit device properties (from tapetype parameters), global device
+properties (from global <emphasis>device_property</emphasis> parameters),
+properties in device definitions, and properties in changer definitions.
+Properties are applied in this order, with later properties taking
+priority.</para>
+
+<para>There are only three implicit properties:
+<emphasis>MAX_VOLUME_USAGE</emphasis> is set based on the tapetype
+<emphasis>length</emphasis> parameter, <emphasis>READ_BLOCK_SIZE</emphasis> is
+set if <emphasis>readblocksize</emphasis> is set, and
+<emphasis>BLOCK_SIZE</emphasis> is set based on the
+<emphasis>blocksize</emphasis> parameter.</para>
+
+<para>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.</para>
-(note that "chg-robot" is not yet implemented, so this is hypothetical). A
-changer defininition creates a changer "alias", in this case named
-<emphasis>hp-robot</emphasis>, which can then be named where an application
-expects a changer - for example, the target of the <command>amvault</command> command.</para>
+</refsect2>
</refsect1>
<refsect1><title>CHANGER DRIVERS</title>
<para>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.</para>
-<refsect2><title>chg-disk (new)</title>
+<refsect2><title>chg-disk:VTAPEROOT (new)</title>
<programlisting>
tpchanger "chg-disk:/u01/vtapes"
</programlisting>
supporting parallel access to vtapes stored in directories named
<computeroutput>slotN</computeroutput> in the directory specified after
<computeroutput>chg-disk:</computeroutput>. It does so by creating numbered
-"drives" so that simultaneous processes can access distinct slots.</para>
+"drives" so that simultaneous processes can access distinct slots. This changer is fast-search capable.</para>
+
+<para>The current slot can be accessed using the device name
+<computeroutput>file:VTAPEROOT</computeroutput>. This is useful for the <manref
+name="amrestore" vol="8" /> command line.</para>
</refsect2>
<programlisting>
tapedev "file:/u01/vtapes"
tpchanger "chg-disk"
+changerfile "chg-disk.conf" # optional file
</programlisting>
<para>This changer script supports sequential access to vtapes stored in
directories named <computeroutput>slotN</computeroutput> in the directory
-specified by the <emphasis>tapedev</emphasis> parameter.</para>
+specified by the <emphasis>tapedev</emphasis> parameter.
+The configuration file parameter is:
+<programlisting>
+LASTSLOT=number # The number of slots, default to tapecycle setting.
+</programlisting>
+</para>
+
+<para>This changer is not fast-search capable.</para>
+
+</refsect2>
+
+<refsect2><title>chg-multi:DEVICE-LIST</title>
+<programlisting>
+tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
+changerfile "chg-multi-state"
+</programlisting>
+
+<para>This script simply round-robins a number of distinct device names, as
+specified in the <emphasis>tpchanger</emphasis> setting. It is useful when
+all volumes for a configuration have different device names -- for example,
+if you have many standalone drive. The <emphasis>changerfile</emphasis> must exist; it is used to save the state file.
+</para>
+
+<para>This changer is not fast-search capable.</para>
+
+<refsect3><title>Properties</title>
+<!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
+
+<variablelist>
+<!-- ==== -->
+<varlistentry><term>FIRST-SLOT</term><listitem>
+This property gives the number of the first slot. The default value is "1".
+</listitem></varlistentry>
+<!-- ==== -->
+</variablelist>
+
+</refsect3>
+
+<refsect3><title>Special Operations</title>
+
+<para>A number of special operations are available for <command>chg-multi</command> via
+<manref name="amtape" vol="8" /> subcommands.</para>
+
+<para>The <command>reset</command> subcommand will change the current slot to
+the first available slot, but does not erase any stored state maintained by the
+changer.</para>
+
+<para>The <command>eject</command> subcommand will eject the volume in the
+given drive</para>
+
+<para>The <command>clean</command> subcommand is not yet implemented.</para>
+
+<para>The <command>update</command> 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:
+<programlisting>
+amtape CONFIG update 1-3,9
+</programlisting>
+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:
+<programlisting>
+amtape CONFIG update 2=DailySet-028
+</programlisting>
+In this case, the changer updates its state to indicate that
+<computeroutput>DailySet-028</computeroutput> is in slot 2, without trying to
+load the tape.
+<programlisting>
+amtape CONFIG update 1-3,9=
+</programlisting>
+In this case, the changer marks the stated slots as an unknown state.
+</para>
+
+</refsect3>
</refsect2>
-<refsect2><title>chg-multi</title>
+<refsect2><title>chg-multi (old)</title>
<programlisting>
tpchanger "chg-multi"
changerfile "chg-multi-state"
for filenames of state files.
</para>
+<para>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: </para>
+
+<variablelist>
+<varlistentry><term>multieject</term><listitem>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.
+</listitem></varlistentry>
+
+<varlistentry><term>needeject</term><listitem>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.
+</listitem></varlistentry>
+
+<varlistentry><term>gravity</term><listitem>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.
+</listitem></varlistentry>
+
+<varlistentry><term>slot X</term><listitem>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.
+</listitem></varlistentry>
+</variablelist>
+
+<para>This changer is not fast-search capable.</para>
+
</refsect2>
<refsect2><title>chg-manual</title>
</programlisting>
</para>
+<para>This changer is not fast-search capable.</para>
+
</refsect2>
-<refsect2><title>chg-zd-mtx</title>
+<refsect2><title>chg-zd-mtx (old)</title>
<programlisting>
tpchanger "chg-zd-mtx"
changerdev "/dev/sg0" # used with 'mtx -f'
</programlisting>
</para>
+<para>This changer is fast-search capable if and only if
+<command>havereader</command> is true.</para>
+
</refsect2>
-<refsect2><title>chg-rait</title>
+<refsect2><title>chg-rait:{CHILD1,CHILD2,..}</title>
<programlisting>
-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}"
</programlisting>
-<para>This changer script constructs RAIT devices out of the devices provided by several "sub-changers". The configuration file specifies <computeroutput>nchangers</computeroutput>, the number of
-subchangers, and then provides <computeroutput>tpchanger</computeroutput>, <computeroutput>changerdev_N</computeroutput>, <computeroutput>changerfile_N</computeroutput>, and <computeroutput>tpchanger_N</computeroutput> for each sub-changer, 1 through N.</para>
+<para>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
+<manref name="amanda-devices" vol="7"/>).</para>
+
+<para>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 "<computeroutput>top</computeroutput>", "<computeroutput>strange</computeroutput>", and "<computeroutput>3</computeroutput>", then the RAIT changer will return "<computeroutput>{top,strange,3}</computeroutput>". 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 <command>chg-zd-mtx</command> child changers (and, naturally, two tape drives). In this arrangement, the first slot would be named <computeroutput>{1,11}</computeroutput>.</para>
+
+<para>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, "<computeroutput>17</computeroutput>" is equivalent to "<computeroutput>{17,17,17,17}</computeroutput>".</para>
+
+<para>Drive names are parsed in a similar fashion, for operations that take drive names (clean and eject).</para>
+
+<para>This changer is fast-search capable only if all of its child changers are fast-search capable.</para>
+
+<note>The old chg-rait script is no longer supported nor shipped with Amanda, although the old script will continue to function via <command>chg-compat</command>, giving users time to upgrade their configuration.
+</note><!-- previous newline is important -->
</refsect2>
-<refsect2><title>chg-null</title>
+<refsect2><title>chg-null:</title>
<programlisting>
-tpchanger "chg-null"
+tpchanger "chg-null:"
</programlisting>
-<para>This changer always provides the device "null:". It is sometimes useful in conjunction with <command>chg-rait</command>.</para>
+<para>This changer always provides the device "null:". It is sometimes useful in conjunction with <command>chg-rait:</command>.</para>
+
+</refsect2>
+
+<refsect2><title>chg-robot:DEVICE</title>
+<programlisting>
+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"
+</programlisting>
+
+<para>This changer drives a robotic tape library using the operating system's
+<command>mtx</command> command. It replaces the ancient
+<command>chg-zd-mtx</command> 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.</para>
+
+<para>This changer does not accept a <command>changerdev</command> parameter,
+but the <command>changerfile</command> 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
+<emphasis>$localstatedir/amanda</emphasis>, e.g.,
+<command>/var/amanda/chg-robot-dev-sg0</command>. 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.</para>
+
+<para>With a barcode reader present, it is possible for
+<command>chg-robot</command> 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
+<manref name="amtape" vol="8" /> subcommand <command>update</command>.</para>
+
+<para>This changer is fast-search capable even without a barcode reader. For
+such libraries, it is the responsibility of the operator to
+<command>update</command> the changer when tapes are added to or removed from
+the library.</para>
+
+<para>There is a shell script in the <filename>contrib/</filename> directory of
+Amanda's source distribution which can help you convert a
+<command>chg-zd-mtx</command> configuration into a <command>chg-robot</command>
+configuration. Just give it your Amanda configuration name:
+<programlisting>
+ sh contrib/convert-zd-mtx-to-robot.sh $config
+</programlisting>
+The script can be downloaded at <uri
+type="webpage">http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh</uri></para>
+
+<refsect3><title>Special Operations</title>
+
+<para>A number of special operations are available for <command>chg-robot</command> via
+<manref name="amtape" vol="8" /> subcommands.</para>
+
+<para>The <command>reset</command> subcommand will change the current slot to
+the first available slot, but does not erase any stored state maintained by the
+changer.</para>
+
+<para>The <command>eject</command> 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.</para>
+
+<para>The <command>clean</command> subcommand is not yet implemented.</para>
+
+<para>The <command>update</command> 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:
+<programlisting>
+amtape CONFIG update 1-3,9
+</programlisting>
+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:
+<programlisting>
+amtape CONFIG update 2=DailySet-028
+</programlisting>
+In this case, the changer updates its state to indicate that
+<computeroutput>DailySet-028</computeroutput> is in slot 2, without trying to
+load the tape.
+<programlisting>
+amtape CONFIG update 1-3,9=
+</programlisting>
+In this case, the changer marks the stated slots as an unknown state.
+</para>
+
+</refsect3>
+
+<refsect3><title>Properties</title>
+<!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
+
+<variablelist>
+<!-- ==== -->
+<varlistentry><term>DRIVE-CHOICE</term><listitem>
+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.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>EJECT-BEFORE-UNLOAD</term><listitem>
+Set this boolean property to true if the library requires an
+<command>offline</command> operation be performed on the tape drive before it
+can be unloaded. If set, then <command>mt</command> will be invoked to
+perform this operation. Most libraries do not require this workaround.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>EJECT-DELAY</term><listitem>
+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.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>FAST-SEARCH</term><listitem>
+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.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>IGNORE-BARCODES</term><listitem>
+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.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>LOAD-POLL</term><listitem>
+<para>This property specifies the timing of Amanda's polling for the tape drive to
+be ready after loading a new tape. See "Timing", below.</para>
+
+<para>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
+<programlisting>
+"D [poll P [until U]]"
+</programlisting>
+For a simple delay with no polling, use e.g.,
+<programlisting>
+property "load-poll" "13s"
+</programlisting>
+To delay and then poll, use e.g.,
+<programlisting>
+property "load-poll" "13s poll 5s"
+</programlisting>
+and to add a maximum total time, use e.g.,
+<programlisting>
+property "load-poll" "0s poll 5s until 2m"
+</programlisting>
+The default value is <command>"0s poll 3s until 2m"</command>.
+</para>
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>MTX</term><listitem>
+The path to the 'mtx' binary. The default value is defined at compile time.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>STATUS-INTERVAL</term><listitem>
+This is the minimum time between invocations of <command>mtx status</command>
+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 <command>mtx
+status</command> takes a considerable time to complete, this value should be
+increased. See "Timing", below.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>TAPE-DEVICE</term><listitem>
+This property describes the correspondance of drive numbers in the library to
+Amanda devices, in the format <emphasis>DRIVE=DEVICE</emphasis>. The property
+can be specified multiple times to describe multiple devices. The device will
+usually be a tape device name starting with <command>tape:</command>, but may
+also refer to a device alias (see <manref name="amanda-devices" vol="7"/>). As
+a shortcut, if the <command>tapedev</command> parameter is specified in the
+changer definition, then it is assumed to be the device name for drive 0.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>UNLOAD-DELAY</term><listitem>
+This specifies the minimum time between an unload operation any any subsequent
+operation. The default value is 0 seconds. See "Timing", below.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>USE-SLOTS</term><listitem>
+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.
+</listitem></varlistentry>
+</variablelist>
+</refsect3>
+
+<refsect3><title>Timing</title>
+
+<para>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.</para>
+
+<para>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.</para>
+
+<para>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.</para>
+
+<para>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.</para>
+
+<para>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.</para>
+
+<para>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.</para>
+
+<para>Each of the times specified in these properties may be given as integers
+with the optional suffix <command>s</command> for seconds (the default) or
+<command>m</command> for minutes.</para>
+
+</refsect3>
+
+</refsect2>
+
+<refsect2><title>chg-ndmp:HOST[:PORT]@SCSIDEV</title>
+<programlisting>
+ 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"
+</programlisting>
+
+<para>This changer is very similar to <command>chg-robot</command>, but
+controls a tape changer on an NDMP server instead of a local device. The
+<command>HOST</command> in the <command>tpchanger</command> should be the
+hostname of the NDMP server. The <command>PORT</command> is optional. The
+<command>SCSIDEV</command> should specify the SCSI device on the NDMP server
+which controls the changer. The format of this parameter is
+implementation-specific.</para>
+
+<para>The appropriate authentication properties will be automatically set on
+any devices created by this changer.</para>
+
+<refsect3><title>Properties</title>
+
+<para>This changer supports all of the properties supported by
+<command>chg-robot</command>, although the value of <command>MTX</command> is
+ignored. The following properties are also recognized:</para>
+
+<!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
+<variablelist>
+<!-- ==== -->
+<varlistentry><term>NDMP_AUTH</term><listitem>
+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).
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>NDMP-PASSWORD</term><listitem>
+The password for the NDMP server.
+</listitem></varlistentry>
+<!-- ==== -->
+<varlistentry><term>NDMP-USERNAME</term><listitem>
+The username for the NDMP server.
+</listitem></varlistentry>
+<!-- ==== -->
+</variablelist>
+
+</refsect3>
</refsect2>
</refsect1>
-<refsect1><title>SEE ALSO</title>
-<para>
-<citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>amanda.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-</para>
+<seealso>
+<manref name="amanda.conf" vol="5"/>,
+<manref name="amanda-devices" vol="7"/>,
+</seealso>
+
-</refsect1>
</refentry>
projects / debian / amanda / blobdiff