salvage(8dfs)

Synopsis

salvage -aggregate name [-recoveronly] [{-verifyonly | -salvageonly}] [-force]
[-verbose] [-help]

Options

-aggregate name
Specifies the device name or aggregate name of the DCE LFS aggregate to be verified, recovered, or salvaged. These names are specified in the first and second fields of the entry for the aggregate in the dcelocal/var/dfs/dfstab file.

-recoveronly
Directs the Salvager to recover the specified aggregate. The Salvager replays the log of metadata changes that resides on the aggregate. See the Description section for information about using and combining the command's options.

-verifyonly
Directs the Salvager to verify the specified aggregate. The Salvager examines the structure of the aggregate to determine if it contains any inconsistencies, reporting any that it finds. See the Description section for information about using and combining the command's options.

-salvageonly
Directs the Salvager to salvage the specified aggregate. The Salvager attempts to repair any inconsistencies it finds on the aggregate. See the Description section for information about using and combining the command's options.

-force
Executes the Salvager in noninteractive mode. By default, the Salvager prompts for confirmation before proceeding in certain situations (for example, if it believes an aggregate on which it is run may be a non-LFS partition). Use this option to direct the Salvager to proceed with all operations without asking whether it should continue. Use this option with care; the Salvager's changes can be unpredictable if this option is used with an invalid aggregate.

-verbose
Directs the Salvager to produce detailed information about the aggregate as it executes. The information is useful primarily for debugging purposes. It is displayed on standard output (which can be redirected). Use this option alone or with any combination of the available options.

-help
Prints the online help for this command. All other valid options specified with this option are ignored.

The help and apropos commands available with all command suites are also available with the salvage command. See the bos help and bos apropos reference pages for examples using these commands.

Description
The dcelocal/bin/salvage command invokes the DFS Salvager on the DCE LFS aggregate specified with the -aggregate option. Following a system restart, the Salvager employs the DCE LFS log mechanism to return consistency to a file system by running recovery on the aggregate on which the file system resides. Recovery is the replaying of the log on the aggregate; the log records all changes made to metadata as a result of operations such as file creation and deletion. If problems are detected in the basic structure of the aggregate, if the log mechanism is damaged, or if the storage medium of the aggregate is suspect, the salvage command must be used to verify or repair the structure of the aggregate.

Use the command's -recoveronly, -verifyonly, and -salvageonly options to indicate the operations the Salvager is to perform on the specified aggregate, as follows:

· Specify the -recoveronly option
To run recovery on the aggregate without attempting to find or repair any inconsistencies found on it. Recovery is the replaying of the log on the aggregate. Use this option to quickly return consistency to an aggregate that does not need to be salvaged; this represents the normal production use of the Salvager. Unless the contents of the log or the physical structure of the aggregate is damaged, replaying the log is an effective guarantee of a file system's integrity.

· Specify the -verifyonly option
To determine whether the structure of the aggregate contains any inconsistencies without running recovery or attempting to repair any inconsistencies found on the aggregate. Use this option to assess the extent of the damage to an aggregate. The Salvager makes no modifications to an aggregate during verification. Note that it is normal for the Salvager to find errors when it verifies an aggregate that has not been recovered; the presence of an unrecovered log on an aggregate makes the findings of the Salvager, positive or negative, of dubious worth.

· Specify the -recoveronly and -verifyonly options
To run recovery on the aggregate and then analyze its structure without attempting to repair any inconsistencies found on it. Use these options if you believe replaying the log can return consistency to the aggregate, but you want to verify the consistency of the aggregate after recovery is run. Recovering an aggregate and then verifying its structure represents a cautious application of the Salvager.

· Specify the -salvageonly option
To attempt to repair any inconsistencies found in the structure of the aggregate without first running recovery on it. Use this option if you believe the log is damaged or replaying the log will not return consistency to the aggregate and may in fact further damage it. Under normal circumstances, do not salvage an aggregate without first recovering it.

