Section 3.5. Restoring with the restore Utility

3.5. Restoring with the restore Utility

While writing this section, one phrase kept coming to mind, from a commercial for a motion-sickness medication in the U.S. called Dramamine. "The time to take Dramamine is too late to take Dramamine." (By then, you're already sick.) The same thing applies to learning how to use the restore utility. You need to become very familiar with the various ways in which you can use restore to retrieve data from a backup created with dump. If you are in the midst of a critical restore as you read this, don't worry: this section is organized with that scenario in mind and includes every trick available in restore.

This next section assumes that you know the volume was made with dump and that you know its block size. If you do not have this information, see the section "How Do I Read This Volume?" in Chapter 23.

3.5.1. Is the Backup Volume Readable?

To make sure that you know the format and block size of a tape, try listing its table of contents. The following command produces the table of contents of a volume created with dump:

$ restore tbfy block_size device-name

For example, to read the table of contents of a dump tape (made with a blocking factor of 32) on /dev/rmt/0cbn, issue the following command:

$ restore tbfy 32 /dev/rmt/0cbn

If that works, then the rest is easy. (If not, read "How Do I Read This Volume?" in Chapter 23.)

3.5.2. Blocking Factor

Sometimes dump can write in a blocking factor that restore cannot read. This problem is usually very simple to get around. Once again, you need the block size in which the volume was written. Determine the volume's block size as discussed in Chapter 23. Let's assume that the block size of the volume is 65536. Use dd to read the volume, and pipe the output of dd to dump, giving "-" as the file argument. This tells restore to read its data from standard input.

# dd if=device-name bs=64k|restore tfy -

Why does this work? The blocking of data while writing to a volume drive actually changes how the data physically resides on the volume. The restore command needs to understand the blocking format to be able to read the volume. However, if you use dd to read the data from the volume, the data is put into a pipe. The dd command effectively sets the block size of the pipe to 1, allowing restore to use any block size when reading it.

3.5.3. Byte-Order Differences

The dump backup format is very filesystem-specific. If you have byte-order differences, the versions of dump and restore are probably also different. The easiest, and possibly the only, thing to do is to find a system that has the same operating system as the one that made the volume. That is because reversing the byte order may allow you to read the dump header but, depending on the dump format, it may render the restored files useless.

3.5.4. Different Versions of dump

Unfortunately, this issue only gets worse with time. Unlike the other utilities covered in this chapter, the dump command is tied heavily to the filesystem, and dump generally works with only one type of filesystem. The problem with this is that Unix vendors keep trying to improve the filesystem, so many Unix vendors have more than one type of filesystem. If dump exists at all on your version of Unix, it may support only the older filesystem types. In some cases, there are multiple versions of dump. For example, IRIX has both dump and xfsdump. Each version of dump also has its own version of restore. Different versions of restore may or may not be able to read a backup written by another version of dump. This is yet another area where your mileage will definitely vary.

Probably the best example of the changing nature of dump is SGI's XFS filesystem and its xfsdump command. On the surface, it looks like the old (efs)dump command with a few new options. However, this could not be further from the truth. Assume for a minute that you are using a homegrown program that uses dump. You then add the new XFS filesystem that you just installed to xfsdump's include list. The first thing that xfsdump does is rewind the tape, whether or not the no-rewind device was chosen. It then attempts to read the first block of data on the tape. Depending on the complexity of the script that called xfsdump, the first file on the tape could be an electronic label that the script put on the tape, or it could be the first dump backup that went to the tape. In the latter case, xfsdump says, "This is not an xfsdump backup...I will overwrite it." If it is an xfsdump backup, xfsdump does not overwrite it but appends to it.

Another thing about xfsdump, perhaps its most "interesting" feature, is that it writes multiple tape files per xfsdump backup. Typically, each dump backup creates one tape file on the tape, but xfsdump uses an algorithm to determine how many files it should place on the tape. This supposedly makes recovery quicker, but it also makes it completely incompatible with almost all homegrown shell scripts.

The best thing to do here is be prepared. Know which versions of dump and restore you use, and experiment with them to see if they can read each other's volumes. If you are talking about two versions of dump on the same system, it will probably either always work or never work. Remember to test, test, test.

3.5.5. Syntax of the restore Command

Once you can read a dump volume, you need to decide what data needs to be read and how to read it. This section discusses commonly used arguments to restore and when to use them.

Essentially, there are four things you might want to do with a dump volume:

• Read the table of contents to verify its contents

• Restore an entire filesystem

• Restore selected files

• Perform an "interactive" restore

The first three uses of restore can take their data from standard input. These are the appropriate ways to use the command if you must pipe data to them, such as in the preceding dd example. The interactive restore works well only when it can see the whole dump file or tape. The syntax of a normal restore command is as follows:

$ restore [trxi]vbsfy blocking-factor file-number device-name

3.5.6. The Options to the restore Command

How restore behaves depends on what types of arguments you pass to it.

3.5.6.1. Determining the type of restore

The first argument to restore specifies what type of restore to perform. You may specify only one of four possible arguments:

t

Tells restore to display a table of contents of the volume

r

Specifies that the entire contents of the volume should be restored to the current working directory

x

Tells restore to extract only the files listed at the end of the command

i

Allows you to perform an interactive restore

3.5.6.2. Determining how the restore behaves

The rest of the arguments are optional and specify how restore behaves during the process:

v

Specifies verbose output

s

Tells restore to skip some number of tape files before it begins reading the tape

b

Allows you to specify the blocking factor of the volume you are reading

f

Specifies the filename of the backup drive (or disk file) you are using

y

Tells restore to attempt to recover from read errors

The following sections explain these options in more detail.

3.5.6.3. Creating a dump volume table of contents (t)

The t option is used to see what files are contained on a dump volume. This is a good command to include in any automated shell script that controls your dump backups. It is also handy on the backend if you are unsure of things such as the case or exact locations of the filenames. You can extract the list of files on any dump volume into a file, then use tools like grep to find the files you are looking for. For example:

# restore tfy device >/tmp/dump.list

The preceding command reads the table of contents of the dump backup on device, and sends its output to /tmp/dump.list. The following command searches /tmp/dump.list for the phrase filename:

# grep filename /tmp/dump.list 3455            ./somedirectory/filename

3.5.6.4. Performing a complete (recursive) filesystem restore (r)

The r option is designed to restore an entire filesystem by reading the entire contents of a dump volume into a filesystem. This should be used only if you are absolutely sure that you want to restore the entire filesystem. It requires that you start with the level 0 dump file and then optionally read any incremental backups. It writes the file restoresymtable (called restoresmtable on some Unix versions) and references that file when reading the incremental restores. An incremental dump records the time of the lower-level dump on which it was based. Since the r option is designed to restore an entire filesystem, it does not allow you to read an incremental dump that is based on a dump volume that has not been read yet. For example, suppose that you have three dump backups, a level 0 from Monday, a level 1 from Tuesday, and a level 2 from Wednesday. If you read the level 0 using the r option and then try to read the level 2 without reading the level 1, restore complains.

You should remove the restoresymtable file when the entire restore is complete. (Do not remove it until you have read all levels of your backup tapes, however.)

To use this option, first cd into the filesystem that you want to restore, then load the level 0 backup and execute the following command:

# restore rbvsfy blocking-factor file-number device-name

For example, to restore the entire contents of a dump tape that was made with a blocking factor of 32 and is sitting in /dev/rmt/0cbn, issue the following command:

$ restore rvbfy 32 /dev/rmt/0cbn

After this command completes, load any incremental backups, starting with the lowest-level backup, and execute the same command again. Do this until you have loaded the most recent incremental backup. If you have more than one dump volume of the same level, you need to load only the most recent one. For example, if you make a level 0 once a month and make level 1 backups the rest of the month, to restore the entire filesystem you need to load only the original level and then the latest level 1.

3.5.6.5. Restoring files by name (x)

You can use the x option if you know the exact name and path of the file(s) you want to restore. (Not all restore versions that I tested support using wildcards in the include list, so you do need to know the exact filenames.) It basically makes restore work like tar, allowing you to list on the command line the files to be extracted. Keeping in mind that all dump backups are made with relative pathnames, you need to cd into the filesystem where you want the file(s) to reside. Then, execute the following command to extract the file(s) from the backup:

# restore xbvsfy blocking-factor file-number device-name ./dir/file1 ./dir/file2  

For example, to restore the files /etc/hosts and /etc/passwd from a dump tape that was made with a blocking factor of 32 and is sitting in /dev/rmt/0cbn, issue the following command:

$ restore xvbfy 32 /dev/rmt/0cbn ./etc/hosts ./etc/passwd

3.5.6.6. Restoring files interactively (i)

This is the option that differentiates restore from tar and cpio. When dump makes a backup, it stores at the beginning of the dump an index of what it is about to back up. (As with the other restore modes of operation, you should cd into the filesystem where you want the restored files to reside before executing the restore command.) The interactive option simulates mounting the dump volume and establishes a mock shell where you can use the following commands: cd, ls, pwd, add, delete, and extract. You can use these commands to maneuver around the directories listed on the dump volume much as if you were moving around a filesystem.

When you see a file that you want to include in your restore, simply enter add filename. Most versions of restore also support shell wildcards here, too, so you can also enter add *pattern*. Once a file is selected for a restore, an asterisk appears next to it the next time you ask for a file listing with ls. If you notice that you have added a file that you do not want to restore, just enter delete filename or delete *pattern*. This, of course, does not delete the file from the volume; it merely drops that file from the list of files to be extracted. Once you have selected the files that you want to restore, simply type exTRact.

restore then asks a question about which volume to start with. This question is relevant only if you are restoring a few files that are spread across multiple tapes. Because the files are dumped in inode order, you can put the last tape in first, and restore can read the first file's inode number and tell immediately if it needs to read anything on that tape; if so, it has to read only up to the last inode on that tape. If it still needs to read files off the other tapes, put them in the drive in decreasing order; again, it knows whether it has to read those tapes and how much of them to read. If you put tape 1 in first, it simply reads the tapes sequentially. If you are restoring a filesystem, this works just fine.

If you are restoring a few files from a dump backup that spans multiple tapes, put the tapes in the drive in reverse order and answer with the appropriate number. If you have only one tape or are just going to read the tapes sequentially, just enter the number 1.

The file(s) that you selected are then restored into the directory where you were when you entered the restore command. (restore makes any directories that it needs to restore the files.) Once the restore has completed, it asks you, set owner/mode for '.'? Many people don't understand what this question means. Assume that you backed up /home/curtis, which was owned by the user curtis. If you are restoring that home directory to /tmp, answering "Yes" results in the /tmp being owned by the user curtis! Therefore, be careful when restoring files to alternate locations and answering "Yes" to this question. Answering "No" results in the directory permissions being left as they are.

Example 3-1 is a sample restore session. Most of the extra verbose comments that you see here, such as block size, the date that dump made the volume, and other messages, are the result of adding the verbose (v) option (the verbose option is discussed later in this section). In this session, the file /etc/passwd is selected and restored to / tmp/etc/passwd. (That is because I am sitting in the /tmp directory when I start the restore.)

Example 3-1. Sample restore session

# cd /tmp # ufsrestore ifvy /tmp/dump Verify volume and initialize maps Media block size is 126 Dump   date: Sun Apr 30 23:07:22 2006 Dumped from: Sun Apr 30 22:15:37 2006 Level 9 dump of / on apollo:/dev/dsk/c0t0d0s0 Label: none Extract directories from tape Initialize symbol table. ufsrestore > ls .:      2 *./             2 *../        11395  devices/   28480  etc/ ufsrestore > cd etc ufsrestore > ls ./etc:  28480  ./              2 *../         28562  dumpdates   28486  passwd ufsrestore > add passwd Make node ./etc ufsrestore > ls ./etc:  28480 *./              2 *../         28562  dumpdates   28486 *passwd ufsrestore > extract Extract requested files You have not read any volumes yet. Unless you know which volume your file(s) are on you should start with the last volume and work towards the first. Specify next volume #: 1 extract file ./etc/passwd Add links Set directory mode, owner, and times. set owner/mode for '.'? [yn] n ufsrestore > q # ls -lt /tmp/etc/passwd -rw-r--r--   1 root       sys       34983 Apr 28 23:54 /tmp/etc/passwd

3.5.6.7. Restoring files to another location

All filenames on a dump backup volume have a relative pathname. In other words, if you back up /home, which includes /home/mickey and /home/mouse, the listing looks like this:

15643   ./mickey 12456   ./mouse

So, restoring the files to an alternate location is very easy. Simply change directories to something other than the original mount point (e.g., /home1) and start the restore from there. restore creates directories as needed. If you change the directory /home to /tmp in the preceding example, it creates /tmp/mickey and /tmp/mouse.

3.5.6.8. Requesting verbose output (v)

The v option does not require an argument and results in a verbose output. It displays a lot of extra information, such as the date and level of the backup, as well as the name of each file as it is restored.

The s, b, and f options require an argument. These options work just like their counterparts in the dump command. (This is not to say that the s option performs the same function in both commands, though.) List all the options you want to use just after the restore command, then list each option's accompanying argument in the same order as you listed the options. For example, to use the b, f, and s options, issue the following command:

# restore tbfsy blocking-factor device-file file-number

3.5.6.9. Skipping files (s)

The v option is used to read a dump backup other than the first one on a tape. When you issue multiple dump commands to a nonrewinding tape device, each becomes a separate file; files are separated by an EOF mark. You cannot read all of these in one stroke with a single command. (If you were restoring, you probably wouldn't want to, because each is probably a backup of a separate filesystem.) You have to read each backup with a separate restore command. There are two scenarios here. You can:

• Consecutively read every filesystem from the tape, such as when you want a table of contents of the entire tape.

• Read a certain filesystem from a tape.

Reading multiple filesystems consecutively may be accomplished by simply executing several restore commands in a sequence, using the nonrewinding tape device. Whether this works for you depends on how your system's tape device driver functions. After a successful execution of a restore command, the tape may stop at the end of the file just after the EOF mark. If it is a Berkeley-style device, it may stop at the end of the file just before the EOF mark. In that case, the next restore command would fail. You sometimes can fix this by executing one forward space file command (e.g., mt -t device fsf 1). This positions the tape just after the EOF mark, and you can then execute your next restore command.

Reading a certain filesystem's dump backup from tape can be accomplished one of two ways. You can:

• Position the tape to the appropriate dump file using mt or tctl and then execute your restore command with no s argument.

• Rewind the tape and use the s option to tell restore which file to read. It then forwards the tape to that file and reads it. s requires an argument, from 1 to n. This value should be the number of the file that you want to read from the tape. The first backup on the tape is numbered 1, so issuing the command restore tsf 1 device is functionally the same as restore tf device.

Please note the difference between mt and restore. The way mt and restore number the tape files is off by one. If you want to tell mt to go to the second file on tape, issue the command mt -t device fsf 1. If you want restore to read the second dump volume on the tape, issue the command restore [irtx]s 2. This has confused more than one system administrator!

3.5.6.10. Specifying a blocking factor (b)

The b option explicitly tells restore what blocking factor dump used when writing the volume. It requires an argument that is a numeric value, normally between 1 and 126, or the highest blocking factor that your version of dump supports. This blocking factor is multiplied by the minimum block size that your version of dump supports. The minimum block size is usually 1,024 but may be 512. (Check your version's manpages.) Many versions of restore can now automatically detect most common blocking factors, so you may not even need this option. If you determine that you have a blocking factor that your version of restore cannot automatically detect, use it to tell restore which blocking factor was used. If you are using dd to read the data and pipe it into restore, you do not need to use the b option.

3.5.6.11. Specifying a backup drive or file (f)

The f option is used quite often, and it tells restore to read from the device specified in the accompanying argument, instead of the default tape drive for your version of Unix. The argument may specify any of the following:

/dev/rmt/0

A local device name (e.g., /dev/rmt0, /dev/rmt/8500compressed)

/backup/dumpfile

Any backup file that was created by dump

remote_host: /dev/rmt/0

A remote device, by specifying a hostname prior to the device (Not all versions of restore support the use of remote hosts.)

Be sure to read "Using ssh or rsh as a Conduit Between Systems" near the end of this chapter for a more secure way to use remote devices.

"-"

Standard input, such as when reading from dd, or a dump sent to standard output

3.5.6.12. Specifying no query during restore (y)

Normally, when restore encounters an error in the file, it stops and asks you if you want to continue. If you add the y option, it does not ask you this question and tries to continue as best it can when it encounters an error.