Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / man-pages / pod5 / butc.pod

=head1 NAME

butc - Defines Tape Coordinator instructions for automated tape devices

=head1 DESCRIPTION

The F<CFG_I<device_name>> file includes instructions that configure a Tape
Coordinator (B<butc>) for use with automated backup devices such as tape
stackers and jukeboxes, enable the Tape Coordinator to dump and restore
data to a I<backup data file> on a local disk device, and enable greater
automation of other aspects of the backup process.

There is a separate configuration file for each tape device or backup data
file. Creating the file is optional, and unnecessary if none of the
instructions it can include pertain to a given tape device. The
ASCII-format file must reside in the F</usr/afs/backup> directory on the
Tape Coordinator machine if it exists.

The F<CFG_I<device_name>> file does not replace the
F</usr/afs/backup/tapeconfig> file, a single copy of which still must
exist on every Tape Coordinator machine.

To enable the Tape Coordinator to locate the configuration file, construct
the variable part of the filename, I<device_name>, as follows:

=over 4

=item *

For a tape device, strip off the initial C</dev/> string from the device
name, and replace any other slashes in the name with underscores. For
example, F<CFG_rmt_4m> is the appropriate filename for a device called
F</dev/rmt/4m>.

=item *

For a backup data file, strip off the initial slash (C</>) and replace any
other slashes in the name with underscores. For example,
F<CFG_var_tmp_FILE> is the appropriate filename for a backup data file
called F</var/tmp/FILE>.

=back

The F<CFG_I<device_name>> file lists one or more of the following
instructions, each on its own line. All are optional, and they can appear
in any order. A more detailed description of each instruction follows the
list:

=over 4

=item ASK

Controls whether the Tape Coordinator prompts for guidance when it
encounters error conditions.

=item AUTOQUERY

Controls whether the Tape Coordinator prompts for the first tape.

=item BUFFERSIZE

Sets the size of the memory buffer the Tape Coordinator uses when
transferring data.

=item FILE

Controls whether the dump is written to a tape device or a file.

=item MOUNT

Identifies the file that contains routines for inserting tapes into the
device's drive.

=item NAME_CHECK

Controls whether the Tape Coordinator verifies that a tape's AFS tape
name matches the dump being written.

=item UNMOUNT

Identifies the file that contains routines for removing tapes from the
device's drive.

=back

=head2 The ASK Instruction

The C<ASK> instruction takes a boolean value as its argument, in the
following format:

   ASK (YES | NO)

When the value is C<YES>, the Tape Coordinator generates a prompt in its
window, requesting a response to the error cases described in the
following list. This is the default behavior if the C<ASK> instruction
does not appear in the F<CFG_I<device_name>> file.

When the value is C<NO>, the Tape Coordinator does not prompt in error
cases, but instead uses the automatic default responses described in the
following list. The Tape Coordinator also logs the error in the
F<TE_I<device_name>> file. Suppressing the prompts enables the Tape
Coordinator to run unattended, though it still prompts for insertion of
tapes unless the C<MOUNT> instruction is used.

The error cases controlled by this instruction are the following:

=over 4

=item *

The Backup System is unable to dump a volume while running the backup dump
command. With a C<YES> value, the Tape Coordinator prompts to offer three
choices: try to dump the volume again immediately, omit the volume from
the dump but continue the operation, or terminate the operation. With a
C<NO> value, the Tape Coordinator omits the volume from the dump and
continues the operation.

=item *

The Backup System is unable to restore a volume while running the B<backup
diskrestore>, B<backup volrestore>, or B<backup volsetrestore>
command. With a C<YES> value, the Tape Coordinator prompts to offer two
choices: omit the volume and continue restoring the other volumes, or
terminate the operation. With a C<NO> value, it continues the operation
without prompting, omitting the problematic volume but restoring the
remaining ones.

=item *

The Backup System cannot determine if the dump set includes any more
tapes, while running the B<backup scantape> command (the reference page
for that command discusses possible reasons for this problem).  With a
C<YES> value, the Tape Coordinator prompts to ask if there are more tapes
to scan. With a C<NO> value, it proceeds as though there are more tapes
and invokes the routine named by the C<MOUNT> instruction in the
configuration file, or prompts the operator to insert the next tape.

=item *

