Imported Upstream version 2.4.4p3
[debian/amanda] / docs / TAPE.CHANGERS
1 AMANDA TAPE CHANGER SUPPORT
2
3 Originally by James da Silva <jds@cs.umd.edu>
4 Heavily modified by various contributors
5
6 1. INTRODUCTION
7
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.
12
13 The interface is a bit simplistic and has only had complications added
14 when there is a body of field experience.
15
16
17 2. SPECIFYING A TAPE CHANGER IN AMANDA.CONF
18
19 All device-specifics are hidden by a glue program that the rest of Amanda
20 calls to interact with the tape changer.
21
22 The name of this changer program is given by the "tpchanger" variable
23 in the amanda.conf file.  Example entry:
24
25         tpchanger "chg-multi"      # use multi-unit tape changer emulator
26
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.
31
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.
35
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.
42
43 See the documentation with the specific changer you're interested in to
44 see exaclty how these variables are used (if at all).
45
46
47 3. DEVICE-SPECIFIC TAPE CHANGER SCRIPT
48
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.
53
54 The script/program must support the following commands:
55
56     <tpchanger> -slot <slot-specifier>
57
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.
62
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
65                 error text.
66
67                 Returns 0 on success.
68
69                 Returns 1 on positioning error (eg at bottom of gravity
70                 stacker or slot empty).
71
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.
75
76         Examples:
77                 % chg-multi -slot 0
78                 0 /dev/nrst8                    # exitcode returned is 0
79
80                 % chg-multi -slot 1
81                 1 slot 1 is empty               # exitcode returned is 1
82
83                 % chg-multi -slot bogus-slot
84                 <none> no slot `bogus-slot'     # exitcode returned is 2
85
86
87     <tpchanger> -info 
88
89                 Outputs to stdout three or more fields:
90                 
91                   * The current slot string (required)
92                   
93                   * The number of slots (required)
94
95                   * Flag indicating whether the changer can go backwards
96                     (0 if it can't, 1 if it can). (required)
97
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)
103
104         Examples:
105                 % chg-multi -info
106                 0 10 1                          # exitcode returned is 0
107
108                 % chg-zd-mtx -info
109                 0 10 1 1
110
111     <tpchanger> -reset
112
113                 Resets the changer to known state and loads the first slot.
114
115                 Output and error handling are the same as
116
117                   "<tpchanger> -slot first"
118
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
122                 at the top.
123
124         Examples:
125                 % chg-multi -reset
126                 0 /dev/nrst8                    # exitcode returned is 0
127
128                 % chg-multi -reset
129                 0 slot 0 is empty               # exitcode returned is 1
130
131                 % chg-multi -reset
132                 0 tape-changer not responding   # exitcode returned is 2
133
134     <tpchanger> -eject
135
136                 Unloads the current slot (if loaded) and puts that tape away.
137
138                 Output and error handling are the same as the -slot command.
139
140                 Note that a tape may or may not be loaded when this command
141                 completes, depending on the hardware.
142
143         Examples:
144                 % chg-multi -eject
145                 0 /dev/nrst8                    # exitcode returned is 0
146
147                 % chg-multi -eject
148                 0 drive was not loaded          # exitcode returned is 1
149
150 The tape changer program MAY support the following commands:
151
152     <tpchanger> -search <labelstr>
153
154                 Loads an Amanda tape by name (labelstr).
155                 
156                 Output and error handling are the same as the -slot command.
157
158                 Taper, amcheck and amtape will use this command if the
159                 changer reports it is searchable.
160
161         Example:
162                 % chg-zd-mtx -search DailySet005
163                 5 /dev/nrst8                    # exitcode returned is 0
164
165     <tpchanger> -label <labelstr>
166                 Associates the Amanda label <labelstr> with the barcode 
167                 of the currently loaded (in the tape drive) tape.
168
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.
172
173         Example:
174                 % chg-zd-mtx -label DailySet006
175                 6 /dev/nrst8                    # exitcode returned is 0
176
177
178 For all the commands:
179
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
182         described above.
183
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.
187
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.
193
194         Any other exit code is considered fatal and will cause Amanda
195         to stop attempting to talk to the tape changer.
196
197
198 4.  SLOT NAMES AND THE "CURRENT" SLOT
199
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
203 from the slots.
204
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).
212
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:
218
219         current The position of the last loaded tape, as described above
220
221         next    The position after current, wrapping from the last slot to
222                 the first.
223
224         prev    The position before current, wrapping from the first slot to
225                 the last.
226
227         first   The first slot in the tape rack.
228
229         last    The last slot in the tape rack.
230
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.
234
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.
238
239
240 5. OPERATOR INTERFACE
241
242 The amtape program is the main operator interface to Amanda's tape
243 changer support.  The commands supported include:
244
245         amtape <conf> slot <slot-specifier>
246                 Load the tape from the specified slot into the drive
247
248         amtape <conf> eject
249                 Send an eject command to the tape-changer.  Effect is changer
250                 specific.
251
252         amtape <conf> reset
253                 Send a reset command to the tape-changer.  Effect is changer
254                 specific.
255
256         amtape <conf> show
257                 Go through the entire tape rack, showing the labels of all 
258                 amanda tapes encountered.
259
260         amtape <conf> label <label>
261                 Find and load the tape with the specified label
262
263         amtape <conf> taper
264                 Perform taper's scan algorithm (see below), loading the tape
265                 which would be picked for the next amdump run.
266
267         amtape <conf> clean
268                 If a cleaning tape is defined by the changer, load it in
269                 the drive and put it away when done.
270         
271         amtape <conf> device
272                 Output the current tape device name.
273         
274         amtape <conf> current
275                 Display the contents of the current slot.
276         
277         amtape <conf> update
278                 Scan the entire tape rack and update the barcode database.
279
280 See the amtape(8) man page for more details.
281
282 In addition to amtape, amlabel has been modified to allow optionally
283 specifying a slot:
284
285         amlabel <conf> <label> [slot <slot-specifier>]
286
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
292 amdump run.
293
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.
301
302
303 6. HOW AMDUMP INTERACTS WITH THE TAPE CHANGER
304
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.
310
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.
314
315 Normal tape changers (those that can go backwards):
316
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.
322
323 Gravity stackers (anything that can not go backwards):
324
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.
329
330
331 7. BUILT-IN TAPE CHANGERS
332
333 ================================
334 chg-multi (formerly chg-generic)
335 ================================
336
337 This tape changer script supports several common configurations:
338
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.
342
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.
346
347   - Using a changer accessed through several "virtual" tape devices
348     which determine which slot actually gets loaded in the tape drive.
349
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.
355
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.
359
360 ================================
361 chg-manual (formerly no-changer)
362 ================================
363
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.
368
369 =============================
370 chg-mtx (formerly hp-changer)
371 =============================
372
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
380 tape (cleanslot).
381
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).
385
386 ==========
387 chg-zd-mtx
388 ==========
389
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.
394
395 In addition to the `changerfile'-clean and the `changerfile'-access files,
396 it maintains a `changerfile'-slot file that indicates the currently
397 loaded slot.
398
399 There are lots of comments at the start of the script describing how to
400 set it up.
401
402 ========
403 chg-disk
404 ========
405
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
409 on a hard disk.
410
411 The directory tree should be:
412 slot_root_dir -|
413                |- info
414                |- data -> slot1/
415                |- slot1/
416                |- slot2/
417                |- ...
418                |- slotn/
419
420 Where "slot_root_dir" is the tapedev "file:xxx" parameter and "n" the
421 tapecycle parameter.
422
423 Please refer to the HOWTO-FILE-DRIVER for details of usage.
424
425
426
427
428 =======================================================
429 chg-scsi-chio (formerly seagate-changer, then chg-chio)
430 =======================================================
431
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.
441
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
455 cleaning the drives.
456
457 In amanda.conf:
458
459 tapedev "x"       with x between 0 and 9, selects the configuration to use
460 changerfile "filename"            specifies the changer configuration file
461
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
466                                                 config-file.
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
473                                                 should be OK.
474 cleanmax x              x some positive int     How many cleanings does a 
475                                                 cleaning tape survive
476 changerdev  <device>                            The device for the robot
477
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:
481
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 
496                                                 cleaning tape
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
502                                                                                          
503 Comments begin with an '#' until end of line.
504 Allowed separators are TAB and SPACE. 
505
506 ========================================================================
507 chg-scsi (new interface, try to drive a robot with direct scsi commands)
508 ========================================================================
509
510 The config and the sysntax is the same as for chg-scsi-chio. New
511 is the config type 
512
513 emubarcode      1
514
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.
517
518 debuglevel x:y
519
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
522
523 havebarcode 1
524
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.
527
528 scsitapedev <devicename>
529
530 This device is used to control the tape, read status infos etc.
531
532 tapestatus <filename>
533
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
537
538 labelfile <filename>
539
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.
543
544 eject > 1
545
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
548 th@ant.han.de
549
550 changerident <ident>
551
552 With this it is possible to specify which internal driver to use for
553 controlling/error handling of the robot
554
555 tapeident <ident>
556
557 Some as above but for the tape.
558
559
560 New command line option:
561 -status [all|types|robot|sense|ModeSenseRobot|ModeSenseTape|fd]
562
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.
570
571
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
574 HP_UX 10.20     
575 IRIX 6.x
576 Solaris
577 Linux
578 AIX
579 FreeBSD 3.0/4.0
580
581 Tape and robot on different IDs run native on
582 Linux
583 HP-UX 10.20
584 Irix 6.x
585 FreeBSD
586
587 Tape and robot on different IDs with special modules run on:
588
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"
595
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;
602
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)
606
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;
611
612
613 For HP you have to create the special device files for the pass throu
614 interface. Check if the ctl driver is installed.
615 Example:
616 # lsdev -C ctl
617     Character     Block       Driver          Class
618       203          -1         sctl            ctl
619
620 Next check on which bus your drives are connected. (ioscan)
621
622 with the Character device num form the lsdev and the card instance from
623 ioscan create the special file.
624 Example:
625 mknod /dev/scsi/1 c 203 0x001000
626                           ||||
627                           ||| LUN of device
628                           ||SCSI ID of the device
629                           2 digit instance number from ioscan
630
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
634 changerdev 0:3:0
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
638 not work.
639
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.
647
648 On IRIX you find the SCSI pass through interfaces for every device in /dev/scsi
649
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 
656 TANDBERG TDS 1420
657 ADIC VLS DLT Library
658
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.
664
665 For all problems please contact th@ant.han.de. Please include in your
666 mail the debug file. (/tmp/amanda/chg-scsi.debug)
667
668
669 ===========================================================================
670 chg-chio (new perl script that replaces the original chg-chio written in C)
671 ===========================================================================
672
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.
678
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.
681
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.]
685
686 ==============================
687 chg-chs (formerly chs-changer)
688 ==============================
689
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
695 values!)
696
697 ==============================
698 chg-rth (formerly rth-changer)
699 ==============================
700
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.
705
706 ==============================
707 chg-juke
708 ==============================
709
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.
716
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}")
721
722 ==============================
723 chg-rait
724 ==============================
725
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:
731  
732    nchangers=3
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"
745
746 The third uses the null changer.  The tapedev_n entries are only needed
747 if the changerfile in question uses them.
748
749
750 ================================
751 chg-iomega
752 ================================
753
754 This changer script is designed for IOMEGA or JAZZ disks of various sizes
755 as well as any other removable disk media.
756
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.
759
760 Make sure you comply with any of the following.
761 - Add statements 
762         tpchanger "chg-iomega"
763         tapedev "file:<mount_point_of_removable_disk>"
764         (e.g. tapedev "file:/mnt/iomega" )
765         tapetype IOMEGA      
766
767         
768         define tapetype IOMEGA {
769             comment "IOMega 250 MB floppys"
770             length 250 mbytes
771             filemark 100 kbytes
772             speed 1 mbytes
773         }
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 
782   disk size.
783
784
785 ==============================
786 chg-null
787 ==============================
788
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, 
791 or for testing.