AUDIT VOLUME (Verify database information for a storage pool volume)

Edit online

Use this command to check for inconsistencies between database information and a storage pool volume. The server checks for inconsistencies by comparing metadata in the volume with metadata that is saved for the volume on the server database. Processing information that is generated during an audit is sent to the activity log and server console.

Restrictions:
  • You cannot use this command for volumes that are assigned to copy-container storage pools.
  • You can audit only volumes that belong to storage pools with DATAFORMAT=NATIVE and DATAFORMAT=NONBLOCK.
  • You cannot audit a volume if it is being deleted from a primary or copy storage pool.
  • While an audit process is active, clients cannot restore data from the specified volume or store new data to that volume.
When the server detects a file with errors, the following conditions affect how the file is processed:
  • The type of storage pool to which the volume belongs
  • Whether the FIX option is specified on the AUDIT VOLUME command
  • Whether the file is also stored on a volume that is assigned to other pools

If IBM Storage Protect does not detect errors for a file that was marked as damaged, the state of the file is reset so that it can be used.

The server does not delete archive files that are on deletion hold. If archive retention protection is enabled, the server does not delete archive files whose retention period has not expired.

To display information about the contents of a storage pool volume, use the QUERY CONTENT command.

To audit multiple volumes, you can use the FROMDATE and TODATE parameters. Use the STGPOOL parameter to audit all volumes in a storage pool. When you use the parameters FROMDATE, TODATE, or both, the server limits the audit to only the sequential media volumes that meet the date criteria, and automatically includes all online disk volumes in storage. To limit the number of volumes that might include disk volumes, use the FROMDATE, TODATE, and STGPOOL parameters.

If you are running a server with archive retention protection enabled, and you have data that is stored in storage pools that are defined with the parameter RECLAMATIONTYPE=SNAPLOCK, the Last Access Date on the NetApp SnapLock Filer for a volume should be equal to the End Reclaim Period date that you see when you issue a QUERY VOLUME F=D command on that volume. During AUDIT VOLUME processing, these dates are compared. If they do not match and the AUDIT VOLUME command is being run with the FIX=NO parameter, a message is issued to prompt you to resolve the inconsistency by running the command with the FIX=YES parameter. If they do not match and the AUDIT VOLUME command is being run with the FIX=YES parameter, the inconsistencies are resolved.

Attention: Use the FIX=Yes parameter only if your tape drive and storage area network (SAN) infrastructure is stable. Ensure that the tape heads are clean and that the tape device drivers are stable and reliable. Otherwise, you risk deleting data that is error free when you use this parameter. The server cannot determine whether a tape is physically damaged or whether a tape infrastructure is unstable.

This command creates a background process that can be canceled with the CANCEL PROCESS command. To display information on background processes, use the QUERY PROCESS command.

Privilege class

To issue this command, you must have system privilege, unrestricted storage privilege, or restricted storage privilege for the storage pool to which the volume is defined.

Syntax

Read syntax diagramSkip visual syntax diagramAUDit Volume volume_nameAFix=NoFix=NoYesSKIPPartial=NoSKIPPartial=NoYesQuiet=NoQuiet=NoYes1READCLOUDDATA=CONDitionalREADCLOUDDATA=CONDitionalYes
A (at least one of these parameters must be specified)
Read syntax diagramSkip visual syntax diagram2STGPool=poolname2RETSet3=retset_id2FROMDate=TODAYFROMDate=dateTODate=TODay2TODate=date
Notes:
  • 1 The READCLOUDDATA parameter applies only to cloud volumes.
  • 2 You cannot specify a volume name if you specify a storage pool name, retention set ID, FROMDATE, or TODATE.
  • 3 You can filter a list of volumes that contain data for a retention set by specifying the RETSET parameter with one or more of the following parameters: STGPOOL, FROMDATE, and TODATE.

Parameters

