2 .\" Title: amanda-changers
3 .\" Author: Dustin J. Mitchell <dustin@zmanda.com>
4 .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
6 .\" Manual: Miscellanea
7 .\" Source: Amanda 2.6.1p2
10 .TH "AMANDA\-CHANGERS" "7" "11/05/2009" "Amanda 2\&.6\&.1p2" "Miscellanea"
11 .\" -----------------------------------------------------------------
12 .\" * set default formatting
13 .\" -----------------------------------------------------------------
14 .\" disable hyphenation
16 .\" disable justification (adjust text to left margin only)
18 .\" -----------------------------------------------------------------
19 .\" * MAIN CONTENT STARTS HERE *
20 .\" -----------------------------------------------------------------
22 amanda-changers \- Configuring and Using Amanda Changers
25 Amanda uses changers to arbitrate access to devices (\fBamanda-devices\fR(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
27 overview of the API, and does not address details that are only of concern to developers\&. For that purpose, consult the Amanda source code and http://wiki\&.zmanda\&.com\&.
30 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
32 .SH "SPECIFYING CHANGERS"
34 Changer specifications are strings like
35 chg\-disk:/my/vtapes\&. The
37 prefix serves to differentiate changers from devices (see
38 \fBamanda-devices\fR(7))\&. The next portion (disk, in this case) identifies the particular changer driver to use, and everything that follows the
40 is interpreted by the driver\&.
42 A name which does not match this pattern, but which matches an old changer script (e\&.g\&.,
43 chg\-zd\-mtx), invokes the backward\-compatibility changer driver as
44 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\&.,
45 chg\-single:tape:/dev/rmt/0\&.
47 Changers which require additional parameters can also be described in
49 with "changer" sections, for example,
52 define changer hp\-robot {
53 tapedev "chg\-robot:/dev/sg1"
54 property "drives" "0=/dev/nst0;1=/dev/nst0"
55 property "slots" "1\-10"
58 (note that "chg\-robot" is not yet implemented, so this is hypothetical)\&. A changer defininition creates a changer "alias", in this case named
59 \fIhp\-robot\fR, which can then be named where an application expects a changer \- for example, the target of the
64 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\&.
67 tpchanger "chg\-disk:/u01/vtapes"
70 This changer driver replaces the old
71 \fBchg\-disk\fR, supporting parallel access to vtapes stored in directories named
73 in the directory specified after
74 chg\-disk:\&. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots\&.
77 tapedev "file:/u01/vtapes"
81 This changer script supports sequential access to vtapes stored in directories named
83 in the directory specified by the
88 tpchanger "chg\-multi"
89 changerfile "chg\-multi\-state"
92 This script simply round\-robins a number of distinct device names, as specified in its configuration file\&. It is useful when all volumes for a configuration have different device names \-\- for example, with S3 devices\&. The
94 need not exist; it is used as a prefix for filenames of state files\&.
97 tpchanger "chg\-manual"
98 changerfile "chg\-manual\&.conf"
101 This script simply provides distinct device names in a round\-robin fashion, as specified in its configuration file\&. It is useful when all volumes for a configuration have different device names \-\- for example, with S3 devices\&. The configuration file parameters are (as listed in the script):
104 resend_mail=900 # resend mail every __ seconds
105 timeout_mail=604800 # time out after this many seconds (default 7 days)
106 request="[type]" # How to request a new tape (default "tty_email")
107 request="tty" # Use the tty to ask the user to change tape\&.
108 # Can\'t be use by cron
109 request="email" # Send an email to ask the user to change tape\&.
110 request="tty_email" # Use the tty if it exist or send an email\&.
114 tpchanger "chg\-zd\-mtx"
115 changerdev "/dev/sg0" # used with \'mtx \-f\'
116 changerfile "chg\-zd\-mtx\&.conf"
117 tapedev "tape:/dev/nst0"
120 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
122 option and has subcommands like
123 \fBstatus\fR\&. The configuration file parameters are (as listed in the script itself):
126 firstslot=? #### First storage slot (element)
127 lastslot=? #### Last storage slot (element)
128 cleanslot=\-1 #### Slot with cleaner tape \-\- default is "\-1"
129 #### Set negative to indicate no cleaner available
130 driveslot=0 #### Drive slot number\&. Defaults to 0
131 #### Use the \'Data Transfer Element\' you want
132 autoclean=0 #### Set to \'1\' or greater to enable
133 autocleancount=99 #### Number of access before a clean\&.
134 havereader=0 #### If you have a barcode reader, set to 1\&.
135 offline_before_unload=0 #### Does your robot require an
136 #### \'mt offline\' before mtx unload?
137 poll_drive_ready=NN #### Time (seconds) between tests to see if
138 #### the tape drive has gone ready (default: 3)\&.
139 max_drive_wait=NN #### Maximum time (seconds) to wait for the
140 #### tape drive to become ready (default: 120)\&.
141 initial_poll_delay=NN #### initial delay after load before polling for
143 slotinfofile=FILENAME #### record slot information to this file, in
144 #### the line\-based format "SLOT LABEL\en"
148 tpchanger "chg\-rait"
149 changerfile "chg\-rait\&.conf"
152 This changer script constructs RAIT devices out of the devices provided by several "sub\-changers"\&. The configuration file specifies
153 nchangers, the number of subchangers, and then provides
158 for each sub\-changer, 1 through N\&.
161 tpchanger "chg\-null"
164 This changer always provides the device "null:"\&. It is sometimes useful in conjunction with
166 .SS "Unmaintained Changers"
168 Amanda has many other changer scripts and programs beyond those described here (see the
170 in the source directory), but most of these scripts are unmaintained and undocumented, and will be removed when the new changer API is fully implemented\&.
175 \fBamanda.conf\fR(5),
176 \fBamanda-devices\fR(7),
179 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
181 Zmanda, Inc\&. (http://www\&.zmanda\&.com)