· Omit the -recoveronly, -verifyonly, and -salvageonly options
To run recovery on the aggregate and then attempt to repair any inconsistencies found in the structure of the aggregate. Because recovery eliminates inconsistencies in an undamaged file system, an aggregate is typically recovered before it is salvaged. In general, it is good first to recover and then to salvage an aggregate if a machine panics or experiences a hardware failure.

Omit these three options if you believe the log should be replayed before attempts are made to repair any inconsistencies found on the aggregate. (Omitting the three options is equivalent to specifying the -recoveronly and -salvageonly options.)

The following rule summarizes the interaction of the -recoveronly, -verifyonly, and -salvageonly options: The salvage command runs recovery on an aggregate and attempts to repair it unless one of the three options is specified; once one of these options is specified, you must explicitly request any operation you want the Salvager to perform on the aggregate.

The basic function of the Salvager is similar to that of the UNIX fsck program. The Salvager recovers a DCE LFS aggregate and repairs problems it detects in the structure of the aggregate. It does not verify or repair the format of user data contained in files on the aggregate. If it makes changes, the Salvager displays the path names of the files affected by the modifications, when the path names can be determined. The owners of the files can then verify the files' contents, and the files can be restored from backups if necessary.

The Salvager verifies the structure of an aggregate by examining all of the anodes, directories, and other metadata in each fileset on the aggregate. An anode is an area on the disk that provides information used to locate data such as files, directories, ACLs, and other types of file system objects. Each fileset contains an arbitrary number of anodes, all of which must reside on the same aggregate. By following the links between the various types of anodes, the Salvager can determine whether the organization of an aggregate and the filesets it contains is correct and make repairs if necessary.

Not all aggregates can be salvaged. In cases of extensive damage to the structure of the metadata on an aggregate or damage to the physical disk that houses an aggregate, the Salvager cannot repair inconsistencies. Also, the Salvager cannot verify or repair damage to user data on an aggregate. The Salvager cannot detect problems that modified the contents of a file but did not damage the structure of an aggregate or change the metadata of the aggregate.

Like the UNIX fsck command, the Salvager analyzes the consistency of an aggregate by making successive passes through the aggregate. With each successive pass, the Salvager examines and extracts a different type of information from the blocks and anodes on the aggregate. Later passes of the Salvager use information found in earlier passes to help in the analysis.

Unlike the fsck command, the Salvager does not normally prompt for additional information as it executes. It typically performs the requested operation without prompting for input or pausing to verify any changes before it makes them. It prompts for confirmation only in the following cases:

· It believes the specified aggregate does not contain a DCE LFS file system. This can occur if it finds a non-LFS superblock whose creation time is more recent than the creation time of the DCE LFS superblock.

· It finds that the size of the aggregate recorded in the DCE LFS superblock exceeds the capacity of the partition on which the aggregate resides.

At the prompt, you can choose to cancel or continue the operation. If you continue the operation under either of these circumstances and the aggregate proves to be invalid, unpredictable results can ensue. The best response in either case is to cancel the operation and attempt to determine the cause of the problem.

If you are confident that you want the Salvager to continue in any case, you can include the -force option with the command. This option directs the Salvager to perform the requested operation without prompting for confirmation. Exercise caution when using the -force option; the Salvager can produce unpredictable results if this option is used with an invalid aggregate.

In general, the Salvager exits with an error code of at least 16 without analyzing a partition that it is sure is not a DCE LFS aggregate. It also exits with an error code of 16 if an aggregate to be recovered or salvaged is currently exported to the global namespace, or if a fileset on the aggregate to be recovered or salvaged is mounted locally. (If necessary, you can use the dfsexport command to detach an exported aggregate from the namespace.)

As the Salvager executes, it maintains a number of internal lists. Each list consists of anodes that failed verification in specific ways. When it initially scans an aggregate, the Salvager marks as "unsafe" anodes with which it encounters problems. The Salvager later attempts to determine the actual path names associated with these anodes to include the path names in the lists. When it has finished salvaging, the Salvager displays any nonempty lists. It also returns one of a number of informative exit codes, depending on the inconsistencies it found and the repairs it made. More information about the lists and exit codes displayed by the Salvager appears later in this reference page.

