butc - Defines Tape Coordinator instructions for automated tape devices

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 CW/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 (CW/) 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: Controls whether the Tape Coordinator prompts for guidance when it encounters error conditions. Controls whether the Tape Coordinator prompts for the first tape. Sets the size of the memory buffer the Tape Coordinator uses when transferring data. Controls whether the dump is written to a tape device or a file. Identifies the file that contains routines for inserting tapes into the device's drive. Controls whether the Tape Coordinator verifies that a tape's AFS tape name matches the dump being written. Identifies the file that contains routines for removing tapes from the device's drive.

The CWASK instruction takes a boolean value as its argument, in the following format:

   ASK (YES | NO)

When the value is CWNO, 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 CWMOUNT 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 CWYES 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 CWNO 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 CWYES value, the Tape Coordinator prompts to offer two choices: omit the volume and continue restoring the other volumes, or terminate the operation. With a CWNO 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 CWYES value, the Tape Coordinator prompts to ask if there are more tapes to scan. With a CWNO value, it proceeds as though there are more tapes and invokes the routine named by the CWMOUNT 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 CWYES value, the Tape Coordinator prompts to offer two choices: continue or terminate the labeling operation. With a CWNO value, it terminates the operation without relabeling the tape.

The CWAUTOQUERY instruction takes a boolean value as its argument, in the following format:

   AUTOQUERY (YES | NO)

When the value is CWNO, 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 CWMOUNT 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 CWAUTOQUERY 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 CWMOUNT instruction. It also refers to the CWMOUNT instruction if it encounters an error while attempting to access the first tape.

The CWBUFFERSIZE instruction takes an integer value, and optionally units, in the following format:

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

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 CWFILE instruction takes a boolean value as its argument, in the following format:

   FILE (NO | YES)

When the value is CWYES, 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 CWYES, 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 CWFILE instruction was set to CWYES. (In the same way, if the CWFILE instruction is set to CWNO, 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 CWMOUNT script, or to prompt the operator if the CWMOUNT instruction does not appear in the configuration file. If there is a CWMOUNT 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 CWMOUNT 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 CWPos 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 CWMOUNT instruction takes a pathname as its argument, in the following format:

   MOUNT <filename>

When the Tape Coordinator needs to mount a tape, it checks the configuration file for a CWMOUNT instruction. If there is no CWMOUNT instruction, the Tape Coordinator prompts the operator to insert a tape before it attempts to open the tape device. If there is a CWMOUNT instruction, the Tape Coordinator executes the routine in the referenced file. The routine invoked by the CWMOUNT 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 CWAUTOQUERY 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 CWMOUNT 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 CWMOUNT 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: CWappenddump (when a backup dump command includes the -append flag). CWdump (when a backup dump command does not include the -append flag). CWlabeltape CWreadlabel CWrestore (for a backup diskrestore, backup volrestore, or backup volsetrestore command). CWrestoredb CWsavedb CWscantape 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 CWMOUNT instruction. The tape name. For some operations, the Tape Coordinator passes the string CWnone, 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 CWnone for operations where it does not know the tape ID or the tape does not necessarily have an ID.

The routine invoked by the CWMOUNT 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 CWMOUNT instruction does not return this exit code, the Tape Coordinator never calls the CWUNMOUNT 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 CWMOUNT routine is running, the Tape Coordinator passes the termination signal to the routine; the entire operation terminates.

The CWNAME_CHECK instruction takes a boolean value as its argument, in the following format:

   NAME_CHECK (YES | NO)

When the value is CWNO, 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 CWUNMOUNT instruction takes a pathname as its argument, in the following format:

   UNMOUNT <filename>

After closing a tape device, the Tape Coordinator checks the configuration file for an CWUNMOUNT instruction, whether or not the close operation succeeds. If there is no CWUNMOUNT 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 CWUNMOUNT 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).

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

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.

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

   2G   5K   /dev/stacker0.1   0

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

   #! /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}

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

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

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

   #! /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}

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 CWln -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 CWtapename and CWtapeid parameters to construct the file name.

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

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.