1 .\" Title: amanda-changers
2 .\" Author: Dustin J. Mitchell <dustin@zmanda.com>
3 .\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
5 .\" Manual: Miscellanea
6 .\" Source: Amanda 2.6.1
9 .TH "AMANDA\-CHANGERS" "7" "01/22/2009" "Amanda 2\&.6\&.1" "Miscellanea"
10 .\" -----------------------------------------------------------------
11 .\" * (re)Define some macros
12 .\" -----------------------------------------------------------------
13 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14 .\" toupper - uppercase a string (locale-aware)
15 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
19 .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
21 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 .\" SH-xref - format a cross-reference to an SH section
23 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33 .\" SH - level-one heading that works better for non-TTY output
34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 .\" put an extra blank line of space above the head in non-TTY output
43 .nr an-prevailing-indent \\n[IN]
47 .HTML-TAG ".NH \\n[an-level]"
49 .nr an-no-space-flag 1
51 \." make the size of the head bigger
56 .\" if n (TTY output), use uppercase
61 .\" if not n (not TTY), use normal case (not uppercase)
65 .\" if not n (not TTY), put a border/line under subheading
70 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71 .\" SS - level-two heading that works better for non-TTY output
72 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77 .nr an-prevailing-indent \\n[IN]
82 .nr an-no-space-flag 1
85 \." make the size of the head bigger
91 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 .\" BB/BE - put background/screen (filled box) around block of text
93 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106 .if "\\$2"adjust-for-leading-newline" \{\
114 .nr BW \\n(.lu-\\n(.i
117 .ie "\\$2"adjust-for-leading-newline" \{\
118 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
121 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
132 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 .\" BM/EM - put colored marker in margin next to block of text
134 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
159 .\" -----------------------------------------------------------------
160 .\" * set default formatting
161 .\" -----------------------------------------------------------------
162 .\" disable hyphenation
164 .\" disable justification (adjust text to left margin only)
166 .\" -----------------------------------------------------------------
167 .\" * MAIN CONTENT STARTS HERE *
168 .\" -----------------------------------------------------------------
170 amanda-changers \- Configuring and Using Amanda Changers
173 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
175 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\&.
178 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
180 .SH "SPECIFYING CHANGERS"
182 Changer specifications are strings like
183 \FCchg\-disk:/my/vtapes\F[]\&. The
185 prefix serves to differentiate changers from devices (see
186 \fBamanda-devices\fR(7))\&. The next portion (\FCdisk\F[], in this case) identifies the particular changer driver to use, and everything that follows the
188 is interpreted by the driver\&.
190 A name which does not match this pattern, but which matches an old changer script (e\&.g\&.,
191 \FCchg\-zd\-mtx\F[]), invokes the backward\-compatibility changer driver as
192 \FCchg\-compat:chg\-zd\-mtx\F[]\&. 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\&.,
193 \FCchg\-single:tape:/dev/rmt/0\F[]\&.
195 Changers which require additional parameters can also be described in
197 with "changer" sections, for example,
200 define changer hp\-robot {
201 tapedev "chg\-robot:/dev/sg1"
202 property "drives" "0=/dev/nst0;1=/dev/nst0"
203 property "slots" "1\-10"
206 (note that "chg\-robot" is not yet implemented, so this is hypothetical)\&. A changer defininition creates a changer "alias", in this case named
207 \fIhp\-robot\fR, which can then be named where an application expects a changer \- for example, the target of the
210 .SH "CHANGER DRIVERS"
212 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\&.
213 .SS "chg\-disk (new)"
215 tpchanger "chg\-disk:/u01/vtapes"
218 This changer driver replaces the old
219 \fBchg\-disk\fR, supporting parallel access to vtapes stored in directories named
221 in the directory specified after
222 \FCchg\-disk:\F[]\&. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots\&.
223 .SS "chg\-disk (old)"
225 tapedev "file:/u01/vtapes"
226 tpchanger "chg\-disk"
229 This changer script supports sequential access to vtapes stored in directories named
231 in the directory specified by the
236 tpchanger "chg\-multi"
237 changerfile "chg\-multi\-state"
240 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
242 need not exist; it is used as a prefix for filenames of state files\&.
245 tpchanger "chg\-manual"
246 changerfile "chg\-manual\&.conf"
249 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):
252 resend_mail=900 # resend mail every __ seconds
253 timeout_mail=604800 # time out after this many seconds (default 7 days)
254 request="[type]" # How to request a new tape (default "tty_email")
255 request="tty" # Use the tty to ask the user to change tape\&.
256 # Can\'t be use by cron
257 request="email" # Send an email to ask the user to change tape\&.
258 request="tty_email" # Use the tty if it exist or send an email\&.
262 tpchanger "chg\-zd\-mtx"
263 changerdev "/dev/sg0" # used with \'mtx \-f\'
264 changerfile "chg\-zd\-mtx\&.conf"
265 tapedev "tape:/dev/nst0"
268 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
270 option and has subcommands like
271 \fBstatus\fR\&. The configuration file parameters are (as listed in the script itself):
274 firstslot=? #### First storage slot (element)
275 lastslot=? #### Last storage slot (element)
276 cleanslot=\-1 #### Slot with cleaner tape \-\- default is "\-1"
277 #### Set negative to indicate no cleaner available
278 driveslot=0 #### Drive slot number\&. Defaults to 0
279 #### Use the \'Data Transfer Element\' you want
280 autoclean=0 #### Set to \'1\' or greater to enable
281 autocleancount=99 #### Number of access before a clean\&.
282 havereader=0 #### If you have a barcode reader, set to 1\&.
283 offline_before_unload=0 #### Does your robot require an
284 #### \'mt offline\' before mtx unload?
285 poll_drive_ready=NN #### Time (seconds) between tests to see if
286 #### the tape drive has gone ready (default: 3)\&.
287 max_drive_wait=NN #### Maximum time (seconds) to wait for the
288 #### tape drive to become ready (default: 120)\&.
289 initial_poll_delay=NN #### initial delay after load before polling for
291 slotinfofile=FILENAME #### record slot information to this file, in
292 #### the line\-based format "SLOT LABEL\en"
296 tpchanger "chg\-rait"
297 changerfile "chg\-rait\&.conf"
300 This changer script constructs RAIT devices out of the devices provided by several "sub\-changers"\&. The configuration file specifies
301 \FCnchangers\F[], the number of subchangers, and then provides
304 \FCchangerfile_N\F[], and
306 for each sub\-changer, 1 through N\&.
309 tpchanger "chg\-null"
312 This changer always provides the device "null:"\&. It is sometimes useful in conjunction with
314 .SS "Unmaintained Changers"
316 Amanda has many other changer scripts and programs beyond those described here (see the
318 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\&.
323 \fBamanda.conf\fR(5),
324 \fBamanda-devices\fR(7),
327 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
329 Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])