![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
Defines Tape Coordinator configuration instructions for automated tape devices
Description
The CFG_device_name file includes instructions that configure a Tape Coordinator 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 /usr/afs/backup directory on the Tape Coordinator machine if it exists.
The CFG_device_name file does not replace the /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, device_name, as follows:
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:
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 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 sizevalue 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 /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 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:
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 following Examples section. 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 routine invoked by the MOUNT instruction must return an exit code to the Tape Coordinator:
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 following Examples section. 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:
Privilege Required
The file is protected by UNIX mode bits. Creating the file requires the w (write) and x (execute) permissions on the /usr/afs/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 /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 /usr/afs/backup/CFG_stacker0.1 file. To review the meaning of each instruction, see the preceding Description section.
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 /usr/afs/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 Backup Data File
In this example, the administrator creates the following entry for a backup data file called HSM_device in the /usr/afs/backup/tapeconfig file. It has port offset 20.
1G 0K /dev/HSM_device 20
The administrator includes the following lines in the /usr/afs/backup/CFG_HSM_device file. To review the meaning of each instruction, see the preceding Description section.
MOUNT /usr/afs/backup/file FILE YES ASK NO
Finally, the administrator writes the following executable routine in the /usr/afs/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.
Related Information
![[Top of Topic]](../top.gif)