+\fBchg\-rait:\fR\&.
+.SS "chg\-robot:DEVICE"
+.nf
+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"
+.fi
+.PP
+This changer drives a robotic tape library using the operating system\*(Aqs
+\fBmtx\fR
+command\&. It replaces the ancient
+\fBchg\-zd\-mtx\fR
+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\&.
+.PP
+This changer does not accept a
+\fBchangerdev\fR
+parameter, but the
+\fBchangerfile\fR
+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
+\fI$localstatedir/amanda\fR, e\&.g\&.,
+\fB/var/amanda/chg\-robot\-dev\-sg0\fR\&. 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\&.
+.PP
+With a barcode reader present, it is possible for
+\fBchg\-robot\fR
+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\*(Aqs state is inaccurate, use the
+\fBamtape\fR(8)
+subcommand
+\fBupdate\fR\&.
+.PP
+This changer is fast\-search capable even without a barcode reader\&. For such libraries, it is the responsibility of the operator to
+\fBupdate\fR
+the changer when tapes are added to or removed from the library\&.
+.PP
+There is a shell script in the
+contrib/
+directory of Amanda\*(Aqs source distribution which can help you convert a
+\fBchg\-zd\-mtx\fR
+configuration into a
+\fBchg\-robot\fR
+configuration\&. Just give it your Amanda configuration name:
+.sp
+.nf
+ sh contrib/convert\-zd\-mtx\-to\-robot\&.sh $config
+.fi
+The script can be downloaded at
+http://github\&.com/zmanda/amanda/raw/master/contrib/convert\-zd\-mtx\-to\-robot\&.sh
+.SS "Special Operations"
+.PP
+A number of special operations are available for
+\fBchg\-robot\fR
+via
+\fBamtape\fR(8)
+subcommands\&.
+.PP
+The
+\fBreset\fR
+subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer\&.
+.PP
+The
+\fBeject\fR
+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\&.
+.PP
+The
+\fBclean\fR
+subcommand is not yet implemented\&.
+.PP
+The
+\fBupdate\fR
+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:
+.sp
+.nf
+amtape CONFIG update 1\-3,9
+.fi
+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:
+.sp
+.nf
+amtape CONFIG update 2=DailySet\-028
+.fi
+In this case, the changer updates its state to indicate that
+DailySet\-028
+is in slot 2, without trying to load the tape\&.
+.sp
+.nf
+amtape CONFIG update 1\-3,9=
+.fi
+In this case, the changer marks the stated slots as an unknown state\&.
+.SS "Properties"
+.PP
+DRIVE\-CHOICE
+.RS 4
+
+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\&.
+.RE
+.PP
+EJECT\-BEFORE\-UNLOAD
+.RS 4
+
+Set this boolean property to true if the library requires an
+\fBoffline\fR operation be performed on the tape drive before it
+can be unloaded\&. If set, then \fBmt\fR will be invoked to
+perform this operation\&. Most libraries do not require this workaround\&.
+.RE
+.PP
+EJECT\-DELAY
+.RS 4
+
+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\&.
+.RE
+.PP
+FAST\-SEARCH
+.RS 4
+
+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\&.
+.RE
+.PP
+IGNORE\-BARCODES
+.RS 4
+
+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\&.
+.RE
+.PP
+LOAD\-POLL
+.RS 4
+This property specifies the timing of Amanda\*(Aqs polling for the tape drive to be ready after loading a new tape\&. See "Timing", below\&.
+.sp
+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
+.sp
+.nf
+"D [poll P [until U]]"
+.fi
+For a simple delay with no polling, use e\&.g\&.,
+.sp
+.nf
+property "load\-poll" "13s"
+.fi
+To delay and then poll, use e\&.g\&.,
+.sp
+.nf
+property "load\-poll" "13s poll 5s"
+.fi
+and to add a maximum total time, use e\&.g\&.,
+.sp
+.nf
+property "load\-poll" "0s poll 5s until 2m"
+.fi
+The default value is
+\fB"0s poll 3s until 2m"\fR\&.
+.RE
+.PP
+LOCK\-TIMEOUT
+.RS 4
+
+The time in seconds amanda wait to lock the statefile (default:1000)
+.RE
+.PP
+MTX
+.RS 4
+
+The path to the \*(Aqmtx\*(Aq binary\&. The default value is defined at compile time\&.
+.RE
+.PP
+STATUS\-INTERVAL
+.RS 4
+
+This is the minimum time between invocations of \fBmtx status\fR
+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 \fBmtx
+status\fR takes a considerable time to complete, this value should be
+increased\&. See "Timing", below\&.
+.RE
+.PP
+TAPE\-DEVICE
+.RS 4
+
+This property describes the correspondance of drive numbers in the library to
+Amanda devices, in the format \fIDRIVE=DEVICE\fR\&. The property
+can be specified multiple times to describe multiple devices\&. The device will
+usually be a tape device name starting with \fBtape:\fR, but may
+also refer to a device alias (see \fBamanda-devices\fR(7))\&. As
+a shortcut, if the \fBtapedev\fR parameter is specified in the
+changer definition, then it is assumed to be the device name for drive 0\&.
+.RE
+.PP
+UNLOAD\-DELAY
+.RS 4
+
+This specifies the minimum time between an unload operation any any subsequent
+operation\&. The default value is 0 seconds\&. See "Timing", below\&.
+.RE
+.PP
+USE\-SLOTS
+.RS 4
+
+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\&.
+.RE
+.SS "Timing"
+.PP
+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\&.
+.PP
+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\&.
+.PP
+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\&.
+.PP
+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\&.
+.PP
+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\&.
+.PP
+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\&.
+.PP
+Each of the times specified in these properties may be given as integers with the optional suffix
+\fBs\fR
+for seconds (the default) or
+\fBm\fR
+for minutes\&.
+.SS "chg\-ndmp:HOST[:PORT]@SCSIDEV"
+.nf
+ 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"
+.fi
+.PP
+This changer is very similar to
+\fBchg\-robot\fR, but controls a tape changer on an NDMP server instead of a local device\&. The
+\fBHOST\fR
+in the
+\fBtpchanger\fR
+should be the hostname of the NDMP server\&. The
+\fBPORT\fR
+is optional\&. The
+\fBSCSIDEV\fR
+should specify the SCSI device on the NDMP server which controls the changer\&. The format of this parameter is implementation\-specific\&.
+.PP
+The appropriate authentication properties will be automatically set on any devices created by this changer\&.
+.SS "Properties"
+.PP
+This changer supports all of the properties supported by
+\fBchg\-robot\fR, although the value of
+\fBMTX\fR
+is ignored\&. The following properties are also recognized:
+.PP
+NDMP_AUTH
+.RS 4
+
+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)\&.
+.RE
+.PP
+NDMP\-PASSWORD
+.RS 4
+
+The password for the NDMP server\&.
+.RE
+.PP
+NDMP\-USERNAME
+.RS 4
+
+The username for the NDMP server\&.
+.RE
+.PP
+VERBOSE
+.RS 4
+
+If true, enables the NDMJOB library\*(Aqs verbose (packet\-level) debugging\&.
+.RE
+.SS "chg\-single:DEVICE"
+.nf
+tpchanger "chg\-single:tape:/dev/nst0"
+.fi
+.PP
+This changer is for use with standalone drive, it can work with any device\&. The device (\fBtape:/dev/nst0\fR) must be set in the tpchanger definition\&.
+.PP
+The
+\fBchg\-single\fR
+changer has no property\&.