The Backup System determines that the tape contains an unexpired dump
while running the B<backup labeltape> command. With a C<YES> value, the
Tape Coordinator prompts to offer two choices: continue or terminate the
labeling operation. With a C<NO> value, it terminates the operation
without relabeling the tape.

=back

=head2 The AUTOQUERY Instruction

The C<AUTOQUERY> instruction takes a boolean value as its argument,
in the following format:

   AUTOQUERY (YES | NO)

When the value is C<YES>, the Tape Coordinator checks for the C<MOUNT>
instruction in the configuration file when it needs to read the first tape
involved in an operation. As described for that instruction, it then
either prompts for the tape or invokes the specified routine to mount the
tape. This is the default behavior if the C<AUTOQUERY> instruction does
not appear in the configuration file.

When the value is C<NO>, the Tape Coordinator assumes that the first tape
required for an operation is already in the drive. It does not prompt the
operator or invoke the C<MOUNT> routine unless there is an error in
accessing the first tape. This setting is equivalent in effect to
including the B<-noautoquery> flag to the B<butc> command.

Note that the setting of the C<AUTOQUERY> instruction controls the Tape
Coordinator's behavior only with respect to the first tape required for an
operation. For subsequent tapes, the Tape Coordinator always checks for
the C<MOUNT> instruction. It also refers to the C<MOUNT> instruction if it
encounters an error while attempting to access the first tape.

=head2 The BUFFERSIZE Instruction

The C<BUFFERSIZE> instruction takes an integer value, and optionally
units, in the following format:

   BUFFERSIZE <size>[(k | K | m | M | g | G)]

where <size> specifies the amount of memory the Tape Coordinator allocates
to use as a buffer during both dump and restore operations.  The default
unit is bytes, but use C<k> or C<K> to specify kilobytes, C<m> or C<M> for
megabytes, and C<g> or C<G> for gigabytes. There is no space between the
<size> value and the units letter.

By default, the Tape Coordinator uses a 16 KB buffer during dump
operations. As it receives volume data from the Volume Server, the Tape
Coordinator gathers 16 KB of data in the buffer before transferring the
entire 16 KB to the tape device or backup data file. Similarly, during a
restore operation the Tape Coordinator by default buffers 32 KB of data
from the tape device or backup data file before transferring the entire 32
KB to the Volume Server for restoration into the file system. Buffering
makes the volume of data flowing to and from a tape device more even and
so promotes tape streaming, which is the most efficient way for a tape
device to operate.

In a normal network configuration, the default buffer sizes are usually
large enough to promote tape streaming. If the network between the Tape
Coordinator machine and file server machines is slow, it can help to
increase the buffer size.

=head2 The FILE Instruction

The C<FILE> instruction takes a boolean value as its argument, in the
following format:

   FILE (NO | YES)

When the value is C<NO>, the Tape Coordinator writes to a tape device
during a dump operation and reads from one during a restore
operation. This is the default behavior if the C<FILE> instruction does
not appear in the configuration file.

When the value is C<YES>, the Tape Coordinator writes volume data to a
backup data file on the local disk during a dump operation and reads
volume data from a file during a restore operation. If the file does not
exist when the Tape Coordinator attempts to access it to write a dump, the
Tape Coordinator creates it. For a restore operation to succeed, the file
must exist and contain volume data previously written to it by a B<backup
dump> operation.

When the value is C<YES>, the backup data file's complete pathname must
appear (instead of a tape drive device name) in the third field of the
corresponding port offset entry in the local F</usr/afs/backup/tapeconfig>
file. If the field instead refers to a tape device, dump operations appear
to succeed but are inoperative. It is not possible to restore data that
was accidently dumped to a tape device while the C<FILE> instruction was
set to C<YES>. (In the same way, if the C<FILE> instruction is set to
C<NO>, the F<tapeconfig> entry must refer to an actual tape device.)

Rather than put an actual file pathname in the third field of the
F<tapeconfig> file, however, the recommended configuration is to create a
symbolic link in the F</dev> directory that points to the actual file
pathname, and record the symbolic link in this field. This configuration
has a couple of advantages:

=over 4

=item *

It makes the I<device_name> portion of the F<CFG_I<device_name>>,
F<TE_I<device_name>>, and F<TL_I<device_name>> names as short as
possible. Because the symbolic link is in the F</dev> directory as though
it were a tape device, the device configuration file's name is constructed
by stripping off the entire F</dev/> prefix, instead of just the initial
slash. If, for example, the symbolic link is called F</dev/FILE>, the
device configuration file name is F<CFG_FILE>, whereas if the actual
pathname F</var/tmp/FILE> appears in the B<tapeconfig> file, the file's
name must be F<CFG_var_tmp_FILE>.