volume_name
Specifies the name of the storage pool volume you want to audit. This parameter is required if you do not specify a storage pool. You cannot specify a volume name together with the FROMDATE and TODATE parameters.
Fix
Specifies how the server resolves inconsistencies between the database inventory and the specified storage pool volume. This parameter is optional. The default is NO.
Files are processed differently, depending on whether the volume is assigned to a primary or a copy storage pool.
  • Primary storage pool:
    Note: If the AUDIT VOLUME command does not detect an error in a file that was previously marked as damaged, IBM Storage Protect resets the state of the file so that it can be used. This error detection behavior provides a means for resetting the state of damaged files if it is determined that the errors were caused by a correctable hardware problem such as a dirty tape head.
    Fix=No
    IBM Storage Protect reports, but does not delete, database records that refer to files with inconsistencies:
    • IBM Storage Protect marks the file as damaged in the database. If a backup copy is stored in a copy storage pool, you can restore the file by using the RESTORE VOLUME or RESTORE STGPOOL command.
    • If the file is a cached copy, you must delete references to the file on this volume by issuing the AUDIT VOLUME command and specifying FIX=YES. If the physical file is not a cached copy, and a duplicate is stored in a copy storage pool, it can be restored by using the RESTORE VOLUME or RESTORE STGPOOL command.
    Fix=Yes
    The server fixes any inconsistencies as they are detected:
    • If the physical file is a cached copy, the server deletes the database records that refer to the cached file. The primary file is stored on another volume.
    • If the physical file is not a cached copy, and the file is also stored in one or more copy storage pools, the error is reported and the physical file marked as damaged in the database. You can restore the physical file by using the RESTORE VOLUME or RESTORE STGPOOL command.
    • If the physical file is not a cached copy, and the physical file is not stored in a copy storage pool, each logical file for which inconsistencies are detected are deleted from the database.
    • If archive retention protection is enabled by using the SET ARCHIVERETENTIONPROTECTION command, a cached copy of data can be deleted if needed. Data in primary and copy storage pools can only be marked damaged and never deleted.

    Do not use the AUDIT VOLUME command with FIX=YES if a restore process (RESTORE STGPOOL or RESTORE VOLUME) is running. The AUDIT VOLUME command might cause the restore to be incomplete.

  • Copy storage pool:
    Fix=No
    The server reports the error and marks the physical file copy as damaged in the database.
    Fix=Yes
    The server deletes any references to the physical file and any database records that point to a physical file that does not exist.
SKIPPartial
Specifies whether IBM Storage Protect ignores partial files, which are files that span multiple storage pool volumes. This parameter is optional. The default value is NO. When you perform an audit operation on a sequential access media volume, this parameter prevents additional sequential access media mounts that might be necessary to audit any partial files. You can specify one of the following values:
No
IBM Storage Protect audits files that span multiple volumes.
Unless you specify SKIPPARTIAL=YES, IBM Storage Protect attempts to process each file stored on the volume, including files that span into and out of other volumes. To audit files that span multiple volumes, the following conditions must be true:
  • For sequential access volumes, the additional sequential access volumes must have an access mode of read/write or read-only.
  • For random access volumes, the additional volumes must be online.
Yes
IBM Storage Protect audits only files that are stored on the volume to be audited. The status of any partial files is unknown.
Quiet
Specifies whether IBM Storage Protect sends detailed informational messages to the activity log and the server console about irretrievable files on the volume. This parameter is optional. The default is NO. You can specify one of the following values:
No
Specifies that IBM Storage Protect sends detailed informational messages and a summary. Each message contains the node, file space, and client name for the file.
Yes
Specifies that IBM Storage Protect sends only a summary report.
READCLOUDDATA
Specifies whether IBM Storage Protect reads data in the cloud volume to detect possible inconsistencies after IBM Storage Protect compares the entity tag (ETag) that is reported by the cloud service to the ETag that is saved in the server database. This parameter is optional. The default value is CONDITIONAL. You can specify one of the following values:
CONDitional
Specifies that IBM Storage Protect reads data in the cloud volume only if the ETag that is reported by the cloud service does not match the ETag that is saved in the server database. If the ETags match, IBM Storage Protect does not read the metadata.
Yes
Specifies that IBM Storage Protect reads data in the cloud volume, even if the ETag that is reported by the cloud service matches the ETag that is saved in the server database.

If the ETag that is saved in the server database does not match the ETag that is reported by the cloud service, and IBM Storage Protect does not find inconsistencies in the data, the ETag that is saved in the server is updated to match the ETag that is reported by the cloud service.

