Ubuntu Manpage: butc - Defines Tape Coordinator instructions for automated tape devices

Provided by: openafs-client_1.8.10-2.1ubuntu3.4_amd64

NAME

       butc - Defines Tape Coordinator instructions for automated tape devices

DESCRIPTION

The CFG_device_name file includes instructions that configure a Tape Coordinator (butc) for use with
automated backup devices such as tape stackers and jukeboxes, enable the Tape Coordinator to dump and
restore data to a 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 /var/lib/openafs/backup directory on the Tape Coordinator machine if
it exists.

The CFG_device_name file does not replace the /var/lib/openafs/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, device_name, as follows:

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

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

The CFG_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:

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

AUTOQUERY
Controls whether the Tape Coordinator prompts for the first tape.

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

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

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

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

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

The ASK Instruction
The "ASK" instruction takes a boolean value as its argument, in the following format:

ASK (YES | NO)

When the value is "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 "ASK" instruction
does not appear in the CFG_device_name file.

When the value is "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 TE_device_name file. Suppressing the prompts enables the Tape Coordinator to run unattended, though
it still prompts for insertion of tapes unless the "MOUNT" instruction is used.

The error cases controlled by this instruction are the following:

• The Backup System is unable to dump a volume while running the backup dump command. With a "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 "NO"
value, the Tape Coordinator omits the volume from the dump and continues the operation.

• The Backup System is unable to restore a volume while running the backup diskrestore, backup
volrestore, or backup volsetrestore command. With a "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 "NO" value, it continues the operation without prompting, omitting the problematic
volume but restoring the remaining ones.

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

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

The AUTOQUERY Instruction
The "AUTOQUERY" instruction takes a boolean value as its argument, in the following format:

AUTOQUERY (YES | NO)

When the value is "YES", the Tape Coordinator checks for the "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 "AUTOQUERY" instruction does not appear in the configuration file.

When the value is "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 "MOUNT" routine unless there is an
error in accessing the first tape. This setting is equivalent in effect to including the -noautoquery
flag to the butc command.

Note that the setting of the "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 "MOUNT" instruction. It also refers to the "MOUNT" instruction if it encounters an error
while attempting to access the first tape.

The BUFFERSIZE Instruction
The "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 "k" or "K" to specify kilobytes, "m" or
"M" for megabytes, and "g" or "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.

The FILE Instruction
The "FILE" instruction takes a boolean value as its argument, in the following format:

FILE (NO | YES)

When the value is "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 "FILE" instruction does not
appear in the configuration file.

When the value is "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 backup dump operation.

When the value is "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
/var/lib/openafs/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 "FILE" instruction was set to "YES". (In the same way, if the "FILE" instruction is
set to "NO", the tapeconfig entry must refer to an actual tape device.)

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

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

• 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 "MOUNT"
script, or to prompt the operator if the "MOUNT" instruction does not appear in the configuration
file.

• If there is a "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.

• If there is no "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.

If the third field in the 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
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
backup dumpinfo command issued with the -id option, the value in the "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.

The MOUNT Instruction
The "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 "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 "MOUNT"
instruction. If there is no "MOUNT" instruction, the Tape Coordinator prompts the operator to insert a
tape before it attempts to open the tape device. If there is a "MOUNT" instruction, the Tape Coordinator
executes the routine in the referenced file. The routine invoked by the "MOUNT" instruction inherits the
local identity (UNIX UID) and AFS tokens of the butc command's issuer.

There is an exception to this sequence: if the "AUTOQUERY NO" instruction appears in the configuration
file, or the -noautoquery flag was included on the 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 "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 "MOUNT" instruction, it passes the
following parameters to the routine in the indicated order:

• The tape device or backup data file's pathname, as recorded in the /var/lib/openafs/backup/tapeconfig
file.

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

• "appenddump" (when a backup dump command includes the -append flag).

• "dump" (when a backup dump command does not include the -append flag).

• "labeltape"

• "readlabel"

• "restore" (for a backup diskrestore, backup volrestore, or backup volsetrestore command).

• "restoredb"

• "savedb"

• "scantape"

• 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 "MOUNT" instruction.

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

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

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

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

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

• 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.

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

The NAME_CHECK Instruction
The "NAME_CHECK" instruction takes a boolean value as its argument, in the following format:

NAME_CHECK (YES | NO)

When the value is "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 backup dump command. The AFS tape name must be
"<NULL>" or match the tape name that the backup dump operation assigns based on the volume set and dump
level names. This is the default behavior if the "NAME_CHECK" instruction does not appear in the
configuration file.

When the value is "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.

The UNMOUNT Instruction
The "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 "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 "UNMOUNT"
instruction, whether or not the close operation succeeds. If there is no "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 "UNMOUNT" instruction, the
Tape Coordinator executes the referenced file. It invokes the routine only once, passing in the following
parameters:

• The tape device pathname (as specified in the /var/lib/openafs/backup/tapeconfig file).

• The tape operation (always unmount).

PRIVILEGE REQUIRED

       The  file  is  protected  by UNIX mode bits. Creating the file requires the "w" (write) and "x" (execute)
       permissions on  the  /var/lib/openafs/backup  directory.  Editing  the  file  requires  the  "w"  (write)
       permission on the file.

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.

   Example CFG_device_name File for Stackers
       In  this example, the administrator creates the following entry for a tape stacker called "stacker0.1" in
       the /var/lib/openafs/backup/tapeconfig file. It has port offset 0.

          2G   5K   /dev/stacker0.1   0

       The administrator includes the following five lines in the  /var/lib/openafs/backup/CFG_stacker0.1  file.
       To review the meaning of each instruction, see "DESCRIPTION".

          MOUNT /var/lib/openafs/backup/stacker0.1
          UNMOUNT /var/lib/openafs/backup/stacker0.1
          AUTOQUERY NO
          ASK NO
          NAME_CHECK NO

       Finally,     the     administrator     writes     the     following    executable    routine    in    the
       /var/lib/openafs/backup/stacker0.1 file referenced by the  "MOUNT"  and  "UNMOUNT"  instructions  in  the
       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: "tries" and "operation". It
       follows the recommended practice of prompting for a tape if the value of the  "tries"  parameter  exceeds
       one, because that implies that the stacker is out of tapes.

       For  a  backup  dump  or  backup  savedb  operation,  the routine calls the example "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).

   Example CFG_device_name File for Dumping to a Data File
       In this example, the administrator creates the following entry for a backup data file  called  HSM_device
       in the /var/lib/openafs/backup/tapeconfig file. It has port offset 20.

          1G   0K   /dev/HSM_device   20

       The  administrator  includes  the  following lines in the /var/lib/openafs/backup/CFG_HSM_device file. To
       review the meaning of each instruction, see "DESCRIPTION".

          MOUNT /var/lib/openafs/backup/file
          FILE YES
          ASK NO

       Finally, the administrator writes the following executable routine  in  the  /var/lib/openafs/backup/file
       file  referenced  by  the  "MOUNT"  instruction  in  the  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  "tries"  and  "operation"  parameters
       passed  to  it by the Backup System. The "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 ("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 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 backup dump, backup restore, backup  savedb,
       or  backup  restoredb  operation,  the routine invokes the UNIX "ln -s" command to create a symbolic link
       from the backup data file named in the tapeconfig file to the actual file to use (this is the recommended
       method). It uses the value of the "tapename" and "tapeid" parameters to construct the file name.

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.

OpenAFS                                            2025-05-19                                            BUTC(5)

NAME

DESCRIPTION

PRIVILEGE REQUIRED

EXAMPLES

SEE ALSO

COPYRIGHT