3
butc - Defines Tape Coordinator instructions for automated tape devices
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.
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.
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.
23
To enable the Tape Coordinator to locate the configuration file, construct
24
the variable part of the filename, I<device_name>, as follows:
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
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>.
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
53
Controls whether the Tape Coordinator prompts for guidance when it
54
encounters error conditions.
58
Controls whether the Tape Coordinator prompts for the first tape.
62
Sets the size of the memory buffer the Tape Coordinator uses when
67
Controls whether the dump is written to a tape device or a file.
71
Identifies the file that contains routines for inserting tapes into the
76
Controls whether the Tape Coordinator verifies that a tape's AFS tape
77
name matches the dump being written.
81
Identifies the file that contains routines for removing tapes from the
86
=head2 The ASK Instruction
88
The C<ASK> instruction takes a boolean value as its argument, in the
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.
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.
105
The error cases controlled by this instruction are the following:
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.
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
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.
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.
148
=head2 The AUTOQUERY Instruction
150
The C<AUTOQUERY> instruction takes a boolean value as its argument,
151
in the following format:
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.
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.
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.
174
=head2 The BUFFERSIZE Instruction
176
The C<BUFFERSIZE> instruction takes an integer value, and optionally
177
units, in the following format:
179
BUFFERSIZE <size>[(k | K | m | M | g | G)]
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.
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
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.
203
=head2 The FILE Instruction
205
The C<FILE> instruction takes a boolean value as its argument, in the
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.
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
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.)
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:
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>.
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.
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.
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
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.
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
295
=head2 The MOUNT Instruction
297
The C<MOUNT> instruction takes a pathname as its argument, in the
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.
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.
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.
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
334
The tape device or backup data file's pathname, as recorded in the
335
F</usr/afs/backup/tapeconfig> file.
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:
347
C<appenddump> (when a backup dump command includes the B<-append> flag).
351
C<dump> (when a backup dump command does not include the B<-append> flag).
363
C<restore> (for a B<backup diskrestore>, backup volrestore, or B<backup
364
volsetrestore> command).
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>
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,
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.
403
The routine invoked by the C<MOUNT> instruction must return an exit code
404
to the Tape Coordinator:
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.
417
Code 1 (one) indicates that the routine failed to mount the tape. The Tape
418
Coordinator terminates the operation.
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
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.
433
=head2 The NAME_CHECK Instruction
435
The C<NAME_CHECK> instruction takes a boolean value as its argument, in
436
the following format:
438
NAME_CHECK (YES | NO)
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
448
When the value is C<NO>, the Tape Coordinator does not check the AFS tape
449
name before writing to the tape.
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.
454
=head2 The UNMOUNT Instruction
456
The C<UNMOUNT> instruction takes a pathname as its argument, in the
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.
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:
482
The tape device pathname (as specified in the
483
F</usr/afs/backup/tapeconfig> file).
487
The tape operation (always unmount).
491
=head1 PRIVILEGE REQUIRED
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
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.
505
=head2 Example F<CFG_I<device_name>> File for Stackers
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
511
2G 5K /dev/stacker0.1 0
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>.
517
MOUNT /usr/afs/backup/stacker0.1
518
UNMOUNT /usr/afs/backup/stacker0.1
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.
535
set exit_continue = 0
537
set exit_interactive = 2
539
#--------------------------------------------
541
if (${tries} > 1) then
542
echo "Too many tries"
543
exit ${exit_interactive}
546
if (${operation} == "unmount") then
547
echo "UnMount: Will leave tape in drive"
548
exit ${exit_continue}
551
if ((${operation} == "dump") |\
552
(${operation} == "appenddump") |\
553
(${operation} == "savedb")) then
555
stackerCmd_NextTape ${devicefile}
556
if (${status} != 0)exit${exit_interactive}
558
exit ${exit_continue}
561
if ((${operation} == "labeltape") |\
562
(${operation} == "readlabel")) then
564
exit ${exit_continue}
567
echo "Prompt for tape"
568
exit ${exit_interactive}
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.
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
583
=head2 Example F<CFG_I<device_name>> File for Dumping to a Data File
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.
589
1G 0K /dev/HSM_device 20
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>.
595
MOUNT /usr/afs/backup/file
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
611
set exit_continue = 0
613
set exit_interactive = 2
615
#--------------------------------------------
617
if (${tries} > 1) then
618
echo "Too many tries"
619
exit ${exit_interactive}
622
if (${operation} == "labeltape") then
623
echo "Won't label a tape/file"
627
if ((${operation} == "dump") |\
628
(${operation} == "appenddump") |\
629
(${operation} == "restore") |\
630
(${operation} == "savedb") |\
631
(${operation} == "restoredb")) then
633
/bin/rm -f ${devicefile}
634
/bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
635
if (${status} != 0) exit ${exit_abort}
638
exit ${exit_continue}
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.
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.
661
L<backup_diskrestore(8)>,
663
L<backup_restoredb(8)>,
665
L<backup_volrestore(8)>,
666
L<backup_volsetrestore(8)>
670
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
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.
added
removed
debian/doc/pod5/butc.pod
