Backing Up Data
| Chapter 7. Backing Up and Restoring AFS Data |

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

Using the Backup System's Interfaces |  | Displaying Backup Dump Records