Administration Guide

Backing Up and Restoring AFS Data

The instructions in this chapter explain how to back up and restore AFS data and to administer the Backup Database. They assume that you have already configured all of the Backup System components by following the instructions in Configuring the AFS Backup System.

Summary of Instructions

This chapter explains how to perform the following tasks by using the indicated commands:

Using the Backup System's Interfaces

When performing backup operations, you interact with three Backup System components:

• You initiate backup operations by issuing commands from the backup suite. You can issue the commands in a command shell (or invoke them in a shell script) on any AFS client or server machine from which you can access the backup binary. In the conventional configuration, the binary resides in the /usr/afs/bin directory on a server machine and the /usr/afsws/etc directory on a client machine.

  The suite provides an interactive mode, in which you can issue multiple commands over a persistent connection to the Backup Server and the Volume Location (VL) Server. Interactive mode has several convenient features. For a discussion and instructions, see Using Interactive and Regular Command Mode.

  Note that some operating systems include a backup command of their own. You must configure machines that run such an operating system to ensure that you are accessing the desired backup binary.

• Before you perform a backup operation that involves reading or writing to a tape device or backup data file, you must open a dedicated connection to the appropriate Tape Coordinator machine and start the Tape Coordinator (butc) process that handles the device or file. The butc process must continue to run over the dedicated connection as long as it is executing an operation or is to be available to execute one. For further discussion and instructions, see Starting and Stopping the Tape Coordinator Process.

• The Backup Server (buserver) process must be running on database server machines, because most backup operations require accessing or changing information in the Backup Database. The IBM AFS Quick Beginnings explains how to configure the Backup Server.

For consistent Backup System performance, the AFS build level of all three binaries (backup, butc, and buserver) must match. For instructions on displaying the build level, see Displaying A Binary File's Build Level.

Performing Backup Operations as the Local Superuser Root or in a Foreign Cell

By default, the volumes and Backup Database involved in a backup operation must reside on server machines that belong to the cell named in the /usr/vice/etc/ThisCell files on both the Tape Coordinator machine and the machine where you issue the backup command. Also, to issue most backup commands you must have AFS tokens for an identity listed in the local cell's /usr/afs/etc/UserList file (which by convention is the same on every server machine in a cell). You can, however, perform backup operations on volumes or the Backup Database from a foreign cell, or perform backup operations while logged in as the local superuser root rather than as a privileged AFS identity.

To perform backup operations on volumes that reside in a foreign cell using machines from the local cell, you must designate the foreign cell as the cell of execution for both the Tape Coordinator and the backup command interpreter. Use one of the two following methods. For either method, you must also have tokens as an administrator listed in the foreign cell's /usr/afs/etc/UserList file.

• Before issuing backup commands and the butc command, set the AFSCELL environment variable to the foreign cell name in both command shells.

• Include the -cell argument to the butc and all backup commands. If you include the argument on the backup (interactive) command, it applies to all commands issued during the interactive session.

To perform backup operations without having administrative AFS tokens, you must log on as the local superuser root on both the Tape Coordinator machine and the machine where you issue backup commands. Both machines must be server machines, or at least have a /usr/afs/etc/KeyFile file that matches the file on other server machines. Then include the -localauth argument on both the butc command and all backup commands (or the backup (interactive) command). The Tape Coordinator and backup command interpreter construct a server ticket using the server encryption key with the highest key version number in the local /usr/afs/etc/KeyFile file, and present it to the Backup Server, Volume Server, and VL Server that belong to the cell named in the local /usr/afs/etc/ThisCell file. The ticket never expires.

You cannot combine the -cell and -localauth options on the same command. Also, each one overrides the local cell setting defined by the AFSCELL environment variable or the /usr/vice/etc/ThisCell file.

Using Interactive and Regular Command Mode

The backup command suite provides an interactive mode, in which you can issue multiple commands over a persistent connection to the Backup Server and the VL Server. Interactive mode provides the following features:

• The backup> prompt replaces the usual command shell prompt.

• You omit the initial backup string from command names. Type only the operation code and option names.

• You cannot issue commands that do not belong to the backup suite.

• If you assume an administrative AFS identity or specify a foreign cell as you enter interactive mode, it applies to all commands issued during the interactive session. See Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.

• You do not need to enclose shell metacharacters in double quotes.

When you initiate a backup operation in interactive mode, the Backup System assigns it a job ID number. You can display the list of current and pending operations with the (backup) jobs command, for which instructions appear in To display pending or running jobs in interactive mode. (In both regular and interactive modes, the Tape Coordinator also assigns a task ID number to each operation you initiate with a backup command. You can track task ID numbers with the backup status command. See Starting and Stopping the Tape Coordinator Process.)

You can cancel an operation in interactive mode with the (backup) kill command, for which instructions appear in To cancel operations in interactive mode. However, it is best not to interrupt a dump operation because the resulting dump is incomplete, and interrupting a restore operation can leave volumes in an inconsistent state, or even completely remove them from the server machine. For further discussion, see Backing Up Data and Restoring and Recovering Data.

The (backup) jobs and (backup) kill commands are available only in interactive mode and there is no equivalent functionality in regular command mode.

To enter interactive mode

1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. Entering interactive mode does not itself require privilege, but most other backup commands do, and the AFS identity you assume when entering the mode applies to all commands you issue within it. 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. Issue the backup (interactive) command at the system prompt. The backup> prompt appears. You can include either, but not both, of the -localauth and -cell options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.

      % backup
      backup>
   

To exit interactive mode

1. Issue the quit command at the backup> prompt. The command shell prompt reappears when the command succeeds, which it does only if there are no jobs pending or currently running. To display and cancel pending or running jobs, follow the instructions in To display pending or running jobs in interactive mode and To cancel operations in interactive mode.

      backup> quit
      %
   

To display pending or running jobs in interactive mode

1. Issue the jobs command at the backup> prompt.

      backup> jobs
   

   where

   j

   Is the shortest acceptable abbreviation of jobs.

The output always includes the expiration date and time of the tokens that the backup command interpreter is using during the current interactive session, in the following format:

   date   time: TOKEN EXPIRATION

If the execution date and time specified for a scheduled dump operation is later than date time, then its individual line (as described in the following paragraphs) appears below this line to indicate that the current tokens will not be available to it.

If the issuer of the backup command included the -localauth flag when entering interactive mode, the line instead reads as follows:

   :  TOKEN NEVER EXPIRES

The entry for a scheduled dump operation has the following format:

   Job job_ID:  timestamp:  dump  volume_set  dump_level

where

job_ID

Is a job identification number assigned by the Backup System.

timestamp

Indicates the date and time the dump operation is to begin, in the format month/date/year hours:minutes (in 24-hour format)

volume_set

Indicates the volume set to dump.

dump_level

Indicates the dump level at which to perform the dump operation.

The line for a pending or running operation of any other type has the following format:

   Job job_ID:  operation  status

where

job_ID

Is a job identification number assigned by the Backup System.

operation

Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:

Dump (dump name)

Initiated by the backup dump command. The dump name has the following format:

volume_set_name.dump_level_name

Restore

Initiated by the backup diskrestore, backup volrestore, or backup volsetrestore command.

Labeltape (tape_label)

Initiated by the backup labeltape command. The tape_label is the name specified by the backup labeltape command's -name or -pname argument.

Scantape

Initiated by the backup scantape command.

SaveDb

Initiated by the backup savedb command.

RestoreDb

Initiated by the backup restoredb command.

status

Indicates the job's current status in one of the following messages. If no message appears, the job is either still pending or has finished.

number Kbytes, volume volume_name

For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so far, and the volume currently being dumped.

number Kbytes, restore.volume

For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a backup data file so far.

[abort requested]

The (backup) kill command was issued, but the termination signal has yet to reach the Tape Coordinator.

[abort sent]

The operation is canceled by the (backup) kill command. Once the Backup System removes an operation from the queue or stops it from running, it no longer appears at all in the output from the command.

[butc contact lost]

The backup command interpreter cannot reach the Tape Coordinator. The message can mean either that the Tape Coordinator handling the operation was terminated or failed while the operation was running, or that the connection to the Tape Coordinator timed out.

[done]

The Tape Coordinator has finished the operation.

[drive wait]

The operation is waiting for the specified tape drive to become free.

[operator wait]

The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.

To cancel operations in interactive mode

1. Issue the jobs command at the backup> prompt, to learn the job ID number of the operation you want to cancel. For details, see To display pending or running jobs in interactive mode.

      backup> jobs
   

2. Issue the (backup) kill command to cancel the operation.

      backup> kill <job ID or dump set name>
   

   where

   k

   Is the shortest acceptable abbreviation of kill.

   job ID or dump set name

   Specifies either the job ID number of the operation to cancel, as reported by the jobs command, or for a dump operation only, the dump name in the format volume_set_name.dump_level_name.

Starting and Stopping the Tape Coordinator Process

Before performing a backup operation that reads from or writes to a tape device or backup data file, you must start the Tape Coordinator (butc) process that handles the drive or file. This section explains how to start, stop, and check the status of a Tape Coordinator process. To use these instructions, you must have already configured the Tape Coordinator machine and created a Tape Coordinator entry in the Backup Database, as instructed in Configuring Tape Coordinator Machines and Tape Devices.

The Tape Coordinator assigns a task ID number to each operation it performs. The number is distinct from the job ID number assigned by the backup command interpreter in interactive mode (which is discussed in Using Interactive and Regular Command Mode). The Tape Coordinator reports the task ID number in its onscreen trace and in the messages that it writes to its log and error files. To view the task ID numbers of a Tape Coordinator's running or pending operations, issue the backup status command.

To start a Tape Coordinator process

1. Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file of the cell in which the Tape Coordinator is to access volume data and the Backup Database. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

      % bos listusers <machine name>
   

   Alternately, you can log into a file server machine as the local superuser root in Step 3.

2. Verify that you can write to the Tape Coordinator's log and error files in the local /usr/afs/backup directory (the TE_device_name and TL_device_name files). If the log and error files do not already exist, you must be able to insert and write to files in the /usr/afs/backup directory.

3. Open a connection (using a command such as telnet or rlogin) to the Tape Coordinator machine that drives the tape device, or whose local disk houses the backup data file. The Tape Coordinator uses a devoted connection or window that must remain open for the Tape Coordinator to accept requests and while it is executing them.

   If you plan to include the -localauth flag to the butc command in the next step, log in as the local superuser root.

4. Issue the butc command to start the Tape Coordinator. You can include either, but not both, of the -localauth and -cell options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.

      % butc [<port offset>]  [-debuglevel <trace level>]  \
             [-cell <cellname>] [-noautoquery] [-localauth]
   

   where

   butc

   Must be typed in full.

   port offset

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

   -debuglevel

   Specifies the type of trace messages that the Tape Coordinator writes to the standard output stream (stdout). Provide one of the following three values, or omit this argument to display the default type of messages (equivalent to setting a value of 0 [zero]):

   • 0: The Tape Coordinator generates only the minimum number of messages necessary to communicate with the backup operator, including prompts for insertion of additional tapes and messages that indicate errors or the beginning or completion of operations.

   • 1: In addition to the messages displayed at level 0, the Tape Coordinator displays the name of each volume being dumped or restored.

   • 2: In addition to the messages displayed at levels 0 and 1, the Tape Coordinator displays all of the messages it is also writing to its log file (/usr/afs/backup/TL_device_name).

   cellname

   Names the cell in which to perform the backup operations (the cell where the relevant volumes reside and the Backup Server process is running). If you omit this argument, the Tape Coordinator uses its home cell, as defined in the local /usr/vice/etc/ThisCell file. Do not combine this argument with the -localauth flag.

   -noautoquery

   Disables the Tape Coordinator's prompt for the first tape it needs for each operation. For a description of the advantages and consequences of including this flag, see Eliminating the Search or Prompt for the Initial Tape.

   -localauth

   Constructs a server ticket using a key from the local /usr/afs/etc/KeyFile file. The butc process presents it to the Backup Server, Volume Server, and VL Server during mutual authentication. You must be logged into a file server machine as the local superuser root to include this flag, and cannot combine it with the -cell argument.

