ioefsutl salvage

Purpose

ioefsutl salvage is a batch utility that scans an aggregate and reports inconsistencies. Aggregates can be verified, recovered (that is, the log is replayed), or salvaged (that is, the aggregate is repaired). This utility is known as the salvager.

This utility is not normally needed. If a system failure occurs, the aggregate log is replayed automatically the next time the aggregate is attached or mounted. This action typically brings the aggregate back to a consistent state. The aggregate must not be mounted or attached when ioefsutl salvage is run.

Format

ioefsutl salvage -aggregate name [-verifyonly][-level][-help]

Options

-aggregate name
Specifies the name of the aggregate to be verified or salvaged. The aggregate name is not case-sensitive. It is converted to uppercase.
-help
Prints the online help for this command. All other valid options that are specified with this option are ignored.
-level
Prints the level of the ioefsutl command. This information is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.
-verifyonly
Specifies that the salvager is to verify the specified aggregate. It should not attempt to repair any damage that was found. The log is replayed before the verification unless an error occurs during the replay. If this option is omitted, the salvager will replay the log, verify the specified aggregate, and then attempt to repair any damage that was found.

Results

For -verifyonly, the salvager returns the following return codes:
Return code Explanation
00 Success. The aggregate is correct and no repair is needed.
04 The aggregate has some inconsistencies that need repair.
08 An error occurred during verification; the report might be incomplete.
12 A severe error occurred during verification. Verify that processing was halted. The aggregate is not repairable.
16 Terminating error.
EIO The salvager could not read or write the DASD.
EBUSY The aggregate was mounted or attached.
EMVSERR The salvager had an internal error. This return code is preceded by a dump for an abend 2C3 and reason code EA660701.
ENOMEM The salvager ran out of storage.
EINVAL The salvager arguments were incorrect.
For no options specified, the salvager returns the following return codes:
Return code Explanation
00 Success. The aggregate is correct and no repair is needed.
04 The aggregate has some inconsistencies that were repaired.
08 An error occurred during verification; the report might be incomplete; the aggregate could not be repaired.
12 A severe error occurred during verification; verify that processing has stopped; the aggregate could not be repaired.
16 Terminating error.
EIO The salvager could not read or write the DASD.
EBUSY The aggregate was mounted or attached.
EMVSERR The salvager had an internal error. This return code is preceded by a dump for an abend 2C3 and reason code EA660701.
ENOMEM The salvager ran out of storage.
EINVAL The salvager arguments were incorrect.