=item *

It provides for a more graceful, and potentially automated, recovery if
the Tape Coordinator cannot write a complete dump into the backup data
file (because the partition housing the backup data file becomes full, for
example). The Tape Coordinator's reaction to this problem is to invoke the
C<MOUNT> script, or to prompt the operator if the C<MOUNT> instruction
does not appear in the configuration file.

=over 4

=item *

If there is a C<MOUNT> routine, the operator can prepare for this
situation by adding a subroutine that changes the symbolic link to point
to another backup data file on a partition where there is space available.

=item *

If there is no C<MOUNT> instruction, the prompt enables the operator
manually to change the symbolic link to point to another backup data file,
then press Return to signal that the Tape Coordinator can continue the
operation.

=back

=back

If the third field in the F<tapeconfig> file names the actual file, there
is no way to recover from exhausting the space on the partition that
houses the backup data file. It is not possible to change the
F<tapeconfig> file in the middle of an operation.

When writing to a backup data file, the Tape Coordinator writes data at 16
KB offsets. If a given block of data (such as the marker that signals the
beginning or end of a volume) does not fill the entire 16 KB, the Tape
Coordinator still skips to the next offset before writing the next
block. In the output of a B<backup dumpinfo> command issued with the
B<-id> option, the value in the C<Pos> column is the ordinal of the 16-KB
offset at which the volume data begins, and so is not generally only one
higher than the position number on the previous line, as it is for dumps
to tape.

=head2 The MOUNT Instruction

The C<MOUNT> instruction takes a pathname as its argument, in the
following format:

   MOUNT <filename>

The referenced executable file must reside on the local disk and contain a
shell script or program that directs an automated tape device, such as a
jukebox or stacker, to mount a tape (insert it into the tape reader).  The
operator must write the routine to invoke the mount command specified by
the device's manufacturer; AFS does not include any scripts, although an
example appears in L</EXAMPLES>.  The script or program inherits the Tape
Coordinator's AFS authentication status.

When the Tape Coordinator needs to mount a tape, it checks the
configuration file for a C<MOUNT> instruction. If there is no C<MOUNT>
instruction, the Tape Coordinator prompts the operator to insert a tape
before it attempts to open the tape device. If there is a C<MOUNT>
instruction, the Tape Coordinator executes the routine in the referenced
file. The routine invoked by the C<MOUNT> instruction inherits the local
identity (UNIX UID) and AFS tokens of the B<butc> command's issuer.

There is an exception to this sequence: if the C<AUTOQUERY NO> instruction
appears in the configuration file, or the B<-noautoquery> flag was
included on the B<butc> command, then the Tape Coordinator assumes that
the operator has already inserted the first tape needed for a given
operation. It attempts to read the tape immediately, and only checks for
the C<MOUNT> instruction or prompts the operator if the tape is missing or
is not the required one.

When the Tape Coordinator invokes the routine indicated by the C<MOUNT>
instruction, it passes the following parameters to the routine in the
indicated order:

=over 4

=item *

The tape device or backup data file's pathname, as recorded in the
F</usr/afs/backup/tapeconfig> file.

=item *

The tape operation, which (except for the exceptions noted in the
following list) matches the B<backup> command operation code used to
initiate the operation:

=over 4

=item *

C<appenddump> (when a backup dump command includes the B<-append> flag).

=item *

C<dump> (when a backup dump command does not include the B<-append> flag).

=item *

C<labeltape>

=item *

C<readlabel>

=item *

C<restore> (for a B<backup diskrestore>, backup volrestore, or B<backup
volsetrestore> command).

=item *

C<restoredb>

=item *

C<savedb>

=item *

C<scantape>

=back

=item *

The number of times the Tape Coordinator has attempted to open the tape
device or backup data file. If the open attempt returns an error, the Tape
Coordinator increments this value by one and again invokes the C<MOUNT>
instruction.

=item *

The tape name. For some operations, the Tape Coordinator passes the string
C<none>, because it does not know the tape name (when running the B<backup
scantape> or B<backup readlabel>, for example), or because the tape does
not necessarily have a name (when running the B<backup labeltape> command,
for example).