To stop a Tape Coordinator process

1. Enter an interrupt signal such as <Ctrl-c> over the dedicated connection to the Tape Coordinator.

To check the status of a Tape Coordinator process

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. Issue the backup status command.

      % backup status [<TC port offset>]
   

   where

   st

   Is the shortest acceptable abbreviation of status.

   TC port offset

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

The following message indicates that the Tape Coordinator is not currently performing an operation:

   Tape coordinator is idle

Otherwise, the output includes a message of the following format for each running or pending operation:

   Task task_ID:  operation:   status

where

task_ID

Is a task identification number assigned by the Tape Coordinator. It begins with the Tape Coordinator's port offset number.

operation

Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:

• Dump (the backup dump command)

• Restore (the backup diskrestore, backup volrestore, or backup volsetrestore commands)

• Labeltape (the backup labeltape command)

• Scantape (the backup scantape command)

• SaveDb (the backup savedb command)

• RestoreDb (the backup restoredb command)

status

Indicates the job's current status in one of the following messages.

number Kbytes transferred, volume volume_name

For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so far, and the volume currently being dumped.

number Kbytes, restore.volume

For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a backup data file so far.

[abort requested]

The (backup) kill command was issued, but the termination signal has yet to reach the Tape Coordinator.

[abort sent]

The operation is canceled by the (backup) kill command. Once the Backup System removes an operation from the queue or stops it from running, it no longer appears at all in the output from the command.

[butc contact lost]

The backup command interpreter cannot reach the Tape Coordinator. The message can mean either that the Tape Coordinator handling the operation was terminated or failed while the operation was running, or that the connection to the Tape Coordinator timed out.

[done]

The Tape Coordinator has finished the operation.

[drive wait]

The operation is waiting for the specified tape drive to become free.

[operator wait]

The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.

