2 Chapter 8. Amanda Tape Changer Support
3 Prev Part II. About Tapes and Changers Next
5 -------------------------------------------------------------------------------
7 Chapter 8. Amanda Tape Changer Support
18 XML-conversion;Updates
26 Specifying_a_tape_changer_in_amanda.conf
28 Device-specific_tapechanger_script
30 Slot_names_and_the_"current"_slot
34 How_amdump_interacts_with_the_tape_changer
39 chg-multi_(formerly_chg-generic)
41 chg-manual_(formerly_no-changer)
43 chg-mtx_(formerly_hp-changer)
47 chg-scsi-chio_(formerly_seagate-changer,_then_chg-chio)
49 chg-scsi_(new_interface,_try_to_drive_a_robot_with_direct_scsi
72 This document outlines the tape changer support design of Amanda 2.2 and
73 beyond. It defines a small interface for changer software to follow so that
74 Amanda can remain device-independent but still support the widest range of tape
75 software and hardware possible.
76 The interface is a bit simplistic and has only had complications added when
77 there is a body of field experience.
79 Specifying a tape changer in amanda.conf
81 All device-specifics are hidden by a glue program that the rest of Amanda calls
82 to interact with the tape changer.
83 The name of this changer program is given by the "tpchanger" variable in the
84 file amanda.conf. Example entry:
86 tpchanger "chg-multi" # use multi-unit tape changer emulator
89 The tapedev parameter is ignored if a tpchanger program is specified, unless
90 the changer program itself reads tapedev from amanda.conf. The chg-multi
91 changer doesn't, as it reads all its configuration arguments from its own
92 configuration file, specified as changerfile.
93 If the tpchanger program does not begin with a '/', Amanda expects it to reside
94 in libexecdir, and possibly have the version suffix appended depending on how
95 Amanda was configured.
96 Two other amanda.conf parameters are available for changer use, however their
97 definition is left entirely up to the changer script itself. They are
98 changerfile and changerdev. Typically changerfile will point to the
99 configuration file specific to the changer, or be a base name of several
100 related changer files. The changerdev variable may point to the /dev entry used
101 to access the changer device.
102 See the documentation with the specific changer you're interested in to see
103 exaclty how these variables are used (if at all).
105 Device-specific tapechanger script
107 The tape changer script/program is always from the directory with amanda.conf.
108 It is never passed the configuration name it is running on behalf of, but since
109 amgetconf works without a name from the current directory, that should be
111 The script/program must support the following commands:
113 * <tpchanger> -slot <slot-specifier>
115 If changer is loaded, unloads the current slot (if different than "slot-
116 specifier") and puts that tape away, then loads the requested slot. See the
117 next section for the list of valid slot requests.
118 Outputs to stdout the slot name and name of the device file to access the tape
119 on success, or a slot name and error text.
120 Returns 0 on success.
121 Returns 1 on positioning error (eg at bottom of gravity stacker or slot empty).
122 Returns 2 any other fatal error. The slot name may be invalid, but must be
123 present. Error message goes to stdout in place of device name.
127 0 /dev/nrst8 # exitcode returned is 0
130 1 slot 1 is empty # exitcode returned is 1
132 % chg-multi -slot bogus-slot
133 <none> no slot `bogus-slot' # exitcode returned is 2
138 Outputs to stdout three or more fields:
139 The current slot string (required)
140 The number of slots (required)
141 Flag indicating whether the changer can go backwards
142 (0 if it can't, 1 if it can). (required)
143 Flag indicating whether the changer is searchable
144 (optional). Shows whether the changer supports the -search and -label commands
145 and is able to load a tape given only the Amanda label string (0 or omitted if
146 it can't, 1 if it can). (optional)
150 0 10 1 # exitcode returned is 0
158 Resets the changer to known state and loads the first slot.
159 Output and error handling are the same as
160 "<tpchanger> -slot first"
161 In the case of a gravity stacker that must be reset by hand, this could be run
162 (via " amtape <conf> reset") to inform the software the stacker is positioned
167 0 /dev/nrst8 # exitcode returned is 0
170 0 slot 0 is empty # exitcode returned is 1
173 0 tape-changer not responding # exitcode returned is 2
178 Unloads the current slot (if loaded) and puts that tape away.
179 Output and error handling are the same as the -slot command.
180 Note that a tape may or may not be loaded when this command completes,
181 depending on the hardware.
185 0 /dev/nrst8 # exitcode returned is 0
188 0 drive was not loaded # exitcode returned is 1
190 The tape changer program MAY support the following commands:
192 * <tpchanger> -search <labelstr>
194 Loads an Amanda tape by name (labelstr).
195 Output and error handling are the same as the -slot command.
196 taper, amcheck and amtape will use this command if the changer reports it is
200 % chg-zd-mtx -search DailySet005
201 5 /dev/nrst8 # exitcode returned is 0
203 -<tpchanger> -label <labelstr> Associates the Amanda label <labelstr> with the
204 barcode of the currently loaded (in the tape drive) tape.
205 Outputs to stdout the current slot and tape device. amlabel will use this
206 command if your changer is searchable to build up the barcode database.
209 % chg-zd-mtx -label DailySet006
210 6 /dev/nrst8 # exitcode returned is 0
212 For all the commands:
213 An exit code of 0 implies that the operation was completely successful, and the
214 output may be parsed by the Amanda code as described above.
215 For non-zero exit codes, the first field is still the slot name, but the actual
216 error messages are not fixed. They are just displayed and/or logged as-is by
217 the calling Amanda program.
218 An exit code of 1 implies the operation failed in a benign way, for example an
219 empty slot or an attempt to go backwards in a gravity stacker. The calling
220 Amanda program will print the error message if appropriate and continue,
221 perhaps requesting a different slot be loaded.
222 Any other exit code is considered fatal and will cause Amanda to stop
223 attempting to talk to the tape changer.
225 Slot names and the "current" slot
227 Some tape changers, such as carousels and gravity stackers, have a hardware
228 notion of current position. Others have no current position when no tape is
229 loaded: all tapes are in their slots and the changer arm is docked away from
231 Nevertheless, Amanda requires tape-changer scripts to maintain the notion of a
232 "current" position. This is for performance reasons: as tapes tend to be loaded
233 into the rack in order, and Amanda uses them in order, the next tape to use can
234 be found much quicker if the position of the current one is remembered. As an
235 example, the chg-multi script maintains the current position in a chg-
236 multi.state file (or any other file specified in a `statefile' line in the
237 changer configuration file).
238 Amanda does not care how slots are available or how they are named. They could
239 be numbered 0 to N-1, numbered 1 to N, or even designated by letter, A .. Z.
240 The only requirement is that the names do not contain whitespace and that the
241 names "current", "next", "prev", "first", "last" and "advance" retain their
243 current The position of the last loaded tape, as described above
244 next The position after current, wrapping from the last slot to the first.
245 prev The position before current, wrapping from the first slot to the last.
246 first The first slot in the tape rack.
247 last The last slot in the tape rack.
248 advance The same as "next" except the next tape may not be loaded if the
249 changer supports advancing to the next slot without putting that tape in the
251 The current position must be updated even if there is a positioning error (such
252 as "empty slot"). This allows amanda to step through the entire tape rack by
253 issuing successive "slot next" positioning commands.
257 The amtape program is the main operator interface to Amanda's tape changer
258 support. The commands supported include:
259 amtape <conf> slot <slot-specifier> Load the tape from the specified slot into
261 amtape <conf> eject Send an eject command to the tape-changer. Effect is
263 amtape <conf> reset Send a reset command to the tape-changer. Effect is changer
265 amtape <conf> show Go through the entire tape rack, showing the labels of all
266 amanda tapes encountered.
267 amtape <conf> label <label> Find and load the tape with the specified label
268 amtape <conf> taper Perform taper's scan algorithm (see below), loading the
269 tape which would be picked for the next amdump run.
270 amtape <conf> clean If a cleaning tape is defined by the changer, load it in
271 the drive and put it away when done.
272 amtape <conf> device Output the current tape device name.
273 amtape <conf> current Display the contents of the current slot.
274 amtape <conf> update Scan the entire tape rack and update the barcode database.
275 See the amtape(8) man page for more details.
276 In addition to amtape, amlabel has been modified to allow optionally specifying
278 amlabel <conf> <label> [slot <slot-specifier>]
279 amcheck looks for the next tape in the rack the same way the taper does. If
280 multiple tapes are used in one night, amcheck attempts to find all the needed
281 tapes in turn if the tape-changer is random access. On a one-way gravity
282 stacker, amcheck only finds the first tape, since finding the subsequent ones
283 would put the first one out of reach of that night's amdump run.
284 amrestore and amrecover do not yet include any tape changer support directly,
285 as amrestore knows nothing about the amanda.conf files or server-side
286 databases. This is a deliberate decision to keep amrestore independent, so it
287 can be run from any host with a tape drive, even if the original tape server
288 host is down. To use amrestore in a tape-changer environment, use amtape to
289 find the right tape, then run amrestore giving the resulting tape device name.
291 How amdump interacts with the tape changer
293 Amanda does not require a particular tape label for a run. Any label that
294 matches the labelstr regex and is determined to be "inactive" according to the
295 tapelist database, may be written to. However, there is a preferred 'next'
296 tape, the one that is next in the cycle implied by the current tapelist.
297 amdump uses two algorithms, depending on whether the tape changer can go
298 backwards in the rack or not. If multiple tapes are needed in a single run,
299 this algorithm is repeated in turn whenever a new tape is required.
300 Normal tape changers (those that can go backwards):
301 With a full-access tape changer, amdump searches the entire rack for the
302 preferred tape label. This tape will usually be found at the current or next
303 position, but might be located anywhere. If the tape is found, it is used. If
304 it is not found, the first tape encountered that matches the labelstr and is
305 not active is picked.
306 Gravity stackers (anything that can not go backwards):
307 To avoid going all the way to the bottom of the stacker only to find that the
308 preferred tape isn't present and nothing can be done, Amanda picks the first
309 tape (starting at the current position) that matches the labelstr and is not
310 active, regardless of whether it is the preferred tape.
312 Builtin tape-changers
315 chg-multi (formerly chg-generic)
317 This tape changer script supports several common configurations:
319 * Using multiple tape drives in a single host to emulate a tape changer. This
320 can also be used with a single physical drive to write several tapes in an
324 * Using a gravity stacker or a real changer configured to sequentially load the
325 next tape when the current one is ejected. Also supports a changer which
326 cycles to the first tape after loading the last one.
329 * Using a changer accessed through several "virtual" tape devices which
330 determine which slot actually gets loaded in the tape drive.
332 The advantage of this changer script is that you do not need to get into the
333 complexity of dealing with a real changer interface. All the action goes
334 through the tape device interface with standard mt commands, which eases many
335 portability issues. Many common tape jukeboxes can be configured in a
336 sequential or cycle mode.
337 chg-multi ignores `tapedev' and `changerdev' because `changerfile' may specify
338 several tape devices to be used. A sample configuration file may be found in
339 example/chg-multi.conf.
341 chg-manual (formerly no-changer)
343 This is a poor man's tape changer that requires the backup operator to change
344 tapes manually. It expects `tapedev' in amanda.conf to point to a valid tape
345 device, and stores some status data in files whose names start with the
346 `changerfile'. `changerdev' is ignored.
348 chg-mtx (formerly hp-changer)
350 An mtx-based tape changer script. `changerdev' must specify the tape device
351 controlled by the mtx program, and `tapedev' must point to the no-rewind tape
352 device to be used. More than likely, both `changerdev' and `tapedev' will
353 reference the same device file. `changerfile' must specify a prefix for status
354 files maintained by this script. It will maintain files named `changerfile'/
355 changer-clean and `changerfile'/changer-access. You may have to edit the script
356 to specify which slot contains a cleaning tape (cleanslot).
357 The mtx program must support commands such as `-s', `-l' and `-u'. If the one
358 you've got requires `status', `load' and `unload', you should use chg-zd-mtx
363 Based on chg-mtx, but modified in order to support the Zubkoff/Dandelion
364 version of mtx. Eric DOUTRELEAU <Eric.Doutreleau@int-evry.fr>, who contributed
365 this script, reported that it works on a Solaris/sparc box with a HP 1557A
367 In addition to the `changerfile'-clean and the `changerfile'-access files, it
368 maintains a `changerfile'-slot file that indicates the currently loaded slot.
369 There are lots of comments at the start of the script describing how to set it
372 chg-scsi-chio (formerly seagate-changer, then chg-chio)
374 A C program that relies on scsi tape-changer interfaces. It may either use the
375 tape changer interface specified in chio.h (Gerd Knor's SCSI media changer
376 driver, a Linux kernel loadable module), or it may use built-in tape changer
377 interfaces available on HPUX, Solaris 2.5, IRIX and possibly others, but only
378 the chio and HPUX interfaces are currently implemented . `tapedev' specifies
379 the tape device to be used; `changer_dev' is the device used to talk to the
380 kernel module (for chio, usually /dev/ch0), and `changerfile' specifies a
381 filename in which the current slot number will be stored.
382 Now there is another way, to get the chg-scsi a little bit more flexible. If
383 you use only one digit in the `tapedev' parameter, the chg-scsi expects that
384 changerfile points to a real configuration file, not only a counting file. In
385 this configuration file you may specify that the tapedrive needs an eject
386 command and an optional waittime, necessary after inserting the tape into the
387 drive. You are also able to configure a range of slots which should be used by
388 your configuration. The idea behind this is, that you don't want Amanda to
389 cycle all the tapes if Amanda searches exactly one tape. If you have a library
390 which supports more than one drive you can also specify which drive to use. For
391 each configuration (there should be at least one) you have to specify a file,
392 where Amanda remembers which tape is actually in the drive. For future use
393 there is also some stuff for cleaning the drives.
396 tapedev "x" with x between 0 and 9, selects the configuration to use
397 changerfile "filename" specifies the changer configuration file
400 In the changer-config-file the following could be set:
403 # x between 0 and 9 number of configurations defined. This should be the
404 first parameter in the config-file.
406 # x 0 or 1 1 means that the drives need an eject command, before the robot
409 # x between 0 and MAX_INT specifies the seconds to wait before the drive
410 could be used after inserting a tape. 5 should be OK.
412 # x some positive int How many cleanings does a cleaning tape survive
414 # The device for the robot
417 And then there come some configuration sections, separated by the word `config`
418 followed by the ordinal of that configuration (0 to 9). In each configuration
419 section you should specify:
421 drivenum x x between 0 and the number of drives in the library
422 This one specifies the drive to
423 use with this configuration
424 dev <device> The device for the tapedrive
425 startuse x x between 0 and maximum slotnumber of your library
426 Starting here we may use the tapes
427 enduse x x between start and maximum slotnumber
428 This is the last tape we may use
429 in this configuration. If we reach
430 this one the next will be start..
431 statfile <filename> Here we remember the last used
432 slot for this configuration
433 cleancart x x between 0 and maximum slotnumber
434 In this slot we find the
436 cleanfile <filename> Here we will remember how
437 often we used the cleaning tape
438 usagecount <filename> This points to a file which is
439 deleted after cleaning the drive
440 e.g. the usagetime of the drive
443 Comments begin with an '#' until end of line. Allowed separators are TAB and
446 chg-scsi (new interface, try to drive a robot with direct scsi commands)
448 The config and the syntax is the same as for chg-scsi-chio. New is the config
451 With this option and the option labelfile chg-scsi will try to create an
452 inventory. With this inventory it should be possible to use the search feature
455 This option will set the debug level and select for which part debug messages
456 should be sent to the debug file. In case of problems you should set it to 9:0
458 This will force the program to read the barcodes, and don not try to figure out
459 if there is an barcode reader available.
460 scsitapedev <devicename>
461 This device is used to control the tape, read status infos etc.
462 tapestatus <filename>
463 If this option is given on every eject/move the log pages of the tape device
464 will be dumped in this file. There are 2 log pages were you can see how many
465 read/write errors (corrected) are processed by the tape
467 This file is used for the mapping from barcode labels to Amanda volume labels.
468 It is used if the changer has a barcode reader. To initialize run amtape show,
469 this will add the mapping for the tapes in the magazine.
471 Use the mtio ioctl to eject the tape, use only if the standard (1) does not
472 work, and send the debug output (/tmp/amanda/chg-scsi.debug) to th@ant.han.de
474 With this it is possible to specify which internal driver to use for
475 controlling/error handling of the robot
477 Some as above but for the tape.
478 New command line option: -status
479 [all|types|robot|sense|ModeSenseRobot|ModeSenseTape|fd]
480 <all> will show the result form all options. <types> will list the known driver
481 types. <robot> will show the status of all elements (tape/robot/slots..)
482 <sense> will show the result from a request sense <ModeSenseRobot> will show
483 the sense page from the robot <ModeSenseTape> will show the sense page from the
484 tape <fd> will show the devices which are open, and some info about it.
485 At the moment changer with tape and robot on the same SCSI id ( but on
486 different luns) will run on the following platforms:
487 - HP_UX 10.20 - IRIX 6.x - Solaris - Linux - AIX - FreeBSD 3.0/4.0
488 Tape and robot on different IDs run native on - Linux - HP-UX 10.20 - Irix 6.x
490 Tape and robot on different IDs with special modules run on: Solaris with sst
491 kernel module, which is not any longer needed in solaris 2.8. See in the
492 contrib/sst directory The configuration on solaris 2.8 with the sgen driver is
493 done by creating the file /kernel/drv/sgen.conf
494 This file should contain at the beginning the following device-type-config-
495 list="changer","sequential"
496 This will force the driver to attach only to the devices with type either
497 changer (the robot) and sequential (the tape). Next you must tell the driver on
498 which id it should check for devices (tape on id 5, robot on id 6 in this
500 name="sgen" class="scsi" target=5 lun=0; name="sgen" class="scsi" target=6
502 This will create the 2 device files /dev/scsi/sequential/c0t5d0 (scsitapedev
503 option in chg-scsi.conf) /dev/scsi/changer/c0t6d0 (changer option in chg-
505 So the complete sgen.conf looks like: device-type-config-
506 list="changer","sequential name="sgen" class="scsi" target=5 lun=0; name="sgen"
507 class="scsi" target=6 lun=0;
508 For HP you have to create the special device files for the pass throu
509 interface. Check if the ctl driver is installed. Example:
512 Character Block Driver Class
515 Next check on which bus your drives are connected. (ioscan) with the Character
516 device num form the lsdev and the card instance from ioscan create the special
519 mknod /dev/scsi/1 c 203 0x001000
522 ||SCSI ID of the device
523 2 digit instance number from ioscan
525 On FreeBSD 4.0 the syntax for the device files has changed. Now you have to
526 tell chg-scsi the bus:target:lun combination. If you for example on your scsi
527 bus 0 target 3 an robot the syntax is changerdev 0:3:0 To get this info you can
528 use the camcontrol command, <camcontrl devlist> will give you a list of known
529 devices. Don't specify dev and scsitapedev in your chg-scsi.conf !!, this will
531 On Linux you need either sg (generic scsi) as module or it must be compiled
532 into the kernel. If the sg driver doses not work try to use the ioctl
533 interface. For that you have to undef the LINUX_CHG define in changer-src/scsi-
534 linux.c Also you have to change the NORMAL_TIMEOUT in /usr/src/linux/drivers/
535 scsi/scsi_ioctl.c from (10 * HZ) to (5 * 60 * HZ). On linux it does not run if
536 you are using an aha1542 SCSI controller. The driver can not handle the
537 extended request sense.
538 On IRIX you find the SCSI pass through interfaces for every device in /dev/
540 chg-scsi has been tested/run with the following devices: Exabyte 10h and eliant
541 tape HP-Surestore 1200e and C1553A tape BreeceHill Q2.15 (EXB-120) and DLT7000
542 tape Powerstor L200 and DLT7000 ARCHIVE Python 28849-XXX TANDBERG TDS 1420 ADIC
544 It is now possible with a changer that has barcode reader to load tapes faster.
545 Also amdump will find tapes faster. Every time a tape is labeled the
546 information in the labelfile will be updated. To initialize the label mapping
547 you can also do an amtape config show. This will put the mapping for all tapes
548 in the magazine into the mapping file.
549 For all problems please contact th@ant.han.de. Please include in your mail the
550 debug file. (/tmp/amanda/chg-scsi.debug)
554 (new perl script that replaces the original chg-chio written in C) This script
555 is based on the FreeBSD version of chio, a program to communicate with the
556 jukebox. This script has for the moment only been test with FreeBSD and is
557 likely not to work on any other system. Let me know if this is the case and
558 send me the output of the chio program for your version of chio. It does not
559 restrict the number of tapes, except that if there is only one tape in the
560 juke, it is supposed to be in max_slot and not in slot 1. [This is the first
561 version of the changer script and I would appreciate all comments on it, at
562 nick.hibma@jrc.it. It has been tested only with FreeBSD 2.2.5 and the
563 accompanying chio program.]
567 (formerly chs-changer) A tape changer script very similar to chg-multi, that
568 uses the `chs' program to change tapes. As in chg-multi, `tapedev' is ignored.
569 `changerfile' names its configuration file, similar to chg-multi.conf.
570 `changerdev' will be passed to CHS in a -f command-line switch, unless it is
571 set to an empty string or "/dev/null" (watch out for default values!)
575 (formerly rth-changer) A perl5 script that controls an HPc1553 tape drive via a
576 Peripheral Vision Inc. SCSI control subsystem that interprets commands sent on
577 the SCSI bus. It expects `tapedev' to specify the tape device to be used.
578 `changerfile' and `changerdev' are ignored.
582 A shell script that uses the Fermilab "juke" software (see http://www.fnal.gov/
583 fermitools, the "juke" link) to control tape chagners. It supports mounting
584 multiple tapes for RAIT tapedrive sets, both multiple jukeboxes, or one jukebox
585 with multiple tape drives, or combinations. 'juke' must be configured to know
586 tape drives by the same name Amanda calls them. It uses 'changerfile' to track
587 Amanda's current tape state, 'tapedev' must be the tape drive (or RAIT set)
588 name, and 'changerdev' is the juke software's name for the changer, or a csh-
589 glob that expands to several jukebox names (i.e. "changer{a,b,c}").
593 A shell script that runs other changers in tandem, and returns a rait:
594 {dev1,dev2,...} tape device based on the results of each other changer. So if
595 you wanted to have 2 stackers striped with no parity, and you have chg-mtx
596 support for your stackers, you would use the follwing changerfile:
600 tpchanger_1="chg-mtx"
601 changerdev_1="/dev/mtx1"
602 changerfile_1="/some/file1"
603 tapedev_1="/some/dev"
604 tpchanger_2="chg-mtx"
605 changerdev_2="/dev/mtx2"
606 changerfile_2="/some/file2"
607 tapedev_2="/some/dev"
608 tpchanger_3="chg-null"
609 changerdev_3="/dev/null"
610 changerfile_3="/some/file3"
611 tapedev_3="/some/dev"
613 The third uses the null changer. The tapedev_n entries are only needed if the
614 changerfile in question uses them.
618 Clone of the chg-zd-mtx, but modified to be applied on local directories
619 instead of tapes. This changer emulates a robotic that uses virtual tapes
620 instead of real ones, where the virtual tapes are real directories on a hard
622 The directory tree should be:
632 Where "slot_root_dir" is the tapedev "file:xxx" parameter and "n" the tapecycle
634 Please refer to How_to_use_the_Amanda_file-driver for details of usage.
638 This changer script is designed for IOMEGA or JAZZ disks of various sizes as
639 well as any other removable disk media. This is a PURELY MANUAL changer. It
640 requests insertion of disk media via messages on /dev/tty. So it cannot be used
641 via crontab. Make sure you comply with any of the following. - Add statements
643 tpchanger "chg-iomega"
644 tapedev "file:<mount_point_of_removable_disk>"
645 (e.g. tapedev "file:/mnt/iomega" )
649 define tapetype IOMEGA {
650 comment "IOMega 250 MB floppys"
656 to your amanda.conf. - Add entry to /etc/fstab to specify mount point of
657 removable disk and make this disk mountable by any user. - Format all disks,
658 add a "data" sub directory and label all disks by using amlabel. - Be aware
659 that as of version 2.4.4p1, Amanda can't handle backups that are larger than
660 the size of the removable disk media. So make sure /etc/amanda/<backup_set>/
661 disklist specifies chunks smaller than the disk size.
665 A trivial changer which loads/unloads on a null: device. Useful with chg-rait
666 to throw away a parity stripe by puttin on a null jukebox, or for testing.
670 Refer to http://www.amanda.org/docs/tapechangers.html for the current version
672 -------------------------------------------------------------------------------
675 Chapter 7. Tapetypes Home Chapter 9. chg-scsi