=item *

The tape ID recorded in the Backup Database. As with the tape name, the
Backup System passes the string C<none> for operations where it does not
know the tape ID or the tape does not necessarily have an ID.

=back

The routine invoked by the C<MOUNT> instruction must return an exit code
to the Tape Coordinator:

=over 4

=item *

Code 0 (zero) indicates that the routine successfully mounted the
tape. The Tape Coordinator continues the backup operation.  If the routine
invoked by the C<MOUNT> instruction does not return this exit code, the
Tape Coordinator never calls the C<UNMOUNT> instruction.

=item *

Code 1 (one) indicates that the routine failed to mount the tape. The Tape
Coordinator terminates the operation.

=item *

Any other code indicates that the routine was not able to access the
correct tape. The Tape Coordinator prompts the operator to insert the
correct tape.

=back

If the backup command was issued in interactive mode and the operator
issues the B<backup kill> command while the C<MOUNT> routine is running,
the Tape Coordinator passes the termination signal to the routine; the
entire operation terminates.

=head2 The NAME_CHECK Instruction

The C<NAME_CHECK> instruction takes a boolean value as its argument, in
the following format:

   NAME_CHECK (YES | NO)

When the value is C<YES> and the tape does not have a permanent name, the
Tape Coordinator checks the AFS tape name when dumping a volume in
response to the B<backup dump> command. The AFS tape name must be C<<
<NULL> >> or match the tape name that the B<backup dump> operation assigns
based on the volume set and dump level names. This is the default behavior
if the C<NAME_CHECK> instruction does not appear in the configuration
file.

When the value is C<NO>, the Tape Coordinator does not check the AFS tape
name before writing to the tape.

The Tape Coordinator always checks that all dumps on the tape are expired,
and refuses to write to a tape that contains unexpired dumps.

=head2 The UNMOUNT Instruction

The C<UNMOUNT> instruction takes a pathname as its argument, in the
following format:

   UNMOUNT <filename>

The referenced executable file must reside on the local disk and contain a
shell script or program that directs an automated tape device, such as a
jukebox or stacker, to unmount a tape (remove it from the tape reader).
The operator must write the routine to invoke the unmount command
specified by the device's manufacturer; AFS does not include any scripts,
although an example appears in L</EXAMPLES>.  The script or program
inherits the Tape Coordinator's AFS authentication status.

After closing a tape device, the Tape Coordinator checks the configuration
file for an C<UNMOUNT> instruction, whether or not the B<close> operation
succeeds. If there is no C<UNMOUNT> instruction, the Tape Coordinator
takes no action, in which case the operator must take the action necessary
to remove the current tape from the drive before another can be
inserted. If there is an C<UNMOUNT> instruction, the Tape Coordinator
executes the referenced file. It invokes the routine only once, passing in
the following parameters:

=over 4

=item *

The tape device pathname (as specified in the
F</usr/afs/backup/tapeconfig> file).

=item *

The tape operation (always unmount).

=back

=head1 PRIVILEGE REQUIRED

The file is protected by UNIX mode bits. Creating the file requires the
C<w> (write) and C<x> (execute) permissions on the F</usr/afs/backup>
directory. Editing the file requires the C<w> (write) permission on the
file.

=head1 EXAMPLES

The following example configuration files demonstrate one way to structure
a configuration file for a stacker or backup dump file. The examples are
not necessarily appropriate for a specific cell; if using them as models,
be sure to adapt them to the cell's needs and equipment.

=head2 Example F<CFG_I<device_name>> File for Stackers

In this example, the administrator creates the following entry for a tape
stacker called C<stacker0.1> in the F</usr/afs/backup/tapeconfig> file. It
has port offset 0.

   2G   5K   /dev/stacker0.1   0

The administrator includes the following five lines in the
F</usr/afs/backup/CFG_stacker0.1> file. To review the meaning of each
instruction, see L</DESCRIPTION>.

   MOUNT /usr/afs/backup/stacker0.1
   UNMOUNT /usr/afs/backup/stacker0.1
   AUTOQUERY NO
   ASK NO
   NAME_CHECK NO