If the Tape Coordinator is communicating with an XBSA server (a third-party backup utility that implements the Open Group's Backup Service API [XBSA]), the following message appears last in the output:

   XBSA_program Tape coordinator

where XBSA_program is the name of the XBSA-compliant program.

Backing Up Data

This section explains how to use the backup dump command to back up AFS data to tape or to a backup data file. The instructions assume that you understand Backup System concepts and have already configured the Backup System according to the instructions in Configuring the AFS Backup System. Specifically, you must already have:

• Decided whether to dump data to tape or to a backup data file, and configured the Tape Coordinator machine and Tape Coordinator process appropriately. See Configuring Tape Coordinator Machines and Tape Devices and Dumping Data to a Backup Data File.

• Defined a volume set that includes the volumes you want to dump together. See Defining and Displaying Volume Sets and Volume Entries.

• Defined the dump level in the dump hierarchy at which you want to dump the volume set. If it is an incremental dump level, you must have previously created a dump at its parent level. See Defining and Displaying the Dump Hierarchy.

• Created a device configuration file. Such a file is required for each tape stacker, jukebox device, or backup data file. You can also use it to configure the Backup System's automation features. See Automating and Increasing the Efficiency of the Backup Process.

The most basic way to perform a dump operation is to create an initial dump of a single volume set as soon as the appropriate Tape Coordinator is available, by providing only the required arguments to the backup dump command. Instructions appear in To create a dump. The command has several optional arguments that you can use to increase the efficiency and flexibility of your backup procedures:

• To append a dump to the end of a set of tapes that already contains other dumps, include the -append argument. Otherwise, the Backup System creates an initial dump. Appending dumps enables you to use a tape's full capacity and has other potentially useful features. For a discussion, see Appending Dumps to an Existing Dump Set.

• To schedule one or more dump operations to run at a future time, include the -at argument. For a discussion and instructions, see Scheduling Dumps.

• To initiate a number of dump operations with a single backup dump command, include the -file argument to name a file in which you have listed the commands. For a discussion and instructions, see Appending Dumps to an Existing Dump Set and Scheduling Dumps.

• To generate a list of the volumes to be included in a dump, without actually dumping them, combine the -n flag with the other arguments to be used on the actual command.

Making Backup Operations More Efficient

There are several ways to make dump operations more efficient, less prone to error, and less disruptive to your users. Several of them also simplify the process of restoring data if that becomes necessary.

• It is best not to dump the read/write or read-only version of a volume, because no other users or processes can access a volume while it is being dumped. Instead, shortly before the dump operation begins, create a backup version of each volume to be dumped, and dump the backup version. Creating a Backup version usually makes the source volume unavailable for just a few moments (during which access attempts by other processes are blocked but do not fail). To automate the creation of backup volumes, you can create a cron process in the /usr/afs/local/BosConfig file on one or more server machines, setting its start time at a sufficient interval before the dump operation is to begin. Include the -localauth argument to the vos backup or vos backupsys command to enable it to run without administrative tokens. For instructions, see To create and start a new process.

• The volume set, dump level, and Tape Coordinator port offset you specify on the backup dump command line must be properly defined in the Backup Database. The Backup System checks the database before beginning a dump operation and halts the command immediately if any of the required entities are missing. If necessary, use the indicated commands:

  • To display volume sets, use the backup listvolsets command as described in To display volume sets and volume entries.

  • To display dump levels, use the backup listdumps command as described in To display the dump hierarchy.

  • To display port offsets, use the backup listhosts command as described in To display the list of configured Tape Coordinators.

• Ensure that a valid token corresponding to a privileged administrative identity is available to the Backup System processes both when the backup dump command is issued and when the dump operation actually runs (for a complete description or the necessary privileges, see Granting Administrative Privilege to Backup Operators). This is a special concern for scheduled dumps. One alternative is to run backup commands (or the script that invokes them) and the butc command on server machines, and to include the -localauth argument on the command. In this case, the processes use the key with the highest key version number in the local /usr/afs/etc/KeyFile file to construct a token that never expires. Otherwise, you must use a method to renew tokens before they expire, or grant tokens with long lifetimes. In either case, you must protect against improper access to the tokens by securing the machines both physically and against unauthorized network access. The protection possibly needs to be even stronger than when a human operator is present during the operations.

• Record tape capacity and filemark size values that are as accurate as possible in the Tape Coordinator's /usr/afs/backup/tapeconfig file and on the tape's label. For suggested values and a description of what can happen when they are inaccurate, see Configuring the tapeconfig File.

• If an unattended dump requires multiple tapes, arrange to provide them by properly configuring a tape stacker or jukebox and writing a tape-mounting script to be invoked in the device's CFG_device_name file. For instructions, see Invoking a Device's Tape Mounting and Unmounting Routines.

• You can configure any tape device or backup data file's CFG_device_name file to take advantage of the Backup System's automation features. See Automating and Increasing the Efficiency of the Backup Process.

• When you issue a backup command in regular (noninteractive) mode, the command shell prompt does not return until the operation completes. To avoid having to open additional connections, issue the backup dump command in interactive mode, especially when including the -at argument to schedule dump operations.

• An incremental dump proceeds most smoothly if there is a dump created at the dump level immediately above the level you are using. If the Backup System does not find a Backup Database record for a dump created at the immediate parent level, it looks for a dump created at one level higher in the hierarchy, continuing up to the full dump level if necessary. It creates an incremental dump at the level one below the lowest valid parent dump that it finds, or even creates a full dump if that is necessary. This algorithm guarantees that the dump captures all data that has changed since the last dump, but has a couple of disadvantages. First, the Backup System's search through the database for a valid parent dump takes extra time. Second, the subsequent pattern of dumps can be confusing to a human operator who needs to restore data from them, because they were not performed at the expected dump levels.

  The easiest way to guarantee that a dump exists at the immediate parent level is always to perform dump operations on the predetermined schedule. To check that the parent dump exists, you can issue the backup dumpinfo command (as described in To display dump records) and search for it in the output. Alternatively, issue the backup volinfo command (as described in To display a volume's dump history) for a volume that you believe is in the parent dump.

• Always use dump levels from the same hierarchy (levels that are descendants of the same full level) when dumping a given volume set. The result of alternating between levels from different hierarchies can be confusing when you need to restore data or read dump records. It also increases the chance that changed data is not captured in any dump, or is backed up redundantly into more than one dump.

• Use permanent tape names rather than AFS tape names. You can make permanent names more descriptive than is allowed by an AFS tape name's strict format, and also bypass the name-checking step that the Backup System performs by default when a tape has an AFS tape name only. You can also configure the Tape Coordinator always to skip the check, however; for instructions and a description of the acceptable format for AFS tape names, see Eliminating the AFS Tape Name Check.

• If you write dumps to tape, restore operations are simplest if all of your tape devices are compatible (can read the same type of tape, at the same compression ratios, and so on). If you must use incompatible devices, then at least use compatible devices for all dumps performed at dump levels that are at the same depth in their respective hierarchies (compatible devices for all dumps performed at a full dump level, compatible devices for all dumps performed at a level 1 incremental dump level, and so on). The -portoffset argument to the backup diskrestore and backup volsetrestore commands accepts multiple port offset numbers, but uses the first listed port offset when restoring all full dumps, the second port offset when restoring all level 1 dumps, and so on. If you did not use compatible tape devices when creating dumps at the same depth in a hierarchy, you must restore one volume at a time with the backup volrestore command.

• In some cases, it makes sense to use a temporary volume set, which exists only within the context of the interactive session in which it is created and for which no record is created in the Backup Database. One suitable situation is when dumping a volume to tape in preparation for removing it permanently (perhaps because its owner is leaving the cell). In this case, you can define a volume entry that includes only the volume of interest without cluttering up the Backup Database with a volume set record that you are using only once.

• Do not perform a dump operation when you know that there are network, machine, or server process problems that can prevent the Backup System from accessing volumes or the Volume Location Database (VLDB). Although the Backup System automatically makes a number of repeated attempts to get to an inaccessible volume, the dump operation takes extra time and in some cases stops completely to prompt you for instructions on how to continue. Furthermore, if the Backup System's last access attempt fails and the volume is omitted from the dump, you must take extra steps to have it backed up (namely, the steps described just following for a halted dump operation). For a more complete description of how the Backup System makes repeated access attempts, see How Your Configuration Choices Influence the Dump Process.

• Review the logs created by the Backup System as soon as possible after a dump operation completes, particularly if it ran unattended. They name any volumes that were not successfully backed up, among other problems. The Backup Server writes to the /usr/afs/logs/BackupLog file on the local disk of the database server machine, and you can use the bos getlog command to read it remotely if you wish; for instructions, see Displaying Server Process Log Files. The Tape Coordinator writes to two files in the local /usr/afs/backup directory on the machine where it is running: the TE_device_name file records errors, and the TL_device_name file records both trace and error messages.

• Avoid halting a dump operation (for instance, by issuing the (backup) kill command in interactive mode), both because it introduces the potential for confusion and because recovering from the interruption requires extra effort. When a dump operation is interrupted, the volumes that were backed up before the halt signal is received are complete on the tape or in the backup data file, and are usable in restore operations. The records in the Backup Database about the volumes' dump history accurately show when and at which dump level they were backed up; to display the records, use the backup volinfo command as described in To display a volume's dump history.

  However, there is no indication in the dump's Backup Database record that volumes were omitted; to display the record, use the backup dumpinfo command as described in To display dump records. You must choose one of the following methods for dealing with the volumes that were not backed up before the dump operation halted. (Actually, you must make the same decision if the dump operation halts for reasons outside your control.)

  • You can take no action, waiting until the next regularly scheduled dump operation to back them up. At that time, the Backup System automatically dumps them at the appropriate level to guarantee that the dump captures all of the data that changed since the volume was last dumped. However, you are gambling that restoring the volume is not necessary before the next dump operation. If restoration is necessary, you can restore the volume only to its state at the time it was last included in a dump--you have lost all changes made to the volume since that time.

  • You can discard the entire dump and run the dump operation again. To discard the dump, use the backup labeltape command to relabel the tapes or backup data file, which automatically removes all associated records from the Backup Database. For instructions, see Writing and Reading Tape Labels. If a long time has passed since the backup version of the volumes was created, some of the source volumes have possibly changed. If that seems likely, reissue the vos backup or vos backupsys command on them before redoing the dump operation.

  • You can create a new volume set that includes the missed volumes and dump it at a full dump level (even if you specify an incremental dump level, the Backup System uses the full dump level at the top of your specified level's hierarchy, because it has never before backed up these volumes as part of the new volume set). The next time you dump the original volume set, the Backup System automatically dumps the missed volumes at the level one below the level it used the last time it dumped the volumes as part of the original volume set.

How Your Configuration Choices Influence the Dump Process

This section provides an overview of the backup process, describing what happens at each stage both by default and as a result of your configuration choices, including the configuration instructions you include in the device-specific CFG_device_name file. For the sake of clarity, it tracks the progress of a single backup dump command that creates an initial dump. For a discussion of the slight differences in the procedure when you append or schedule dumps, see Appending Dumps to an Existing Dump Set or Scheduling Dumps.

As a concrete example, the following description traces a dump of the volume set user at the /weekly/mon/tues/wed dump level. The user volume set has one volume entry that matches the backup version of all user volumes:

   .*    .*    user.*\.backup

The dump level belongs to the following dump hierarchy.

   /weekly
          /mon
              /tues
                   /wed
                       /thurs
                             /fri

1. You issue the butc command to start a Tape Coordinator to handle the dump operation. The Tape Coordinator does not have to be running when you issue the backup dump command, but must be active in time to accept the list of volumes to be included in the dump, when Step 3 is completed. To avoid coordination problems, it is best to start the Tape Coordinator before issuing the backup dump command.

   As the Tape Coordinator initializes, it reads the entry in its local /usr/afs/backup/tapeconfig file for the port offset you specify on the butc command line. The entry specifies the name of the device to use, and the Tape Coordinator verifies that it can access it. It also reads the device's configuration file, /usr/afs/backup/CFG_device_name, if it exists. See Step 6 for a description of how the instructions in the file influence the dump operation.

2. You issue the backup dump command, specifying a volume set, dump level, and the same port offset number you specified on the butc command in Step 1. The Backup System verifies that they have correct Backup Database records and halts the operation with an error message if they do not.

   If you issue the command in interactive mode, the Backup System assigns the operation a job ID number, which you can use to check the operation's status or halt it by using the (backup) jobs or (backup) kill command, respectively. For instructions, see To display pending or running jobs in interactive mode and To cancel operations in interactive mode.

3. The Backup System works with the VL Server to generate a list of the volumes in the VLDB that match the name and location criteria defined in the volume set's volume entries. If a volume matches more than one volume entry, the Backup System ignores the duplicates so that the dump includes only one copy of data from the volume.

   To reduce the number of times you need to switch tapes during a restore operation, the Backup System sorts the volumes by server machine and partition, and during the dump operation writes the data from all volumes stored on a specific partition before moving to the next partition.

   As previously mentioned, it is best to back up backup volumes rather than read/write volumes, to avoid blocking users' access to data during the dump. To achieve this, you must explicitly include the .backup suffix on the volume names in volume entry definitions. For instructions, and to learn how to define volume entries that match multiple volumes, see Defining and Displaying Volume Sets and Volume Entries.

   In the example, suppose that 50 volumes match the user volume set criteria, including three called user.pat.backup, user.terry.backup, and user.smith.backup.

4. The Backup System next scans the dump hierarchy for the dump level you have specified on the backup dump command line. If it is a full level, then in the current operation the Backup System backs up all of the data in all of the volumes in the list obtained in Step 3.

   If the dump level is incremental, the Backup System reads each volume's dump history in the Backup Database to learn which of the parent levels in its pathname was used when the volume was most recently backed up as part of this volume set. In the usual case, it is the current dump level's immediate parent level.

   An incremental dump of a volume includes only the data that changed since the volume was included in the parent dump. To determine which data are eligible, the Backup System uses the concept of a volume's clone date. A read/write volume's clone date is when the Backup System locks the volume before copying its contents into a dump. A backup volume's clone date is the completion time of the operation that created it by cloning its read/write source volume (the operation initiated by a vos backup or vos backupsys command). A read-only volume's clone date is the time of the release operation (initiated by the vos release command) that completed most recently before the dump operation.

   More precisely then, an incremental dump includes only data that have a modification timestamp between the clone date of the volume included in the parent dump (the parent clone date) and the clone date of the volume to be included in the current dump (the current clone date).

   There are some common exceptions to the general rule that a volume's parent dump is the dump created at the immediate parent level:

   • The volume did not exist at all at the time of the last dump. In this case, the Backup System automatically does a full dump of it.

   • The volume did not match the volume set's name and location criteria at the time of the last dump. In this case, the Backup System automatically does a full dump of it, even if it was backed up recently (fully or incrementally) as part of another volume set. This redundancy is an argument for defining volume entries in terms of names rather than locations, particularly if you move volumes frequently.

   • The volume was not included in the dump at the immediate parent level for some reason (perhaps a process, machine, or network access prevented the Backup System from accessing it). In this case, the Backup System sets the clone date to the time of the last dump operation that included the volume. If the volume was not included in a dump performed at any of the levels in the current level's pathname, the Backup System does a full dump of it.

   In the example, the current dump level is /weekly/mon/tues/wed. The user.pat.backup and user.terry.backup volumes were included in the dump performed yesterday, Tuesday, at the /weekly/mon/tues level. The Backup System uses as their parent clone date 3:00 a.m. on Tuesday, which is when backup versions of them were created just before Tuesday's dump operation. However, Tuesday's dump did not include the user.smith.backup volume for some reason. The last time it was included in a dump was Monday, at the /weekly/mon level. The Backup System uses a parent clone date of Monday at 2:47 a.m., which is when a backup version of the volume was created just before the dump operation on Monday.

5. If performing an incremental dump, the Backup System works with the Volume Server to prepare a list of all of the files in each volume that have changed (have modification timestamps) between the parent clone date and the current clone date. The dump includes the complete contents of every such file. If a file has not changed, the dump includes only a placeholder stub for it. The dump also includes a copy of the complete directory structure in the volume, whether or not it has changed since the previous dump.

   If none of the data in the volume has changed since the last dump, the Backup System omits the volume completely. It generates the following message in the Tape Coordinator window and log files:

      Volume volume_name (volume_ID) not dumped - has not been modified 
         since last dump.
   

6. The Tape Coordinator prepares to back up the data. If there is a CFG_device_name file, the Tape Coordinator already read it in Step 1. The following list describes how the instructions in the file guide the Tape Coordinator's behavior at this point:

   FILE

   If this instruction is set to YES, the Tape Coordinator writes data to a backup data file. The device_name field in the tapeconfig file must also specify a filename for the dump to work properly. For further discussion and instructions on configuring a backup data file, see Dumping Data to a Backup Data File.

   If it is set to NO or does not appear in the file, the Tape Coordinator writes to a tape device.

   MOUNT and UNMOUNT

   If there is a MOUNT instruction in the file, each time the Tape Coordinator needs a new tape, it invokes the indicated script or program to mount a tape in the device's tape drive. There must be a MOUNT instruction if you want to utilize a tape stacker or jukebox's ability to switch between tapes automatically. If there is no MOUNT instruction, the Tape Coordinator prompts the human operator whenever it needs a tape.

   The AUTOQUERY instruction, which is described just following, modifies the Tape Coordinator's tape acquisition procedure for the first tape it needs in a dump operation.

   If there is an UNMOUNT instruction, then the Tape Coordinator invokes the indicated script or program whenever it closes the tape device. Not all tape devices have a separate tape unmounting routine, in which case the UNMOUNT instruction is not necessary. For more details on both instructions, see Invoking a Device's Tape Mounting and Unmounting Routines.

   AUTOQUERY

   If this instruction is set to NO, the Tape Coordinator assumes that the first tape needed for the dump operation is already in the tape drive. It does not use its usual tape acquisition procedure as described in the preceding discussion of the MOUNT instruction. You can achieve the same effect by including the -noautoquery flag to the butc command.

   If this instruction is absent or set to YES, the Tape Coordinator uses its usual tape acquisition procedure even for the first tape. For more details, see Eliminating the Search or Prompt for the Initial Tape.

   BUFFERSIZE

   If this instruction appears in the file, the Tape Coordinator sets its buffer size to the specified value rather than using the default buffer size of 16 KB. For further discussion, see Setting the Memory Buffer Size to Promote Tape Streaming.

   If there is no CFG_device_name file, the Tape Coordinator writes data to a tape device and prompts the human operator each time it needs a tape (the only exception being the first tape if you include the -noautoquery flag to the butc command).

7. The Tape Coordinator opens either a tape drive or backup data file at this point, as directed by the instructions in the CFG_device_name file (described in Step 6). The instructions also determine whether it invokes a mount script or prompts the operator. In Step 1 the Tape Coordinator read in the device's capacity and filemark size from the tapeconfig file. It now reads the same values from the tape or backup data file's magnetic label, and overwrites the tapeconfig values if there is a difference.

   If creating an initial dump (as in the current example) and there is no permanent name on the label, the Tape Coordinator next checks that the AFS tape name has one of the three acceptable formats. If not, it rejects the tape and you must use the backup labeltape command to write an acceptable name. You can bypass this name-checking step by including the NAME_CHECK NO instruction in the CFG_device_name file. For discussion and a list of the acceptable AFS tape name values, see Eliminating the AFS Tape Name Check.

8. For an initial dump, the Tape Coordinator starts writing at the beginning of the tape or backup dump file, overwriting any existing data. To prevent inappropriate overwriting, the Backup System first checks the Backup Database for any dump records associated with the name (permanent or AFS tape name) on the tape or backup dump file's label. It refuses to write to a backup data file that has unexpired dumps in it, or to a tape that belongs to a dump set with any unexpired dumps. To recycle a file or tape before all dumps have expired, you must use the backup labeltape command to relabel it. Doing so removes the Backup Database records of all dumps in the file or on all tapes in the dump set, which makes it impossible to restore data from any of the tapes. For more information on expiration dates, see Defining Expiration Dates.

   The Tape Coordinator also checks for two other types of inappropriate tape reuse. The tape cannot already have data on it that belongs to the dump currently being performed, because that implies that the previous tape is still in the drive, or you have mistakenly reinserted it. The Tape Coordinator generates the following message and attempts to obtain another tape:

      Can't overwrite tape containing the dump in progress
   

   The tape cannot contain data from a parent dump of the current (incremental) dump, because overwriting a parent dump makes it impossible to restore data from the current dump. The Tape Coordinator generates the following message and attempts to obtain another tape:

      Can't overwrite the parent dump parent_name (parent_dump_ID)
   

9. The Tape Coordinator now writes data to the tape or backup data file. It uses the capacity and filemark size it obtained in Step 7 as it tracks how much more space is available, automatically using its tape acquisition procedure if the dump is not finished when it reaches the end of the tape. For a more detailed description, and a discussion of what happens if the Tape Coordinator reaches the physical end-of-tape unexpectedly, see Configuring the tapeconfig File. Similarly, for instructions on configuring a backup data file to optimize recovery from unexpectedly running out of space, see Step 6 in the instructions in Dumping Data to a Backup Data File.

   If the Tape Coordinator cannot access a volume during the dump (perhaps because of a server process, machine, or network outage), it skips the volume and continues dumping all volumes that it can access. It generates an error message in the Tape Coordinator window and log file about the omitted volume. It generates a similar message if it discovers that a backup volume has not been recloned since the previous dump operation (that is, that the volume's current clone date is the same as its parent clone date):

      Volume volume_name (volume_ID) not dumped - has not been re-cloned 
          since last dump.
   

   After completing a first pass through all of the volumes, it attempts to dump each omitted volume again. It first checks to see if the reason that the volume was inaccessible during the first pass is that it has been moved since the VL Server generated the list of volumes to dump in Step 3. If so, it dumps the volume from its new site. If the second attempt to access a volume also fails, the Tape Coordinator it generates the following message, prompting you for instruction on how to proceed:

      Dump of volume volume_name (volume_ID) failed
      Please select action to be taken for this volume.
         r - retry, try dumping this volume again
         o - omit, this volume from this dump
         a - abort, the entire dump
   

   To increase the automation of the dump process, you can include the ASK NO instruction in the CFG_device_name file to suppress this prompt and have the Tape Coordinator automatically omit the volume from the dump.

   If you are tracking the dump as it happens, the prompt enables you to take corrective action. If the volume has not been recloned, you can issue the vos backup command. If the volume is inaccessible, you can investigate and attempt to resolve the cause.

10. If the tape or backup data file does not already have an AFS tape name, the Backup System constructs the appropriate one and records it on the label and in the Backup Database. It also assigns a dump name and ID number to the dump and records them in dump record that it creates in the Backup Database. For details on tape and dump names, see Dump Names and Tape Names. For instructions on displaying dump records or a volume's dump history, or scanning the contents of a tape, see Displaying Backup Dump Records.

Appending Dumps to an Existing Dump Set

The AFS Backup System enables you to append dumps to the end of the final tape in a dump set by including the -append flag to the backup dump command. Appending dumps improves Backup System automation and efficiency in several ways:

• It maximizes use of a tape's capacity. An initial dump must always start on a new tape, but does not necessarily extend to the end of the final tape in the dump set. You can fill up the unused tape by appending one or more dumps.

• It can reduce the number of tapes and tape changes needed to complete a dump operation. Rather than performing a series of initial dumps first, instead begin with an initial dump and follow it immediately with several appended dumps. In this way you can write all dumps in the series to the same tape (assuming the tape is large enough to accommodate them all). If, in contrast, you perform all of the initial dumps first, each must begin on a new tape and you must switch tapes again if you then want to append dumps.

  You can either issue the appropriate series of backup dump commands at the interactive backup> prompt, or record them in a file that you then name with the -file argument to the backup dump command. Appending dumps in this way enables you to run multiple unattended backup operations even without a tape stacker or jukebox, if all of the dumps fit on one tape.

• It can reduce the number of tape changes during a restore operation. For example, if you append all of the incremental dumps of a volume set to tapes in one dump set, then restoring a volume from the volume set requires a minimum number of tape changes. It is best not to append incremental dumps to a tape that contains the parent full dump, however: if the tape is lost or damaged, you lose all of the data from the volume.

  Although it can be efficient to group together appended dumps that are related, the Backup System does not require any relationship between the appended dumps on a tape or in a dump set.

When writing an appended dump, the Backup System performs most of the steps described in How Your Configuration Choices Influence the Dump Process. Appended dumps do not have to be related to one another or the initial dump, so it skips Step 7: there is no need to check that the AFS tape name reflects the volume set and dump level names in this case. It also skips Step 8. Because it is not overwriting any existing data on the tape, it does not need to check the expiration dates of existing dumps on the tape or in the file. Then in Step 9 the Tape Coordinator scans to the end of the last dump on the tape or in the backup data file before it begins writing data.

The Backup System imposes the following conditions on appended dumps:

• If writing to tape, the Tape Coordinator checks that it is the final one in a dump set for which there are complete and valid tape and dump records in the Backup Database. If not, it rejects the tape and requests an acceptable one. If you believe the tape has valid data on it, you can reconstruct the Backup Database dump records for it by using the -dbadd argument to the backup scantape command as instructed in To scan the contents of a tape.

• The most recent dump on the tape or in the backup data file must have completed successfully.

• The dump set to which the tape or file belongs must begin with an initial dump that is recorded in the Backup Database. If there are no dumps on the current tape, then the Backup System treats the dump operation as an initial dump and imposes the relevant requirements (for example, checks the AFS tape name if appropriate).

As you append dumps, keep in mind that all of a dump set's dump and tape records in the Backup Database are indexed to the initial dump. If you want to delete an appended dump's record, you must delete the initial dump record, and doing so erases the records of all dumps in the dump set. Without those records, you cannot restore any of the data in the dump set.

Similarly, all of the dumps in a dump set must expire before you can recycle (write a new initial dump to) any of the tapes in a dump set. Do not append a dump if its expiration date is later than the date on which you want to recycle any of the tapes in its dump set. To recycle a tape before the last expiration date, you must delete the initial dump's record from the Backup Database. Either use the backup labeltape command to relabel the tape as instructed in To label a tape, or use the backup deletedump command to delete the record directly as instructed in To delete dump records from the Backup Database.

Although in theory you can append as many dumps as you wish, it generally makes sense to limit the number of tapes in a dump set (for example, to five), for these reasons:

• If an unreadable spot develops on one of the tapes in a dump set, it can prevent the Tape Coordinator from scanning the tape as part of a backup scantape operation you use to reconstruct Backup Database records. The Tape Coordinator can almost always scan the tape successfully up to the point of damage and can usually skip past minor damage. A scanning operation can start on any tape in a dump set, so damage on one tape does not prevent scanning of the others in the dump set. However, you can scan only the tapes that precede the damaged one in the dump set or the ones that follow the damaged one, but not both. (For more information on using tapes to reconstruct the information in the Backup Database, see To scan the contents of a tape.)

  An unreadable bad spot can also prevent you from restoring a volume completely, because restore operations must begin with the full dump and continue with each incremental dump in order. If you cannot restore a specific dump, you cannot restore any data from later incremental dumps.

• If you decide in the future to archive one or more dumps, then you must archive the entire set of tapes that constitute the dump set, rather than just the ones that contain the data of interest. This wastes both tape and archive storage space. For more information on archiving, see Archiving Tapes.

Scheduling Dumps

By default, the Backup System starts executing a dump operation as soon as you enter the backup dump command, and the Tape Coordinator begins writing data as soon as it is not busy and the list of files to write is available. You can, however, schedule a dump operation to begin at a specific later time:

• To schedule a single dump operation, include the -at argument to specify its start time.

• To schedule multiple dump operations, list the operations in a file named by the -file argument and use the -at argument to specify when the backup command interpreter reads the file. If you omit the -at argument, the command interpreter reads the file immediately, which does not count as scheduling, but does allow you to initiate multiple dump operations in a single command. Do not combine the -file argument with the -volumeset, -dump, -portoffset, -append, or -n options.

  For file-formatting instructions, see the description of the -file argument in Step 7 of To create a dump.

The Backup System performs initial and appended dumps in the same manner whether they are scheduled or begin running as soon as you issue the backup dump command. The only difference is that the requirements for successful execution hold both at the time you issue the command and when the Backup System actually begins running it. All required Backup Database entries for volume sets, dump levels, and port offsets, and all dump and tape records must exist at both times. Perhaps more importantly, the required administrative tokens must be available at both times. See Making Backup Operations More Efficient.

To create a dump

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. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

3. If using a tape device, insert the tape.

4. Issue the backup command to enter interactive mode.

      % backup
   

5. Decide which volume set and dump level to use. If necessary, issue the backup listvolsets and backup listdumps commands to display the existing volume sets and dump levels. For complete instructions and a description of the output, see To display volume sets and volume entries and To display the dump hierarchy.

      backup> listvolsets  [<volume set name>]
      backup> listdumps
   

   If you want to use a temporary volume set, you must create it during the current interactive session. This can be useful if you are dumping a volume to tape in preparation for removing it permanently (perhaps because its owner is leaving the cell). In this case, you can define a volume entry that includes only the volume of interest without cluttering up the Backup Database with a volume set record that you are using only once. Complete instructions appear in Defining and Displaying Volume Sets and Volume Entries.

      backup>  addvolset <volume set name> -temporary
      backup> addvolentry  -name <volume set name>  \
                           -server <machine name>  \
                           -partition <partition name>  \
                           -volumes <volume name (regular expression)>
   

6. If you are creating an initial dump and writing to a tape or backup data file that does not have a permanent name, its AFS tape name must satisfy the Backup System's format requirements as described in Eliminating the AFS Tape Name Check. If necessary, use the backup readlabel command to display the label and the backup labeltape command to change the names, as instructed in Writing and Reading Tape Labels. You must also relabel a tape if you want to overwrite it and it is part of a dump set that includes any unexpired dumps, though this is not recommended. For a discussion of the appropriate way to recycle tapes, see Creating a Tape Recycling Schedule.

7. Issue the backup dump command to dump the volume set.

   • To create one initial dump, provide only the volume set name, dump level name, and port offset (if not zero).

   • To create one appended dump, add the -append flag.

   • To schedule a single initial or appended dump, add the -at argument.

   • To initiate multiple dump operations, record the appropriate commands in a file and name it with the -file argument. Do not combine this argument with options other than the -at argument.

      backup> dump <volume set name> <dump level name> [<TC port offset>]   \
                   [-at <Date/time to start dump>+]  \
                   [-append]  [-n] [-file <load file>]
   

   where

   dump

   Must be typed in full.

   volume set name

   Names the volume set to dump.

   dump level name

   Specifies the complete pathname of the dump level at which to dump the volume set.

   TC port offset

   Specifies the port offset number of the Tape Coordinator process that is handling the operation. You must provide this argument unless the default value of 0 (zero) is appropriate.

   -at

   Specifies the date and time in the future at which to run the command, or to read the file named by the -file argument. Provide a value in the format mm/dd/yyyy [hh:MM], where the month (mm), day (dd), and year (yyyy) are required. Valid values for the year range from 1970 to 2037; higher values are not valid because the latest possible date in the standard UNIX representation is in February 2038. The Backup System automatically reduces any later date to the maximum value in 2038.

   The hour and minutes (hh:MM) are optional, but if provided must be in 24-hour format (for example, the value 14:36 represents 2:36 p.m.). If you omit them, the time defaults to midnight (00:00 hours).

   As an example, the value 04/23/1999 20:20 schedules the command for 8:20 p.m. on 23 April 1999.

   Note:

   A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition.

   -append

   Creates an appended dump by scanning to the end of the data from one or more previous dump operations that it finds on the tape or in the backup data file.

   -n

   Displays the names of all volumes to be included in the indicated dump, without actually writing data to tape or the backup data file. Combine this flag with the arguments you plan to use on the actual command, but not with the -file argument.

   -file

   Specifies the local disk or AFS pathname of a file containing backup commands. The Backup System reads the file immediately, or at the time specified by the -at argument if it is provided. A partial pathname is interpreted relative to the current working directory.

   Place each backup dump command on its own line in the indicated file, using the same syntax as for the command line, but without the word backup at the start of the line. Each command must include the volume set name and dump level name arguments plus the TC port offset argument if the default value of zero is not appropriate. Commands in the file can also include any of the backup dump command's optional arguments, including the -at argument (which must specify a date and time later than the date and time at which the Backup System reads the file).

8. If you did not include the -noautoquery flag when you issued the butc command, or if the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for labeling.

   If more than one tape is required, you must either include the MOUNT instruction in the CFG_device_name file and stock the corresponding stacker or jukebox with tapes, or remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.

9. After the dump operation completes, review the Backup System's log files to check for errors. Use the bos getlog command as instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a text editor on the Tape Coordinator machine to read the TE_device_name and TL_device_name files in the local /usr/afs/backup directory.

   It is also a good idea to record the tape name and dump ID number on the exterior label of each tape.

Displaying Backup Dump Records

The backup command suite includes three commands for displaying information about data you have backed up:

• To display information about one or more dump operations, such as the date it was performed and the number of volumes included, use the backup dumpinfo command as described in To display dump records. You can display a detailed record of a single dump or more condensed records for a certain number of dumps, starting with the most recent and going back in time. You can specify the number of dumps or accept the default of 10.

• To display a volume's dump history, use the backup volinfo command as described in To display a volume's dump history.

• To display information extracted from a tape or backup data file about the volumes it includes, use the backup scantape command. To create new dump and tape records in the Backup Database derived from the tape and dump labels, add the -dbadd flag. For instructions, see To scan the contents of a tape.

To display dump records

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. Issue the backup dumpinfo command to list information about dumps recorded in the Backup Database.

      % backup dumpinfo [-ndumps <no. of dumps>]  [-id <dump id>]  [-verbose]
   

   where

   dump

   Is the shortest acceptable abbreviation of dumpinfo.

   -ndumps

   Displays the Backup Database record for each of the specified number of dumps, starting with the most recent and going back in time. If the database contains fewer dumps than are requested, the output includes the records for all existing dumps. Do not combine this argument with the -id argument or -verbose flag; omit all three options to display the records for the last 10 dumps.

   -id

   Specifies the dump ID number of a single dump for which to display the Backup Database record. You must include the -id switch. Do not combine this option with the -ndumps or -verbose arguments; omit all three arguments to display the records for the last 10 dumps.

   -verbose

   Provides more detailed information about the dump specified with the -id argument, which must be provided along with it. Do not combine this flag with the -ndumps option.

If the -ndumps argument is provided, the output presents the following information in table form, with a separate line for each dump:

dumpid

The dump ID number.

parentid

The dump ID number of the dump's parent dump. A value of 0 (zero) identifies a full dump.

lv

The depth in the dump hierarchy of the dump level used to create the dump. A value of 0 (zero) identifies a full dump, in which case the value in the parentid field is also 0. A value of 1 or greater indicates an incremental dump made at the corresponding level in the dump hierarchy.

created

The date and time at which the Backup System started the dump operation that created the dump.

nt

The number of tapes that contain the data in the dump. A value of 0 (zero) indicates that the dump operation was terminated or failed. Use the backup deletedump command to remove such entries.

nvols

The number of volumes from which the dump includes data. If a volume spans tapes, it is counted twice. A value of 0 (zero) indicates that the dump operation was terminated or failed; the value in the nt field is also 0 in this case.

dump name

The dump name in the form

   volume_set_name.dump_level_name (initial_dump_ID)
   

where volume_set_name is the name of the volume set, and dump_level_name is the last element in the dump level pathname at which the volume set was dumped.

The initial_dump_ID, if displayed, is the dump ID of the initial dump in the dump set to which this dump belongs. If there is no value in parentheses, the dump is the initial dump in a dump set that has no appended dumps.

If the -id argument is provided alone, the first line of output begins with the string Dump and reports information for the entire dump in the following fields:

id

The dump ID number.

level

The depth in the dump hierarchy of the dump level used to create the dump. A value of 0 (zero) identifies a full dump. A value of 1 (one) or greater indicates an incremental dump made at the specified level in the dump hierarchy.

volumes

The number of volumes for which the dump includes data.

created

The date and time at which the dump operation began.

If an XBSA server was the backup medium for the dump (rather than a tape device or backup data file), the following line appears next:

   Backup Service: XBSA_program: Server: hostname

where XBSA_program is the name of the XBSA-compliant program and hostname is the name of the machine on which the program runs.

Next the output includes an entry for each tape that houses volume data from the dump. Following the string Tape, the first two lines of each entry report information about that tape in the following fields:

name

The tape's permanent name if it has one, or its AFS tape name otherwise, and its tape ID number in parentheses.

nVolumes

The number of volumes for which this tape includes dump data.

created

The date and time at which the Tape Coordinator began writing data to this tape.

Following another blank line, the tape-specific information concludes with a table that includes a line for each volume dump on the tape. The information appears in columns with the following headings:

Pos

The relative position of each volume in this tape or file. On a tape, the counter begins at position 2 (the tape label occupies position 1), and increments by one for each volume. For volumes in a backup data file, the position numbers start with 1 and do not usually increment only by one, because each is the ordinal of the 16 KB offset in the file at which the volume's data begins. The difference between the position numbers therefore indicates how many 16 KB blocks each volume's data occupies. For example, if the second volume is at position 5 and the third volume in the list is at position 9, that means that the dump of the second volume occupies 64 KB (four 16-KB blocks) of space in the file.

Clone time

For a backup or read-only volume, the time at which it was cloned from its read/write source. For a Read/Write volume, it is the same as the dump creation date reported on the first line of the output.

Nbytes

The number of bytes of data in the dump of the volume.

Volume

The volume name, complete with .backup or .readonly extension if appropriate.

If both the -id and -verbose options are provided, the output is divided into several sections:

• The first section, headed by the underlined string Dump, includes information about the entire dump. The fields labeled id, level, created, and nVolumes report the same values (though in a different order) as appear on the first line of output when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:

  Group id

  The dump's group ID number, which is recorded in the dump's Backup Database record if the GROUPID instruction appears in the Tape Coordinator's /usr/afs/backup/CFG_tcid file when the dump is created.

  maxTapes

  The number of tapes that contain the dump set to which this dump belongs.

  Start Tape Seq

  The ordinal of the tape on which this dump begins in the set of tapes that contain the dump set.

• For each tape that contains data from this dump, there follows a section headed by the underlined string Tape. The fields labeled name, written, and nVolumes report the same values (though in a different order) as appear on the second and third lines of output when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:

  expires

  The date and time when this tape can be recycled, because all dumps it contains have expired.

  nMBytes Data and nBytes Data

  Summed together, these fields represent the total amount of dumped data actually from volumes (as opposed to labels, filemarks, and other markers).

  KBytes Tape Used

  The number of kilobytes of tape (or disk space, for a backup data file) used to store the dump data. It is generally larger than the sum of the values in the nMBytes Data and nBytes Data fields, because it includes the space required for the label, file marks and other markers, and because the Backup System writes data at 16 KB offsets, even if the data in a given block doesn't fill the entire 16 KB.

• For each volume on a given tape, there follows a section headed by the underlined string Volume. The fields labeled name, position, clone, and nBytes report the same values (though in a different order) as appear in the table that lists the volumes in each tape when the -id argument is provided by itself. Other fields of potential interest to the backup operator are:

  id

  The volume ID.

  tape

  The name of the tape containing this volume data.

The following example command displays the Backup Database records for the five most recent dump operations.

   % backup dump 5
      dumpid   parentid lv created          nt nvols dump name
   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
   925033000          0 0  04/25/1999 05:36  2    73 sys.week

To display a volume's dump history

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. Issue the backup volinfo command to display a volume's dump history.

      % backup volinfo <volume name>
   

   where

   voli

   Is the shortest acceptable abbreviation of volinfo.

   volume name

   Names the volume for which to display the dump history. If you dumped the backup or read-only version of the volume, include the .backup or .readonly extension.

The output includes a line for each Backup Database dump record that mentions the specified volume, order from most to least recent. The output for each record appears in a table with six columns:

dumpID

The dump ID of the dump that includes the volume.

lvl

The depth in the dump hierarchy of the dump level at which the volume was dumped. A value of 0 indicates a full dump. A value of 1 or greater indicates an incremental dump made at the specified depth in the dump hierarchy.

parentid

The dump ID of the dump's parent dump. A value of 0 indicates a full dump, which has no parent; in this case, the value in the lvl column is also 0.

creation date

The date and time at which the Backup System started the dump operation that created the dump.

clone date

For a backup or read-only volume, the time at which it was cloned from its read/write source. For a read/write volume, the same as the value in the creation date field.

tape name

The name of the tape containing the dump: either the permanent tape name, or an AFS tape name in the format volume_set_name.dump_level_name.tape_index where volume_set_name is the name of the volume set associated with the initial dump in the dump set of which this tape is a part; dump_level_name is the name of the dump level at which the initial dump was backed up; tape_index is the ordinal of the tape in the dump set. Either type of name can be followed by a dump ID in parentheses; if it appears, it is the dump ID of the initial dump in the dump set to which this appended dump belongs.

The following example shows part of the dump history of the backup volume user.smith.backup:

   % backup volinfo user.smith.backup
   DumpID    lvl parentID  creation   date  clone date       tape name
   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 
   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 
       .     .      .         .       .       .      .         .
       .     .      .         .       .       .      .         .

To scan the contents of a tape

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. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

3. If scanning a tape, place it in the drive.

4. (Optional) Issue the backup command to enter interactive mode.

      % backup
   

5. Issue the backup scantape command to read the contents of the tape.

      backup> scantape [-dbadd] [-portoffset <TC port offset>]
   

   where

   sc

   Is the shortest acceptable abbreviation of scantape.

   -dbadd

   Constructs dump and tape records from the tape and dump labels in the dump and writes them into the Backup Database.

   TC port offset

   Specifies the port offset number of the Tape Coordinator process that is handling the operation. You must provide this argument unless the default value of 0 (zero) is appropriate.

6. If you did not include the -noautoquery flag when you issued the butc command, or the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES instruction, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for reading.

To terminate a tape scanning operation, use a termination signal such as <Ctrl-c>, or issue the (backup) kill command in interactive mode. It is best not to interrupt the scan if you included the -dbadd argument. If the Backup System has already written new records into the Backup Database, then you must remove them before rerunning the scanning operation. If during the repeated scan operation the Backup System finds that a record it needs to create already exists, it halts the operation.

For each dump on the tape, the output in the Tape Coordinator window displays the dump label followed by an entry for each volume. There is no output in the command window. The dump label has the same fields as the tape label displayed by the backup readlabel command, as described in Writing and Reading Tape Labels. Or see the IBM AFS Administration Reference for a detailed description of the fields in the output.

The following example shows the dump label and first volume entry on the tape in the device that has port offset 2:

   % backup scantape 2
   -- Dump label --
   tape name = monthly_guest
   AFS tape name = guests.monthly.3
   creationTime =  Mon Feb  1 04:06:40 1999
   cell = abc.com
   size = 2150000 Kbytes
   dump path = /monthly
   dump id = 917860000
   useCount = 44
   -- End of dump label --
   -- volume --
   volume name: user.guest10.backup
   volume ID 1937573829
   dumpSetName: guests.monthly
   dumpID 917860000
   level 0
   parentID 0
   endTime 0
   clonedate Mon Feb  1 03:03:23 1999

Restoring and Recovering Data

The purpose of making backups is to enable you to recover when data becomes corrupted or is removed accidentally, returning the data to a coherent past state. The AFS Backup System provides three commands that restore varying numbers of volumes:

• To restore one or more volumes to a single site (partition on an AFS file server machine), use the backup volrestore command.

• To restore one or more volumes that are defined as a volume set, each to a specified site, use the backup volsetrestore command.

• To restore an entire partition (that is, all of the volumes that the VLDB lists as resident on it), use the backup diskrestore command.

The commands are suited to different purposes because they vary in the combinations of features they offer and in the requirements they impose. To decide which is appropriate for a specific restore operation, see the subsequent sections of this introduction: Using the backup volrestore Command, Using the backup diskrestore Command, and Using the backup volsetrestore Command.

Making Restore Operations More Efficient

The following comments apply to all types of restore operation:

• The Backup System begins by restoring the most recent full dump of a volume. As it restores subsequent incremental dumps, it alters the data in the full dump appropriately, essentially repeating the volume's change history. The backup diskrestore and backup volsetrestore commands always restore all incremental dumps, bringing a volume to its state at the time of the most recent incremental dump. You can use the backup volrestore command to return a volume to its state at a specified time in the past, by not restoring the data from incremental dumps performed after that time.

• The Backup System sets a restored volume's creation date to the date and time of the restore operation. The creation date appears in the Creation field of the output from the vos examine and vos listvol commands.

• When identifying the volumes to restore, it is best to specify the base (read/write) name. In this case, the Backup System searches the Backup Database for the most recent dump set that includes data from either the read/write or backup version of the volume, and restores dumps of that volume starting with the most recent full dump. If you include the .backup or .readonly extension on the volume name, the Backup System restores dumps of that version only. If it cannot find data dumped from that version, it does not perform the restoration even if another version was dumped.

• All three restoration commands accept the -n option, which generates a list of the volumes to be restored and the tapes or backup data files that contain the necessary dumps, without actually restoring data to AFS server partitions. This enables you to gather together the tapes before beginning the restore operation, even preloading them into a stacker or jukebox if you are using one.

• If you back up AFS data to tape, restoration is simplest if all of your tape devices are compatible, meaning that they can read the same type of tape, at the same compression ratios, and so on. (This suggestion also appears in Making Backup Operations More Efficient, because by the time you need to restore data it is too late to implement it.) You can still restore multiple volumes with a single command even if data was backed up using incompatible devices, because the -portoffset argument to all three restoration commands accepts multiple values. However, the Backup System uses the first port offset listed when restoring the full dump of each volume, the next port offset when restoring the level 1 incremental dump of each volume, and so on. If you did not use a compatible tape device when creating the full dump of every volume (and at each incremental level too), you cannot restore multiple volumes with a single command. You must use the backup volrestore command to restore one volume at a time, or use the backup volsetrestore command after defining volume sets that group volumes according to the tape device used to dump them.

• During a restore operation, the Backup System uses instructions in the relevant CFG_device_name configuration file in much the same way as during a dump operation, as described in How Your Configuration Choices Influence the Dump Process. It uses the MOUNT, UNMOUNT, AUTOQUERY, BUFFERSIZE, and FILE instructions just as for a dump operation. A difference for the BUFFERSIZE instruction is that the default buffer size overridden by the instruction is 32 KB for restore operations rather than the 16 KB used for dump operations. The Backup System does not use the NAME_CHECK instruction at all during restore operations. The ASK instruction controls whether the Backup System prompts you if it cannot restore a volume for any reason. If the setting is NO, it skips the problematic volume and restores as many of the other volumes as possible.

• Do not perform a restore operation when you know that there are network, machine, or server process problems that can prevent the Backup System from accessing volumes or the VLDB. Although the Backup System automatically makes a number of repeated attempts to restore a volume, the restore operation takes extra time and in some cases stops completely to prompt you for instructions on how to continue.

• Avoid halting a restore operation (for instance by issuing the (backup) kill command in interactive mode). If a restore operation is interrupted for any reason, including causes outside your control, reissue the same restoration command as soon as is practical; if an outage or other problem caused the operation to halt, do not continue until the system returns to normal.

  Any volume that is completely restored when the operation halts is online and usable, but very few volumes are likely to be in this state. When restoring multiple volumes at once, the Backup System restores the full dump of every volume before beginning the level 1 incremental restore for any of them, and so on, completing the restore of every volume at a specific incremental level before beginning to restore data from the next incremental level. Unless a volume was dumped at fewer incremental levels than others being restored as part of the same operation, it is unlikely to be complete.

  It is even more dangerous to interrupt a restore operation if you are overwriting the current contents of the volume. Depending on how far the restore operation has progressed, it is possible that the volume is in such an inconsistent state that the Backup System removes it entirely. The data being restored is still available on tape or in the backup data file, but you must take extra steps to re-create the volume.

Using the backup volrestore Command

The backup volrestore command is most appropriate when you need to restore a few volumes to a single site (partition on a file server machine). By default, it restores the volumes to their state at the time of the most recent dump operation (this is termed a full restore). You can also use the command to perform a date-specific restore, which restores only the dumps (full and incremental) performed before a specified date and time, leaving the volume in the state it was in at the time of the final relevant incremental dump. The backup diskrestore and backup volsetrestore commands can only perform full restores.

You can restore data into a new copy of each volume rather than overwriting the current version, by including the -extension argument. After mounting the new volume in the filespace, you can compare the contents of the two and decide which to keep permanently.

The following list summarizes how to combine the backup volrestore command's arguments to restore a volume in different ways:

• To perform a date-specific restore as described just previously, use the -date argument to specify the date and optionally time. The Backup System restores the most recent full dump and each subsequent incremental dump for which the clone date of the volume included in the dump is before the indicated date and time (for a definition of the clone date, see Step 4 in How Your Configuration Choices Influence the Dump Process). You can combine this argument with the -extension argument to place the date-specific restore in a new volume.

• To move a volume to a new site as you overwrite its contents with the restored data, use the -server and -partition arguments, singly or in combination, to specify the new site rather than the current site. The Backup System creates a new volume at that site, removes the existing volume, and updates the site information in the volume's VLDB entry. The volume's backup version is not removed automatically from the original site, if it exists. Use the vos remove command to remove it and the vos backup command to create a backup version at the new site.

• To create a new volume to house the restored data, rather than overwriting an existing volume, use the -extension argument. The Backup System creates the new volume on the server and partition named by the -server and -partition arguments, derives its name by adding the extension to the name specified with the -volume argument, and creates a new VLDB entry for it. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it. To make the contents of the new volume accessible, use the fs mkmount command to mount it. You can then compare its contents to those of the existing volume, to see which to retain permanently.

• To restore a volume that no longer exists on an AFS server partition, but for which you have backed up data, specify the name of the new volume with the -volume argument and use the -server and -partition arguments to place it at the desired site. The Backup System creates a new volume and new VLDB entry.

To restore volumes with the backup volrestore command

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. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

   Repeat the command for each Tape Coordinator if you are using more than one tape device.

3. If using a tape device, insert the tape.

4. Issue the backup command to enter interactive mode.

      % backup
   

5. Issue the backup volrestore command with the desired arguments.

      backup> volrestore <destination machine> <destination partition>  \ 
                         -volume <volume(s) to restore>+  \
                         [-extension <new volume name extension>]  \
                         [-date <date from which to restore>]  \
                         [-portoffset <TC port offsets>+] [-n]
   

   where

   volr

   Is the shortest acceptable abbreviation of volrestore.

   destination machine

   Names the file server machine on which to restore each volume. It does not have to be a volume's current site.

   destination partition

   Names the partition on which to restore each volume. It does not have to be a volume's current site.

   -volume

   Names each volume to restore. It is best to provide the base (read/write) name, for the reasons discussed in Making Restore Operations More Efficient.

   -extension

   Creates a new volume to house the restored data, with a name derived by appending the specified string to each volume named by the -volume extension. The Backup System preserves the contents of the existing volume if it still exists. Do not use either of the .readonly or .backup extensions, which are reserved. The combination of base volume name and extension cannot exceed 22 characters in length. If you want a period to separate the extension from the name, specify it as the first character of the string (as in .rst, for example).

   -date

   Specifies a date and optionally time; the restored volume includes data from dumps performed before the date only. Provide a value in the format mm/dd/yyyy [hh:MM], where the required mm/dd/yyyy portion indicates the month (mm), day (dd), and year (yyyy), and the optional hh:MM portion indicates the hour and minutes in 24-hour format (for example, the value 14:36 represents 2:36 p.m.). If omitted, the time defaults to 59 seconds after midnight (00:00:59 hours).

   Valid values for the year range from 1970 to 2037; higher values are not valid because the latest possible date in the standard UNIX representation is in February 2038. The command interpreter automatically reduces any later date to the maximum value.

   Note:

   A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition.

   -portoffset

   Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation. If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels.

   Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of the values in the list, provide it explicitly in the appropriate order.

   -n

   Displays the list of tapes that contain the dumps required by the restore operation, without actually performing the operation.

6. If you did not include the -noautoquery flag when you issued the butc command, or the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for labeling.

   If more than one tape is required, you must either include the MOUNT instruction in the CFG_device_name file and stock the corresponding stacker or jukebox with tapes, or remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.

7. After the restore operation completes, review the Backup System's log files to check for errors. Use the bos getlog command as instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a text editor on the Tape Coordinator machine to read the TE_device_name and TL_device_name files in the local /usr/afs/backup directory.

Using the backup diskrestore Command

The backup diskrestore command is most appropriate when you need to restore all of the volumes on an AFS server partition, perhaps because a hardware failure has corrupted or destroyed all of the data. The command performs a full restore of all of the read/write volumes for which the VLDB lists the specified partition as the current site, using the dumps of either the read/write or backup version of each volume depending on which type was dumped more recently. (You can restore any backup or read-only volumes that resided on the partition by using the vos backup and vos release commands after the backup diskrestore operation is complete.)

By default, the Backup System restores the volumes to the site they previously occupied. To move the partition contents to a different site, use the -newserver and -newpartition arguments, singly or in combination.

By default, the Backup System overwrites the contents of existing volumes with the restored data. To create a new volume to house the restored data instead, use the -extension argument. The Backup System creates the new volume at the site designated by the -newserver and -newpartition arguments if they are used or the -server and -partition arguments otherwise. It derives the volume name by adding the extension to the read/write base name listed in the VLDB, and creates a new VLDB entry. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it.

If a partition seems damaged, be sure not to run the vos syncserv command before the backup diskrestore command. As noted, the Backup System restores volumes according to VLDB site definitions. The vos syncserv command sometimes removes a volume's VLDB entry when the corruption on the partition is so severe that the Volume Server cannot confirm the volume's presence.

To restore a partition with the backup diskrestore command

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. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

   Repeat the command for each Tape Coordinator if you are using more than one tape device.

3. If using a tape device, insert the tape.

4. Issue the backup command to enter interactive mode.

      % backup
   

5. Issue the backup diskrestore command with the desired arguments.

      backup> diskrestore <machine to restore> <partition to restore>  \
                          [-portoffset <TC port offset>+]  \
                          [-newserver <destination machine>]  \
                          [-newpartition <destination partition>]  \
                          [-extension <new volume name extension>] [-n]
   

   where

   di

   Is the shortest acceptable abbreviation of diskrestore.

   machine to restore

   Names the file server machine that the VLDB lists as the site of the volumes that need to be restored.

   partition to restore

   Names the partition that the VLDB lists as the site of the volumes that need to be restored.

   -portoffset

   Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation. If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels.

   Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of the values in the list, provide it explicitly in the appropriate order.

   -newserver

   Names an alternate file server machine to which to restore the volumes. If you omit this argument, the volumes are restored to the file server machine named by the -server argument.

   -newpartition

   Names an alternate partition to which to restore the data. If you omit this argument, the volumes are restored to the partition named by the -partition argument.

   -extension

   Creates a new volume for each volume being restored, to house the restored data, appending the specified string to the volume's read/write base name as listed in the VLDB. Any string other than .readonly or .backup is acceptable, but the combination of the base name and extension cannot exceed 22 characters in length. To use a period to separate the extension from the name, specify it as the first character of the string (as in .rst, for example).

   -n

   Displays a list of the tapes necessary to perform the requested restore, without actually performing the operation.

6. If you did not include the -noautoquery flag when you issued the butc command, or the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for labeling.

   If more than one tape is required, you must either include the MOUNT instruction in the CFG_device_name file and stock the corresponding stacker or jukebox with tapes, or remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.

7. After the restore operation completes, review the Backup System's log files to check for errors. Use the bos getlog command as instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a text editor on the Tape Coordinator machine to read the TE_device_name and TL_device_name files in the local /usr/afs/backup directory.

Using the backup volsetrestore Command

The backup volsetrestore command is most appropriate when you need to perform a full restore of several read/write volumes, placing each at a specified site. You specify the volumes to restore either by naming a volume set with the -name argument or by listing each volume's name and restoration site in a file named by the -file argument, as described in the following sections.

Because the backup volsetrestore command enables you to restore a large number of volumes with a single command, the restore operation can potentially take hours to complete. One way to reduce the time is to run multiple instances of the command simultaneously. Either use the -name argument to specify disjoint volume sets for each command, or the -file argument to name files that list different volumes. You must have several Tape Coordinators available to read the required tapes. Depending on how the volumes to be restored were dumped to tape, specifying disjoint volume sets can also reduce the number of tape changes required.

Restoring a Volume Set with the -name Argument

Use the -name argument to restore a group of volumes defined in a volume set. The Backup System creates a list of the volumes in the VLDB that match the server, partition, and volume name criteria defined in the volume set's volume entries, and for which dumps are available. The volumes do not have to exist on the server partition as long as the VLDB still lists them (this can happen when, for instance, a hardware problem destroys the contents of an entire disk).

By default, the Backup System restores, as a read/write volume, each volume that matches the volume set criteria to the site listed in the VLDB. If a volume of the matching name exists at that site, its current contents are overwritten. You can instead create a new volume to house the restored data by including the -extension argument. The Backup System creates the new volume at the existing volume's site, derives its name by adding the extension to the existing volume's read/write base name, and creates a new VLDB entry for it. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it. To make the contents of the new volume accessible, use the fs mkmount command to mount it. You can then compare its contents to those of the existing volume, to see which to retain permanently.

It is not required that the volume set was previously used to back up volumes (was used as the -volumeset option to the backup dump command). It can be defined especially to match the volumes that need to be restored with this command, and that is usually the better choice. Indeed, a temporary volume set, created by including the -temporary flag to the backup addvolset command, can be especially useful in this context (instructions appear in Defining and Displaying Volume Sets and Volume Entries). A temporary volume set is not added to the Backup Database and exists only during the current interactive backup session, which is suitable if the volume set is needed only to complete the single restore operation initialized by this command.

The reason that a specially defined volume set is probably better is that volume sets previously defined for use in dump operations usually match the backup version of volumes, whereas for a restore operation it is best to define volume entries that match the base (read/write) name. In this case, the Backup System searches the Backup Database for the newest dump set that includes a dump of either the read/write or the backup version of the volume. If, in contrast, a volume entry explicitly matches the volume's backup or read-only version, the Backup System uses dumps of that volume version only, restoring them to a read/write volume by stripping off the .backup or .readonly extension.

If there are VLDB entries that match the volume set criteria, but for which there are no dumps recorded in the Backup Database, the Backup System cannot restore them. It generates an error message on the standard error stream for each one.

Restoring Volumes Listed in a File with the -file Argument

Use the -file argument to specify the name and site of each read/write volume to restore. Each volume's entry must appear on its own (unbroken) line in the file, and comply with the following format:

   machine    partition   volume    [comments...]

where

machine

Names the file server machine to which to restore the volume. You can move the volume as you restore it by naming a machine other than the current site.

partition

Names the partition to which to restore the volume. You can move the volume as you restore it by naming a partition other than the current site.

volume

Names the volume to restore. Specify the base (read/write) name to have the Backup System search the Backup Database for the newest dump set that includes a dump of either the read/write or the backup version of the volume. It restores the dumps of that version of the volume, starting with the most recent full dump. If, in contrast, you include the .backup or .readonly extension, the Backup System restores dumps of that volume version only, but into a read/write volume without the extension. The base name must match the name used in Backup Database dump records rather than in the VLDB, if they differ, because the Backup System does not consult the VLDB when you use the -file argument.

comments...

Is any other text. The Backup System ignores any text on each line that appears after the volume name, so you can use this field for helpful notes.

Do not use wildcards (for example, .*) in the machine, partition, or volume fields. It is acceptable for multiple lines in the file to name the same volume, but the Backup System processes only the first of them.

By default, the Backup System replaces the existing version of each volume with the restored data, placing the volume at the site specified in the machine and partition fields. You can instead create a new volume to house the restored contents by including the -extension argument. The Backup System creates a new volume at the site named in the machine and partition fields, derives its name by adding the specified extension to the read/write version of the name in the volume field, and creates a new VLDB entry for it. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it. To make the contents of the new volume accessible, use the fs mkmount command to mount it. You can then compare its contents to those of the existing volume, to see which to retain permanently.

If the file includes entries for volumes that have no dumps recorded in the Backup Database, the Backup System cannot restore them. It generates an error message on the standard error stream for each one.

One way to generate a file to use as input to the -file argument is to issue the command with the -name and -n options and direct the output to a file. The output includes a line like the following for each volume (shown here on two lines only for legibility reasons); the value comes from the source indicated in the following list:

   machine   partition   volume_dumped  # as   volume_restored;    \
         tape_name   (tape_ID);   pos   position_number;   date

where

machine

Names the file server machine that currently houses the volume, as listed in the VLDB.

partition

Names the partition that currently houses the volume, as listed in the VLDB.

volume_dumped

Specifies the version (read/write or backup) of the volume that was dumped, as listed in the Backup Database.

volume_restored

Specifies the name under which the Backup System restores the volume when the -n flag is not included. If you include the -extension argument with the -name and -n options, then the extension appears on the name in this field (as in user.pat.rst, for example).

tape_name

Names the tape containing the dump of the volume, from the Backup Database. If the tape has a permanent name, it appears here; otherwise, it is the AFS tape name.

tape_ID

The tape ID of the tape containing the dump of the volume, from the Backup Database.

position_number

Specifies the dump's position on the tape (for example, 31 indicates that 30 volume dumps precede the current one on the tape). If the dump was written to a backup data file, this number is the ordinal of the 16 KB-offset at which the volume's data begins.

date

The date and time when the volume was dumped.

To make the entries suitable for use with the -file argument, edit them as indicated:

• The Backup System uses only the first three fields on each line of the input file, and so ignores all the fields after the number sign (#). You can remove them if it makes it easier for you to read the file, but that is not necessary.

• The volume_dumped (third) field of each line in the output file becomes the volume field in the input file. The Backup System restores data to read/write volumes only, so remove the .backup or .readonly extension if it appears on the name in the volume_dumped field.

• The output file includes a line for every dump operation in which a specific volume was included (the full dump and any incremental dumps), but the Backup System only processes the first line in the input file that mentions a specific volume. You can remove the repeated lines if it makes the file easier for you to read.

• The machine and partition fields on an output line designate the volume's current site. To move the volume to another location as you restore it, change the values.

To restore a group of volumes with the backup volsetrestore command

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. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

   Repeat the command for each Tape Coordinator if you are using more than one tape device.

3. If using a tape device, insert the tape.

4. Issue the backup command to enter interactive mode.

      % backup
   

5. (Optional) If appropriate, issue the (backup) addvolset command to create a new volume set expressly for this restore operation. Include the -temporary flag if you do not need to add the volume set to the Backup Database. Then issue one or more (backup) addvolentry commands to create volume entries that include only the volumes to be restored. Complete instructions appear in Defining and Displaying Volume Sets and Volume Entries.

      backup> addvolset <volume set name>  [-temporary]
      
      backup> addvolentry  -name <volume set name>  \
                           -server <machine name>  \
                           -partition <partition name>  \
                           -volumes <volume name (regular expression)>
   

6. Issue the backup volsetrestore command with the desired arguments.

      backup> volsetrestore [-name <volume set name>]  \
                    [-file <file name>]  \
                    [-portoffset <TC port offset>+]  \
                    [-extension <new volume name extension>] [-n] 
   

   where

   -name

   Names a volume set to restore. The Backup System restores all of the volumes listed in the VLDB that match the volume set's volume entries, as described in Restoring a Volume Set with the -name Argument. Provide this argument or the -file argument, but not both.

   -file

   Specifies the full pathname of a file that lists one or more volumes and the site (file server machine and partition) to which to restore each. The input file has the format described in Restoring Volumes Listed in a File with the -file Argument. Use either this argument or the -name argument, but not both.

   -portoffset

   Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation. If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels.

   Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of the values in the list, provide it explicitly in the appropriate order.

   -extension

   Creates a new volume for each volume being restored, to house the restored data, appending the specified string to the volume's read/write base name as listed in the VLDB. Any string other than .readonly or .backup is acceptable, but the combination of the base name and extension cannot exceed 22 characters in length. To use a period to separate the extension from the name, specify it as the first character of the string (as in .rst, for example).

   -n

   Displays a list of the volumes to be restored when the flag is not included, without actually restoring them. The Output section of this reference page details the format of the output. When combined with the -name argument, its output is easily edited for use as input to the -file argument on a subsequent backup volsetrestore command.

7. If you did not include the -noautoquery flag when you issued the butc command, or the device's CFG_device_name configuration file includes the instruction AUTOQUERY YES, then the Tape Coordinator prompts you to place the tape in the device's drive. You have already done so, but you must now press <Return> to indicate that the tape is ready for labeling.

   If more than one tape is required, you must either include the MOUNT instruction in the CFG_device_name file and stock the corresponding stacker or jukebox with tapes, or remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.

8. After the restore operation completes, review the Backup System's log files to check for errors. Use the bos getlog command as instructed in Displaying Server Process Log Files to read the /usr/afs/logs/BackupLog file, and a text editor on the Tape Coordinator machine to read the TE_device_name and TL_device_name files in the local /usr/afs/backup directory.

Maintaining the Backup Database

The Backup Database stores all of the configuration and tracking information that the Backup System uses when dumping and restoring data. If a hardware failure or other problem on a database server machine corrupts or damages the database, it is relatively easy to recreate the configuration information (the dump hierarchy and lists of volume sets and Tape Coordinator port offset numbers). However, restoring the dump tracking information (dump records) is more complicated and time-consuming. To protect yourself against loss of data, back up the Backup Database itself to tape on a regular schedule.

Another potential concern is that the Backup Database can grow large rather quickly, because the Backup System keeps very detailed and cross-referenced records of dump operations. Backup operations become less efficient if the Backup Server has to navigate through a large number of obsolete records to find the data it needs. To keep the database to a manageable size, use the backup deletedump command to delete obsolete records, as described in Removing Obsolete Records from the Backup Database. If you later find that you have removed records that you still need, you can use the backup scantape command to read the information from the dump and tape labels on the corresponding tapes back into the database, as instructed in To scan the contents of a tape.

Backing Up and Restoring the Backup Database

Because of the importance of the information in the Backup Database, it is best to back it up to tape or other permanent media on a regular basis. As for the other AFS, administrative databases, the recommended method is to use a utility designed to back up a machine's local disk, such as the UNIX tar command. For instructions, see Backing Up and Restoring the Administrative Databases.

In the rare event that the Backup Database seems damaged or corrupted, you can use the backup dbverify command to check its status. If it is corrupted, use the backup savedb command to repair some types of damage. Then use the backup restoredb to return the corrected database to the local disks of the database server machines. For instructions, see Checking for and Repairing Corruption in the Backup Database.

Checking for and Repairing Corruption in the Backup Database

In rare cases, the Backup Database can become damaged or corrupted, perhaps because of disk or other hardware errors. Use the backup dbverify command to check the integrity of the database. If it is corrupted, the most efficient way to repair it is to use the backup savedb command to copy the database to tape. The command automatically repairs several types of corruption, and you can then use the backup restoredb command to transfer the repaired copy of the database back to the local disks of the database server machines.

The backup savedb command also removes orphan blocks, which are ranges of memory that the Backup Server preallocated in the database but cannot use. Orphan blocks do not interfere with database access, but do waste disk space. The backup dbverify command reports the existence of orphan blocks if you include the -detail flag.

To verify the integrity of the Backup Database

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. Issue the backup dbverify command to check the integrity of the Backup Database.

      % backup dbverify [-detail]
   

   where

   db

   Is the shortest acceptable abbreviation of dbverify.

   -detail

   Reports the existence of orphan blocks and other information about the database, as described on the backup dbverify reference page in the IBM AFS Administration Reference.

   The output reports one of the following messages:

   • Database OK indicates that the Backup Database is undamaged.

   • Database not OK indicates that the Backup Database is damaged. To recover from the problem, use the instructions in To repair corruption in the Backup Database.

To repair corruption in the Backup Database

1. Log in as the local superuser root on each database server machine in the cell.

2. If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a connection to the appropriate Tape Coordinator machine and issue the butc command, for which complete instructions appear in To start a Tape Coordinator process.

      % butc [<port offset>] [-noautoquery]
   

3. If writing to tape, place a tape in the appropriate device.

4. Working on one of the machines, issue the backup command to enter interactive mode.

      #  backup -localauth
   

   where -localauth constructs a server ticket from the local /usr/afs/etc/KeyFile file. This flag enables you to issue a privileged command while logged in as the local superuser root but without AFS administrative tokens.

5. Verify that no backup operations are actively running. If necessary, issue the (backup) status command as described in To check the status of a Tape Coordinator process. Repeat for each Tape Coordinator port offset in turn.

      backup> status -portoffset <TC port offset>
   

6. Issue the (backup) savedb command to repair corruption in the database as it is written to tape or a file.

      backup> savedb [-portoffset <TC port offset>]
   

   where

   sa

   Is the shortest acceptable abbreviation of savedb.

   -portoffset

   Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this operation. You must provide this argument unless the default value of 0 (zero) is appropriate.

7. Exit interactive mode.

      backup>  quit  
   

8. On each machine in turn, issue the bos shutdown command to shut down the Backup Server process. Include the -localauth flag because you are logged in as the local superuser root, but do not necessarily have administrative tokens. For complete command syntax, see To stop processes temporarily.

      # /usr/afs/bin/bos shutdown <machine name> buserver  -localauth  -wait
   

9. On each machine in turn, issue the following commands to remove the Backup Database.

      # cd /usr/afs/db
      # rm bdb.DB0
      # rm bdb.DBSYS1
   

10. On each machine in turn, starting with the machine with the lowest IP address, issue the bos start command to restart the Backup Server process, which creates a zero-length copy of the Backup Database as it starts. For complete command syntax, see To start processes by changing their status flags to Run.

       # /usr/afs/bin/bos start <machine name> buserver  -localauth
    

11. Working on one of the machines, issue the backup command to enter interactive mode.

       #  backup -localauth
    

    where -localauth constructs a server ticket from the local /usr/afs/etc/KeyFile file.

12. Issue the (backup) addhost command to create an entry in the new, empty database for the Tape Coordinator process handling the tape or file from which you are reading the repaired copy of the database (presumably the process you started in Step 2 and which performed the backup savedb operation in Step 6). For complete syntax, see Step 8 in To configure a Tape Coordinator machine.

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

13. Issue the (backup) restoredb command to copy the repaired database to the database server machines.

       backup> restoredb  [-portoffset <TC port offset>]
    

    where

    res

    Is the shortest acceptable abbreviation of restoredb.

    -portoffset

    Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this operation. You must provide this argument unless the default value of 0 (zero) is appropriate.

14. (Optional) Exit interactive mode if you do not plan to issue any additional backup commands.

       backup> quit
    

15. (Optional) If desired, enter Ctrl-d or another interrupt signal to exit the root shell on each database server machine. You can also issue the Ctrl-c signal on the Tape Coordinator machine to stop the process.

Removing Obsolete Records from the Backup Database

Whenever you recycle or relabel a tape using the backup dump or backup labeltape command, the Backup System automatically removes all of the dump records for the dumps contained on the tape and all other tapes in the dump set. However, obsolete records can still accumulate in the Backup Database over time. For example, when you discard a backup tape after using it the maximum number of times recommended by the manufacturer, the records for dumps on it remain in the database. Similarly, the Backup System does not automatically remove a dump's record when the dump reaches its expiration date, but only if you then recycle or relabel the tape that contains the dump. Finally, if a backup operation halts in the middle, the records for any volumes successfully written to tape before the halt remain in the database.

A very large Backup Database can make backup operations less efficient because the Backup Server has to navigate through a large number of records to find the ones it needs. To remove obsolete records, use the backup deletedump command. Either identify individual dumps by dump ID number, or specify the removal of all dumps created during a certain time period. Keep in mind that you cannot remove the record of an appended dump except by removing the record of its initial dump, which removes the records of all associated appended dumps. Removing records of a dump makes it impossible to restore data from the corresponding tapes or from any dump that refers to the deleted dump as its parent, directly or indirectly. That is, restore operations must begin with the full dump and continue with each incremental dump in order. If you have removed the records for a specific dump, you cannot restore any data from later incremental dumps.

Another way to truncate the Backup Database is to include the -archive argument to the backup savedb command. After a copy of the database is written to tape or to a backup data file, the Backup Server deletes the dump records for all dump operations with timestamps prior to the date and time you specify. However, issuing the backup deletedump command with only the -to argument is equivalent in effect and is simpler because it does not require starting a Tape Coordinator process as the backup savedb command does. For further information on the -archive argument to the backup savedb command, see the command's reference page in the IBM AFS Administration Reference.

If you later need to access deleted dump records, and the corresponding tapes still exist, you can use the -dbadd argument to the backup scantape command to scan their contents into the database, as instructed in To scan the contents of a tape.

To delete dump records from the Backup Database

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. (Optional) Issue the backup command to enter interactive mode, if you want to delete multiple records or issue additional commands. The interactive prompt appears in the following step.

      % backup
   

3. (Optional) Issue the backup dumpinfo command to list information from the Backup Database that can help you decide which records to delete. For detailed instructions, see To display dump records.

      backup> dumpinfo [<no. of dumps>]  [-id <dump id>]  [-verbose]
   

4. Issue the backup deletedump command to delete one or more dump sets.

      backup> deletedump [-dumpid <dumpid>+] [-from <date time>]  \
                         [-to <date time>] 
   

   where

   dele

   Is the shortest acceptable abbreviation of deletedump.

   -dumpid

   Specifies the dump ID of each initial dump to delete from the Backup Database. The records for all associated appended dumps are also deleted. Provide either this argument or the -to (and optionally, -from) argument.

   -from

   Specifies the beginning of a range of dates; the record for any dump created during the indicated period of time is deleted.

   To omit all records before the time indicated with the -to argument, omit this argument. Otherwise provide a value in the following format

   mm/dd/yyyy [hh:MM]

   where the month (mm), day (dd), and year (yyyy) are required. You can omit the hour and minutes (hh:MM) to indicate the default of midnight (00:00 hours). If you provide them, use 24-hour format (for example, the value 14:36 represents 2:36 p.m.).

   You must provide the -to argument along with this one.

   Note:

   A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition.

   -to

   Specifies the end of a range of dates; the record of any dump created during the range is deleted from the Backup Database.

   To delete all records created after the date you specify with the -from argument, specify the value NOW. To delete every dump record in the Backup Database, provide the value NOW and omit the -from argument. Otherwise, provide a date value in the same format as described for the -from argument. Valid values for the year (yyyy) range from 1970 to 2037; higher values are not valid because the latest possible date in the standard UNIX representation is in early 2038. The command interpreter automatically reduces any later date to the maximum value in 2038.

   If you omit the time portion (hh:MM), it defaults to 59 seconds after midnight (00:00:59 hours). Similarly, the backup command interpreter automatically adds 59 seconds to any time value you provide. In both cases, adding 59 seconds compensates for how the Backup Database and backup dumpinfo command represent dump creation times in hours and minutes only. For example, the Database records a creation timestamp of 20:55 for any dump operation that begins between 20:55:00 and 20:55:59. Automatically adding 59 seconds to a time thus includes the records for all dumps created during that minute.

   Provide either this argument, or the -dumpid argument. This argument is required if the -from argument is provided.

   Note:

   A plus sign follows this argument in the command's syntax statement because it accepts a multiword value which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates. Provide only one date (and optionally, time) definition.