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 version 1.0 is no longer supported.
19 The Amanda Changer API version 2.0, composed of perl objects that can
21 manage parallel access to multiple devices and other complexity. At
22 this point, all Amanda programs use the new Changer API directly.
23 The Changer API strives to treat all changers identically, so that
25 Amanda's behavior is independent of the changer in use. However, some
26 parts of Amanda operate differently depending on whether a changer can
27 efficiently search for a volume with a given label. This distinction is
28 really only apparent with tape libraries: those with barcode readers
29 can quickly find a desired tape, while those without may fall back to
30 an inefficient scan of each volume. The capability to perform quick
31 searches is called "fast-search", and each changer is annotated below
32 to indicate its support.
33
35 Changer specifications are strings like chg-disk:/my/vtapes. The chg-
36 prefix serves to differentiate changers from devices (see amanda-
37 devices(7)). The next portion (disk, in this case) identifies the
38 particular changer driver to use, and everything that follows the : is
39 interpreted by the driver. Note that the : character is required, even
40 when nothing follows it.
41 A name which does not match this pattern, is treated as an Amanda
43 device, and is wrapped by the single-device changer, e.g.,
44 chg-single:tape:/dev/rmt/0.
45 Changers which require additional parameters can also be described in
47 amanda.conf(5) with "changer" sections. Such a changer defininition
48 creates a changer "alias", in this case named hp-robot, which can then
49 be named where an application expects a changer - for example, the
50 target of the amvault command or in a global tpchanger parameter.
51 CONFIGURATION
53 The preferred method of specifying configuration for a changer is as a
54 "changer" section in amanda.conf(5). The tapedev parameter then
55 indicates, by name, the changer that will be used by default by most
56 Amanda programs. For example:
57 define changer hp-robot {
59 tapedev "chg-robot:/dev/sg1"
60 property "tape-device" "0=tape:/dev/nst0"
61 property append "tape-device" "1=tape:/dev/nst1"
62 device-property "BLOCK_SIZE" "512k"
63 }
64 # ...
65 tapedev "hp-robot"
66 Several changer drivers accept changer properties which control the
68 behavior of the changer. These properties must be specified in a
69 changer definition, as in the hp-robot example, above.
70 Devices, too, can take properties to control their behavior (see
72 amanda-devices(7)). Device properties can come from four places:
73 implicit device properties (from tapetype parameters), global device
74 properties (from global device-property parameters), properties in
75 device definitions, and properties in changer definitions. Properties
76 are applied in this order, with later properties taking priority.
77 There are only three implicit properties: MAX_VOLUME_USAGE is set based
79 on the tapetype length parameter, READ_BLOCK_SIZE is set if
80 readblocksize is set, and BLOCK_SIZE is set based on the blocksize
81 parameter.
82 Global device properties always apply. If the changer specifies a
84 device by alias, then device properties from the definition apply. If
85 the changer is specified by an alias, then properties from that
86 definition applied.
87
89 This section lists the changer drivers included with Amanda, and basic
90 instructions for using them. For complete How-To information, consult
91 the Amanda wiki at http://wiki.zmanda.com.
92 chg-aggregate:changer
94 define changer robot0 {
95 tpchanger "chg-robot:/dev/sg0"
96 property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
97 }
98 define changer robot1 {
99 tpchanger "chg-robot:/dev/sg1"
100 property "tape-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
101 }
102 define changer single {
103 tpchanger "chg-single:/dev/rmt/4"
104 }
105 define changer aggregate {
106 tpchanger "chg-aggregate:{robot0,robot1,single}"
107 property "state-filename" "/etc/amanda/CONF/aggregate.state"
108 }
110 tpchanger "aggregate"
111 This changer driver allow the use of two or more changers or standalone
113 drives in sequence.
114 Properties
116 LOCK-TIMEOUT
117 The time in seconds amanda wait to lock the statefile
119 (default:1000)
120 STATE_FILENAME
122 The name of the state file (default:
124 "$CONFIG_DIR/$changer_name.state".
125 chg-disk:VTAPEROOT
127 tpchanger "chg-disk:/var/mnt/vtapes"
128 property "num-slot" "10"
129 property "auto-create-slot" "yes"
130 property "removable" "yes"
131 property "mount" "yes"
132 property "umount" "yes"
133 property "umount-lockfile" "/etc/amanda/conf/vtapes-lock"
134 property "umount-idle" "1"
135 This changer driver replaces the old chg-disk, supporting parallel
137 access to vtapes stored in directories named slotN in the directory
138 specified after chg-disk:. It does so by creating numbered "drives" so
139 that simultaneous processes can access distinct slots. This changer is
140 fast-search capable.
141 The current slot can be accessed using the device name file:VTAPEROOT.
143 This is useful for the amrestore(8) command line.
144 Properties
146 AUTO-CREATE-SLOT
147 If a slotN directory in the range 1 to NUM-SLOT does not already
149 exist, and this property is true, then the changer will create the
150 directory.
151 LOCK-TIMEOUT
153 The time in seconds amanda wait to lock the statefile
155 (default:1000)
156 MOUNT
158 If this property is true, the changer try to mount the removable
160 disk if nothing is mounted. The system must be configured to allow
161 the amanda user to mount it.
162 NUM-SLOT
164 The minimum number of slots in the changer, where the first slot is
166 slot1. If additional slot directories exist, they will also be
167 used.
168 REMOVABLE
170 If this property is true, then the changer will verify that the
172 changer directory (e.g., /var/mnt/vtapes) is on a different
173 filesystem from its parent directory (e.g., /var/mnt). This is
174 useful for removable disks, as it will prevent Amanda from creating
175 slot directories when the removable disk is not mounted.
176 UMOUNT
178 If this property is true, the changer try to umount the removable
180 disk when it exit. The system must be configured to allow the
181 amanda user to umount it.
182 UMOUNT-LOCKFILE
184 If UMOUNT is set, it require a lockfile outside of the mount point
186 to prevent race.
187 UMOUNT-IDLE
189 If set, the changer try to umount the removable disk when it is not
191 in use. The umount-idle value is a delay in second to wait before
192 doing the umount. A value >= 1 is required to prevent useless
193 mount/umount.
194 chg-diskflat:VTAPEROOT
196 tpchanger "chg-diskflat:/var/mnt/vtapes-flat"
197 property "num-slot" "10"
198 property "auto-create-slot" "yes"
199 property "removable" "yes"
200 property "mount" "yes"
201 property "umount" "yes"
202 property "umount-lockfile" "/etc/amanda/conf/vtapes-flat-lock"
203 property "umount-idle" "1"
204 This changer driver can be used only with the diskflat device,
206 supporting parallel access to vtapes stored in files named with the
207 label in the directory specified after chg-diskflat:. It does so by
208 creating numbered "drives" so that simultaneous processes can access
209 distinct slots. This changer is fast-search capable.
210 Properties
212 Have the same properties as the chg-disk changers
213 chg-multi:DEVICE-LIST
215 tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
216 changerfile "chg-multi-state"
217 This script simply round-robins a number of distinct device names, as
219 specified in the tpchanger setting. It is useful when all volumes for a
220 configuration have different device names -- for example, if you have
221 many standalone drive. The changerfile must exist; it is used to save
222 the state file.
223 The child devices are specified using the same syntax as for the RAIT
225 device (see amanda-changers(7)). The range specification can be
226 especially useful here:
227 tpchanger "chg-multi:s3:mycompany-backups/tape-{001..100}"
229 This changer is not fast-search capable.
231 Properties
233 FIRST-SLOT
234 This property gives the number of the first slot. The default value
236 is "1".
237 LOCK-TIMEOUT
239 The time in seconds amanda wait to lock the statefile
241 (default:1000)
242 Special Operations
244 A number of special operations are available for chg-multi via
245 amtape(8) subcommands.
246 The reset subcommand will change the current slot to the first
248 available slot, but does not erase any stored state maintained by the
249 changer.
250 The eject subcommand will eject the volume in the given drive
252 The clean subcommand is not yet implemented.
254 The update subcommand instructs the changer to update its state
256 database. Given no arguments, the changer will scan all available
257 slots, loading each tape and reading its label. Especially for large
258 libraries, this can take a long time. If only a few slots have changed,
259 they can be listed on the command line:
260 amtape CONFIG update 1-3,9
262 In this case, the changer will only scan the stated slots. Finally, the
263 changer will not scan at all if it is given the tape label for the
264 slot:
265 amtape CONFIG update 2=DailySet-028
267 In this case, the changer updates its state to indicate that
268 DailySet-028 is in slot 2, without trying to load the tape.
269 amtape CONFIG update 1-3,9=
271 In this case, the changer marks the stated slots as an unknown state.
272 amtape CONFIG update error=
274 In this case, the changer marks all slot in error as an unknown state.
275 chg-rait:{CHILD1,CHILD2,..}
277 define changer vtape {
278 tpchanger "chg-disk:/path/to/vtape"
279 }
280 define changer robot {
281 tpchanger "chg-robot:/dev/sg0"
282 tapedev "tape:/dev/nst0"
283 }
284 tpchanger "chg-rait:{vtape,robot}"
285 This changer script constructs RAIT devices out of the devices provided
287 by several "sub-changers". The sub-changers are specified using the
288 same shell-like syntax as the RAIT device (see amanda-devices(7)).
289 Chg-rait does not require that all of the child changers have the same
291 slot names: compound slot names are created by combining the slot names
292 supplied by the child changers using the same shell-like syntax. For
293 example, if the child changers return slots "top", "strange", and "3",
294 then the RAIT changer will return "{top,strange,3}". This makes it
295 possible to, for example, mirror data on tapes in slots 1-10 to tapes
296 in slots 11-20 of the same robot, using two chg-zd-mtx child changers
297 (and, naturally, two tape drives). In this arrangement, the first slot
298 would be named {1,11}.
299 As a convenience to the user, the RAIT changer will also accept
301 un-braced slot names, and supply the same name to each child changer.
302 Thus with a 4-device RAIT changer, "17" is equivalent to
303 "{17,17,17,17}".
304 Drive names are parsed in a similar fashion, for operations that take
306 drive names (clean and eject).
307 This changer is fast-search capable only if all of its child changers
309 are fast-search capable.
310 chg-null:
312 tpchanger "chg-null:"
313 This changer always provides the device "null:". It is sometimes useful
315 in conjunction with chg-rait:.
316 chg-robot:DEVICE
318 define changer robot {
319 tpchanger "chg-robot:/dev/sg0"
320 property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
321 property "eject-before-unload" "yes"
322 property "use-slots" "1-5,11-20"
323 }
324 tpchanger "robot"
325 This changer drives a robotic tape library using the operating system's
327 mtx command. It replaces the ancient chg-zd-mtx script. The changer
328 uses all of the information available to operate as efficiently as
329 possible. Even without a barcode reader, the changer can usually load a
330 tape immediately, without resorting to a sequential scan of many tapes.
331 It is capable of sharing state across multiple Amanda configurations,
332 avoiding conflicts and optimally tracking the contents of the library.
333 This changer does not accept a changerdev parameter, but the
335 changerfile parameter can be used to specify a filename at which it
336 should store its state. Ordinarily, this state is stored in a file
337 named after the changer device under $localstatedir/amanda, e.g.,
338 /var/amanda/chg-robot-dev-sg0. There should be a single such statefile
339 for each distinct tape library attached to the Amanda server, even if
340 multiple Amanda configurations reference that library.
341 With a barcode reader present, it is possible for chg-robot to track
343 the state of the library reliably, even recognizing tapes that are
344 removed and later re-inserted (by remembering their barcodes). Without
345 barcodes, the changer can still remember the slot in which it last saw
346 the tape with a particular label, although this information can become
347 stale if the tapes are rearranged by an operator. In any case, the
348 changer will never "hunt" for a tape by repeatedly loading slots and
349 checking labels. If the changer's state is inaccurate, use the
350 amtape(8) subcommand update.
351 This changer is fast-search capable even without a barcode reader. For
353 such libraries, it is the responsibility of the operator to update the
354 changer when tapes are added to or removed from the library.
355 There is a shell script in the contrib/ directory of Amanda's source
357 distribution which can help you convert a chg-zd-mtx configuration into
358 a chg-robot configuration. Just give it your Amanda configuration name:
359 sh contrib/convert-zd-mtx-to-robot.sh $config
361 The script can be downloaded at
362 http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh
363 Special Operations
365 A number of special operations are available for chg-robot via
366 amtape(8) subcommands.
367 The reset subcommand will change the current slot to the first
369 available slot, but does not erase any stored state maintained by the
370 changer.
371 The eject subcommand will unload the volume in the given drive,
373 ejecting first if the changer properties dictate. Note that, despite
374 the subcommand name, the changer attempts to avoid the state where a
375 volume has been ejected from the drive but not unloaded back to a
376 storage slot.
377 The clean subcommand is not yet implemented.
379 The update subcommand instructs the changer to update its state
381 database. Given no arguments, the changer will scan all available
382 slots, loading each tape and reading its label. Especially for large
383 libraries, this can take a long time. If only a few slots have changed,
384 they can be listed on the command line:
385 amtape CONFIG update 1-3,9
387 In this case, the changer will only scan the stated slots. Finally, the
388 changer will not scan at all if it is given the tape label for the
389 slot:
390 amtape CONFIG update 2=DailySet-028
392 In this case, the changer updates its state to indicate that
393 DailySet-028 is in slot 2, without trying to load the tape.
394 amtape CONFIG update 1-3,9=
396 In this case, the changer marks the stated slots as an unknown state.
397 amtape CONFIG update error=
399 In this case, the changer marks all slot in error as an unknown state.
400 Properties
402 BROKEN-DRIVE-LOADED-SLOT
403 Set this boolean property to true if mtx doesn't return correctly
405 which slot is loaded in a drive.
406 DRIVE-CHOICE
408 This property controls the algorithm used to select a drive in
410 which to load a tape. If set to the default ("lru"), the changer
411 attempts to use the least recently used drive, resulting in a
412 round-robin behavior. The "firstavail" algorithm selects the first
413 available drive, thus preferring the first drive specified via the
414 TAPE-DEVICE property.
415 EJECT-BEFORE-UNLOAD
417 Set this boolean property to true if the library requires an
419 offline operation be performed on the tape drive before it can be
420 unloaded. If set, then mt will be invoked to perform this
421 operation. Most libraries do not require this workaround.
422 EJECT-DELAY
424 This is the time between ejecting a tape and unloading the volume
426 to a storage slot, and defaults to 0 seconds. It is only used if
427 EJECT-BEFORE-UNLOAD is true. See "Timing", below.
428 FAST-SEARCH
430 This boolean property indicates whether the changer advertises the
432 ability to find volumes without sequential scanning. The
433 traditional taperscan algorithm alters its behavior based on this
434 flag, so it is sometimes necessary to adjust it, although the
435 changer will always search for a desired tape using the most
436 efficient means available. The default value is true.
437 IGNORE-BARCODES
439 If this boolean property is true, then chg-robot will ignore any
441 barcode information that the library provides. This property is
442 probably only useful when the library returns incorrect barcodes,
443 for example due to a malfunction in the barcode reader.
444 LOAD-POLL
446 This property specifies the timing of Amanda's polling for the tape
447 drive to be ready after loading a new tape. See "Timing", below.
448 The script "polls" by trying to open the tape device repeatedly
450 until no error is encountered. The property specifies the time to
451 wait before the first poll (D), the frequency at which to poll and
452 retry on errors (P); and the time after which it should give up
453 (U). The format is
454 "D [poll P [until U]]"
456 For a simple delay with no polling, use e.g.,
457 property "load-poll" "13s"
459 To delay and then poll, use e.g.,
460 property "load-poll" "13s poll 5s"
462 and to add a maximum total time, use e.g.,
463 property "load-poll" "0s poll 5s until 2m"
465 The default value is "0s poll 3s until 2m".
466 LOCK-TIMEOUT
468 The time in seconds amanda wait to lock the statefile
470 (default:1000)
471 MTX
473 The path to the 'mtx' binary. The default value is defined at
475 compile time.
476 STATUS-INTERVAL
478 This is the minimum time between invocations of mtx status to
480 determine the state of the changer library. The default value, 2
481 seconds, avoids back-to-back status invocations but ensures that
482 the metadata is up to date. For operating systems or libraries
483 where the mtx status takes a considerable time to complete, this
484 value should be increased. See "Timing", below.
485 TAPE-DEVICE
487 This property describes the correspondence of drive numbers in the
489 library to Amanda devices, in the format DRIVE=DEVICE. The
490 property can be specified multiple times to describe multiple
491 devices. The device will usually be a tape device name starting
492 with tape:, but may also refer to a device alias (see amanda-
493 devices(7)). As a shortcut, if the tapedev parameter is specified
494 in the changer definition, then it is assumed to be the device name
495 for drive 0.
496 UNLOAD-DELAY
498 This specifies the minimum time between an unload operation any any
500 subsequent operation. The default value is 0 seconds. See
501 "Timing", below.
502 USE-SLOTS
504 This property, if specifies, enumerates the slots to which this
506 changer should limit itself. The slots are specified as a
507 comma-separated list of ranges, e.g., "1-5,11-15,19,22". The
508 property can be specified more than once, and the resulting sets
509 will be combined. The changer will refuse to load tapes not found
510 in these slots, except for import/export purposes.
511 Timing
513 Tape libraries are fickle, and in many cases will report that an
514 operation is complete when it is still in progress. Chg-robot takes
515 several timing-related properties to accommodate such behavior.
516 A typical sequence of operations performed during a load are: get
518 library status, eject a tape, unload the tape back to a storage slot,
519 load a new tape, and read the label on that tape to ensure the drive is
520 ready.
521 On most systems, the library status check is nearly instantaneous --
523 the changer library provides its cached state to the host without
524 initiating any robot motion. In order to keep its metadata up-to-date,
525 chg-robot runs this command very frequently, but this frequency can be
526 reduced (at the cost of potentially stale metadata) by setting the
527 STATUS-INTERVAL property to a larger value.
528 Some tape libraries do not integrate the eject operation (performed by
530 the embedded tape drive) with the unload operation (performed by the
531 library robot), and can actually cause physical damage by attempting to
532 remove the tape before the ejection is complete. For such changers, set
533 the EJECT-DELAY property to allow enough time for the eject to
534 complete.
535 Once a tape is unloaded, if the library needs time to "quiesce" before
537 processing another command, add that time to the UNLOAD-DELAY
538 parameter. No other operations will be performed on the library until
539 this delay has elapsed.
540 Once a tape has been loaded, chg-robot waits until the drive is ready
542 before allowing Amanda to use the volume, as described for LOAD-POLL,
543 above.
544 Each of the times specified in these properties may be given as
546 integers with the optional suffix s for seconds (the default) or m for
547 minutes.
548 chg-ndmp:HOST[:PORT]@SCSIDEV
550 tpchanger "chg-ndmp:filer.company.com@/dev/sg0"
551 property "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"
552 property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"
553 property "use-slots" "1-12"
554 property "ndmp-auth" "text"
555 property "ndmp-username" "luke"
556 property "ndmp-password" "leia"
557 This changer is very similar to chg-robot, but controls a tape changer
559 on an NDMP server instead of a local device. The HOST in the tpchanger
560 should be the hostname of the NDMP server. The PORT is optional. The
561 SCSIDEV should specify the SCSI device on the NDMP server which
562 controls the changer. The format of this parameter is
563 implementation-specific.
564 The appropriate authentication properties will be automatically set on
566 any devices created by this changer.
567 Properties
569 This changer supports all of the properties supported by chg-robot,
570 although the value of MTX is ignored. The following properties are also
571 recognized:
572 NDMP_AUTH
574 Authentication method to use to connect to the NDMP server. One of
576 "md5" (default), "text", "none" (for an empty authentication
577 attempt) or "void" (for no authentication attempt at all).
578 NDMP-PASSWORD
580 The password for the NDMP server.
582 NDMP-USERNAME
584 The username for the NDMP server.
586 VERBOSE
588 If true, enables the NDMJOB library's verbose (packet-level)
590 debugging.
591 chg-single:DEVICE
593 tpchanger "chg-single:tape:/dev/nst0"
594 This changer is for use with standalone drive, it can work with any
596 device. The device (tape:/dev/nst0) must be set in the tpchanger
597 definition.
598 The chg-single changer has no property.
600 Unmaintained Changers
602 Amanda has many other changer scripts and programs beyond those
603 described here (see the changer-src/ in the source directory), but most
604 of these scripts are unmaintained and undocumented, and will be removed
605 when the new changer API is fully implemented.
606
608 amanda(8), amanda.conf(5), amanda-devices(7)
609 The Amanda Wiki: : http://wiki.zmanda.com/
611
613 Dustin J. Mitchell <dustin@zmanda.com>
614 Zmanda, Inc. (http://www.zmanda.com)
615Amanda 3.5.4 07/27/2023 AMANDA-CHANGERS(7)