Finally, the administrator writes the following executable routine in the
F</usr/afs/backup/stacker0.1> file referenced by the C<MOUNT> and
C<UNMOUNT> instructions in the F<CFG_stacker0.1> file.

   #! /bin/csh -f

   set devicefile = $1
   set operation = $2
   set tries = $3
   set tapename = $4
   set tapeid = $5

   set exit_continue = 0
   set exit_abort = 1
   set exit_interactive = 2

   #--------------------------------------------

   if (${tries} > 1) then
      echo "Too many tries"
      exit ${exit_interactive}
   endif

   if (${operation} == "unmount") then
      echo "UnMount: Will leave tape in drive"
      exit ${exit_continue}
   endif

   if ((${operation} == "dump")     |\
       (${operation} == "appenddump")     |\
       (${operation} == "savedb"))  then

       stackerCmd_NextTape ${devicefile}
       if (${status} != 0)exit${exit_interactive}
       echo "Will continue"
       exit ${exit_continue}
   endif

   if ((${operation} == "labeltape")    |\
       (${operation} == "readlabel")) then
      echo "Will continue"
      exit ${exit_continue}
   endif

   echo "Prompt for tape"
   exit ${exit_interactive}

This routine uses two of the parameters passed to it by the Backup System:
C<tries> and C<operation>. It follows the recommended practice of
prompting for a tape if the value of the C<tries> parameter exceeds one,
because that implies that the stacker is out of tapes.

For a B<backup dump> or backup savedb operation, the routine calls the
example C<stackerCmd_NextTape> function provided by the stacker's
manufacturer. Note that the final lines in the file return the exit code
that prompts the operator to insert a tape; these lines are invoked when
either the stacker cannot load a tape or a the operation being performed
is not one of those explicitly mentioned in the file (such as a restore
operation).

=head2 Example F<CFG_I<device_name>> File for Dumping to a Data File

In this example, the administrator creates the following entry for a
backup data file called F<HSM_device> in the F</usr/afs/backup/tapeconfig>
file. It has port offset 20.

   1G   0K   /dev/HSM_device   20

The administrator includes the following lines in the
F</usr/afs/backup/CFG_HSM_device> file. To review the meaning of each
instruction, see L</DESCRIPTION>.

   MOUNT /usr/afs/backup/file
   FILE YES
   ASK NO

Finally, the administrator writes the following executable routine in the
F</usr/afs/backup/file> file referenced by the C<MOUNT> instruction in the
F<CFG_HSM_device> file, to control how the Tape Coordinator handles the
file.

   #! /bin/csh -f
   set devicefile = $1
   set operation = $2
   set tries = $3
   set tapename = $4
   set tapeid = $5

   set exit_continue = 0
   set exit_abort = 1
   set exit_interactive = 2

   #--------------------------------------------

   if (${tries} > 1) then
      echo "Too many tries"
      exit ${exit_interactive}
   endif

   if (${operation} == "labeltape") then
      echo "Won't label a tape/file"
      exit ${exit_abort}
   endif

   if ((${operation} == "dump")   |\
       (${operation} == "appenddump")   |\
       (${operation} == "restore")   |\
       (${operation} == "savedb")    |\
       (${operation} == "restoredb")) then

      /bin/rm -f ${devicefile}
      /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
      if (${status} != 0) exit ${exit_abort}
   endif

   exit ${exit_continue}

Like the example routine for a tape stacker, this routine uses the
C<tries> and C<operation> parameters passed to it by the Backup
System. The C<tries> parameter tracks how many times the Tape Coordinator
has attempted to access the file. A value greater than one indicates that
the Tape Coordinator cannot access it, and the routine returns exit code 2
(C<exit_interactive>), which results in a prompt for the operator to load
a tape. The operator can use this opportunity to change the name of the
backup data file specified in the B<tapeconfig> file.

The primary function of this routine is to establish a link between the
device file and the file to be dumped or restored. When the Tape
Coordinator is executing a B<backup dump>, B<backup restore>, B<backup
savedb>, or B<backup restoredb> operation, the routine invokes the UNIX
C<ln -s> command to create a symbolic link from the backup data file named
in the F<tapeconfig> file to the actual file to use (this is the
recommended method). It uses the value of the C<tapename> and C<tapeid>
parameters to construct the file name.

=head1 SEE ALSO

L<tapeconfig(5)>,
L<backup_diskrestore(8)>,
L<backup_dump(8)>,
L<backup_restoredb(8)>,
L<backup_savedb(8)>,
L<backup_volrestore(8)>,
L<backup_volsetrestore(8)>

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.