CFG_tcid

Purpose

Defines Tape Coordinator configuration instructions for automated tape devices, backup data files, or XBSA server programs

Description

A CFG_tcid file includes instructions that configure a Tape Coordinator for more automated operation and for transferring AFS data to and from a certain type of backup media:

• An automated tape device, such as a stacker or jukebox. The file is optional for a Tape Coordinator that writes to such a device, and unnecessary if the default value for all types of instruction are appropriate for the device.

• A backup data file on a local disk device. The configuration file is mandatory and must include the FILE instruction at least.

• A third-party backup utility that implements the Open Group's Backup Service API (XBSA), hereafter referred to as an XBSA server. The file is mandatory and must include the SERVER, TYPE, and PASSFILE or PASSWORD instructions. The General Availability release of AFS 3.6 can communicate with one XBSA server, the Tivoli Storage Manager (TSM).

The Tape Coordinator for a tape device or backup data file must also have an entry in the Backup Database and in the /usr/afs/backup/tapeconfig file on the Tape Coordinator machine. The Tape Coordinator for an XBSA server has only an entry in the Backup Database, not in the tapeconfig file.

Naming the Configuration File

For a Tape Coordinator that communicates with an XBSA server, the tcid portion of the configuration file's name is the Tape Coordinator's port offset number as defined in the Backup Database. An example filename is CFG_22. For the Tape Coordinator for a tape device or backup data file, there are two possible types of values for the tcid portion of the filename. The Tape Coordinator first attempts to open a file with a tcid portion that is the Tape Coordinator's port offset number as defined in the Backup Database and tapeconfig file. If there is no such file, the Tape Coordinator attempts to access a file with a tcid portion that is based on the tape device's device name the backup data file's filename. To enable the Tape Coordinator to locate the file, construct the tcid portion of the filename 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.

Summary of Instructions

The following list briefly describes the instructions that can appear in a configuration file. Each instruction appears on its own line, in any order. Unless otherwise noted, the instructions apply to all backup media (automated tape device, backup data file, and XBSA server). 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 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 its /usr/afs/backup/TE_tcid 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 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 instruction does not apply to XBSA servers.

The BUFFERSIZE Instruction

The BUFFERSIZE instruction takes an integer or decimal value, and optionally units, in the following format:

   BUFFERSIZE size[{k | K | m | M | g | G | t | T}]   

As the Tape Coordinator receives volume data from the Volume Server during a dump operation, it gathers the specified amount of data in the buffer before transferring the entire amount to the backup medium. Similarly, during a restore operation the Tape Coordinator by default buffers data from the backup medium before transferring the entire amount to the Volume Server for restoration into the file system.

The default buffer size is 16 KB, which is usually large enough to promote tape streaming in a normal network configuration. If the network connection between the Tape Coordinator machine and file server machines is slow, it can help to increase the buffer size.

For XBSA servers, the range of acceptable values is 1K through 64K. For tape devices and backup data files, the minimum acceptable value is 16K, and if the specified value is not a multiple of 16 KB, the Tape Coordinator automatically rounds it up to the next such multiple.

The CENTRALLOG Instruction

The CENTRALLOG instruction takes a pathname as its argument, in the following format:

   CENTRALLOG  filename   

The line for each dump operation has the following format:

   task_ID   start_time   complete_time   duration  volume_set  \
         success of total volumes dumped (data_dumped KB)   

   task_ID   start_time   complete_time   duration  success of total volumes restored 

The FILE Instruction

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

   FILE {NO | YES}   

