man5-editing-pass-20051213
[openafs.git] / doc / man-pages / pod5 / butc.pod
1 =head1 NAME
2
3 butc - Defines Tape Coordinator instructions for automated tape devices
4
5 =head1 DESCRIPTION
6
7 The F<CFG_I<device_name>> file includes instructions that configure a Tape
8 Coordinator (B<butc>) for use with automated backup devices such as tape
9 stackers and jukeboxes, enable the Tape Coordinator to dump and restore
10 data to a I<backup data file> on a local disk device, and enable greater
11 automation of other aspects of the backup process.
12
13 There is a separate configuration file for each tape device or backup data
14 file. Creating the file is optional, and unnecessary if none of the
15 instructions it can include pertain to a given tape device. The
16 ASCII-format file must reside in the F</usr/afs/backup> directory on the
17 Tape Coordinator machine if it exists.
18
19 The F<CFG_I<device_name>> file does not replace the
20 F</usr/afs/backup/tapeconfig> file, a single copy of which still must
21 exist on every Tape Coordinator machine.
22
23 To enable the Tape Coordinator to locate the configuration file, construct
24 the variable part of the filename, I<device_name>, as follows:
25
26 =over 4
27
28 =item *
29
30 For a tape device, strip off the initial C</dev/> string from the device
31 name, and replace any other slashes in the name with underscores. For
32 example, F<CFG_rmt_4m> is the appropriate filename for a device called
33 F</dev/rmt/4m>.
34
35 =item *
36
37 For a backup data file, strip off the initial slash (C</>) and replace any
38 other slashes in the name with underscores. For example,
39 F<CFG_var_tmp_FILE> is the appropriate filename for a backup data file
40 called F</var/tmp/FILE>.
41
42 =back
43
44 The F<CFG_I<device_name>> file lists one or more of the following
45 instructions, each on its own line. All are optional, and they can appear
46 in any order. A more detailed description of each instruction follows the
47 list:
48
49 =over 4
50
51 =item ASK
52
53 Controls whether the Tape Coordinator prompts for guidance when it
54 encounters error conditions.
55
56 =item AUTOQUERY
57
58 Controls whether the Tape Coordinator prompts for the first tape.
59
60 =item BUFFERSIZE
61
62 Sets the size of the memory buffer the Tape Coordinator uses when
63 transferring data.
64
65 =item FILE
66
67 Controls whether the dump is written to a tape device or a file.
68
69 =item MOUNT
70
71 Identifies the file that contains routines for inserting tapes into the
72 device's drive.
73
74 =item NAME_CHECK
75
76 Controls whether the Tape Coordinator verifies that a tape's AFS tape
77 name matches the dump being written.
78
79 =item UNMOUNT
80
81 Identifies the file that contains routines for removing tapes from the
82 device's drive.
83
84 =back
85
86 =head2 The ASK Instruction
87
88 The C<ASK> instruction takes a boolean value as its argument, in the
89 following format:
90
91    ASK (YES | NO)
92
93 When the value is C<YES>, the Tape Coordinator generates a prompt in its
94 window, requesting a response to the error cases described in the
95 following list. This is the default behavior if the C<ASK> instruction
96 does not appear in the F<CFG_I<device_name>> file.
97
98 When the value is C<NO>, the Tape Coordinator does not prompt in error
99 cases, but instead uses the automatic default responses described in the
100 following list. The Tape Coordinator also logs the error in the
101 F<TE_I<device_name>> file. Suppressing the prompts enables the Tape
102 Coordinator to run unattended, though it still prompts for insertion of
103 tapes unless the C<MOUNT> instruction is used.
104
105 The error cases controlled by this instruction are the following:
106
107 =over 4
108
109 =item *
110
111 The Backup System is unable to dump a volume while running the backup dump
112 command. With a C<YES> value, the Tape Coordinator prompts to offer three
113 choices: try to dump the volume again immediately, omit the volume from
114 the dump but continue the operation, or terminate the operation. With a
115 C<NO> value, the Tape Coordinator omits the volume from the dump and
116 continues the operation.
117
118 =item *
119
120 The Backup System is unable to restore a volume while running the B<backup
121 diskrestore>, B<backup volrestore>, or B<backup volsetrestore>
122 command. With a C<YES> value, the Tape Coordinator prompts to offer two
123 choices: omit the volume and continue restoring the other volumes, or
124 terminate the operation. With a C<NO> value, it continues the operation
125 without prompting, omitting the problematic volume but restoring the
126 remaining ones.
127
128 =item *
129
130 The Backup System cannot determine if the dump set includes any more
131 tapes, while running the B<backup scantape> command (the reference page
132 for that command discusses possible reasons for this problem).  With a
133 C<YES> value, the Tape Coordinator prompts to ask if there are more tapes
134 to scan. With a C<NO> value, it proceeds as though there are more tapes
135 and invokes the routine named by the C<MOUNT> instruction in the
136 configuration file, or prompts the operator to insert the next tape.
137
138 =item *
139
140 The Backup System determines that the tape contains an unexpired dump
141 while running the B<backup labeltape> command. With a C<YES> value, the
142 Tape Coordinator prompts to offer two choices: continue or terminate the
143 labeling operation. With a C<NO> value, it terminates the operation
144 without relabeling the tape.
145
146 =back
147
148 =head2 The AUTOQUERY Instruction
149
150 The C<AUTOQUERY> instruction takes a boolean value as its argument,
151 in the following format:
152
153    AUTOQUERY (YES | NO)
154
155 When the value is C<YES>, the Tape Coordinator checks for the C<MOUNT>
156 instruction in the configuration file when it needs to read the first tape
157 involved in an operation. As described for that instruction, it then
158 either prompts for the tape or invokes the specified routine to mount the
159 tape. This is the default behavior if the C<AUTOQUERY> instruction does
160 not appear in the configuration file.
161
162 When the value is C<NO>, the Tape Coordinator assumes that the first tape
163 required for an operation is already in the drive. It does not prompt the
164 operator or invoke the C<MOUNT> routine unless there is an error in
165 accessing the first tape. This setting is equivalent in effect to
166 including the B<-noautoquery> flag to the B<butc> command.
167
168 Note that the setting of the C<AUTOQUERY> instruction controls the Tape
169 Coordinator's behavior only with respect to the first tape required for an
170 operation. For subsequent tapes, the Tape Coordinator always checks for
171 the C<MOUNT> instruction. It also refers to the C<MOUNT> instruction if it
172 encounters an error while attempting to access the first tape.
173
174 =head2 The BUFFERSIZE Instruction
175
176 The C<BUFFERSIZE> instruction takes an integer value, and optionally
177 units, in the following format:
178
179    BUFFERSIZE <size>[(k | K | m | M | g | G)]
180
181 where <size> specifies the amount of memory the Tape Coordinator allocates
182 to use as a buffer during both dump and restore operations.  The default
183 unit is bytes, but use C<k> or C<K> to specify kilobytes, C<m> or C<M> for
184 megabytes, and C<g> or C<G> for gigabytes. There is no space between the
185 <size> value and the units letter.
186
187 By default, the Tape Coordinator uses a 16 KB buffer during dump
188 operations. As it receives volume data from the Volume Server, the Tape
189 Coordinator gathers 16 KB of data in the buffer before transferring the
190 entire 16 KB to the tape device or backup data file. Similarly, during a
191 restore operation the Tape Coordinator by default buffers 32 KB of data
192 from the tape device or backup data file before transferring the entire 32
193 KB to the Volume Server for restoration into the file system. Buffering
194 makes the volume of data flowing to and from a tape device more even and
195 so promotes tape streaming, which is the most efficient way for a tape
196 device to operate.
197
198 In a normal network configuration, the default buffer sizes are usually
199 large enough to promote tape streaming. If the network between the Tape
200 Coordinator machine and file server machines is slow, it can help to
201 increase the buffer size.
202
203 =head2 The FILE Instruction
204
205 The C<FILE> instruction takes a boolean value as its argument, in the
206 following format:
207
208    FILE (NO | YES)
209
210 When the value is C<NO>, the Tape Coordinator writes to a tape device
211 during a dump operation and reads from one during a restore
212 operation. This is the default behavior if the C<FILE> instruction does
213 not appear in the configuration file.
214
215 When the value is C<YES>, the Tape Coordinator writes volume data to a
216 backup data file on the local disk during a dump operation and reads
217 volume data from a file during a restore operation. If the file does not
218 exist when the Tape Coordinator attempts to access it to write a dump, the
219 Tape Coordinator creates it. For a restore operation to succeed, the file
220 must exist and contain volume data previously written to it by a B<backup
221 dump> operation.
222
223 When the value is C<YES>, the backup data file's complete pathname must
224 appear (instead of a tape drive device name) in the third field of the
225 corresponding port offset entry in the local F</usr/afs/backup/tapeconfig>
226 file. If the field instead refers to a tape device, dump operations appear
227 to succeed but are inoperative. It is not possible to restore data that
228 was accidently dumped to a tape device while the C<FILE> instruction was
229 set to C<YES>. (In the same way, if the C<FILE> instruction is set to
230 C<NO>, the F<tapeconfig> entry must refer to an actual tape device.)
231
232 Rather than put an actual file pathname in the third field of the
233 F<tapeconfig> file, however, the recommended configuration is to create a
234 symbolic link in the F</dev> directory that points to the actual file
235 pathname, and record the symbolic link in this field. This configuration
236 has a couple of advantages:
237
238 =over 4
239
240 =item *
241
242 It makes the I<device_name> portion of the F<CFG_I<device_name>>,
243 F<TE_I<device_name>>, and F<TL_I<device_name>> names as short as
244 possible. Because the symbolic link is in the F</dev> directory as though
245 it were a tape device, the device configuration file's name is constructed
246 by stripping off the entire F</dev/> prefix, instead of just the initial
247 slash. If, for example, the symbolic link is called F</dev/FILE>, the
248 device configuration file name is F<CFG_FILE>, whereas if the actual
249 pathname F</var/tmp/FILE> appears in the B<tapeconfig> file, the file's
250 name must be F<CFG_var_tmp_FILE>.
251
252 =item *
253
254 It provides for a more graceful, and potentially automated, recovery if
255 the Tape Coordinator cannot write a complete dump into the backup data
256 file (because the partition housing the backup data file becomes full, for
257 example). The Tape Coordinator's reaction to this problem is to invoke the
258 C<MOUNT> script, or to prompt the operator if the C<MOUNT> instruction
259 does not appear in the configuration file.
260
261 =over 4
262
263 =item *
264
265 If there is a C<MOUNT> routine, the operator can prepare for this
266 situation by adding a subroutine that changes the symbolic link to point
267 to another backup data file on a partition where there is space available.
268
269 =item *
270
271 If there is no C<MOUNT> instruction, the prompt enables the operator
272 manually to change the symbolic link to point to another backup data file,
273 then press Return to signal that the Tape Coordinator can continue the
274 operation.
275
276 =back
277
278 =back
279
280 If the third field in the F<tapeconfig> file names the actual file, there
281 is no way to recover from exhausting the space on the partition that
282 houses the backup data file. It is not possible to change the
283 F<tapeconfig> file in the middle of an operation.
284
285 When writing to a backup data file, the Tape Coordinator writes data at 16
286 KB offsets. If a given block of data (such as the marker that signals the
287 beginning or end of a volume) does not fill the entire 16 KB, the Tape
288 Coordinator still skips to the next offset before writing the next
289 block. In the output of a B<backup dumpinfo> command issued with the
290 B<-id> option, the value in the C<Pos> column is the ordinal of the 16-KB
291 offset at which the volume data begins, and so is not generally only one
292 higher than the position number on the previous line, as it is for dumps
293 to tape.
294
295 =head2 The MOUNT Instruction
296
297 The C<MOUNT> instruction takes a pathname as its argument, in the
298 following format:
299
300    MOUNT <filename>
301
302 The referenced executable file must reside on the local disk and contain a
303 shell script or program that directs an automated tape device, such as a
304 jukebox or stacker, to mount a tape (insert it into the tape reader).  The
305 operator must write the routine to invoke the mount command specified by
306 the device's manufacturer; AFS does not include any scripts, although an
307 example appears in L<EXAMPLES>.  The script or program inherits the Tape
308 Coordinator's AFS authentication status.
309
310 When the Tape Coordinator needs to mount a tape, it checks the
311 configuration file for a C<MOUNT> instruction. If there is no C<MOUNT>
312 instruction, the Tape Coordinator prompts the operator to insert a tape
313 before it attempts to open the tape device. If there is a C<MOUNT>
314 instruction, the Tape Coordinator executes the routine in the referenced
315 file. The routine invoked by the C<MOUNT> instruction inherits the local
316 identity (UNIX UID) and AFS tokens of the B<butc> command's issuer.
317
318 There is an exception to this sequence: if the C<AUTOQUERY NO> instruction
319 appears in the configuration file, or the B<-noautoquery> flag was
320 included on the B<butc> command, then the Tape Coordinator assumes that
321 the operator has already inserted the first tape needed for a given
322 operation. It attempts to read the tape immediately, and only checks for
323 the C<MOUNT> instruction or prompts the operator if the tape is missing or
324 is not the required one.
325
326 When the Tape Coordinator invokes the routine indicated by the C<MOUNT>
327 instruction, it passes the following parameters to the routine in the
328 indicated order:
329
330 =over 4
331
332 =item *
333
334 The tape device or backup data file's pathname, as recorded in the
335 F</usr/afs/backup/tapeconfig> file.
336
337 =item *
338
339 The tape operation, which (except for the exceptions noted in the
340 following list) matches the B<backup> command operation code used to
341 initiate the operation:
342
343 =over 4
344
345 =item *
346
347 C<appenddump> (when a backup dump command includes the B<-append> flag).
348
349 =item *
350
351 C<dump> (when a backup dump command does not include the B<-append> flag).
352
353 =item *
354
355 C<labeltape>
356
357 =item *
358
359 C<readlabel>
360
361 =item *
362
363 C<restore> (for a B<backup diskrestore>, backup volrestore, or B<backup
364 volsetrestore> command).
365
366 =item *
367
368 C<restoredb>
369
370 =item *
371
372 C<savedb>
373
374 =item *
375
376 C<scantape>
377
378 =back
379
380 =item *
381
382 The number of times the Tape Coordinator has attempted to open the tape
383 device or backup data file. If the open attempt returns an error, the Tape
384 Coordinator increments this value by one and again invokes the C<MOUNT>
385 instruction.
386
387 =item *
388
389 The tape name. For some operations, the Tape Coordinator passes the string
390 C<none>, because it does not know the tape name (when running the B<backup
391 scantape> or B<backup readlabel>, for example), or because the tape does
392 not necessarily have a name (when running the B<backup labeltape> command,
393 for example).
394
395 =item *
396
397 The tape ID recorded in the Backup Database. As with the tape name, the
398 Backup System passes the string C<none> for operations where it does not
399 know the tape ID or the tape does not necessarily have an ID.
400
401 =back
402
403 The routine invoked by the C<MOUNT> instruction must return an exit code
404 to the Tape Coordinator:
405
406 =over 4
407
408 =item *
409
410 Code 0 (zero) indicates that the routine successfully mounted the
411 tape. The Tape Coordinator continues the backup operation.  If the routine
412 invoked by the C<MOUNT> instruction does not return this exit code, the
413 Tape Coordinator never calls the C<UNMOUNT> instruction.
414
415 =item *
416
417 Code 1 (one) indicates that the routine failed to mount the tape. The Tape
418 Coordinator terminates the operation.
419
420 =item *
421
422 Any other code indicates that the routine was not able to access the
423 correct tape. The Tape Coordinator prompts the operator to insert the
424 correct tape.
425
426 =back
427
428 If the backup command was issued in interactive mode and the operator
429 issues the B<backup kill> command while the C<MOUNT> routine is running,
430 the Tape Coordinator passes the termination signal to the routine; the
431 entire operation terminates.
432
433 =head2 The NAME_CHECK Instruction
434
435 The C<NAME_CHECK> instruction takes a boolean value as its argument, in
436 the following format:
437
438    NAME_CHECK (YES | NO)
439
440 When the value is C<YES> and the tape does not have a permanent name, the
441 Tape Coordinator checks the AFS tape name when dumping a volume in
442 response to the B<backup dump> command. The AFS tape name must be C<<
443 <NULL> >> or match the tape name that the B<backup dump> operation assigns
444 based on the volume set and dump level names. This is the default behavior
445 if the C<NAME_CHECK> instruction does not appear in the configuration
446 file.
447
448 When the value is C<NO>, the Tape Coordinator does not check the AFS tape
449 name before writing to the tape.
450
451 The Tape Coordinator always checks that all dumps on the tape are expired,
452 and refuses to write to a tape that contains unexpired dumps.
453
454 =head2 The UNMOUNT Instruction
455
456 The C<UNMOUNT> instruction takes a pathname as its argument, in the
457 following format:
458
459    UNMOUNT <filename>
460
461 The referenced executable file must reside on the local disk and contain a
462 shell script or program that directs an automated tape device, such as a
463 jukebox or stacker, to unmount a tape (remove it from the tape reader).
464 The operator must write the routine to invoke the unmount command
465 specified by the device's manufacturer; AFS does not include any scripts,
466 although an example appears in L<EXAMPLES>.  The script or program
467 inherits the Tape Coordinator's AFS authentication status.
468
469 After closing a tape device, the Tape Coordinator checks the configuration
470 file for an C<UNMOUNT> instruction, whether or not the B<close> operation
471 succeeds. If there is no C<UNMOUNT> instruction, the Tape Coordinator
472 takes no action, in which case the operator must take the action necessary
473 to remove the current tape from the drive before another can be
474 inserted. If there is an C<UNMOUNT> instruction, the Tape Coordinator
475 executes the referenced file. It invokes the routine only once, passing in
476 the following parameters:
477
478 =over 4
479
480 =item *
481
482 The tape device pathname (as specified in the
483 F</usr/afs/backup/tapeconfig> file).
484
485 =item *
486
487 The tape operation (always unmount).
488
489 =back
490
491 =head1 PRIVILEGE REQUIRED
492
493 The file is protected by UNIX mode bits. Creating the file requires the
494 C<w> (write) and C<x> (execute) permissions on the F</usr/afs/backup>
495 directory. Editing the file requires the C<w> (write) permission on the
496 file.
497
498 =head1 EXAMPLES
499
500 The following example configuration files demonstrate one way to structure
501 a configuration file for a stacker or backup dump file. The examples are
502 not necessarily appropriate for a specific cell; if using them as models,
503 be sure to adapt them to the cell's needs and equipment.
504
505 =head2 Example F<CFG_I<device_name>> File for Stackers
506
507 In this example, the administrator creates the following entry for a tape
508 stacker called C<stacker0.1> in the F</usr/afs/backup/tapeconfig> file. It
509 has port offset 0.
510
511    2G   5K   /dev/stacker0.1   0
512
513 The administrator includes the following five lines in the
514 F</usr/afs/backup/CFG_stacker0.1> file. To review the meaning of each
515 instruction, see L<DESCRIPTION>.
516
517    MOUNT /usr/afs/backup/stacker0.1
518    UNMOUNT /usr/afs/backup/stacker0.1
519    AUTOQUERY NO
520    ASK NO
521    NAME_CHECK NO
522
523 Finally, the administrator writes the following executable routine in the
524 F</usr/afs/backup/stacker0.1> file referenced by the C<MOUNT> and
525 C<UNMOUNT> instructions in the F<CFG_stacker0.1> file.
526
527    #! /bin/csh -f
528
529    set devicefile = $1
530    set operation = $2
531    set tries = $3
532    set tapename = $4
533    set tapeid = $5
534      
535    set exit_continue = 0
536    set exit_abort = 1
537    set exit_interactive = 2
538     
539    #--------------------------------------------
540      
541    if (${tries} > 1) then
542       echo "Too many tries"
543       exit ${exit_interactive}
544    endif
545      
546    if (${operation} == "unmount") then
547       echo "UnMount: Will leave tape in drive"
548       exit ${exit_continue}
549    endif
550      
551    if ((${operation} == "dump")     |\
552        (${operation} == "appenddump")     |\
553        (${operation} == "savedb"))  then
554      
555        stackerCmd_NextTape ${devicefile}
556        if (${status} != 0)exit${exit_interactive}
557        echo "Will continue"
558        exit ${exit_continue}
559    endif
560      
561    if ((${operation} == "labeltape")    |\
562        (${operation} == "readlabel")) then
563       echo "Will continue"
564       exit ${exit_continue}
565    endif
566      
567    echo "Prompt for tape"
568    exit ${exit_interactive}
569
570 This routine uses two of the parameters passed to it by the Backup System:
571 C<tries> and C<operation>. It follows the recommended practice of
572 prompting for a tape if the value of the C<tries> parameter exceeds one,
573 because that implies that the stacker is out of tapes.
574
575 For a B<backup dump> or backup savedb operation, the routine calls the
576 example C<stackerCmd_NextTape> function provided by the stacker's
577 manufacturer. Note that the final lines in the file return the exit code
578 that prompts the operator to insert a tape; these lines are invoked when
579 either the stacker cannot load a tape or a the operation being performed
580 is not one of those explicitly mentioned in the file (such as a restore
581 operation).
582
583 =head2 Example F<CFG_I<device_name>> File for Dumping to a Data File
584
585 In this example, the administrator creates the following entry for a
586 backup data file called F<HSM_device> in the F</usr/afs/backup/tapeconfig>
587 file. It has port offset 20.
588
589    1G   0K   /dev/HSM_device   20
590
591 The administrator includes the following lines in the
592 F</usr/afs/backup/CFG_HSM_device> file. To review the meaning of each
593 instruction, see L<DESCRIPTION>.
594
595    MOUNT /usr/afs/backup/file
596    FILE YES
597    ASK NO
598
599 Finally, the administrator writes the following executable routine in the
600 F</usr/afs/backup/file> file referenced by the C<MOUNT> instruction in the
601 F<CFG_HSM_device> file, to control how the Tape Coordinator handles the
602 file.
603
604    #! /bin/csh -f
605    set devicefile = $1
606    set operation = $2
607    set tries = $3
608    set tapename = $4
609    set tapeid = $5
610
611    set exit_continue = 0
612    set exit_abort = 1
613    set exit_interactive = 2
614      
615    #--------------------------------------------
616      
617    if (${tries} > 1) then
618       echo "Too many tries"
619       exit ${exit_interactive}
620    endif
621      
622    if (${operation} == "labeltape") then
623       echo "Won't label a tape/file"
624       exit ${exit_abort}
625    endif
626      
627    if ((${operation} == "dump")   |\
628        (${operation} == "appenddump")   |\
629        (${operation} == "restore")   |\
630        (${operation} == "savedb")    |\
631        (${operation} == "restoredb")) then
632      
633       /bin/rm -f ${devicefile}
634       /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
635       if (${status} != 0) exit ${exit_abort}
636    endif
637      
638    exit ${exit_continue}
639
640 Like the example routine for a tape stacker, this routine uses the
641 C<tries> and C<operation> parameters passed to it by the Backup
642 System. The C<tries> parameter tracks how many times the Tape Coordinator
643 has attempted to access the file. A value greater than one indicates that
644 the Tape Coordinator cannot access it, and the routine returns exit code 2
645 (C<exit_interactive>), which results in a prompt for the operator to load
646 a tape. The operator can use this opportunity to change the name of the
647 backup data file specified in the B<tapeconfig> file.
648
649 The primary function of this routine is to establish a link between the
650 device file and the file to be dumped or restored. When the Tape
651 Coordinator is executing a B<backup dump>, B<backup restore>, B<backup
652 savedb>, or B<backup restoredb> operation, the routine invokes the UNIX
653 C<ln -s> command to create a symbolic link from the backup data file named
654 in the F<tapeconfig> file to the actual file to use (this is the
655 recommended method). It uses the value of the C<tapename> and C<tapeid>
656 parameters to construct the file name.
657
658 =head1 SEE ALSO
659
660 L<tapeconfig(5)>,
661 L<backup_diskrestore(8)>,
662 L<backup_dump(8)>,
663 L<backup_restoredb(8)>,
664 L<backup_savedb(8)>,
665 L<backup_volrestore(8)>,
666 L<backup_volsetrestore(8)>
667
668 =head1 COPYRIGHT
669
670 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
671
672 This documentation is covered by the IBM Public License Version 1.0.  It was
673 converted from HTML to POD by software written by Chas Williams and Russ
674 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.