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.
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.
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.
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>
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.
If using a tape device, insert the tape.
Issue the backup command to enter interactive mode.
% backup
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
Is the shortest acceptable abbreviation of volrestore.
Names the file server machine on which to restore each volume. It does not have to be a volume's current site.
Names the partition on which to restore each volume. It does not have to be a volume's current site.
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.
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).
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.
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.
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.
Displays the list of tapes that contain the dumps required by the restore operation, without actually performing the operation.
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.
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.
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.
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>
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.
If using a tape device, insert the tape.
Issue the backup command to enter interactive mode.
% backup
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
Is the shortest acceptable abbreviation of diskrestore.
Names the file server machine that the VLDB lists as the site of the volumes that need to be restored.
Names the partition that the VLDB lists as the site of the volumes that need to be restored.
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.
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.
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.
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).
Displays a list of the tapes necessary to perform the requested restore, without actually performing the operation.
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.
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.
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.
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.
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
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.
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.
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.
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
Names the file server machine that currently houses the volume, as listed in the VLDB.
Names the partition that currently houses the volume, as listed in the VLDB.
Specifies the version (read/write or backup) of the volume that was dumped, as listed in the Backup Database.
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).
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.
The tape ID of the tape containing the dump of the volume, from the Backup Database.
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.
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.
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>
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.
If using a tape device, insert the tape.
Issue the backup command to enter interactive mode.
% backup
(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)>
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
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.
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.
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.
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).
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.
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.
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.