1AMANDA-CHANGERS(7) Miscellanea AMANDA-CHANGERS(7)
2
6 amanda-changers - Configuring and Using Amanda Changers
7
9 Amanda uses changers to arbitrate access to devices (amanda-devices(7))
10 and data volumes. Changers provide an abstraction of tape robots, but
11 are used to manage non-tape media, too. Amanda communicates with
12 changers through the Changer API. This manpage contains a user-level
13 overview of the API, and does not address details that are only of
14 concern to developers. For that purpose, consult the Amanda source code
15 and http://wiki.zmanda.com.
16
18 The Amanda Changer API is in transition from version 1.0 - driven by
19 shell scripts invoked for each changer operation - to version 2.0,
20 composed of perl objects that can manage parallel access to multiple
21 devices and other complexity. At this point, all Amanda programs use
22 the new Changer API directly, although 1.0 changer scripts are still
23 fully supported via chg-compat.
24 The Changer API strives to treat all changers identically, so that
26 Amanda´s behavior is independent of the changer in use. However, some
27 parts of Amanda operate differently depending on whether a changer can
28 efficiently search for a volume with a given label. This distinction is
29 really only apparent with tape libraries: those with barcode readers
30 can quickly find a desired tape, while those without may fall back to
31 an inefficient scan of each volume. The capability to perform quick
32 searches is called "fast-search", and each changer is annotated below
33 to indicate its support.
34
36 Changer specifications are strings like chg-disk:/my/vtapes. The chg-
37 prefix serves to differentiate changers from devices (see amanda-
38 devices(7)). The next portion (disk, in this case) identifies the
39 particular changer driver to use, and everything that follows the : is
40 interpreted by the driver. Note that the : character is required, even
41 when nothing follows it. This is an easy way to distinguish new changer
42 specifications from old.
43 A name which does not match this pattern, but which matches an old
45 changer script (e.g., chg-zd-mtx), invokes the backward-compatibility
46 changer driver as e.g., chg-compat:chg-zd-mtx. If the name does not
47 match an old changer, then it is treated as an Amanda device, and is
48 wrapped by the single-device changer, e.g., chg-single:tape:/dev/rmt/0.
49 Changers which require additional parameters can also be described in
51 amanda.conf(5) with "changer" sections. Such a changer defininition
52 creates a changer "alias", in this case named hp-robot, which can then
53 be named where an application expects a changer - for example, the
54 target of the amvault command or in a global tpchanger parameter.
55 CONFIGURATION
57 The preferred method of specifying configuration for a changer is as a
58 "changer" section in amanda.conf(5). The tapedev parameter then
59 indicates, by name, the changer that will be used by default by most
60 Amanda programs. For example:
61 define changer hp-robot {
63 tapedev "chg-robot:/dev/sg1"
64 property "tape-device" "0=tape:/dev/nst0"
65 property append "tape-device" "1=tape:/dev/nst1"
66 device_property "BLOCK_SIZE" "512k"
67 }
68 # ...
69 tapedev "hp-robot"
70 Several changer drivers accept changer properties which control the
72 behavior of the changer. These properties must be specified in a
73 changer definition, as in the hp-robot example, above.
74 Devices, too, can take properties to control their behavior (see
76 amanda-devices(7)). Device properties can come from four places:
77 implicit device properties (from tapetype parameters), global device
78 properties (from global device_property parameters), properties in
79 device definitions, and properties in changer definitions. Properties
80 are applied in this order, with later properties taking priority.
81 There are only three implicit properties: MAX_VOLUME_USAGE is set based
83 on the tapetype length parameter, READ_BLOCK_SIZE is set if
84 readblocksize is set, and BLOCK_SIZE is set based on the blocksize
85 parameter.
86 Global device properties always apply. If the changer specifies a
88 device by alias, then device properties from the definition apply. If
89 the changer is specified by an alias, then properties from that
90 definition applied.
91
93 This section lists the changer drivers included with Amanda, and basic
94 instructions for using them. For complete How-To information, consult
95 the Amanda wiki at http://wiki.zmanda.com.
96 chg-disk:VTAPEROOT (new)
98 tpchanger "chg-disk:/u01/vtapes"
99 This changer driver replaces the old chg-disk, supporting parallel
101 access to vtapes stored in directories named slotN in the directory
102 specified after chg-disk:. It does so by creating numbered "drives" so
103 that simultaneous processes can access distinct slots. This changer is
104 fast-search capable.
105 The current slot can be accessed using the device name file:VTAPEROOT.
107 This is useful for the amrestore(8) command line.
108 chg-disk (old)
110 tapedev "file:/u01/vtapes"
111 tpchanger "chg-disk"
112 changerfile "chg-disk.conf" # optional file
113 This changer script supports sequential access to vtapes stored in
115 directories named slotN in the directory specified by the tapedev
116 parameter. The configuration file parameter is:
117 LASTSLOT=number # The number of slots, default to tapecycle setting.
119 This changer is not fast-search capable.
121 chg-multi:DEVICE-LIST
123 tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
124 changerfile "chg-multi-state"
125 This script simply round-robins a number of distinct device names, as
127 specified in the tpchanger setting. It is useful when all volumes for a
128 configuration have different device names -- for example, if you have
129 many standalone drive. The changerfile must exist; it is used to save
130 the state file.
131 This changer is not fast-search capable.
133 Properties
135 FIRST-SLOT
136 This property gives the number of the first slot. The default value
138 is "1".
139 Special Operations
141 A number of special operations are available for chg-multi via
142 amtape(8) subcommands.
143 The reset subcommand will change the current slot to the first
145 available slot, but does not erase any stored state maintained by the
146 changer.
147 The eject subcommand will eject the volume in the given drive
149 The clean subcommand is not yet implemented.
151 The update subcommand instructs the changer to update its state
153 database. Given no arguments, the changer will scan all available
154 slots, loading each tape and reading its label. Especially for large
155 libraries, this can take a long time. If only a few slots have changed,
156 they can be listed on the command line:
157 amtape CONFIG update 1-3,9
159 In this case, the changer will only scan the stated slots. Finally, the
160 changer will not scan at all if it is given the tape label for the
161 slot:
162 amtape CONFIG update 2=DailySet-028
164 In this case, the changer updates its state to indicate that
165 DailySet-028 is in slot 2, without trying to load the tape.
166 amtape CONFIG update 1-3,9=
168 In this case, the changer marks the stated slots as an unknown state.
169 chg-multi (old)
171 tpchanger "chg-multi"
172 changerfile "chg-multi-state"
173 This script simply round-robins a number of distinct device names, as
175 specified in its configuration file. It is useful when all volumes for
176 a configuration have different device names -- for example, with S3
177 devices. The changerfile need not exist; it is used as a prefix for
178 filenames of state files.
179 The configuration file has simple lines with a parameter and its value
181 separated by a space. The # character introduces a comment. The
182 configuration parameters are:
183 multieject
185 If this is 1, use an ´mt offline´ command to change to the next
186 tape, or multiple such commands for skipping several tapes at a
187 time.
188 needeject
190 This option is incompatible with ´multieject´. This should be 1 for
191 changers accessed through several virtual tape devices, when the
192 changer needs the current tape to be ejected before changing to
193 another device.
194 gravity
196 Set this to 1 if the changer/stacker is unable to loop back to the
197 first tape after unloading the last one, or if you don´t want
198 amanda to go through the tape stack looking for the exact tape it
199 wants instead of using the first acceptable one.
200 slot X
202 The configuration file should list as many ´slot X´ statements as
203 the number of slots supported by the changer or the number of
204 separate tape drives used.
205 This changer is not fast-search capable.
207 chg-manual
209 tpchanger "chg-manual"
210 changerfile "chg-manual.conf"
211 This script simply provides distinct device names in a round-robin
213 fashion, as specified in its configuration file. It is useful when all
214 volumes for a configuration have different device names -- for example,
215 with S3 devices. The configuration file parameters are (as listed in
216 the script):
217 resend_mail=900 # resend mail every __ seconds
219 timeout_mail=604800 # time out after this many seconds (default 7 days)
220 request="[type]" # How to request a new tape (default "tty_email")
221 request="tty" # Use the tty to ask the user to change tape.
222 # Can´t be use by cron
223 request="email" # Send an email to ask the user to change tape.
224 request="tty_email" # Use the tty if it exist or send an email.
225 This changer is not fast-search capable.
227 chg-zd-mtx (old)
229 tpchanger "chg-zd-mtx"
230 changerdev "/dev/sg0" # used with ´mtx -f´
231 changerfile "chg-zd-mtx.conf"
232 tapedev "tape:/dev/nst0"
233 This script interfaces with a tape drive using the Zubkoff/Dandelion
235 version of mtx. That´s the version that takes a device specifier with
236 the -f option and has subcommands like status. The configuration file
237 parameters are (as listed in the script itself):
238 firstslot=? #### First storage slot (element)
240 lastslot=? #### Last storage slot (element)
241 cleanslot=-1 #### Slot with cleaner tape -- default is "-1"
242 #### Set negative to indicate no cleaner available
243 driveslot=0 #### Drive slot number. Defaults to 0
244 #### Use the ´Data Transfer Element´ you want
245 autoclean=0 #### Set to ´1´ or greater to enable
246 autocleancount=99 #### Number of access before a clean.
247 havereader=0 #### If you have a barcode reader, set to 1.
248 offline_before_unload=0 #### Does your robot require an
249 #### ´mt offline´ before mtx unload?
250 poll_drive_ready=NN #### Time (seconds) between tests to see if
251 #### the tape drive has gone ready (default: 3).
252 max_drive_wait=NN #### Maximum time (seconds) to wait for the
253 #### tape drive to become ready (default: 120).
254 initial_poll_delay=NN #### initial delay after load before polling for
255 #### readiness
256 slotinfofile=FILENAME #### record slot information to this file, in
257 #### the line-based format "SLOT LABEL\n"
258 This changer is fast-search capable if and only if havereader is true.
260 chg-rait:{CHILD1,CHILD2,..}
262 define changer vtape {
263 tpcanger "chg-disk:/path/to/vtape"
264 }
265 define changer robot {
266 tpchanger "chg-robot:/dev/sg0"
267 tapedev "tape:/dev/nst0"
268 }
269 tpchanger "chg-rait:{vtape,robot}"
270 This changer script constructs RAIT devices out of the devices provided
272 by several "sub-changers". The sub-changers are specified using the
273 same shell-like syntax as the RAIT device (see amanda-devices(7)).
274 Chg-rait does not require that all of the child changers have the same
276 slot names: compound slot names are created by combining the slot names
277 supplied by the child changers using the same shell-like syntax. For
278 example, if the child changers return slots "top", "strange", and "3",
279 then the RAIT changer will return "{top,strange,3}". This makes it
280 possible to, for example, mirror data on tapes in slots 1-10 to tapes
281 in slots 11-20 of the same robot, using two chg-zd-mtx child changers
282 (and, naturally, two tape drives). In this arrangement, the first slot
283 would be named {1,11}.
284 As a convenience to the user, the RAIT changer will also accept
286 un-braced slot names, and supply the same name to each child changer.
287 Thus with a 4-device RAIT changer, "17" is equivalent to
288 "{17,17,17,17}".
289 Drive names are parsed in a similar fashion, for operations that take
291 drive names (clean and eject).
292 This changer is fast-search capable only if all of its child changers
294 are fast-search capable.
295 Note
297 The old chg-rait script is no longer supported nor shipped with
298 Amanda, although the old script will continue to function via
299 chg-compat, giving users time to upgrade their configuration.
300 chg-null:
302 tpchanger "chg-null:"
303 This changer always provides the device "null:". It is sometimes useful
305 in conjunction with chg-rait:.
306 chg-robot:DEVICE
308 define changer robot {
309 tpchanger "chg-robot:/dev/sg0"
310 property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
311 property "eject-before-unload" "yes"
312 property "use-slots" "1-5,11-20"
313 }
314 tpchanger "robot"
315 This changer drives a robotic tape library using the operating system´s
317 mtx command. It replaces the ancient chg-zd-mtx script. The changer
318 uses all of the information available to operate as efficiently as
319 possible. Even without a barcode reader, the changer can usually load a
320 tape immediately, without resorting to a sequential scan of many tapes.
321 It is capable of sharing state across multiple Amanda configurations,
322 avoiding conflicts and optimally tracking the contents of the library.
323 This changer does not accept a changerdev parameter, but the
325 changerfile parameter can be used to specify a filename at which it
326 should store its state. Ordinarily, this state is stored in a file
327 named after the changer device under $localstatedir/amanda, e.g.,
328 /var/amanda/chg-robot-dev-sg0. There should be a single such statefile
329 for each distinct tape library attached to the Amanda server, even if
330 multiple Amanda configurations reference that library.
331 With a barcode reader present, it is possible for chg-robot to track
333 the state of the library reliably, even recognizing tapes that are
334 removed and later re-inserted (by remembering their barcodes). Without
335 barcodes, the changer can still remember the slot in which it last saw
336 the tape with a particular label, although this information can become
337 stale if the tapes are rearranged by an operator. In any case, the
338 changer will never "hunt" for a tape by repeatedly loading slots and
339 checking labels. If the changer´s state is inaccurate, use the
340 amtape(8) subcommand update.
341 This changer is fast-search capable even without a barcode reader. For
343 such libraries, it is the responsibility of the operator to update the
344 changer when tapes are added to or removed from the library.
345 There is a shell script in the contrib/ directory of Amanda´s source
347 distribution which can help you convert a chg-zd-mtx configuration into
348 a chg-robot configuration. Just give it your Amanda configuration name:
349 sh contrib/convert-zd-mtx-to-robot.sh $config
351 The script can be downloaded at
352 http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh
353 Special Operations
355 A number of special operations are available for chg-robot via
356 amtape(8) subcommands.
357 The reset subcommand will change the current slot to the first
359 available slot, but does not erase any stored state maintained by the
360 changer.
361 The eject subcommand will unload the volume in the given drive,
363 ejecting first if the changer properties dictate. Note that, despite
364 the subcommand name, the changer attempts to avoid the state where a
365 volume has been ejected from the drive but not unloaded back to a
366 storage slot.
367 The clean subcommand is not yet implemented.
369 The update subcommand instructs the changer to update its state
371 database. Given no arguments, the changer will scan all available
372 slots, loading each tape and reading its label. Especially for large
373 libraries, this can take a long time. If only a few slots have changed,
374 they can be listed on the command line:
375 amtape CONFIG update 1-3,9
377 In this case, the changer will only scan the stated slots. Finally, the
378 changer will not scan at all if it is given the tape label for the
379 slot:
380 amtape CONFIG update 2=DailySet-028
382 In this case, the changer updates its state to indicate that
383 DailySet-028 is in slot 2, without trying to load the tape.
384 amtape CONFIG update 1-3,9=
386 In this case, the changer marks the stated slots as an unknown state.
387 Properties
389 DRIVE-CHOICE
390 This property controls the algorithm used to select a drive in
392 which to load a tape. If set to the default ("lru"), the changer
393 attempts to use the least recently used drive, resulting in a
394 round-robin behavior. The "firstavail" algorithm selects the first
395 available drive, thus preferring the first drive specified via the
396 TAPE-DEVICE property.
397 EJECT-BEFORE-UNLOAD
399 Set this boolean property to true if the library requires an
401 offline operation be performed on the tape drive before it can be
402 unloaded. If set, then mt will be invoked to perform this
403 operation. Most libraries do not require this workaround.
404 EJECT-DELAY
406 This is the time between ejecting a tape and unloading the volume
408 to a storage slot, and defaults to 0 seconds. It is only used if
409 EJECT-BEFORE-UNLOAD is true. See "Timing", below.
410 FAST-SEARCH
412 This boolean property indicates whether the changer advertises the
414 ability to find volumes without sequential scanning. The
415 traditional taperscan algorithm alters its behavior based on this
416 flag, so it is sometimes necessary to adjust it, although the
417 changer will always search for a desired tape using the most
418 efficient means available. The default value is true.
419 IGNORE-BARCODES
421 If this boolean property is true, then chg-robot will ignore any
423 barcode information that the library provides. This property is
424 probably only useful when the library returns incorrect barcodes,
425 for example due to a malfunction in the barcode reader.
426 LOAD-POLL
428 This property specifies the timing of Amanda´s polling for the tape
429 drive to be ready after loading a new tape. See "Timing", below.
430 The script "polls" by trying to open the tape device repeatedly
432 until no error is encountered. The property specifies the time to
433 wait before the first poll (D), the frequency at which to poll and
434 retry on errors (P); and the time after which it should give up
435 (U). The format is
436 "D [poll P [until U]]"
438 For a simple delay with no polling, use e.g.,
439 property "load-poll" "13s"
441 To delay and then poll, use e.g.,
442 property "load-poll" "13s poll 5s"
444 and to add a maximum total time, use e.g.,
445 property "load-poll" "0s poll 5s until 2m"
447 The default value is "0s poll 3s until 2m".
448 MTX
450 The path to the ´mtx´ binary. The default value is defined at
452 compile time.
453 STATUS-INTERVAL
455 This is the minimum time between invocations of mtx status to
457 determine the state of the changer library. The default value, 2
458 seconds, avoids back-to-back status invocations but ensures that
459 the metadata is up to date. For operating systems or libraries
460 where the mtx status takes a considerable time to complete, this
461 value should be increased. See "Timing", below.
462 TAPE-DEVICE
464 This property describes the correspondance of drive numbers in the
466 library to Amanda devices, in the format DRIVE=DEVICE. The
467 property can be specified multiple times to describe multiple
468 devices. The device will usually be a tape device name starting
469 with tape:, but may also refer to a device alias (see amanda-
470 devices(7)). As a shortcut, if the tapedev parameter is specified
471 in the changer definition, then it is assumed to be the device name
472 for drive 0.
473 UNLOAD-DELAY
475 This specifies the minimum time between an unload operation any any
477 subsequent operation. The default value is 0 seconds. See
478 "Timing", below.
479 USE-SLOTS
481 This property, if specifies, enumerates the slots to which this
483 changer should limit itself. The slots are specified as a
484 comma-separated list of ranges, e.g., "1-5,11-15,19,22". The
485 property can be specified more than once, and the resulting sets
486 will be combined. The changer will refuse to load tapes not found
487 in these slots, except for import/export purposes.
488 Timing
490 Tape libraries are fickle, and in many cases will report that an
491 operation is complete when it is still in progress. Chg-robot takes
492 several timing-related properties to accomodate such behavior.
493 A typical sequence of operations performed during a load are: get
495 library status, eject a tape, unload the tape back to a storage slot,
496 load a new tape, and read the label on that tape to ensure the drive is
497 ready.
498 On most systems, the library status check is nearly instantaneous --
500 the changer library provides its cached state to the host without
501 initiating any robot motion. In order to keep its metadata up-to-date,
502 chg-robot runs this command very frequently, but this frequency can be
503 reduced (at the cost of potentially stale metadata) by setting the
504 STATUS-INTERVAL property to a larger value.
505 Some tape libraries do not integrate the eject operation (performed by
507 the embedded tape drive) with the unload operation (performed by the
508 library robot), and can actually cause physical damage by attempting to
509 remove the tape before the ejection is complete. For such changers, set
510 the EJECT-DELAY property to allow enough time for the eject to
511 complete.
512 Once a tape is unloaded, if the library needs time to "quiesce" before
514 processing another command, add that time to the UNLOAD-DELAY
515 parameter. No other operations will be performed on the library until
516 this delay has elapsed.
517 Once a tape has been loaded, chg-robot waits until the drive is ready
519 before allowing Amanda to use the volume, as described for LOAD-POLL,
520 above.
521 Each of the times specified in these properties may be given as
523 integers with the optional suffix s for seconds (the default) or m for
524 minutes.
525 chg-ndmp:HOST[:PORT]@SCSIDEV
527 tpchanger "chg-ndmp:filer.company.com@/dev/sg0"
528 property "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"
529 property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"
530 property "use-slots" "1-12"
531 property "ndmp-auth" "text"
532 property "ndmp-username" "luke"
533 property "ndmp-password" "leia"
534 This changer is very similar to chg-robot, but controls a tape changer
536 on an NDMP server instead of a local device. The HOST in the tpchanger
537 should be the hostname of the NDMP server. The PORT is optional. The
538 SCSIDEV should specify the SCSI device on the NDMP server which
539 controls the changer. The format of this parameter is
540 implementation-specific.
541 The appropriate authentication properties will be automatically set on
543 any devices created by this changer.
544 Properties
546 This changer supports all of the properties supported by chg-robot,
547 although the value of MTX is ignored. The following properties are also
548 recognized:
549 NDMP_AUTH
551 Authentication method to use to connect to the NDMP server. One of
553 "md5" (default), "text", "none" (for an empty authentication
554 attempt) or "void" (for no authentication attempt at all).
555 NDMP-PASSWORD
557 The password for the NDMP server.
559 NDMP-USERNAME
561 The username for the NDMP server.
563 Unmaintained Changers
565 Amanda has many other changer scripts and programs beyond those
566 described here (see the changer-src/ in the source directory), but most
567 of these scripts are unmaintained and undocumented, and will be removed
568 when the new changer API is fully implemented.
569
571 amanda(8), amanda.conf(5), amanda-devices(7)
572 The Amanda Wiki: : http://wiki.zmanda.com/
574
576 Dustin J. Mitchell <dustin@zmanda.com>
577 Zmanda, Inc. (http://www.zmanda.com)
578Amanda 3.1.3 10/04/2010 AMANDA-CHANGERS(7)