When the value is YES, the Tape Coordinator uses a backup data file on the local disk as the backup medium. If the file does not exist when the Tape Coordinator attempts 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 is accidently dumped to a tape device while the FILE instruction is set to YES. (In the same way, if the FILE instruction is set to NO and there is no SERVER instruction, 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's name in this field. This configuration has a couple of advantages:

• It makes the tcid portion of the CFG_tcid, TE_tcid, and TL_tcid 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 GROUPID Instruction

The GROUPID instruction takes an integer as its argument, in the following format:

   GROUPID integer   

The LASTLOG Instruction

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

   LASTLOG  {YES | NO}   

When the value is NO, the Tape Coordinator writes to its standard log files (the TE_tcid and TL_tcid files in the /usr/afs/backup directory) for all passes. This is the behavior if the instruction does not appear in the file.

The MAXPASS Instruction

The MAXPASS instruction takes an integer as its argument, in the following format:

   MAXPASS integer   

The MGMTCLASS Instruction

The MGMTCLASS instruction takes a character string as its argument, in the following format:

   MGMTCLASS class_name   

The MOUNT Instruction

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

   MOUNT filename   

The administrator must write the script, including the appropriate routines and logic. The AFS distribution does not include any scripts, although an example appears in the following Examples section. The command or routines invoked by the script inherit the local identity (UNIX UID) and AFS tokens of the butc command's issuer. When the Tape Coordinator needs to mount a tape or access another backup data file, it checks the configuration file for a MOUNT instruction. If there is no 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 script. 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. The Tape Coordinator passes the following parameters to the script indicated by the MOUNT instruction, in the indicated order:

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

2. The tape operation, which generally matches the backup command operation code used to initiate the operation (the following list notes the exceptional cases) :

   • 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

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

4. 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).

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

• Code 0 (zero) indicates that the routine successfully mounted the tape or opened the backup data file. 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 or open the backup data file. The Tape Coordinator terminates the operation.

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

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 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. This instruction does not apply to XBSA servers.

The NODE Instruction

The NODE instruction takes a character string as its argument, in the following format:

   NODE node_name   

The PASSFILE Instruction

The PASSFILE instruction takes a pathname as its argument, in the following format:

   PASSFILE filename   

The PASSWORD Instruction

The PASSWORD instruction takes a character string as its argument, in the following format:

   PASSWORD string   

The SERVER Instruction

The SERVER instruction takes a character string as its argument, in the following format:

   SERVER machine_name   

The STATUS Instruction

The STATUS instruction takes an integer as its argument, in the following format:

   STATUS integer   

As an example, the value 512 means that the Tape Coordinator writes a status message after each 512 buffers of data. It also writes a status message as it completes the dump of each volume.

The message has the following format:

   time_stamp: Task task_ID: total KB: volume: volume_total B

The TYPE Instruction

The TYPE instruction takes a character string as its argument, in the following format:

   TYPE program_name   

The UNMOUNT Instruction

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

   UNMOUNT filename   

The administrator must write the script, including the appropriate routines and logic. The AFS distribution does not include any scripts, although an example appears in the following Examples section. The command or routines invoked by the script inherit the local identity (UNIX UID) and AFS tokens of the butc command's issuer.

After closing a tape device or backup data file, 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 /usr/afs/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 /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_tcid 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   

   MOUNT /usr/afs/backup/stacker0.1
   UNMOUNT /usr/afs/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 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 the operation being performed is not one of those explicitly mentioned in the file (such as a restore operation).

Example CFG_tcid 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   

   MOUNT /usr/afs/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 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.

Example CFG_tcid File for an XBSA Server

The following is an example of a configuration file called /usr/afs/backup/CFG_22, for a Tape Coordinator with port offset 22 that communicates with an Tivoli Storage Management (TSM) server. The combination of BUFFERSIZE and STATUS instructions results in a status message after each 16 MB of data are dumped. To review the meaning of the other instructions, see the preceding Description section.

   SERVER tsmserver1.abc.com
   TYPE tsm
   PASSWORD  TESTPASS
   NODE testnode
   MGMTCLASS standard
   MAXPASS 1
   GROUPID 1000
   CENTRALLOG /usr/afs/backup/centrallog
   BUFFERSIZE 16K
   STATUS 1024