'\" t
.\" Title: amanda-changers
.\" Author: Dustin J. Mitchell <dustin@zmanda.com>
-.\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
-.\" Date: 06/01/2010
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\" Date: 01/10/2013
.\" Manual: Miscellanea
-.\" Source: Amanda 3.1.0
+.\" Source: Amanda 3.3.3
.\" Language: English
.\"
-.TH "AMANDA\-CHANGERS" "7" "06/01/2010" "Amanda 3\&.1\&.0" "Miscellanea"
+.TH "AMANDA\-CHANGERS" "7" "01/10/2013" "Amanda 3\&.3\&.3" "Miscellanea"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
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\&.
.PP
-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\&.
+The Changer API strives to treat all changers identically, so that Amanda\*(Aqs 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\&.
.SH "SPECIFYING CHANGERS"
.PP
Changer specifications are strings like
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"
+ device\-property "BLOCK_SIZE" "512k"
}
# \&.\&.\&.
tapedev "hp\-robot"
.PP
Devices, too, can take properties to control their behavior (see
\fBamanda-devices\fR(7))\&. Device properties can come from four places: implicit device properties (from tapetype parameters), global device properties (from global
-\fIdevice_property\fR
+\fIdevice\-property\fR
parameters), properties in device definitions, and properties in changer definitions\&. Properties are applied in this order, with later properties taking priority\&.
.PP
There are only three implicit properties:
.SH "CHANGER DRIVERS"
.PP
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\&.
+.SS "chg\-aggregate:changer (new)"
+.nf
+define changer robot0 {
+ tpchanger "chg\-robot:/dev/sg0"
+ property "tape\-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
+}
+define changer robot1 {
+ tpchanger "chg\-robot:/dev/sg1"
+ property "tape\-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
+}
+define changer single {
+ tpchanger "chg\-single:/dev/rmt/4"
+}
+define changer aggregate {
+ tpchanger "chg\-aggregate:{robot0,robot1,single}"
+ property "state\-filename" "/etc/amanda/CONF/aggregate\&.state"
+
+}
+tpchanger "aggregate"
+.fi
+.PP
+This changer driver allow to use two or more changers or standalone drive in sequence\&.
+.SS "Properties"
+.PP
+LOCK\-TIMEOUT
+.RS 4
+
+The time in seconds amanda wait to lock the statefile (default:1000)
+.RE
+.PP
+STATE_FILENAME
+.RS 4
+
+The name of the state file (default: "$CONFIG_DIR/$changer_name\&.state"\&.
+.RE
.SS "chg\-disk:VTAPEROOT (new)"
.nf
-tpchanger "chg\-disk:/u01/vtapes"
+tpchanger "chg\-disk:/var/mnt/vtapes"
+property "num\-slot" "10"
+property "auto\-create\-slot" "yes"
+property "removable" "yes"
+property "mount" "yes"
+property "umount" "yes"
+property "umount\-lockfile" "/etc/amanda/conf/vtapes\-lock"
+property "umount\-idle" "1"
.fi
.PP
This changer driver replaces the old
file:VTAPEROOT\&. This is useful for the
\fBamrestore\fR(8)
command line\&.
+.SS "Properties"
+.PP
+AUTO\-CREATE\-SLOT
+.RS 4
+
+If a slotN directory in the range 1 to NUM\-SLOT does not already exist, and this property is true, then the changer will create the directory\&.
+.RE
+.PP
+LOCK\-TIMEOUT
+.RS 4
+
+The time in seconds amanda wait to lock the statefile (default:1000)
+.RE
+.PP
+MOUNT
+.RS 4
+
+If this property is true, the changer try to mount the removable disk if nothing is mounted\&. The system must be configured to allow the amanda user to mount it\&.
+.RE
+.PP
+NUM\-SLOT
+.RS 4
+
+The minimum number of slots in the changer, where the first slot is slot1\&. If additional slot directories exist, they will also be used\&.
+.RE
+.PP
+REMOVABLE
+.RS 4
+
+If this property is true, then the changer will verify that the changer
+directory (e\&.g\&., /var/mnt/vtapes) is on a different
+filesystem from its parent directory (e\&.g\&., /var/mnt)\&.
+This is useful for removable disks, as it will prevent Amanda from creating
+slot directories when the removable disk is not mounted\&.
+.RE
+.PP
+UMOUNT
+.RS 4
+
+If this property is true, the changer try to umount the removable disk when it exit\&. The system must be configured to allow the amanda user to umount it\&.
+.RE
+.PP
+UMOUNT\-LOCKFILE
+.RS 4
+
+If UMOUNT is set, it require a lockfile outside of the mount point to prevent race\&.
+.RE
+.PP
+UMOUNT\-IDLE
+.RS 4
+
+If set, the changer try to umount the removable disk when it is not in use\&. The umount\-idle value is a delay in second to wait before doing the umount\&. A value >= 1 is required to prevent useless mount/umount\&.
+.RE
.SS "chg\-disk (old)"
.nf
tapedev "file:/u01/vtapes"
\fIchangerfile\fR
must exist; it is used to save the state file\&.
.PP
+The child devices are specified using the same syntax as for the RAIT device (see
+\fBamanda-changers\fR(7))\&. The range specification can be especially useful here:
+.sp
+.nf
+tpchanger "chg\-multi:s3:mycompany\-backups/tape\-{001\&.\&.100}"
+.fi
+.PP
This changer is not fast\-search capable\&.
.SS "Properties"
.PP
This property gives the number of the first slot\&. The default value is "1"\&.
.RE
+.PP
+LOCK\-TIMEOUT
+.RS 4
+
+The time in seconds amanda wait to lock the statefile (default:1000)
+.RE
.SS "Special Operations"
.PP
A number of special operations are available for
.PP
multieject
.RS 4
-If this is 1, use an \'mt
-offline\' command to change to the next tape, or multiple such commands for
+If this is 1, use an \*(Aqmt
+offline\*(Aq command to change to the next tape, or multiple such commands for
skipping several tapes at a time\&.
.RE
.PP
needeject
.RS 4
This option is incompatible with
-\'multieject\'\&. This should be 1 for changers accessed through several virtual
+\*(Aqmultieject\*(Aq\&. 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\&.
.RE
.RS 4
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
+last one, or if you don\*(Aqt want amanda to go through the tape stack looking for
the exact tape it wants instead of using the first acceptable one\&.
.RE
.PP
slot X
.RS 4
The configuration file should list
-as many \'slot X\' statements as the number of slots supported by the changer or
+as many \*(Aqslot X\*(Aq statements as the number of slots supported by the changer or
the number of separate tape drives used\&.
.RE
.PP
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
+ # Can\*(Aqt 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\&.
.fi
.SS "chg\-zd\-mtx (old)"
.nf
tpchanger "chg\-zd\-mtx"
-changerdev "/dev/sg0" # used with \'mtx \-f\'
+changerdev "/dev/sg0" # used with \*(Aqmtx \-f\*(Aq
changerfile "chg\-zd\-mtx\&.conf"
tapedev "tape:/dev/nst0"
.fi
.PP
-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
+This script interfaces with a tape drive using the Zubkoff/Dandelion version of mtx\&. That\*(Aqs the version that takes a device specifier with the
\fB\-f\fR
option and has subcommands like
\fBstatus\fR\&. The configuration file parameters are (as listed in the script itself):
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
+ #### Use the \*(AqData Transfer Element\*(Aq you want
+autoclean=0 #### Set to \*(Aq1\*(Aq 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?
+ #### \*(Aqmt offline\*(Aq 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
.SS "chg\-rait:{CHILD1,CHILD2,\&.\&.}"
.nf
define changer vtape {
- tpcanger "chg\-disk:/path/to/vtape"
+ tpchanger "chg\-disk:/path/to/vtape"
}
define changer robot {
tpchanger "chg\-robot:/dev/sg0"
tpchanger "robot"
.fi
.PP
-This changer drives a robotic tape library using the operating system\'s
+This changer drives a robotic tape library using the operating system\*(Aqs
\fBmtx\fR
command\&. It replaces the ancient
\fBchg\-zd\-mtx\fR
.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\'s state is inaccurate, use the
+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
There is a shell script in the
contrib/
-directory of Amanda\'s source distribution which can help you convert a
+directory of Amanda\*(Aqs source distribution which can help you convert a
\fBchg\-zd\-mtx\fR
configuration into a
\fBchg\-robot\fR
.PP
LOAD\-POLL
.RS 4
-This property specifies the timing of Amanda\'s polling for the tape drive to be ready after loading a new tape\&. See "Timing", below\&.
+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
\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 \'mtx\' binary\&. The default value is defined at compile time\&.
+The path to the \*(Aqmtx\*(Aq binary\&. The default value is defined at compile time\&.
.RE
.PP
STATUS\-INTERVAL
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\&.
.SS "Unmaintained Changers"
.PP
Amanda has many other changer scripts and programs beyond those described here (see the
projects / debian / amanda / blobdiff