1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM 'global.entities'>
10 <refentry id='amanda-changers.7'>
13 <refentrytitle>amanda-changers</refentrytitle>
14 <manvolnum>7</manvolnum>
20 <refname>amanda-changers</refname>
21 <refpurpose>Configuring and Using Amanda Changers</refpurpose>
26 <!-- body begins here -->
28 <refsect1><title>DESCRIPTION</title>
30 <para>Amanda uses changers to arbitrate access to devices
31 (<manref name="amanda-devices" vol="7"/>)
32 and data volumes. Changers provide an abstraction of tape robots, but are used
33 to manage non-tape media, too. Amanda communicates with changers through the
34 Changer API. This manpage contains a <emphasis>user-level</emphasis> overview
35 of the API, and does not address details that are only of concern to
36 developers. For that purpose, consult the Amanda source code and
37 http://wiki.zmanda.com.</para>
41 <refsect1><title>TRANSITION</title>
43 <para>The Amanda Changer API is in transition from version 1.0 - driven by
44 shell scripts invoked for each changer operation - to version 2.0, composed of
45 perl objects that can manage parallel access to multiple devices and other
46 complexity. At this point, all Amanda programs use the new Changer API directly,
47 although 1.0 changer scripts are still fully supported via <code>chg-compat</code>.
50 <para>The Changer API strives to treat all changers identically, so that
51 Amanda's behavior is independent of the changer in use. However, some parts of
52 Amanda operate differently depending on whether a changer can efficiently
53 search for a volume with a given label. This distinction is really only
54 apparent with tape libraries: those with barcode readers can quickly find a
55 desired tape, while those without may fall back to an inefficient scan of each
56 volume. The capability to perform quick searches is called "fast-search", and
57 each changer is annotated below to indicate its support.</para>
61 <refsect1><title>SPECIFYING CHANGERS</title>
63 <para>Changer specifications are strings like
64 <computeroutput>chg-disk:/my/vtapes</computeroutput>. The
65 <computeroutput>chg-</computeroutput> prefix serves to differentiate changers
66 from devices (see <manref name="amanda-devices" vol="7"/>). The next portion
67 (<computeroutput>disk</computeroutput>, in this case) identifies the particular
68 changer driver to use, and everything that follows the
69 <computeroutput>:</computeroutput> is interpreted by the driver. Note that the
70 <computeroutput>:</computeroutput> character is required, even when nothing
71 follows it. This is an easy way to distinguish new changer specifications from
74 <para>A name which does not match this pattern, but which matches an old
75 changer script (e.g., <computeroutput>chg-zd-mtx</computeroutput>), invokes the
76 backward-compatibility changer driver as e.g.,
77 <computeroutput>chg-compat:chg-zd-mtx</computeroutput>. If the name does not
78 match an old changer, then it is treated as an Amanda device, and is wrapped by
79 the single-device changer, e.g.,
80 <computeroutput>chg-single:tape:/dev/rmt/0</computeroutput>.</para>
82 <para>Changers which require additional parameters can also be described in
83 &amconf; with "changer" sections. Such a changer defininition creates a
84 changer "alias", in this case named <emphasis>hp-robot</emphasis>, which can
85 then be named where an application expects a changer - for example, the target
86 of the <command>amvault</command> command or in a global
87 <command>tpchanger</command> parameter.</para>
89 <refsect2><title>CONFIGURATION</title>
91 <para>The preferred method of specifying configuration for a changer is as a
92 "changer" section in &amconf;. The <emphasis>tapedev</emphasis> parameter
93 then indicates, by name, the changer that will be used by default by most
94 Amanda programs. For example:
96 define changer hp-robot {
97 tapedev "chg-robot:/dev/sg1"
98 property "tape-device" "0=tape:/dev/nst0"
99 property append "tape-device" "1=tape:/dev/nst1"
100 device-property "BLOCK_SIZE" "512k"
107 <para>Several changer drivers accept <emphasis>changer properties</emphasis> which
108 control the behavior of the changer. These properties must be specified in a
109 changer definition, as in the <emphasis>hp-robot</emphasis> example, above.</para>
111 <para>Devices, too, can take properties to control their behavior (see <manref
112 name="amanda-devices" vol="7" />). Device properties can come from four
113 places: implicit device properties (from tapetype parameters), global device
114 properties (from global <emphasis>device-property</emphasis> parameters),
115 properties in device definitions, and properties in changer definitions.
116 Properties are applied in this order, with later properties taking
119 <para>There are only three implicit properties:
120 <emphasis>MAX_VOLUME_USAGE</emphasis> is set based on the tapetype
121 <emphasis>length</emphasis> parameter, <emphasis>READ_BLOCK_SIZE</emphasis> is
122 set if <emphasis>readblocksize</emphasis> is set, and
123 <emphasis>BLOCK_SIZE</emphasis> is set based on the
124 <emphasis>blocksize</emphasis> parameter.</para>
126 <para>Global device properties always apply. If the changer specifies a device
127 by alias, then device properties from the definition apply. If the changer is
128 specified by an alias, then properties from that definition applied.</para>
133 <refsect1><title>CHANGER DRIVERS</title>
135 <para>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.</para>
137 <refsect2><title>chg-aggregate:changer (new)</title>
139 define changer robot0 {
140 tpchanger "chg-robot:/dev/sg0"
141 property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
143 define changer robot1 {
144 tpchanger "chg-robot:/dev/sg1"
145 property "tape-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
147 define changer single {
148 tpchanger "chg-single:/dev/rmt/4"
150 define changer aggregate {
151 tpchanger "chg-aggregate:{robot0,robot1,single}"
152 property "state-filename" "/etc/amanda/CONF/aggregate.state"
155 tpchanger "aggregate"
158 <para>This changer driver allow to use two or more changers or standalone
159 drive in sequence.</para>
161 <refsect3><title>Properties</title>
162 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
166 <varlistentry><term>LOCK-TIMEOUT</term><listitem>
167 The time in seconds amanda wait to lock the statefile (default:1000)
168 </listitem></varlistentry>
170 <varlistentry><term>STATE_FILENAME</term><listitem>
171 The name of the state file (default: "$CONFIG_DIR/$changer_name.state".
172 </listitem></varlistentry>
177 <refsect2><title>chg-disk:VTAPEROOT (new)</title>
179 tpchanger "chg-disk:/var/mnt/vtapes"
180 property "num-slot" "10"
181 property "auto-create-slot" "yes"
182 property "removable" "yes"
183 property "mount" "yes"
184 property "umount" "yes"
185 property "umount-lockfile" "/etc/amanda/conf/vtapes-lock"
186 property "umount-idle" "1"
189 <para>This changer driver replaces the old <command>chg-disk</command>,
190 supporting parallel access to vtapes stored in directories named
191 <computeroutput>slotN</computeroutput> in the directory specified after
192 <computeroutput>chg-disk:</computeroutput>. It does so by creating numbered
193 "drives" so that simultaneous processes can access distinct slots. This changer is fast-search capable.</para>
195 <para>The current slot can be accessed using the device name
196 <computeroutput>file:VTAPEROOT</computeroutput>. This is useful for the <manref
197 name="amrestore" vol="8" /> command line.</para>
199 <refsect3><title>Properties</title>
200 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
204 <varlistentry><term>AUTO-CREATE-SLOT</term><listitem>
205 If a <computeroutput>slotN</computeroutput> directory in the range 1 to NUM-SLOT does not already exist, and this property is true, then the changer will create the directory.
206 </listitem></varlistentry>
208 <varlistentry><term>LOCK-TIMEOUT</term><listitem>
209 The time in seconds amanda wait to lock the statefile (default:1000)
210 </listitem></varlistentry>
212 <varlistentry><term>MOUNT</term><listitem>
213 If this property is true, the changer try to mount the removable disk if nothing is mounted. The system must be configured to allow the amanda user to mount it.
214 </listitem></varlistentry>
216 <varlistentry><term>NUM-SLOT</term><listitem>
217 The minimum number of slots in the changer, where the first slot is <computeroutput>slot1</computeroutput>. If additional slot directories exist, they will also be used.
218 </listitem></varlistentry>
220 <varlistentry><term>REMOVABLE</term><listitem>
221 If this property is true, then the changer will verify that the changer
222 directory (e.g., <filename>/var/mnt/vtapes</filename>) is on a different
223 filesystem from its parent directory (e.g., <filename>/var/mnt</filename>).
224 This is useful for removable disks, as it will prevent Amanda from creating
225 slot directories when the removable disk is not mounted.
226 </listitem></varlistentry>
228 <varlistentry><term>UMOUNT</term><listitem>
229 If this property is true, the changer try to umount the removable disk when it exit. The system must be configured to allow the amanda user to umount it.
230 </listitem></varlistentry>
232 <varlistentry><term>UMOUNT-LOCKFILE</term><listitem>
233 If UMOUNT is set, it require a lockfile outside of the mount point to prevent race.
234 </listitem></varlistentry>
236 <varlistentry><term>UMOUNT-IDLE</term><listitem>
237 If set, the changer try to umount the removable disk when it is not in use. The umount-idle value is a delay in second to wait before doing the umount. A value >= 1 is required to prevent useless mount/umount.
238 </listitem></varlistentry>
244 <refsect2><title>chg-disk (old)</title>
246 tapedev "file:/u01/vtapes"
248 changerfile "chg-disk.conf" # optional file
251 <para>This changer script supports sequential access to vtapes stored in
252 directories named <computeroutput>slotN</computeroutput> in the directory
253 specified by the <emphasis>tapedev</emphasis> parameter.
254 The configuration file parameter is:
256 LASTSLOT=number # The number of slots, default to tapecycle setting.
260 <para>This changer is not fast-search capable.</para>
264 <refsect2><title>chg-multi:DEVICE-LIST</title>
266 tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
267 changerfile "chg-multi-state"
270 <para>This script simply round-robins a number of distinct device names, as
271 specified in the <emphasis>tpchanger</emphasis> setting. It is useful when
272 all volumes for a configuration have different device names -- for example,
273 if you have many standalone drive. The <emphasis>changerfile</emphasis> must exist; it is used to save the state file.
276 <para>The child devices are specified using the same syntax as for the RAIT
277 device (see <manref name="amanda-changers" vol="7"/>). The range
278 specification can be especially useful here:
280 tpchanger "chg-multi:s3:mycompany-backups/tape-{001..100}"
284 <para>This changer is not fast-search capable.</para>
286 <refsect3><title>Properties</title>
287 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
291 <varlistentry><term>FIRST-SLOT</term><listitem>
292 This property gives the number of the first slot. The default value is "1".
293 </listitem></varlistentry>
295 <varlistentry><term>LOCK-TIMEOUT</term><listitem>
296 The time in seconds amanda wait to lock the statefile (default:1000)
297 </listitem></varlistentry>
303 <refsect3><title>Special Operations</title>
305 <para>A number of special operations are available for <command>chg-multi</command> via
306 <manref name="amtape" vol="8" /> subcommands.</para>
308 <para>The <command>reset</command> subcommand will change the current slot to
309 the first available slot, but does not erase any stored state maintained by the
312 <para>The <command>eject</command> subcommand will eject the volume in the
315 <para>The <command>clean</command> subcommand is not yet implemented.</para>
317 <para>The <command>update</command> subcommand instructs the changer to update
318 its state database. Given no arguments, the changer will scan all available
319 slots, loading each tape and reading its label. Especially for large libraries,
320 this can take a long time. If only a few slots have changed, they can be listed
323 amtape CONFIG update 1-3,9
325 In this case, the changer will only scan the stated slots. Finally, the changer
326 will not scan at all if it is given the tape label for the slot:
328 amtape CONFIG update 2=DailySet-028
330 In this case, the changer updates its state to indicate that
331 <computeroutput>DailySet-028</computeroutput> is in slot 2, without trying to
334 amtape CONFIG update 1-3,9=
336 In this case, the changer marks the stated slots as an unknown state.
343 <refsect2><title>chg-multi (old)</title>
345 tpchanger "chg-multi"
346 changerfile "chg-multi-state"
349 <para>This script simply round-robins a number of distinct device names, as
350 specified in its configuration file. It is useful when all volumes for a
351 configuration have different device names -- for example, with S3 devices.
352 The <emphasis>changerfile</emphasis> need not exist; it is used as a prefix
353 for filenames of state files.
356 <para>The configuration file has simple lines with a parameter and its value separated by a space. The # character introduces a comment. The configuration parameters are: </para>
359 <varlistentry><term>multieject</term><listitem>If this is 1, use an 'mt
360 offline' command to change to the next tape, or multiple such commands for
361 skipping several tapes at a time.
362 </listitem></varlistentry>
364 <varlistentry><term>needeject</term><listitem>This option is incompatible with
365 'multieject'. This should be 1 for changers accessed through several virtual
366 tape devices, when the changer needs the current tape to be ejected before
367 changing to another device.
368 </listitem></varlistentry>
370 <varlistentry><term>gravity</term><listitem>Set this to 1 if the
371 changer/stacker is unable to loop back to the first tape after unloading the
372 last one, or if you don't want amanda to go through the tape stack looking for
373 the exact tape it wants instead of using the first acceptable one.
374 </listitem></varlistentry>
376 <varlistentry><term>slot X</term><listitem>The configuration file should list
377 as many 'slot X' statements as the number of slots supported by the changer or
378 the number of separate tape drives used.
379 </listitem></varlistentry>
382 <para>This changer is not fast-search capable.</para>
386 <refsect2><title>chg-manual</title>
388 tpchanger "chg-manual"
389 changerfile "chg-manual.conf"
392 <para>This script simply provides distinct device names in a round-robin
393 fashion, as specified in its configuration file. It is useful when all volumes
394 for a configuration have different device names -- for example, with S3
395 devices. The configuration file parameters are (as listed in the script):
397 resend_mail=900 # resend mail every __ seconds
398 timeout_mail=604800 # time out after this many seconds (default 7 days)
399 request="[type]" # How to request a new tape (default "tty_email")
400 request="tty" # Use the tty to ask the user to change tape.
401 # Can't be use by cron
402 request="email" # Send an email to ask the user to change tape.
403 request="tty_email" # Use the tty if it exist or send an email.
407 <para>This changer is not fast-search capable.</para>
411 <refsect2><title>chg-zd-mtx (old)</title>
413 tpchanger "chg-zd-mtx"
414 changerdev "/dev/sg0" # used with 'mtx -f'
415 changerfile "chg-zd-mtx.conf"
416 tapedev "tape:/dev/nst0"
419 <para>This script interfaces with a tape drive using the Zubkoff/Dandelion
420 version of mtx. That's the version that takes a device specifier with the
421 <command>-f</command> option and has subcommands like
422 <command>status</command>. The configuration file parameters are (as listed in
425 firstslot=? #### First storage slot (element)
426 lastslot=? #### Last storage slot (element)
427 cleanslot=-1 #### Slot with cleaner tape -- default is "-1"
428 #### Set negative to indicate no cleaner available
429 driveslot=0 #### Drive slot number. Defaults to 0
430 #### Use the 'Data Transfer Element' you want
431 autoclean=0 #### Set to '1' or greater to enable
432 autocleancount=99 #### Number of access before a clean.
433 havereader=0 #### If you have a barcode reader, set to 1.
434 offline_before_unload=0 #### Does your robot require an
435 #### 'mt offline' before mtx unload?
436 poll_drive_ready=NN #### Time (seconds) between tests to see if
437 #### the tape drive has gone ready (default: 3).
438 max_drive_wait=NN #### Maximum time (seconds) to wait for the
439 #### tape drive to become ready (default: 120).
440 initial_poll_delay=NN #### initial delay after load before polling for
442 slotinfofile=FILENAME #### record slot information to this file, in
443 #### the line-based format "SLOT LABEL\n"
447 <para>This changer is fast-search capable if and only if
448 <command>havereader</command> is true.</para>
452 <refsect2><title>chg-rait:{CHILD1,CHILD2,..}</title>
454 define changer vtape {
455 tpchanger "chg-disk:/path/to/vtape"
457 define changer robot {
458 tpchanger "chg-robot:/dev/sg0"
459 tapedev "tape:/dev/nst0"
461 tpchanger "chg-rait:{vtape,robot}"
464 <para>This changer script constructs RAIT devices out of the devices provided
465 by several "sub-changers". The sub-changers are specified using the same
466 shell-like syntax as the RAIT device (see <manref name="amanda-devices"
469 <para>Chg-rait does not require that all of the child changers have the same slot names: compound slot names are created by combining the slot names supplied by the child changers using the same shell-like syntax. For example, if the child changers return slots "<computeroutput>top</computeroutput>", "<computeroutput>strange</computeroutput>", and "<computeroutput>3</computeroutput>", then the RAIT changer will return "<computeroutput>{top,strange,3}</computeroutput>". This makes it possible to, for example, mirror data on tapes in slots 1-10 to tapes in slots 11-20 of the same robot, using two <command>chg-zd-mtx</command> child changers (and, naturally, two tape drives). In this arrangement, the first slot would be named <computeroutput>{1,11}</computeroutput>.</para>
471 <para>As a convenience to the user, the RAIT changer will also accept un-braced slot names, and supply the same name to each child changer. Thus with a 4-device RAIT changer, "<computeroutput>17</computeroutput>" is equivalent to "<computeroutput>{17,17,17,17}</computeroutput>".</para>
473 <para>Drive names are parsed in a similar fashion, for operations that take drive names (clean and eject).</para>
475 <para>This changer is fast-search capable only if all of its child changers are fast-search capable.</para>
477 <note>The old chg-rait script is no longer supported nor shipped with Amanda, although the old script will continue to function via <command>chg-compat</command>, giving users time to upgrade their configuration.
478 </note><!-- previous newline is important -->
482 <refsect2><title>chg-null:</title>
484 tpchanger "chg-null:"
487 <para>This changer always provides the device "null:". It is sometimes useful in conjunction with <command>chg-rait:</command>.</para>
491 <refsect2><title>chg-robot:DEVICE</title>
493 define changer robot {
494 tpchanger "chg-robot:/dev/sg0"
495 property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
496 property "eject-before-unload" "yes"
497 property "use-slots" "1-5,11-20"
502 <para>This changer drives a robotic tape library using the operating system's
503 <command>mtx</command> command. It replaces the ancient
504 <command>chg-zd-mtx</command> script. The changer uses all of the information
505 available to operate as efficiently as possible. Even without a barcode
506 reader, the changer can usually load a tape immediately, without resorting to a
507 sequential scan of many tapes. It is capable of sharing state across multiple
508 Amanda configurations, avoiding conflicts and optimally tracking the contents
509 of the library.</para>
511 <para>This changer does not accept a <command>changerdev</command> parameter,
512 but the <command>changerfile</command> parameter can be used to specify a
513 filename at which it should store its state. Ordinarily, this state is stored
514 in a file named after the changer device under
515 <emphasis>$localstatedir/amanda</emphasis>, e.g.,
516 <command>/var/amanda/chg-robot-dev-sg0</command>. There should be a single
517 such statefile for each distinct tape library attached to the Amanda server, even
518 if multiple Amanda configurations reference that library.</para>
520 <para>With a barcode reader present, it is possible for
521 <command>chg-robot</command> to track the state of the library reliably, even
522 recognizing tapes that are removed and later re-inserted (by remembering their
523 barcodes). Without barcodes, the changer can still remember the slot in which
524 it last saw the tape with a particular label, although this information can
525 become stale if the tapes are rearranged by an operator. In any case, the
526 changer will never "hunt" for a tape by repeatedly loading slots and checking
527 labels. If the changer's state is inaccurate, use the
528 <manref name="amtape" vol="8" /> subcommand <command>update</command>.</para>
530 <para>This changer is fast-search capable even without a barcode reader. For
531 such libraries, it is the responsibility of the operator to
532 <command>update</command> the changer when tapes are added to or removed from
535 <para>There is a shell script in the <filename>contrib/</filename> directory of
536 Amanda's source distribution which can help you convert a
537 <command>chg-zd-mtx</command> configuration into a <command>chg-robot</command>
538 configuration. Just give it your Amanda configuration name:
540 sh contrib/convert-zd-mtx-to-robot.sh $config
542 The script can be downloaded at <uri
543 type="webpage">http://github.com/zmanda/amanda/raw/master/contrib/convert-zd-mtx-to-robot.sh</uri></para>
545 <refsect3><title>Special Operations</title>
547 <para>A number of special operations are available for <command>chg-robot</command> via
548 <manref name="amtape" vol="8" /> subcommands.</para>
550 <para>The <command>reset</command> subcommand will change the current slot to
551 the first available slot, but does not erase any stored state maintained by the
554 <para>The <command>eject</command> subcommand will unload the volume in the
555 given drive, ejecting first if the changer properties dictate. Note that,
556 despite the subcommand name, the changer attempts to avoid the state where a
557 volume has been ejected from the drive but not unloaded back to a storage
560 <para>The <command>clean</command> subcommand is not yet implemented.</para>
562 <para>The <command>update</command> subcommand instructs the changer to update
563 its state database. Given no arguments, the changer will scan all available
564 slots, loading each tape and reading its label. Especially for large libraries,
565 this can take a long time. If only a few slots have changed, they can be listed
568 amtape CONFIG update 1-3,9
570 In this case, the changer will only scan the stated slots. Finally, the changer
571 will not scan at all if it is given the tape label for the slot:
573 amtape CONFIG update 2=DailySet-028
575 In this case, the changer updates its state to indicate that
576 <computeroutput>DailySet-028</computeroutput> is in slot 2, without trying to
579 amtape CONFIG update 1-3,9=
581 In this case, the changer marks the stated slots as an unknown state.
586 <refsect3><title>Properties</title>
587 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
591 <varlistentry><term>DRIVE-CHOICE</term><listitem>
592 This property controls the algorithm used to select a drive in which to load a
593 tape. If set to the default ("lru"), the changer attempts to use the least
594 recently used drive, resulting in a round-robin behavior. The "firstavail"
595 algorithm selects the first available drive, thus preferring the first drive
596 specified via the TAPE-DEVICE property.
597 </listitem></varlistentry>
599 <varlistentry><term>EJECT-BEFORE-UNLOAD</term><listitem>
600 Set this boolean property to true if the library requires an
601 <command>offline</command> operation be performed on the tape drive before it
602 can be unloaded. If set, then <command>mt</command> will be invoked to
603 perform this operation. Most libraries do not require this workaround.
604 </listitem></varlistentry>
606 <varlistentry><term>EJECT-DELAY</term><listitem>
607 This is the time between ejecting a tape and unloading the volume to a storage slot, and
608 defaults to 0 seconds. It is only used if EJECT-BEFORE-UNLOAD is true. See "Timing", below.
609 </listitem></varlistentry>
611 <varlistentry><term>FAST-SEARCH</term><listitem>
612 This boolean property indicates whether the changer advertises the ability to find
613 volumes without sequential scanning. The traditional taperscan algorithm alters its
614 behavior based on this flag, so it is sometimes necessary to adjust it, although the
615 changer will always search for a desired tape using the most efficient means
616 available. The default value is true.
617 </listitem></varlistentry>
619 <varlistentry><term>IGNORE-BARCODES</term><listitem>
620 If this boolean property is true, then chg-robot will ignore any barcode information
621 that the library provides. This property is probably only useful when the library
622 returns incorrect barcodes, for example due to a malfunction in the barcode reader.
623 </listitem></varlistentry>
625 <varlistentry><term>LOAD-POLL</term><listitem>
626 <para>This property specifies the timing of Amanda's polling for the tape drive to
627 be ready after loading a new tape. See "Timing", below.</para>
629 <para>The script "polls" by trying to open the tape device repeatedly until no
630 error is encountered. The property specifies the time to wait before the first
631 poll (D), the frequency at which to poll and retry on errors (P); and the time
632 after which it should give up (U). The format is
634 "D [poll P [until U]]"
636 For a simple delay with no polling, use e.g.,
638 property "load-poll" "13s"
640 To delay and then poll, use e.g.,
642 property "load-poll" "13s poll 5s"
644 and to add a maximum total time, use e.g.,
646 property "load-poll" "0s poll 5s until 2m"
648 The default value is <command>"0s poll 3s until 2m"</command>.
650 </listitem></varlistentry>
652 <varlistentry><term>LOCK-TIMEOUT</term><listitem>
653 The time in seconds amanda wait to lock the statefile (default:1000)
654 </listitem></varlistentry>
656 <varlistentry><term>MTX</term><listitem>
657 The path to the 'mtx' binary. The default value is defined at compile time.
658 </listitem></varlistentry>
660 <varlistentry><term>STATUS-INTERVAL</term><listitem>
661 This is the minimum time between invocations of <command>mtx status</command>
662 to determine the state of the changer library. The default value, 2 seconds,
663 avoids back-to-back status invocations but ensures that the metadata is up to
664 date. For operating systems or libraries where the <command>mtx
665 status</command> takes a considerable time to complete, this value should be
666 increased. See "Timing", below.
667 </listitem></varlistentry>
669 <varlistentry><term>TAPE-DEVICE</term><listitem>
670 This property describes the correspondance of drive numbers in the library to
671 Amanda devices, in the format <emphasis>DRIVE=DEVICE</emphasis>. The property
672 can be specified multiple times to describe multiple devices. The device will
673 usually be a tape device name starting with <command>tape:</command>, but may
674 also refer to a device alias (see <manref name="amanda-devices" vol="7"/>). As
675 a shortcut, if the <command>tapedev</command> parameter is specified in the
676 changer definition, then it is assumed to be the device name for drive 0.
677 </listitem></varlistentry>
679 <varlistentry><term>UNLOAD-DELAY</term><listitem>
680 This specifies the minimum time between an unload operation any any subsequent
681 operation. The default value is 0 seconds. See "Timing", below.
682 </listitem></varlistentry>
684 <varlistentry><term>USE-SLOTS</term><listitem>
685 This property, if specifies, enumerates the slots to which this changer should
686 limit itself. The slots are specified as a comma-separated list of ranges,
687 e.g., "1-5,11-15,19,22". The property can be specified more than once, and
688 the resulting sets will be combined. The changer will refuse to load tapes
689 not found in these slots, except for import/export purposes.
690 </listitem></varlistentry>
694 <refsect3><title>Timing</title>
696 <para>Tape libraries are fickle, and in many cases will report that an
697 operation is complete when it is still in progress. Chg-robot takes several
698 timing-related properties to accomodate such behavior.</para>
700 <para>A typical sequence of operations performed during a load are: get library
701 status, eject a tape, unload the tape back to a storage slot, load a new tape,
702 and read the label on that tape to ensure the drive is ready.</para>
704 <para>On most systems, the library status check is nearly instantaneous -- the
705 changer library provides its cached state to the host without initiating any
706 robot motion. In order to keep its metadata up-to-date, chg-robot runs this
707 command very frequently, but this frequency can be reduced (at the cost of
708 potentially stale metadata) by setting the STATUS-INTERVAL property to a larger
711 <para>Some tape libraries do not integrate the eject operation (performed by
712 the embedded tape drive) with the unload operation (performed by the library
713 robot), and can actually cause physical damage by attempting to remove the tape
714 before the ejection is complete. For such changers, set the EJECT-DELAY
715 property to allow enough time for the eject to complete.</para>
717 <para>Once a tape is unloaded, if the library needs time to "quiesce" before
718 processing another command, add that time to the UNLOAD-DELAY parameter. No
719 other operations will be performed on the library until this delay has
722 <para>Once a tape has been loaded, chg-robot waits until the drive is ready before
723 allowing Amanda to use the volume, as described for LOAD-POLL, above.</para>
725 <para>Each of the times specified in these properties may be given as integers
726 with the optional suffix <command>s</command> for seconds (the default) or
727 <command>m</command> for minutes.</para>
733 <refsect2><title>chg-ndmp:HOST[:PORT]@SCSIDEV</title>
735 tpchanger "chg-ndmp:filer.company.com@/dev/sg0"
736 property "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"
737 property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"
738 property "use-slots" "1-12"
739 property "ndmp-auth" "text"
740 property "ndmp-username" "luke"
741 property "ndmp-password" "leia"
744 <para>This changer is very similar to <command>chg-robot</command>, but
745 controls a tape changer on an NDMP server instead of a local device. The
746 <command>HOST</command> in the <command>tpchanger</command> should be the
747 hostname of the NDMP server. The <command>PORT</command> is optional. The
748 <command>SCSIDEV</command> should specify the SCSI device on the NDMP server
749 which controls the changer. The format of this parameter is
750 implementation-specific.</para>
752 <para>The appropriate authentication properties will be automatically set on
753 any devices created by this changer.</para>
755 <refsect3><title>Properties</title>
757 <para>This changer supports all of the properties supported by
758 <command>chg-robot</command>, although the value of <command>MTX</command> is
759 ignored. The following properties are also recognized:</para>
761 <!-- PLEASE KEEP THIS LIST IN ALPHABETICAL ORDER -->
764 <varlistentry><term>NDMP_AUTH</term><listitem>
765 Authentication method to use to connect to the NDMP server. One of
766 "md5" (default), "text", "none" (for an empty authentication attempt) or "void" (for
767 no authentication attempt at all).
768 </listitem></varlistentry>
770 <varlistentry><term>NDMP-PASSWORD</term><listitem>
771 The password for the NDMP server.
772 </listitem></varlistentry>
774 <varlistentry><term>NDMP-USERNAME</term><listitem>
775 The username for the NDMP server.
776 </listitem></varlistentry>
778 <varlistentry><term>VERBOSE</term><listitem>
779 If true, enables the NDMJOB library's verbose (packet-level) debugging.
780 </listitem></varlistentry>
788 <refsect2><title>chg-single:DEVICE</title>
790 tpchanger "chg-single:tape:/dev/nst0"
793 <para>This changer is for use with standalone drive, it can work with any
794 device. The device (<command>tape:/dev/nst0</command>) must be set in the tpchanger definition.</para>
795 <para>The <command>chg-single</command> changer has no property.</para>
799 <refsect2><title>Unmaintained Changers</title>
801 <para>Amanda has many other changer scripts and programs beyond those described
802 here (see the <computeroutput>changer-src/</computeroutput> in the source
803 directory), but most of these scripts are unmaintained and undocumented, and
804 will be removed when the new changer API is fully implemented.</para>
811 <manref name="amanda.conf" vol="5"/>,
812 <manref name="amanda-devices" vol="7"/>,