FROMDate
Specifies the beginning date of the range to audit volumes. The default is the current date. All sequential media volumes meeting the time range criteria that were written to after this date are audited. The server includes all online disk volumes in storage. The server starts one audit process for each volume and runs the process serially. You cannot use this parameter if you specified a volume. This parameter is optional. To limit the number of volumes that can include disk volumes, use the FROMDATE, TODATE, and STGPOOL parameters.
You can specify the date by using one of the following values:
Value Description Example
MM/DD/YYYY A specific date 10/15/2001

If a date is entered, all candidate volumes that are written on that day (starting at 12:00:01 am) are evaluated.

TODAY The current date TODAY
TODAY-days or -days The current date minus days specified. The maximum number of days you can specify is 9999. TODAY –7 or –7.

To display information beginning with volumes written a week ago, you can specify FROMDATE=TODAY-7 or FROMDATE= -7.

EOLM (End Of Last Month) The last day of the previous month. EOLM
EOLM-days The last day of the previous month minus days specified. EOLM-1

To include files that were active a day before the last day of the previous month.
BOTM (Beginning Of This Month) The first day of the current month. BOTM
BOTM+days The first day of the current month, plus days specified. BOTM+9

To include files that were active on the 10th day of the current month.
TODate
Specifies the ending date of the range for volumes to audit. All sequential media volumes meeting the time range criteria that were written to before this date are audited. The server includes all online disk volumes in storage. If you do not specify a value, the server defaults to the current date. You cannot use this parameter if you specified a volume. This parameter is optional. To limit the number of volumes that can include disk volumes, use the FROMDATE, TODATE, and STGPOOL parameters.
You can specify the date by using one of the following values:
Value Description Example
MM/DD/YYYY A specific date 10/15/2001

If a date is entered, all candidate volumes that are written on that day (ending at 11:59:59 pm) are evaluated.

TODAY The current date TODAY
TODAY-days or -days The current date minus days specified. The maximum number of days you can specify is 9999. TODAY–1 or –1.

To display information was created up to yesterday, you can specify TODATE=TODAY-1 or simply TODATE= -1.

EOLM (End Of Last Month) The last day of the previous month. EOLM
EOLM-days The last day of the previous month minus days specified. EOLM-1

To include files that were active a day before the last day of the previous month.
BOTM (Beginning Of This Month) The first day of the current month. BOTM
BOTM+days The first day of the current month, plus days specified. BOTM+9

To include files that were active on the 10th day of the current month.
STGPool
This parameter specifies that the server only audits the volumes from the specified storage pool. This parameter is optional. You cannot use this parameter if you specified a volume.
RETSet
This parameter specifies that the server audits only the volumes from the specified retention set. This parameter is optional. You cannot use this parameter if you specified a volume.

Example: Verify database information for a specific storage pool volume

Verify that the database information for storage pool volume PROG2 is consistent with the data that is stored on the volume. IBM Storage Protect fixes any inconsistencies.
audit volume prog2 fix=yes

Example: Verify database information for all volumes written to during a specific date range

Verify that the database information for all eligible volumes that were written to from 3/20/2002 to 3/22/2002 is consistent with data that is stored on the volume.
audit volume fromdate=03/20/2002 todate=03/22/2002

Example: Verify database information for all volumes in a specific storage pool

Verify that the database information for all volumes in storage pool STPOOL3 is consistent with data that is stored on the volume for today.
audit volume stgpool=STPOOL3

Example: Verify database information for all volumes in a specific storage pool written to in the last two days

Verify that the database information for all volumes in storage pool STPOOL3 is consistent with data that is stored on the volume for the last two days.
audit volume stgpool=STPOOL3 fromdate=-1

Related commands

Table 1. Commands related to AUDIT VOLUME
Command Description
CANCEL PROCESS Cancels a background server process.
QUERY CONTENT Displays information about files in a storage pool volume.
QUERY PROCESS Displays information about background processes.
QUERY VOLUME Displays information about storage pool volumes.
SET ARCHIVERETENTIONPROTECTION Specifies whether data retention protection is activated.