1AMANDA-CHANGERS(7)                Miscellanea               AMANDA-CHANGERS(7)
2
3
4

NAME

6       amanda-changers - Configuring and Using Amanda Changers
7

DESCRIPTION

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

TRANSITION

18       The Amanda Changer API version 1.0 is no longer supported.
19
20       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
24       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

SPECIFYING CHANGERS

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
42       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
46       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
52   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
58       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
67       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
71       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
78       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
83       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

CHANGER DRIVERS

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
93   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
109       }
110       tpchanger "aggregate"
111
112       This changer driver allow the use of two or more changers or standalone
113       drives in sequence.
114
115   Properties
116       LOCK-TIMEOUT
117
118           The time in seconds amanda wait to lock the statefile
119           (default:1000)
120
121       STATE_FILENAME
122
123           The name of the state file (default:
124           "$CONFIG_DIR/$changer_name.state".
125
126   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
136       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
142       The current slot can be accessed using the device name file:VTAPEROOT.
143       This is useful for the amrestore(8) command line.
144
145   Properties
146       AUTO-CREATE-SLOT
147
148           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
152       LOCK-TIMEOUT
153
154           The time in seconds amanda wait to lock the statefile
155           (default:1000)
156
157       MOUNT
158
159           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
163       NUM-SLOT
164
165           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
169       REMOVABLE
170
171           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
177       UMOUNT
178
179           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
183       UMOUNT-LOCKFILE
184
185           If UMOUNT is set, it require a lockfile outside of the mount point
186           to prevent race.
187
188       UMOUNT-IDLE
189
190           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
195   chg-multi:DEVICE-LIST
196       tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
197       changerfile "chg-multi-state"
198
199       This script simply round-robins a number of distinct device names, as
200       specified in the tpchanger setting. It is useful when all volumes for a
201       configuration have different device names -- for example, if you have
202       many standalone drive. The changerfile must exist; it is used to save
203       the state file.
204
205       The child devices are specified using the same syntax as for the RAIT
206       device (see amanda-changers(7)). The range specification can be
207       especially useful here:
208
209       tpchanger "chg-multi:s3:mycompany-backups/tape-{001..100}"
210
211       This changer is not fast-search capable.
212
213   Properties
214       FIRST-SLOT
215
216           This property gives the number of the first slot. The default value
217           is "1".
218
219       LOCK-TIMEOUT
220
221           The time in seconds amanda wait to lock the statefile
222           (default:1000)
223
224   Special Operations
225       A number of special operations are available for chg-multi via
226       amtape(8) subcommands.
227
228       The reset subcommand will change the current slot to the first
229       available slot, but does not erase any stored state maintained by the
230       changer.
231
232       The eject subcommand will eject the volume in the given drive
233
234       The clean subcommand is not yet implemented.
235
236       The update subcommand instructs the changer to update its state
237       database. Given no arguments, the changer will scan all available
238       slots, loading each tape and reading its label. Especially for large
239       libraries, this can take a long time. If only a few slots have changed,
240       they can be listed on the command line:
241
242       amtape CONFIG update 1-3,9
243       In this case, the changer will only scan the stated slots. Finally, the
244       changer will not scan at all if it is given the tape label for the
245       slot:
246
247       amtape CONFIG update 2=DailySet-028
248       In this case, the changer updates its state to indicate that
249       DailySet-028 is in slot 2, without trying to load the tape.
250
251       amtape CONFIG update 1-3,9=
252       In this case, the changer marks the stated slots as an unknown state.
253
254       amtape CONFIG update error=
255       In this case, the changer marks all slot in error as an unknown state.
256
257   chg-rait:{CHILD1,CHILD2,..}
258       define changer vtape {
259           tpchanger "chg-disk:/path/to/vtape"
260       }
261       define changer robot {
262           tpchanger "chg-robot:/dev/sg0"
263           tapedev "tape:/dev/nst0"
264       }
265       tpchanger "chg-rait:{vtape,robot}"
266
267       This changer script constructs RAIT devices out of the devices provided
268       by several "sub-changers". The sub-changers are specified using the
269       same shell-like syntax as the RAIT device (see amanda-devices(7)).
270
271       Chg-rait does not require that all of the child changers have the same
272       slot names: compound slot names are created by combining the slot names
273       supplied by the child changers using the same shell-like syntax. For
274       example, if the child changers return slots "top", "strange", and "3",
275       then the RAIT changer will return "{top,strange,3}". This makes it
276       possible to, for example, mirror data on tapes in slots 1-10 to tapes
277       in slots 11-20 of the same robot, using two chg-zd-mtx child changers
278       (and, naturally, two tape drives). In this arrangement, the first slot
279       would be named {1,11}.
280
281       As a convenience to the user, the RAIT changer will also accept
282       un-braced slot names, and supply the same name to each child changer.
283       Thus with a 4-device RAIT changer, "17" is equivalent to
284       "{17,17,17,17}".
285
286       Drive names are parsed in a similar fashion, for operations that take
287       drive names (clean and eject).
288
289       This changer is fast-search capable only if all of its child changers
290       are fast-search capable.
291
292   chg-null:
293       tpchanger "chg-null:"
294
295       This changer always provides the device "null:". It is sometimes useful
296       in conjunction with chg-rait:.
297
298   chg-robot:DEVICE
299       define changer robot {
300           tpchanger "chg-robot:/dev/sg0"
301           property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
302           property "eject-before-unload" "yes"
303           property "use-slots" "1-5,11-20"
304       }
305       tpchanger "robot"
306
307       This changer drives a robotic tape library using the operating system's
308       mtx command. It replaces the ancient chg-zd-mtx script. The changer
309       uses all of the information available to operate as efficiently as
310       possible. Even without a barcode reader, the changer can usually load a
311       tape immediately, without resorting to a sequential scan of many tapes.
312       It is capable of sharing state across multiple Amanda configurations,
313       avoiding conflicts and optimally tracking the contents of the library.
314
315       This changer does not accept a changerdev parameter, but the
316       changerfile parameter can be used to specify a filename at which it
317       should store its state. Ordinarily, this state is stored in a file
318       named after the changer device under $localstatedir/amanda, e.g.,
319       /var/amanda/chg-robot-dev-sg0. There should be a single such statefile
320       for each distinct tape library attached to the Amanda server, even if
321       multiple Amanda configurations reference that library.
322
323       With a barcode reader present, it is possible for chg-robot to track
324       the state of the library reliably, even recognizing tapes that are
325       removed and later re-inserted (by remembering their barcodes). Without
326       barcodes, the changer can still remember the slot in which it last saw
327       the tape with a particular label, although this information can become
328       stale if the tapes are rearranged by an operator. In any case, the
329       changer will never "hunt" for a tape by repeatedly loading slots and
330       checking labels. If the changer's state is inaccurate, use the
331       amtape(8) subcommand update.
332
333       This changer is fast-search capable even without a barcode reader. For
334       such libraries, it is the responsibility of the operator to update the
335       changer when tapes are added to or removed from the library.
336
337       There is a shell script in the contrib/ directory of Amanda's source
338       distribution which can help you convert a chg-zd-mtx configuration into
339       a chg-robot configuration. Just give it your Amanda configuration name:
340
341         sh contrib/convert-zd-mtx-to-robot.sh $config
342       The script can be downloaded at
343       http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh
344
345   Special Operations
346       A number of special operations are available for chg-robot via
347       amtape(8) subcommands.
348
349       The reset subcommand will change the current slot to the first
350       available slot, but does not erase any stored state maintained by the
351       changer.
352
353       The eject subcommand will unload the volume in the given drive,
354       ejecting first if the changer properties dictate. Note that, despite
355       the subcommand name, the changer attempts to avoid the state where a
356       volume has been ejected from the drive but not unloaded back to a
357       storage slot.
358
359       The clean subcommand is not yet implemented.
360
361       The update subcommand instructs the changer to update its state
362       database. Given no arguments, the changer will scan all available
363       slots, loading each tape and reading its label. Especially for large
364       libraries, this can take a long time. If only a few slots have changed,
365       they can be listed on the command line:
366
367       amtape CONFIG update 1-3,9
368       In this case, the changer will only scan the stated slots. Finally, the
369       changer will not scan at all if it is given the tape label for the
370       slot:
371
372       amtape CONFIG update 2=DailySet-028
373       In this case, the changer updates its state to indicate that
374       DailySet-028 is in slot 2, without trying to load the tape.
375
376       amtape CONFIG update 1-3,9=
377       In this case, the changer marks the stated slots as an unknown state.
378
379       amtape CONFIG update error=
380       In this case, the changer marks all slot in error as an unknown state.
381
382   Properties
383       BROKEN-DRIVE-LOADED-SLOT
384
385           Set this boolean property to true if mtx doesn't return correctly
386           which slot is loaded in a drive.
387
388       DRIVE-CHOICE
389
390           This property controls the algorithm used to select a drive in
391           which to load a tape.  If set to the default ("lru"), the changer
392           attempts to use the least recently used drive, resulting in a
393           round-robin behavior.  The "firstavail" algorithm selects the first
394           available drive, thus preferring the first drive specified via the
395           TAPE-DEVICE property.
396
397       EJECT-BEFORE-UNLOAD
398
399           Set this boolean property to true if the library requires an
400           offline operation be performed on the tape drive before it can be
401           unloaded.  If set, then mt will be invoked to perform this
402           operation.  Most libraries do not require this workaround.
403
404       EJECT-DELAY
405
406           This is the time between ejecting a tape and unloading the volume
407           to a storage slot, and defaults to 0 seconds.  It is only used if
408           EJECT-BEFORE-UNLOAD is true.  See "Timing", below.
409
410       FAST-SEARCH
411
412           This boolean property indicates whether the changer advertises the
413           ability to find volumes without sequential scanning.  The
414           traditional taperscan algorithm alters its behavior based on this
415           flag, so it is sometimes necessary to adjust it, although the
416           changer will always search for a desired tape using the most
417           efficient means available.  The default value is true.
418
419       IGNORE-BARCODES
420
421           If this boolean property is true, then chg-robot will ignore any
422           barcode information that the library provides.  This property is
423           probably only useful when the library returns incorrect barcodes,
424           for example due to a malfunction in the barcode reader.
425
426       LOAD-POLL
427           This property specifies the timing of Amanda's polling for the tape
428           drive to be ready after loading a new tape. See "Timing", below.
429
430           The script "polls" by trying to open the tape device repeatedly
431           until no error is encountered. The property specifies the time to
432           wait before the first poll (D), the frequency at which to poll and
433           retry on errors (P); and the time after which it should give up
434           (U). The format is
435
436           "D [poll P [until U]]"
437           For a simple delay with no polling, use e.g.,
438
439           property "load-poll" "13s"
440           To delay and then poll, use e.g.,
441
442           property "load-poll" "13s poll 5s"
443           and to add a maximum total time, use e.g.,
444
445           property "load-poll" "0s poll 5s until 2m"
446           The default value is "0s poll 3s until 2m".
447
448       LOCK-TIMEOUT
449
450           The time in seconds amanda wait to lock the statefile
451           (default:1000)
452
453       MTX
454
455           The path to the 'mtx' binary.  The default value is defined at
456           compile time.
457
458       STATUS-INTERVAL
459
460           This is the minimum time between invocations of mtx status to
461           determine the state of the changer library.  The default value, 2
462           seconds, avoids back-to-back status invocations but ensures that
463           the metadata is up to date.  For operating systems or libraries
464           where the mtx status takes a considerable time to complete, this
465           value should be increased.  See "Timing", below.
466
467       TAPE-DEVICE
468
469           This property describes the correspondence of drive numbers in the
470           library to Amanda devices, in the format DRIVE=DEVICE.  The
471           property can be specified multiple times to describe multiple
472           devices.  The device will usually be a tape device name starting
473           with tape:, but may also refer to a device alias (see amanda-
474           devices(7)). As a shortcut, if the tapedev parameter is specified
475           in the changer definition, then it is assumed to be the device name
476           for drive 0.
477
478       UNLOAD-DELAY
479
480           This specifies the minimum time between an unload operation any any
481           subsequent operation.  The default value is 0 seconds.  See
482           "Timing", below.
483
484       USE-SLOTS
485
486           This property, if specifies, enumerates the slots to which this
487           changer should limit itself.  The slots are specified as a
488           comma-separated list of ranges, e.g., "1-5,11-15,19,22".  The
489           property can be specified more than once, and the resulting sets
490           will be combined.  The changer will refuse to load tapes not found
491           in these slots, except for import/export purposes.
492
493   Timing
494       Tape libraries are fickle, and in many cases will report that an
495       operation is complete when it is still in progress. Chg-robot takes
496       several timing-related properties to accommodate such behavior.
497
498       A typical sequence of operations performed during a load are: get
499       library status, eject a tape, unload the tape back to a storage slot,
500       load a new tape, and read the label on that tape to ensure the drive is
501       ready.
502
503       On most systems, the library status check is nearly instantaneous --
504       the changer library provides its cached state to the host without
505       initiating any robot motion. In order to keep its metadata up-to-date,
506       chg-robot runs this command very frequently, but this frequency can be
507       reduced (at the cost of potentially stale metadata) by setting the
508       STATUS-INTERVAL property to a larger value.
509
510       Some tape libraries do not integrate the eject operation (performed by
511       the embedded tape drive) with the unload operation (performed by the
512       library robot), and can actually cause physical damage by attempting to
513       remove the tape before the ejection is complete. For such changers, set
514       the EJECT-DELAY property to allow enough time for the eject to
515       complete.
516
517       Once a tape is unloaded, if the library needs time to "quiesce" before
518       processing another command, add that time to the UNLOAD-DELAY
519       parameter. No other operations will be performed on the library until
520       this delay has elapsed.
521
522       Once a tape has been loaded, chg-robot waits until the drive is ready
523       before allowing Amanda to use the volume, as described for LOAD-POLL,
524       above.
525
526       Each of the times specified in these properties may be given as
527       integers with the optional suffix s for seconds (the default) or m for
528       minutes.
529
530   chg-ndmp:HOST[:PORT]@SCSIDEV
531           tpchanger "chg-ndmp:filer.company.com@/dev/sg0"
532           property        "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"
533           property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"
534           property "use-slots" "1-12"
535           property "ndmp-auth" "text"
536           property "ndmp-username" "luke"
537           property "ndmp-password" "leia"
538
539       This changer is very similar to chg-robot, but controls a tape changer
540       on an NDMP server instead of a local device. The HOST in the tpchanger
541       should be the hostname of the NDMP server. The PORT is optional. The
542       SCSIDEV should specify the SCSI device on the NDMP server which
543       controls the changer. The format of this parameter is
544       implementation-specific.
545
546       The appropriate authentication properties will be automatically set on
547       any devices created by this changer.
548
549   Properties
550       This changer supports all of the properties supported by chg-robot,
551       although the value of MTX is ignored. The following properties are also
552       recognized:
553
554       NDMP_AUTH
555
556           Authentication method to use to connect to the NDMP server.  One of
557           "md5" (default), "text", "none" (for an empty authentication
558           attempt) or "void" (for no authentication attempt at all).
559
560       NDMP-PASSWORD
561
562           The password for the NDMP server.
563
564       NDMP-USERNAME
565
566           The username for the NDMP server.
567
568       VERBOSE
569
570           If true, enables the NDMJOB library's verbose (packet-level)
571           debugging.
572
573   chg-single:DEVICE
574       tpchanger "chg-single:tape:/dev/nst0"
575
576       This changer is for use with standalone drive, it can work with any
577       device. The device (tape:/dev/nst0) must be set in the tpchanger
578       definition.
579
580       The chg-single changer has no property.
581
582   Unmaintained Changers
583       Amanda has many other changer scripts and programs beyond those
584       described here (see the changer-src/ in the source directory), but most
585       of these scripts are unmaintained and undocumented, and will be removed
586       when the new changer API is fully implemented.
587

SEE ALSO

589       amanda(8), amanda.conf(5), amanda-devices(7)
590
591       The Amanda Wiki: : http://wiki.zmanda.com/
592

AUTHOR

594       Dustin J. Mitchell <dustin@zmanda.com>
595           Zmanda, Inc. (http://www.zmanda.com)
596
597
598
599Amanda 3.5.1                      12/01/2017                AMANDA-CHANGERS(7)
Impressum