Internal structures maintained by the Salvager require a minimum of 1 megabyte of swap space. However, the total amount of swap space required by the Salvager depends largely on the size of the aggregate being salvaged and the extent of the damage to the aggregate.

Privilege Required
The privileges required depend on whether the -recoveronly, -verifyonly, or salvageonly option is specified with the command: If just the -verifyonly option is included, the issuer needs only the read permission for the specified device (aggregate); if the -recoveronly or -salvageonly option is included, or if all three of these options are omitted, the issuer must have both the read and write permissions for the specified device. An issuer who is logged in as root on the machine on which the specified device resides always has the necessary privilege to issue the command.

Cautions
The Salvager can be used to salvage only DCE LFS aggregates. If it is executed on a non-LFS partition, it exits with an error code of at least 16 without performing any operations. Use the UNIX fsck program or its equivalent to verify or restore consistency to non-LFS disk partitions.

By default, the Salvager asks for confirmation before proceeding with operations on aggregates that it suspects are non-LFS partitions or whose indicated sizes exceed the capacities of the partitions on which they reside. The command's -force option can be used to direct the Salvager to continue without prompting in these cases. Do not include the -force option under normal conditions; the Salvager can make undesirable changes if the option is used with an invalid aggregate.

If the Salvager is used to recover or salvage an aggregate that is currently exported, it exits with an error code of 16 without performing the operation. Use the dfsexport command to detach an aggregate from the global namespace if necessary before recovering or salvaging it. (The Salvager can be used to verify the structure of a currently exported aggregate, but this is not a good practice; the results may be misleading.) The Salvager also exits with an error code of 16 if a fileset on an aggregate to be recovered or salvaged is mounted locally.

Output
The Salvager sends output to both stdout and stderr. When it is started, the Salvager displays the device name of the aggregate on which it is run and the operation it is to perform. For example, the Salvager displays the following message if it is directed to recover an aggregate:

Will run recovery on device

Similarly, the Salvager displays the following message if it is directed to verify an aggregate:

Verifying device

If you specify the -verbose option with the command, the Salvager generates the following information about the aggregate:

· Physical information about the configuration of the aggregate

· Header information from the aggregate, including the major and minor number of the device on which the aggregate was created, and the date and time at which the aggregate was created

· Information about how space in the aggregate is allocated, including

- The total size of the aggregate in blocks

- The block size

- The fragment size

- The number of the first block in the aggregate

- The location of the principal superblock for the aggregate

- The number of logical blocks in the aggregate

If you use the Salvager to recover an aggregate and the log on the aggregate does not need to be replayed, the Salvager displays only the introductory message described previously. If the log does need to be replayed and the Salvager can successfully recover the aggregate, the Salvager displays the following messages:

Recovery statistics

statistics

Ran recovery on device

In the output, statistics consists of a few lines of information about the log and its replaying, and device is the device name of the aggregate. If it cannot run recovery for any reason, the Salvager displays an appropriate exit code (all Salvager exit codes are listed at the end of this section).

The Salvager can display much more output if it is asked to verify or salvage an aggregate on which it finds metadata errors. As it verifies or salvages a damaged aggregate, it displays a message similar to the following for each fileset in which it encounters metadata problems:

