Provided by: openafs-client_1.4.1-2_i386 bug

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 the EXAMPLES
       manpage.  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 the EXAMPLES
       manpage.  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 the DESCRIPTION manpage.

          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 the DESCRIPTION manpage.

          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.

SEE ALSO

       the tapeconfig(5) manpage, the backup_diskrestore(8) manpage, the
       backup_dump(8) manpage, the backup_restoredb(8) manpage, the
       backup_savedb(8) manpage, the backup_volrestore(8) manpage, the
       backup_volsetrestore(8) manpage

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.