Automating and Increasing the Efficiency of the Backup Process

The Backup System includes several optional features to help you automate the backup process in your cell and make it more efficient. By combining several of the features, you can dump volume data to tape with minimal human intervention in most cases. To take advantage of many of the features, you create a device configuration file in the /usr/afs/backup directory for each tape device that participates in automated operations. For general instructions on creating the device configuration file, see Creating a Device Configuration File. The following list refers you to sections that describe each feature in greater detail.

There are two additional ways to increase backup automation and efficiency that do not involve the device configuration file:

Creating a Device Configuration File

To use many of the features that automate backup operations, create a configuration file for each tape device in the /usr/afs/backup directory on the local disk of the Tape Coordinator machine that drives the device. The filename has the following form:

CFG_device_name

where device_name represents the name of the tape device or backup data file (see Dumping Data to a Backup Data File to learn about writing dumps to a file rather than to tape).

For a tape device, construct the device_name portion of the name by stripping off the initial /dev/ string with which all UNIX device names conventionally begin, and replacing 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, construct the device_name portion by stripping off the initial slash (/) and replacing 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.

Creating a device configuration file is optional. If you do not want to take advantage of any of the features that the file provides, you do not have to create it.

You can include one of each of the following instructions in any order in a device configuration file. All are optional. Place each instruction on its own line, but do not include any newline (<Return>) characters within an instruction.

MOUNT and UNMOUNT

Identify a script of routines for mounting and unmounting tapes in a tape stacker or jukebox's drive as needed. See Invoking a Device's Tape Mounting and Unmounting Routines.

AUTOQUERY

Controls whether the Tape Coordinator prompts for the first tape it needs for a backup operation. See Eliminating the Search or Prompt for the Initial Tape.

ASK

Controls whether the Tape Coordinator asks you how to respond to certain error conditions. See Enabling Default Responses to Error Conditions.

NAME_CHECK

Controls whether the Tape Coordinator verifies that an AFS tape name matches the initial dump you are writing to the tape. See Eliminating the AFS Tape Name Check.

BUFFERSIZE

Sets the size of the memory buffer the Tape Coordinator uses when transferring data between a tape device and a volume. See Setting the Memory Buffer Size to Promote Tape Streaming.

FILE

Controls whether the Tape Coordinator writes dumps to, and restores data from, a tape device or a backup data file. See Dumping Data to a Backup Data File.

Invoking a Device's Tape Mounting and Unmounting Routines

A tape stacker or jukebox helps you automate backup operations because it can switch between multiple tapes during an operation without human intervention. To take advantage of this feature, include the MOUNT and optionally UNMOUNT instructions in the device configuration file that you write for the stacker or jukebox. The instructions share the same syntax:

MOUNT filename
   UNMOUNT filename

where filename is the pathname on the local disk of a script or program you have written that invokes the routines defined by the device's manufacturer for mounting or unmounting a tape in the device's tape drive. (For convenience, the following discussion uses the term script to refers to both scripts and programs.) The script usually also contains additional logic that handles error conditions or modifies the script's behavior depending on which backup operation is being performed.

You can refer to different scripts with the MOUNT or UNMOUNT instructions, or to a single script that invokes both mounting and unmounting routines. The scripts inherit the local identity and AFS tokens associated with to the issuer of the butc command.

You need to include a MOUNT instruction in the device configuration file for all tape devices, but the need for an UNMOUNT instruction depends on the tape-handling routines that the device's manufacturer provides. Some devices, usually stackers, have only a single routine for mounting tapes, which also automatically unmounts a tape whose presence prevents insertion of the required new tape. In this case, an UNMOUNT instruction is not necessary. For devices that have separate mounting and unmounting routines, you must include an UNMOUNT instruction to remove a tape when the Tape Coordinator is finished with it; otherwise, subsequent attempts to run the MOUNT instruction fail with an error.

When the device configuration file includes a MOUNT instruction, you must stock the stacker or jukebox with the necessary tapes before running a backup operation. Many jukeboxes are able to search for the required tape by reading external labels (such as barcodes) on the tapes, but many stackers can only switch between tapes in sequence and sometimes only in one direction. In the latter case, you must also stock the tapes in the correct order.