In volume fileset (avl #integer)

in anode (#integer)

description

It displays the first line once for each fileset, repeating the second and third lines once for each problem anode in the fileset. The output provides the following information:

fileset
The name and ID number of each affected fileset.

avl #integer
A pointer to the anode for the fileset.

in anode (#integer)
A pointer to the anode for a file or other object in the fileset.

description
A brief description of the problem the Salvager found with the anode. If it was used to salvage the aggregate, the Salvager also describes any actions it took to repair the anode.

When it has finished executing, the Salvager lists each file whose metadata it found to be damaged, many of which it likely repaired if it salvaged the aggregate. For each file, it displays a line of the form

condition fileset:pathname volume index: integer anode index: integer

The output provides the following information:

condition
A string that describes the state of the file or its metadata. (Information about the possible conditions follows this list.)

fileset
The name of the fileset in which the affected file resides. In some cases, the Salvager cannot determine the fileset name.

pathname
The pathname of the file, relative to the root directory of the fileset. In some cases, the Salvager cannot reconstruct the pathname for a file.

volume index
A pointer to the anode for the fileset. (This information can be used to identify earlier message displayed by the Salvager that are related to this file.)

anode index
A pointer to the anode for the file. (This information can be used to identify earlier message displayed by the Salvager that are related to this file.)

The following conditions accompany the files most in need of attention:

oughtRestore
Files in which one or more block references in the associated anode were removed or changed. Because it is unlikely such files contain all of their original data, these files should be restored from existing backups. This condition applies only to files on salvaged aggregates.

mayRestore
Files to which modifications were made (for example, files whose ACLs or property lists were changed). The owners of these files should verify their contents, or a system administrator should simply restore them from backups if a directory listing indicates that they have not been modified since the last backup was made. This condition also applies only to files on salvaged aggregates.

zeroLinkCnt
Files whose link counts should be 0 (zero). These files were deleted but not closed when the system crashed or were orphaned by the Salvager as it made repairs to the file system. The system will delete them when the aggregate is exported.

badLinkCnts
Files whose link counts were inconsistent with the number of references found to them. These files should be examined, if possible, or simply restored.

The Salvager can list a file more than once if it determines that multiple conditions apply to the file. It can also display one or more additional conditions (such as badAcls or badPlists), but files with which the additional conditions are associated are typically already covered by one or more of the conditions just described. Information in the additional lists is useful primarily for debugging purposes.

The Salvager also returns one of various exit codes to summarize its actions and findings. It returns the exit codes in the form of bits, which it uses to indicate the state of the aggregate. It can set multiple bits, but in general, the higher the bit, the greater the severity of the aggregate's problems (the higher bit always takes precedence when interpreting the output). The Salvager can return the following exit codes:

All bits off
The Salvager found no problems. It displays a message that includes Done and Checks out. The command need not be run again.

First bit (0x1) set
The Salvager found one or more problems. It displays a message that includes Done and Some inconsistencies found. Run the command on the aggregate without the -verifyonly option to attempt to correct the problems.

Second bit (0x2) set
The Salvager found one or more problems and fixed them. It displays a message that includes Done and Some inconsistencies repaired. The command need not be run again. (Note that if the second bit is set, the first bit is usually also set; because the higher bit takes precedence, you do not need to run the command again.)

Third bit (0x4) set
The Salvager found one or more problems and fixed some of them. It displays a message that includes Incomplete and Some repairs made. Some problems were more severe and require a subsequent salvage to be repaired; run the command on the aggregate without the -verifyonly option to attempt to correct the problems.

Fourth bit (0x8) set
The Salvager found the aggregate to be irreparably damaged. It displays a message that begins Problem. Use the newaggr command to reinitialize the aggregate, and reconstruct the data from existing backups if possible.

Fifth bit (0x10) set
The Salvager found some serious problem that prevents it from running on the aggregate; for example, the attempted recovery of the aggregate failed because of damage to the log, or the attempted salvage of the aggregate failed because the aggregate is not a DCE LFS aggregate, it is currently exported, or it contains a locally mounted fileset. The Salvager displays a message that begins Problem. Attempt to determine the cause of the problem.

Including the -verbose option with the command produces more detailed information about the aggregate as the command executes. However, the additional information is useful primarily for debugging purposes.

Examples
The following command instructs the Salvager to recover the DCE LFS aggregate whose device name is /dev/lv01. This example represents the most-common application of the Salvager.

# salvage /dev/lv01 -recover

The following command instructs the Salvager to analyze the structure of the aggregate to determine if it contains any inconsistencies without running recovery or attempting to repair the inconsistencies:

# salvage /dev/lv01 -verify

The following command directs the Salvager to repair any inconsistencies it finds on the aggregate without first running recovery:

# salvage /dev/lv01 -salvage

Related Information
Commands: dfsexport(8dfs)

newaggr(8dfs)

Files: dfstab(4dfs)