Usage notes

  1. You can run ioefsutl salvage even if the zFS PFS is not active on the system. The ioefsutl salvage utility invokes the salvager on the zFS aggregate that is specified with the -aggregate option.
  2. The salvager cannot process an aggregate that contains multiple file systems or a clone.
  3. The processing of the aggregate is controlled by the specification or the omission of the -verifyonly option.
    • Specify the -verifyonly option

      To determine whether the structure of the aggregate contains any inconsistencies. Use this option to assess the extent of the damage to an aggregate. The salvager runs log recovery and then determines whether there are any inconsistencies. No repair is attempted other than running log recovery.

    • Omit the -verifyonly option

      To run log recovery on the aggregate, verify the aggregate and then attempt to repair any inconsistencies that are found in the structure of the aggregate. Because log recovery eliminates inconsistencies in an undamaged file system, an aggregate is typically recovered before it is salvaged. In general, it is good practice to first recover and then to salvage an aggregate if a system goes down or experiences a hardware failure.

  4. The salvager sets the backup change activity flag if log recovery is run or a repair is done.
  5. The basic function of the salvager is similar to that of the fsck program in many UNIX systems. The salvager recovers a zFS aggregate and repairs problems it detects in the structure of the aggregate. It does not verify or repair the format of user data that is contained in files on the aggregate.
  6. The salvager verifies the structure of an aggregate by examining all of the anodes, directories, and other metadata in each file system on the aggregate. An anode is an area on the disk that provides information that is used to locate data such as files, directories, ACLs, and other types of file system objects. Each file system 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 file system that it contains is correct and make repairs if necessary.
  7. 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.
  8. The salvager is designed to make all repairs in one pass. However, due to the nature of the program's inputs (a corrupted, possibly vastly corrupted file system), IBM® recommends a second running of the salvage program to verify that the aggregate is truly repaired. If verifying the aggregate shows that it is not repaired, then try running the salvager again to repair the aggregate. If this action does not repair the aggregate, you can create a copy of the aggregate and run the salvager more times to try to repair it. If the salvager cannot repair the aggregate after several repair attempts, the copy of the aggregate and salvager job logs will allow IBM service to determine why.
  9. Like the 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 that was found in earlier passes to help in the analysis.
  10. It is possible for the salvager to attempt a dynamic grow of an aggregate. One possible reason for this is if an extended (v5) directory is found to be inconsistent (or broken). The salvager will try to repair it by converting it to a new extended (v5) directory. To do this might require more disk space. If the disk space is not available the directory is marked read-only. The rest of the file system has already been made consistent, so you should still be able to mount the file system and read from the directory.
  11. In general, if the salvager is invoked for a VSAM linear data set that it is sure is not a zFS aggregate, it exits with an error code of at least 16 without analyzing the VSAM linear data set. It exits with an error code of EBUSY (114) if a file system on the aggregate to be recovered or salvaged is mounted or attached. (If necessary, you can use the unmount command to unmount the aggregate.)
  12. As the salvager runs, it maintains a list of sorted error records that need repair. Each record includes details for the salvager to quickly repair the aggregate. The salvager displays corruption messages if verification found any inconsistencies. It also displays progress messages (IOEZ00782I) during verification to indicate how many objects were processed. Depending on the aggregate size and system usage, the salvager batch job may take hours or even longer to complete.
  13. For more information about running the salvage utility, see Understanding the salvager utility.
  14. For a batch job, the ioefsutl salvage options are specified in the EXEC PARM as a single subparameter (a single character string enclosed in apostrophes with no commas separating the options). You cannot put the ending apostrophe in column 72. If it needs to go to the next line, use a continuation character in column 72 (continuing in column 16 with the ending apostrophe on the second line). Remember that a JCL EXEC PARM is limited to 100 characters. For more information about PARM parameter, see z/OS MVS JCL Reference. For an example of the EXEC PARM for ioefsutl salvage, see Figure 1.
  15. ioefsutl salvage can be used to salvage aggregate versions 1.4 and 1.5.
  16. The salvager utility can set or clear the aggregate damaged bit:
    • The -verifyonly option can set the bit if a true corruption is found or clear it if no corruption is found.
    • Repair (with no option) can clear the bit if a successful repair is done.
  17. ioefsutl salvage can also be used to salvage aggregates that contain data that is compressed, encrypted, or both compressed and encrypted.

Privilege required

The issuer must be logged in as a root user (UID=0) or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.

Examples

Figure 1 shows an example of a job to salvage a zFS aggregate:
Figure 1. Job to verify a zFS aggregate using debug parameters specified in IOEZPRM
//USERIDA JOB ,'Salvage verify',
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//SALVAGE  EXEC PGM=IOEFSUTL,REGION=0M,
// PARM=('salvage -aggregate OMVS.PRV.COMPAT.AGGR001 -verifyonly')
//IOEZPRM DD DSN=SYS4.PVT.SY1.PARMLIB(IOEFSPRM),DISP=SHR
//SYSPRINT DD SYSOUT=H
//STDOUT   DD SYSOUT=H
//STDERR   DD SYSOUT=H
//SYSUDUMP DD SYSOUT=H
//CEEDUMP  DD SYSOUT=H
//*

In the PARM=('salvage -aggregate OMVS.PRV.COMPAT.AGGR001 -verifyonly') statement, the salvage and options -aggregate and -verifyonly must be in lowercase.