To obtain a list of the tapes required for a restore operation so that you can prestock them in the tape device, include the -n flag on the appropriate backup command (backup diskrestore, backup volrestore, or backup volsetrestore). For a dump operation, it is generally sufficient to stock the device with more tapes than the operation is likely to require. You can prelabel the tapes with permanent names or AFS tape names, or not prelabel them at all. If you prelabel the tapes for a dump operation with AFS tape names, then it is simplest to load them into the stacker in sequential order by tape index. But it is probably simpler still to prelabel tapes with permanent tape names or use unlabeled tapes, in which case the Backup System generates and applies the appropriately indexed AFS tape name itself during the dump operation.

How the Tape Coordinator Uses the MOUNT and UNMOUNT Instructions

When you issue the butc command to initialize the Tape Coordinator for a given tape device, the Tape Coordinator looks for the device configuration file called /usr/afs/backup/CFG_device_name on its local disk, where device_name has the format described in Creating a Device Configuration File. If the file exists and contains a MOUNT instruction, then whenever the Tape Coordinator needs a tape, it executes the script named by the instruction's filename argument.

If the device configuration file does not exist, or does not include a MOUNT instruction, then whenever the Tape Coordinator needs a tape, it generates a prompt in its window instructing the operator to insert the necessary tape. The operator must insert the tape and press <Return> before the Tape Coordinator continues the backup operation.

Note, however, that you can modify the Tape Coordinator's behavior with respect to the first tape needed for an operation, by setting the AUTOQUERY instruction in the device configuration file to NO, or including the -noautoquery flag to the butc command. In this case, the Tape Coordinator does not execute the MOUNT instruction or prompt for a tape at the start of an operation, because it expects to find the required first tape in the drive. See Eliminating the Search or Prompt for the Initial Tape.

If there is an UNMOUNT instruction in the device configuration file, then whenever the Tape Coordinator closes the tape device, it executes the script named by the instruction's filename argument. It executes the script only once, and regardless of whether the close operation on the device succeeded or not. If the device configuration file does not include an UNMOUNT instruction, then the Tape Coordinator takes no action.

The Available Parameters and Required Exit Codes

When the Tape Coordinator executes the MOUNT script, it passes in five parameters, ordered as follows. You can use the parameters in your script to refine its response to varying circumstances that can arise during a backup operation.

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

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

  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.

Your MOUNT script must return one of the following exit codes to tell the Tape Coordinator whether or not it mounted the tape successfully:

  • Code 0 (zero) indicates a successful mount, and the Tape Coordinator continues the backup operation. If the script or program called by the MOUNT instruction does not return this exit code, the Tape Coordinator never calls the UNMOUNT instruction.

  • Code 1 indicates that mount attempt failed. The Tape Coordinator terminates the backup operation.

  • Any other code indicates that the script was unable to access the correct tape. The Tape Coordinator prompts the operator to insert it.

When the Tape Coordinator executes the UNMOUNT script, it passes in two parameters in the following order.

  1. The tape device's pathname (as specified in the /usr/afs/backup/tapeconfig file)

  2. The tape operation, which is always unmount.

The following example script uses two of the parameters passed to it by the Backup System: tries and operation. It follows the recommended practice of exiting 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 (is a restore operation, for example).

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

Eliminating the Search or Prompt for the Initial Tape

By default, the Tape Coordinator obtains the first tape it needs for a backup operation by reading the device configuration file for the appropriate tape device. If there is a MOUNT instruction in the file, the Tape Coordinator executes the referenced script. If the device configuration file does not exist or does not have a MOUNT instruction in it, the Tape Coordinator prompts you to insert the correct tape and press <Return>.

If you know in advance that an operation requires a tape, you can increase efficiency by placing the required tape in the drive before issuing the backup command and telling the Tape Coordinator's to skip its initial tape-acquisition steps. This both enables the operation to begin more quickly and eliminates that need for you to be present to insert a tape.

There are two ways to bypass the Tape Coordinator's initial tape-acquisition steps:

  1. Include the instruction AUTOQUERY NO in the device configuration file

  2. Include the -noautoquery flag to the butc command

To avoid any error conditions that require operator attention, be sure that the tape you are placing in the drive does not contain any unexpired dumps and is not write protected. If there is no permanent name on the tape's label and you are creating an initial dump, make sure that the AFS tape name either matches the volume set and dump set names or is <NULL>. Alternatively, suppress the Tape Coordinator's name verification step by assigning the value NO to the NAME_CHECK instruction in the device configuration file, as described in Eliminating the AFS Tape Name Check.

Enabling Default Responses to Error Conditions

