+<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>
+<!-- ==== -->
+<varlistentry><term>VERBOSE</term><listitem>
+If true, enables the NDMJOB library's verbose (packet-level) debugging.
+</listitem></varlistentry>
+<!-- ==== -->
+</variablelist>
+
+</refsect3>