1 AMANDA TAPE CHANGER SUPPORT
3 Originally by James da Silva <jds@cs.umd.edu>
4 Heavily modified by various contributors
8 This document outlines the tape changer support design of Amanda 2.2
9 and beyond. It defines a small interface for changer software to follow
10 so that Amanda can remain device-independent but still support the widest
11 range of tape software and hardware possible.
13 The interface is a bit simplistic and has only had complications added
14 when there is a body of field experience.
17 2. SPECIFYING A TAPE CHANGER IN AMANDA.CONF
19 All device-specifics are hidden by a glue program that the rest of Amanda
20 calls to interact with the tape changer.
22 The name of this changer program is given by the "tpchanger" variable
23 in the amanda.conf file. Example entry:
25 tpchanger "chg-multi" # use multi-unit tape changer emulator
27 The tapedev parameter is ignored if a tpchanger program is specified,
28 unless the changer program itself reads tapedev from amanda.conf.
29 The chg-multi changer doesn't, as it reads all its configuration arguments
30 from its own configuration file, specified as changerfile.
32 If the tpchanger program does not begin with a '/', Amanda expects it
33 to reside in libexecdir, and possibly have the version suffix appended
34 depending on how Amanda was configured.
36 Two other amanda.conf parameters are available for changer use, however
37 their definition is left entirely up to the changer script itself.
38 They are changerfile and changerdev. Typically changerfile will point
39 to the configuration file specific to the changer, or be a base name
40 of several related changer files. The changerdev variable may point to
41 the /dev entry used to access the changer device.
43 See the documentation with the specific changer you're interested in to
44 see exaclty how these variables are used (if at all).
47 3. DEVICE-SPECIFIC TAPE CHANGER SCRIPT
49 The tape changer script/program is always from the directory with
50 amanda.conf. It is never passed the configuration name it is running
51 on behalf of, but since amgetconf works without a name from the current
52 directory, that should be sufficient.
54 The script/program must support the following commands:
56 <tpchanger> -slot <slot-specifier>
58 If changer is loaded, unloads the current slot (if
59 different than "slot-specifier") and puts that tape away,
60 then loads the requested slot. See the next section for
61 the list of valid slot requests.
63 Outputs to stdout the slot name and name of the device
64 file to access the tape on success, or a slot name and
69 Returns 1 on positioning error (eg at bottom of gravity
70 stacker or slot empty).
72 Returns 2 any other fatal error.
73 The slot name may be invalid, but must be present.
74 Error message goes to stdout in place of device name.
78 0 /dev/nrst8 # exitcode returned is 0
81 1 slot 1 is empty # exitcode returned is 1
83 % chg-multi -slot bogus-slot
84 <none> no slot `bogus-slot' # exitcode returned is 2
89 Outputs to stdout three or more fields:
91 * The current slot string (required)
93 * The number of slots (required)
95 * Flag indicating whether the changer can go backwards
96 (0 if it can't, 1 if it can). (required)
98 * Flag indicating whether the changer is searchable
99 (optional). Shows whether the changer supports
100 the -search and -label commands and is able to
101 load a tape given only the Amanda label string
102 (0 or omitted if it can't, 1 if it can). (optional)
106 0 10 1 # exitcode returned is 0
113 Resets the changer to known state and loads the first slot.
115 Output and error handling are the same as
117 "<tpchanger> -slot first"
119 In the case of a gravity stacker that must be reset
120 by hand, this could be run (via "amtape <conf> reset")
121 to inform the software the stacker is positioned back
126 0 /dev/nrst8 # exitcode returned is 0
129 0 slot 0 is empty # exitcode returned is 1
132 0 tape-changer not responding # exitcode returned is 2
136 Unloads the current slot (if loaded) and puts that tape away.
138 Output and error handling are the same as the -slot command.
140 Note that a tape may or may not be loaded when this command
141 completes, depending on the hardware.
145 0 /dev/nrst8 # exitcode returned is 0
148 0 drive was not loaded # exitcode returned is 1
150 The tape changer program MAY support the following commands:
152 <tpchanger> -search <labelstr>
154 Loads an Amanda tape by name (labelstr).
156 Output and error handling are the same as the -slot command.
158 Taper, amcheck and amtape will use this command if the
159 changer reports it is searchable.
162 % chg-zd-mtx -search DailySet005
163 5 /dev/nrst8 # exitcode returned is 0
165 <tpchanger> -label <labelstr>
166 Associates the Amanda label <labelstr> with the barcode
167 of the currently loaded (in the tape drive) tape.
169 Outputs to stdout the current slot and tape device.
170 Amlabel will use this command if your changer is
171 searchable to build up the barcode database.
174 % chg-zd-mtx -label DailySet006
175 6 /dev/nrst8 # exitcode returned is 0
178 For all the commands:
180 An exit code of 0 implies that the operation was completely
181 successful, and the output may be parsed by the Amanda code as
184 For non-zero exit codes, the first field is still the slot name,
185 but the actual error messages are not fixed. They are just
186 displayed and/or logged as-is by the calling amanda program.
188 An exit code of 1 implies the operation failed in a benign way,
189 for example an empty slot or an attempt to go backwards in a
190 gravity stacker. The calling Amanda program will print the
191 error message if appropriate and continue, perhaps requesting
192 a different slot be loaded.
194 Any other exit code is considered fatal and will cause Amanda
195 to stop attempting to talk to the tape changer.
198 4. SLOT NAMES AND THE "CURRENT" SLOT
200 Some tape changers, such as carousels and gravity stackers, have a hardware
201 notion of current position. Others have no current position when no tape
202 is loaded: all tapes are in their slots and the changer arm is docked away
205 Nevertheless, Amanda requires tape-changer scripts to maintain the
206 notion of a "current" position. This is for performance reasons: as
207 tapes tend to be loaded into the rack in order, and Amanda uses them in
208 order, the next tape to use can be found much quicker if the position
209 of the current one is remembered. As an example, the chg-multi script
210 maintains the current position in a "chg-multi.state" file (or any other
211 file specified in a `statefile' line in the changer configuration file).
213 Amanda does not care how slots are available or how they are named.
214 They could be numbered 0 to N-1, numbered 1 to N, or even designated by
215 letter, A .. Z. The only requirement is that the names do not contain
216 whitespace and that the names "current", "next", "prev", "first", "last"
217 and "advance" retain their meaning as follows:
219 current The position of the last loaded tape, as described above
221 next The position after current, wrapping from the last slot to
224 prev The position before current, wrapping from the first slot to
227 first The first slot in the tape rack.
229 last The last slot in the tape rack.
231 advance The same as "next" except the next tape may not be loaded if
232 the changer supports advancing to the next slot without
233 putting that tape in the drive.
235 The current position must be updated even if there is a positioning error
236 (such as "empty slot"). This allows amanda to step through the entire tape
237 rack by issuing successive "-slot next" positioning commands.
240 5. OPERATOR INTERFACE
242 The amtape program is the main operator interface to Amanda's tape
243 changer support. The commands supported include:
245 amtape <conf> slot <slot-specifier>
246 Load the tape from the specified slot into the drive
249 Send an eject command to the tape-changer. Effect is changer
253 Send a reset command to the tape-changer. Effect is changer
257 Go through the entire tape rack, showing the labels of all
258 amanda tapes encountered.
260 amtape <conf> label <label>
261 Find and load the tape with the specified label
264 Perform taper's scan algorithm (see below), loading the tape
265 which would be picked for the next amdump run.
268 If a cleaning tape is defined by the changer, load it in
269 the drive and put it away when done.
272 Output the current tape device name.
274 amtape <conf> current
275 Display the contents of the current slot.
278 Scan the entire tape rack and update the barcode database.
280 See the amtape(8) man page for more details.
282 In addition to amtape, amlabel has been modified to allow optionally
285 amlabel <conf> <label> [slot <slot-specifier>]
287 Amcheck looks for the next tape in the rack the same way the taper does.
288 If multiple tapes are used in one night, amcheck attempts to find all the
289 needed tapes in turn if the tape-changer is random access. On a one-way
290 gravity stacker, amcheck only finds the first tape, since finding the
291 subsequent ones would put the first one out of reach of that night's
294 Amrestore and amrecover do not yet include any tape changer support
295 directly, as amrestore knows nothing about the amanda.conf files or
296 server-side databases. This is a deliberate decision to keep amrestore
297 independent, so it can be run from any host with a tape drive, even
298 if the original tape server host is down. To use amrestore in a
299 tape-changer environment, use amtape to find the right tape, then run
300 amrestore giving the resulting tape device name.
303 6. HOW AMDUMP INTERACTS WITH THE TAPE CHANGER
305 Amanda does not require a particular tape label for a run. Any label
306 that matches the labelstr regex and is determined to be "inactive"
307 according to the tapelist database, may be written to. However, there
308 is a preferred 'next' tape, the one that is next in the cycle implied
309 by the current tapelist.
311 Amdump uses two algorithms, depending on whether the tape changer can go
312 backwards in the rack or not. If multiple tapes are needed in a single
313 run, this algorithm is repeated in turn whenever a new tape is required.
315 Normal tape changers (those that can go backwards):
317 With a full-access tape changer, Amdump searches the entire rack for the
318 preferred tape label. This tape will usually be found at the current
319 or next position, but might be located anywhere. If the tape is found,
320 it is used. If it is not found, the first tape encountered that matches
321 the labelstr and is not active is picked.
323 Gravity stackers (anything that can not go backwards):
325 To avoid going all the way to the bottom of the stacker only to find that
326 the preferred tape isn't present and nothing can be done, Amanda picks the
327 first tape (starting at the current position) that matches the labelstr
328 and is not active, regardless of whether it is the preferred tape.
331 7. BUILT-IN TAPE CHANGERS
333 ================================
334 chg-multi (formerly chg-generic)
335 ================================
337 This tape changer script supports several common configurations:
339 - Using multiple tape drives in a single host to emulate a tape changer.
340 This can also be used with a single physical drive to write several
341 tapes in an amanda run.
343 - Using a gravity stacker or a real changer configured to sequentially
344 load the next tape when the current one is ejected. Also supports
345 a changer which cycles to the first tape after loading the last one.
347 - Using a changer accessed through several "virtual" tape devices
348 which determine which slot actually gets loaded in the tape drive.
350 The advantage of this changer script is that you do not need to get into
351 the complexity of dealing with a real changer interface. All the action
352 goes through the tape device interface with standard "mt" commands,
353 which eases many portability issues. Many common tape jukeboxes can be
354 configured in a sequential or cycle mode.
356 chg-multi ignores `tapedev' and `changerdev' because `changerfile' may
357 specify several tape devices to be used. A sample configuration file
358 may be found in example/chg-multi.conf.
360 ================================
361 chg-manual (formerly no-changer)
362 ================================
364 This is a poor man's tape changer that requires the backup operator to
365 change tapes manually. It expects `tapedev' in amanda.conf to point to
366 a valid tape device, and stores some status data in files whose names
367 start with the `changerfile'. `changerdev' is ignored.
369 =============================
370 chg-mtx (formerly hp-changer)
371 =============================
373 An mtx-based tape changer script. `changerdev' must specify the tape
374 device controlled by the mtx program, and `tapedev' must point to the
375 no-rewind tape device to be used. More than likely, both `changerdev' and
376 `tapedev' will reference the same device file. `changerfile' must specify
377 a prefix for status files maintained by this script. It will maintain
378 files named `changerfile'/changer-clean and `changerfile'/changer-access.
379 You may have to edit the script to specify which slot contains a cleaning
382 The `mtx' program must support commands such as `-s', `-l' and `-u'.
383 If the one you've got requires `status', `load' and `unload', you should
384 use chg-zd-mtx instead (see below).
390 Based on chg-mtx, but modified in order to support the Zubkoff/Dandelion
391 version of mtx. Eric DOUTRELEAU <Eric.Doutreleau@int-evry.fr>, who
392 contributed this script, reported that it works on a Solaris/sparc box
393 with a HP 1557A stacker.
395 In addition to the `changerfile'-clean and the `changerfile'-access files,
396 it maintains a `changerfile'-slot file that indicates the currently
399 There are lots of comments at the start of the script describing how to
406 Clone of the chg-zd-mtx, but modified to be applied on local directories
407 instead of tapes. This changer emulates a robotic that uses virtual
408 tapes instead of real ones, where the virtual tapes are real directories
411 The directory tree should be:
420 Where "slot_root_dir" is the tapedev "file:xxx" parameter and "n" the
423 Please refer to the HOWTO-FILE-DRIVER for details of usage.
428 =======================================================
429 chg-scsi-chio (formerly seagate-changer, then chg-chio)
430 =======================================================
432 A C program that relies on scsi tape-changer interfaces. It may
433 either use the tape changer interface specified in chio.h (Gerd Knor's
434 SCSI media changer driver, a Linux kernel loadable module), or it may
435 use built-in tape changer interfaces available on HPUX, Solaris 2.5,
436 IRIX and possibly others, but only the chio and HPUX interfaces are
437 currently implemented . `tapedev' specifies the tape device to be
438 used; `changer_dev' is the device used to talk to the kernel module
439 (for chio, usually /dev/ch0), and `changerfile' specifies a filename
440 in which the current slot number will be stored.
442 Now there is another way, to get the chg-scsi a little bit more
443 flexible. If you use only one digit in the `tapedev' parameter, the
444 chg-scsi expects that changerfile points to a real configuration file,
445 not only a counting file. In this configuration file you may specify
446 that the tapedrive needs an eject command and an optional waittime,
447 necessary after inserting the tape into the drive. You are also able
448 to configure a range of slots which should be used by your
449 configuration. The idea behind this is, that you don't want amanda to
450 cycle all the tapes if amanda searches exactly one tape. If you have
451 a library which supports more than one drive you can also specify
452 which drive to use. For each configuration (there should be at least
453 one) you have to specify a file, where amanda remembers which tape is
454 actually in the drive. For future use there is also some stuff for
459 tapedev "x" with x between 0 and 9, selects the configuration to use
460 changerfile "filename" specifies the changer configuration file
462 In the changer-config-file the following could be set:
463 number_configs x x between 0 and 9 number of configurations
464 defined. This should be
465 the first parameter in the
467 eject x x 0 or 1 1 means that the drives need
468 an eject command, before the
469 robot can handle the tape.
470 sleep x x between 0 and MAX_INT specifies the seconds to wait
471 before the drive could be used
472 after inserting a tape. 5
474 cleanmax x x some positive int How many cleanings does a
475 cleaning tape survive
476 changerdev <device> The device for the robot
478 And then there come some configuration sections, separated by the word `config`
479 followed by the ordinal of that configuration (0 to 9). In each configuration
480 section you should specify:
482 drivenum x x between 0 and the number of drives in the library
483 This one specifies the drive to
484 use with this configuration
485 dev <device> The device for the tapedrive
486 startuse x x between 0 and maximum slotnumber of your library
487 Starting here we may use the tapes
488 enduse x x between start and maximum slotnumber
489 This is the last tape we may use
490 in this configuration. If we reach
491 this one the next will be start..
492 statfile <filename> Here we remember the last used
493 slot for this configuration
494 cleancart x x between 0 and maximum slotnumber
495 In this slot we find the
497 cleanfile <filename> Here we will remember how
498 often we used the cleaning tape
499 usagecount <filename> This points to a file which is
500 deleted after cleaning the drive
501 e.g. the usagetime of the drive
503 Comments begin with an '#' until end of line.
504 Allowed separators are TAB and SPACE.
506 ========================================================================
507 chg-scsi (new interface, try to drive a robot with direct scsi commands)
508 ========================================================================
510 The config and the sysntax is the same as for chg-scsi-chio. New
515 With this option and the option labelfile chg-scsi will try to create an inventory.
516 With this inventory it should be possible to use the search feature for loading tapes.
520 This option will set the debug level and select for which part debug messages should be sent
521 to the debug file. In case of problems you should set it to 9:0
525 This will force the program to read the barcodes, and don not try to figure out if there is an
526 barcode reader available.
528 scsitapedev <devicename>
530 This device is used to control the tape, read status infos etc.
532 tapestatus <filename>
534 If this option is given on every eject/move the log pages of the tape
535 device will be dumped in this file. There are 2 log pages were you
536 can see how many read/write errors (corrected) are processed by the tape
540 This file is used for the mapping from barcode labels to amanda volume labels.
541 It is used if the changer has a barcode reader. To initialize run amtape show,
542 this will add the mapping for the tapes in the magazine.
546 Use the mtio ioctl to eject the tape, use only if the standard (1) does
547 not work, and send the debug output (/tmp/amanda/chg-scsi.debug) to
552 With this it is possible to specify which internal driver to use for
553 controlling/error handling of the robot
557 Some as above but for the tape.
560 New command line option:
561 -status [all|types|robot|sense|ModeSenseRobot|ModeSenseTape|fd]
563 <all> will show the result form all options.
564 <types> will list the known driver types.
565 <robot> will show the status of all elements (tape/robot/slots..)
566 <sense> will show the result from a request sense
567 <ModeSenseRobot> will show the sense page from the robot
568 <ModeSenseTape> will show the sense page from the tape
569 <fd> will show the devices which are open, and some info about it.
572 At the moment changer with tape and robot on the same SCSI id (
573 but on different luns) will run on the following plattforms
581 Tape and robot on different IDs run native on
587 Tape and robot on different IDs with special modules run on:
589 Solaris with sst kernel module, which is not any longer needed in solaris 2.8.
590 See in the contrib/sst directory
591 The configuration on solaris 2.8 with the sgen driver is done by creating
592 the file /kernel/drv/sgen.conf
593 This file should contain at the beginning the following
594 device-type-config-list="changer","sequential"
596 This will force the driver to attach only to the devices with type either
597 changer (the robot) and sequential (the tape).
598 Next you must tell the driver on which id it should check for devices
599 (tape on id 5, robot on id 6 in this example),
600 name="sgen" class="scsi" target=5 lun=0;
601 name="sgen" class="scsi" target=6 lun=0;
603 This will create the 2 device files
604 /dev/scsi/sequential/c0t5d0 (scsitapedev option in chg-scsi.conf)
605 /dev/scsi/changer/c0t6d0 (changer option in chg-scsi.conf)
607 So the complete sgen.conf looks like:
608 device-type-config-list="changer","sequential
609 name="sgen" class="scsi" target=5 lun=0;
610 name="sgen" class="scsi" target=6 lun=0;
613 For HP you have to create the special device files for the pass throu
614 interface. Check if the ctl driver is installed.
617 Character Block Driver Class
620 Next check on which bus your drives are connected. (ioscan)
622 with the Character device num form the lsdev and the card instance from
623 ioscan create the special file.
625 mknod /dev/scsi/1 c 203 0x001000
628 ||SCSI ID of the device
629 2 digit instance number from ioscan
631 On FreeBSD 4.0 the syntax for the device files has changed. Now you
632 have to tell chg-scsi the bus:target:lun combination. If you for
633 example on your scsi bus 0 target 3 an robot the syntax is
635 To get this info you can use the camcontrol command, <camcontrl devlist>
636 will give you a list of known devices.
637 Don't specify dev and scsitapedev in your chg-scsi.conf !!, this will
640 On Linux you need either sg (generic scsi) as module or it must be compiled
641 into the kernel. If the sg driver doses not work try to use the ioctl interface.
642 For that you have to undef the LINUX_CHG define in changer-src/scsi-linux.c
643 Also you have to change the NORMAL_TIMEOUT in /usr/src/linux/drivers/scsi/scsi_ioctl.c
644 from (10 * HZ) to (5 * 60 * HZ).
645 On linux it does not run if you are using an aha1542 SCSI controller. The
646 driver can not handle the extended request sense.
648 On IRIX you find the SCSI pass through interfaces for every device in /dev/scsi
650 chg-scsi has been tested/run with the following devices
651 Exabyte 10h and eliant tape
652 HP-Surestore 1200e and C1553A tape
653 BreeceHill Q2.15 (EXB-120) and DLT7000 tape
654 Powerstor L200 and DLT7000
655 ARCHIVE Python 28849-XXX
659 It is now possible with a changer that has barcode reader to load tapes faster.
660 Also amdump will find tapes faster. Every time a tape is labeled the information
661 in the labelfile will be updated. To initialize the label mapping you can also
662 do an amtape config show. This will put the mapping for all tapes in the magazine
663 into the mapping file.
665 For all problems please contact th@ant.han.de. Please include in your
666 mail the debug file. (/tmp/amanda/chg-scsi.debug)
669 ===========================================================================
670 chg-chio (new perl script that replaces the original chg-chio written in C)
671 ===========================================================================
673 This script is based on the FreeBSD version of chio, a program to
674 communicate with the jukebox. This script has for the moment only
675 been test with FreeBSD and is likely not to work on any other system.
676 Let me know if this is the case and send me the output of the chio
677 program for your version of chio.
679 It does not restrict the number of tapes, except that if there is only
680 one tape in the juke, it is supposed to be in max_slot and not in slot 1.
682 [This is the first version of the changer script and I would
683 appreciate all comments on it, at nick.hibma@jrc.it. It has been
684 tested only with FreeBSD 2.2.5 and the accompanying chio program.]
686 ==============================
687 chg-chs (formerly chs-changer)
688 ==============================
690 A tape changer script very similar to chg-multi, that uses the `chs'
691 program to change tapes. As in chg-multi, `tapedev' is ignored.
692 `changerfile' names its configuration file, similar to chg-multi.conf.
693 `changerdev' will be passed to CHS in a -f command-line switch, unless
694 it is set to an empty string or "/dev/null" (watch out for default
697 ==============================
698 chg-rth (formerly rth-changer)
699 ==============================
701 A perl5 script that controls an HPc1553 tape drive via a Peripheral
702 Vision Inc. SCSI control subsystem that interprets commands sent on
703 the SCSI bus. It expects `tapedev' to specify the tape device to be
704 used. `changerfile' and `changerdev' are ignored.
706 ==============================
708 ==============================
710 A shell script that uses the Fermilab "juke" software (see
711 http://www.fnal.gov/fermitools/, the "juke" link) to control
712 tape chagners. It supports mounting multiple tapes for RAIT
713 tapedrive sets, both multiple jukeboxes, or one jukebox with
714 multiple tape drives, or combinations. 'juke' must be configured
715 to know tape drives by the same name Amanda calls them.
717 It uses 'changerfile' to track Amanda's current tape state,
718 'tapedev' must be the tape drive (or RAIT set) name, and 'changerdev'
719 is the juke software's name for the changer, or a csh-glob that
720 expands to several jukebox names (i.e. "changer{a,b,c}")
722 ==============================
724 ==============================
726 A shell script that runs other changers in tandem, and returns
727 a rait:{dev1,dev2,...} tape device based on the results of
728 each other changer. So if you wanted to have 2 stackers
729 striped with no parity, and you have chg-mtx support for your
730 stackers, you would use the follwing changerfile:
733 tpchanger_1="chg-mtx"
734 changerdev_1="/dev/mtx1"
735 changerfile_1="/some/file1"
736 tapedev_1="/some/dev"
737 tpchanger_2="chg-mtx"
738 changerdev_2="/dev/mtx2"
739 changerfile_2="/some/file2"
740 tapedev_2="/some/dev"
741 tpchanger_3="chg-null"
742 changerdev_3="/dev/null"
743 changerfile_3="/some/file3"
744 tapedev_3="/some/dev"
746 The third uses the null changer. The tapedev_n entries are only needed
747 if the changerfile in question uses them.
750 ================================
752 ================================
754 This changer script is designed for IOMEGA or JAZZ disks of various sizes
755 as well as any other removable disk media.
757 This is a PURELY MANUAL changer. It requests insertion of disk media via
758 messages on /dev/tty. So it cannot be used via crontab.
760 Make sure you comply with any of the following.
762 tpchanger "chg-iomega"
763 tapedev "file:<mount_point_of_removable_disk>"
764 (e.g. tapedev "file:/mnt/iomega" )
768 define tapetype IOMEGA {
769 comment "IOMega 250 MB floppys"
774 to your /etc/amanda/<backup_set>/amanda.conf file
775 - Add entry to /etc/fstab to specify mount point of removable disk
776 and make this disk mountable by any user.
777 - Format all disks, add a "data" sub directory and label all disks
778 by a call to amlabel.
779 - Be aware that as of version 2.4.4p1, amanda can't handle backups that are
780 larger than the size of the removable disk media. So make sure
781 /etc/amanda/<backup_set>/disklist specifies chunks smaller than the
785 ==============================
787 ==============================
789 A trivial changer which loads/unloads on a null: device. Useful with
790 chg-rait to throw away a parity stripe by puttin on a null jukebox,