By default, the Tape Coordinator asks you how to respond when it encounters certain error conditions. To suppress the prompts and cause the Tape Coordinator to handle the errors in a predetermined manner, include the instruction ASK NO in the device configuration file. If you assign the value YES, or omit the ASK instruction completely, the Tape Coordinator prompts you for direction when it encounters one of the errors.

The following list describes the error conditions and the Tape Coordinator's response to them.

  • The Backup System is unable to dump a volume while running the backup dump command. When you assign the value NO, the Tape Coordinator omits the volume from the dump and continues the operation. When you assign the value YES, it prompts to ask if you want to try to dump the volume again immediately, to omit the volume from the dump but continue the operation, or to terminate the operation.

  • The Backup System is unable to restore a volume while running the backup diskrestore, backup volrestore, or backup volsetrestore command. When you assign the value NO, the Tape Coordinator continues the operation, omitting the problematic volume but restoring the remaining ones. When you assign the value YES, it prompts to ask if you want to omit the volume and continue the operation, or to terminate the operation.

  • The Backup System cannot determine if the dump set includes any more tapes while running the backup scantape command (the command's reference page in the OpenAFS Administration Reference discusses possible reasons for this problem). When you assign the value NO, the Tape Coordinator proceeds as though there are more tapes and invokes the MOUNT script named in the device configuration file, or prompts the operator to insert the next tape. When you assign the value YES, it prompts to ask if there are more tapes to scan.

  • The Backup System determines that the tape contains an unexpired dump while running the backup labeltape command. When you assign the value NO, it terminates the operation without relabeling the tape. With a YES value, the Tape Coordinator prompts to ask if you want to relabel the tape anyway.

Eliminating the AFS Tape Name Check

If a tape does not have a permanent name and you are writing an initial dump to it, then by default the Backup System verifies that the tape's AFS tape name is acceptable. It accepts three types of values:

  • A name that reflects the volume set and dump level of the initial dump and the tape's place in the sequence of tapes for the dump set, as described in Dump Names and Tape Names. If the tape does not already have a permanent name, you can assign the AFS tape name by using the -name argument to the backup labeltape command.

  • A <NULL> value, which results when you assign a permanent name, or provide no value for the backup labeltape command's -name argument.

  • No AFS tape name at all, indicating that you have never labeled the tape or written a dump to it.

To bypass the name check, include the NAME_CHECK NO instruction in the device configuration file. This enables you to recycle a tape without first relabeling it, as long as all dumps on it are expired. (If a tape has unexpired dumps on it but you want to recycle it anyway, you must use the backup labeltape command to relabel it first. For this to work, the ASK NO instruction cannot appear in the device configuration file.)

Setting the Memory Buffer Size to Promote Tape Streaming

By default, the Tape Coordinator uses a 16-KB memory 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. Similarly, during a restore operation the Tape Coordinator by default buffers 32 KB of data from the tape device 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.

To determine if altering the buffer size is helpful for your configuration, observe the tape device in operation to see if it is streaming, or consult the manufacturer. To set the buffer size, include the BUFFERSIZE instruction in the device configuration file. It 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.

Dumping Data to a Backup Data File

You can write dumps to a backup data file rather than to tape. This is useful if, for example, you want to transfer the data to a data-archiving system, such as a hierarchical storage management (HSM) system, that you use in conjunction with AFS and the Backup System. You can restore data from a backup data file into the file system as well. Using a backup data file is usually more efficient than issuing the equivalent vos dump and vos restore commands individually for multiple volumes.

Writing to a backup data file is simplest if it is on the local disk of the Tape Coordinator machine, but you can also write the file to an NFS-mounted partition that resides on a remote machine. It is even acceptable to write to a file in AFS, provided that the access control list (ACL) on its parent directory grants the necessary permissions, but it is somewhat circular to back up AFS data into AFS itself.

If the backup data file does not already exist when the Tape Coordinator attempts to write a dump to it, the Tape Coordinator creates it. For a restore operation to succeed, the file must exist and contain volume data previously written to it during a backup dump 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.

Before writing to a backup data file, you need to configure the file as though it were a tape device.

Note

A file pathname, rather than a tape device name, must appear in the third field of the /usr/afs/backup/tapeconfig file when the FILE YES instruction appears in the device configuration file, and vice versa. If the tapeconfig file instead refers to a tape device, dump operations appear to succeed but are inoperative. You cannot restore data that you 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.

To configure a backup data file

  1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

       % bos listusers <machine name>
    
  2. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: <root_password>
    
  3. Optional. Issue the backup command to enter interactive mode.

       # backup
    
  4. Choose the port offset number to assign to the file. If necessary, display previously assigned port offsets by issuing the (backup) listhosts command, which is fully described in To display the list of configured Tape Coordinators.

       backup> listhosts
    

    As for a tape device, acceptable values are the integers 0 (zero) through 58510 (the Backup System can track a maximum of 58,511 port offset numbers). Each port offset must be unique in the cell, but you can associate any number them with a single Tape Coordinator machine. You do not have to assign port offset numbers sequentially.

  5. Issue the (backup) addhost command to register the backup data file's port offset in the Backup Database.

       backup> addhost <tape machine name> [<TC port offset>]
    

    where

    addh

    Is the shortest acceptable abbreviation of addhost.

    tape machine name

    Specifies the fully qualified hostname of the Tape Coordinator machine you invoke to write to the backup data file.

    TC port offset

    Specifies the file's port offset number. You must provide this argument unless the default value of 0 (zero) is appropriate.

  6. Using a text editor, create an entry for the backup data file in the local /usr/afs/backup/tapeconfig file, using the standard syntax:

       [capacity  filemark_size]  device_name   port_offset
    

    where

    capacity

    Specifies the amount of space on the partition that houses the backup data file that you want to make available for the file. To avoid the complications that arise from filling up the partition, it is best to provide a value somewhat smaller than the actual amount of space you expect to be available when the dump operation runs, and never larger than the maximum file size allowed by the operating system.

    Specify a numerical value followed by a letter that indicates units, with no intervening space. The letter k or K indicates kilobytes, m or M indicates megabytes, and g or G indicates gigabytes. If you omit the units letter, the default is kilobytes. If you leave this field empty, the Tape Coordinator uses the maximum acceptable value (2048 GB or 2 TB). Also leave the filemark_size field empty in that case.

    filemark_size

    Specify the value 0 (zero) or leave both this field and the capacity field empty. In the latter case, the Tape Coordinator also uses the value zero.

    device_name

    Specifies the complete pathname of the backup data file. Rather than specifying an actual file pathname, 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 provides these advantages:

    • It makes the device_name portion of the CFG_device_name, of the TE_device_name, and of the TL_device_name filenames as short as possible. Because the symbolic link is in the /dev directory as though it is a tape device, you strip off the entire /dev/ prefix when forming the filename, instead of just the initial slash (/). If, for example, the symbolic link is called /dev/FILE, the device configuration file's name is CFG_FILE, whereas if the actual pathname /var/tmp/FILE appears in the tapeconfig file, the configuration 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 (for example, because the partition housing the backup data file becomes full). The Tape Coordinator's reaction to this problem is to invoke the MOUNT script, or to prompt you if the MOUNT instruction does not appear in the configuration file.

      • If there is a MOUNT script, you can prepare for this situation by adding a subroutine to the script 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 you manually to change the symbolic link to point to another backup data file and then press <Return> to signal that the Tape Coordinator can continue the operation.

      If this field names the actual file, there is no way to recover from exhausting the space on the partition. You cannot change the tapeconfig file in the middle of an operation.

    port_offset

    Specifies the port offset number that you chose for the backup data file.

  7. Create the device configuration file CFG_device_name in the Tape Coordinator machine's /usr/afs/backup directory. Include the FILE YES instruction in the file.

    Construct the device_name portion of the name based on the device name you recorded in the tapeconfig file in Step 6. If, as recommended, you recorded a symbolic link name, strip off the /dev/ string and replace any other slashes (/) in the name with underscores (_). For example, CFG_FILE is the appropriate name if the symbolic link is /dev/FILE. If you recorded the name of an actual file, then strip off the initial slash only and replace any other slashes in the name with underscores. For a backup data file called /var/tmp/FILE, the appropriate device configuration filename is CFG_var_tmp_FILE.

  8. If you chose in Step 6 to record a symbolic link name in the device_name field of the tapeconfig entry, then you must do one of the following:

    • Use the ln -s command to create the appropriate symbolic link in the /dev directory

    • Write a script that initializes the backup data file in this way, and include a MOUNT instruction in the device configuration file to invoke the script. An example script appears following these instructions.

You do not need to create the backup data file itself, because the Tape Coordinator does so if the file does not exist when the dump operation begins.

The following example script illustrates how you can automatically create a symbolic link to the backup data file during the preparation phase for writing to the file. 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 values of the tapename and tapeid parameters passed to it by the Backup System when constructing the filename.

The routine makes use of two other parameters as well: tries and operation. 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.

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