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