AUDIT CONTAINER (Verify the consistency of database information for a cloud container)

Use this command to scan for inconsistencies between database information and a container in a cloud-container storage pool. Cloud-container storage pools are not supported on Linux on System z®.

You can use this command to complete the following actions for a container in a cloud-container storage pool:

Scan the contents of a container to validate the integrity of the data extents
Remove data from a container that is marked as damaged, such as when a file has references in the server database, but has missing or corrupted data in the cloud
Mark an entire container as damaged
Remove data that is marked as orphaned, such as when an object stored in the cloud does not have a reference in the server database

Privilege class

To use this command, you must have system privilege, or unrestricted storage privilege.

Syntax


>>-AUDit CONTainer--+-container_name---------------------------------------------+-->
                    +-STGpool--=--pool_name--------------------------------------+   
                    '-STGpool--=--pool_name--STGPOOLDIRectory--=--directory_name-'   

   .-Action--=--SCANAll-----------.   
>--+------------------------------+----------------------------->
   '-Action--=--+-SCANAll-------+-'   
                +-REMOVEDamaged-+     
                +-MARKDamaged---+     
                '-SCANDamaged---'     

   .-FORCEOrphandbdel--=--No------.   
>--+------------------------------+----------------------------->
   '-FORCEOrphandbdel--=--+-No--+-'   
                          '-Yes-'     

   .-MAXProcess--=--4------.  .-Wait--=--No------.   
>--+-----------------------+--+------------------+-------------->
   '-MAXProcess--=--number-'  '-Wait--=--+-No--+-'   
                                         '-Yes-'     

   .-BEGINDate--=--before_first_audit-.   
>--+----------------------------------+------------------------->
   '-BEGINDate--=--begin_date---------'   

   .-BEGINTime--=--00:00:00---.   
>--+--------------------------+--------------------------------->
   '-BEGINTime--=--begin_time-'   

   .-ENDDate--=--after_last_audit-.  .-ENDTime--=--23:59:59-.   
>--+------------------------------+--+----------------------+--><
   '-ENDDate--=--end_date---------'  '-ENDTime--=--end_time-'

Parameters

container_name

Specifies the name of the container that you want to audit. If you do not specify this parameter, you must specify a cloud-container storage pool.

STGpool

Specifies the name of the cloud-container storage pool that you want to audit. This parameter is optional. If you specify only this parameter, all containers that are defined to the storage pool are audited. If you do not specify this parameter, you must specify a container.

STGPOOLDIRectory

Specifies the name of the cloud-container storage pool directory that you want to audit. This parameter is optional.

Restriction: You must specify a storage pool that uses local storage.

Action

Specifies what action the server takes when a container in a cloud-container storage pool is audited. This parameter is optional. You can specify one of the following values:

SCANAll: Specifies that the server identifies database records that refer to data extents with inconsistencies. A check is done for data in the cloud-container storage pool that does not match data in the server database. This value is the default. The server marks the data extent as damaged in the database.
Tip: If you specify the ACTION=SCANALL parameter on an IBM® Cloud Object Storage storage pool that uses a vault with name indexing disabled, the audit operation scans the entire vault to identify orphaned extents in each container. In this situation, specify WAIT=YES if you want the audit operation to wait for the scan for orphaned extents to complete before it reports the audit as complete. This scan for orphaned extents occurs only if you do not specify a container name. If you specify a container that is in a vault with name indexing disabled, the audit operation does not scan for orphaned extents.
REMOVEDamaged: Specifies that the server removes any references to damaged extents from the server database. The damaged extents are also removed from the cloud-container storage pool if found. The server also removes any orphaned extents from the cloud-container storage pool, and removes the references to these orphaned extents from the database, as specified by the FORCEORPHANDBDEL parameter.
MARKDamaged: Specifies that the server explicitly marks all data extents in the container as damaged.
SCANDamaged: Specifies that the server checks only the existing damaged extents in the container.

Important: If no connection to the cloud exists, the ACTION=SCANALL and ACTION=SCANDAMAGED parameters do not run. However, the ACTION=MARKDAMAGED parameter runs as expected without a cloud connection, and the ACTION=REMOVEDAMAGED parameter marks any damaged data as orphaned. As soon as the connection to the cloud returns, the server deletes the orphaned extents.

State reset condition: If the audit does not detect an error with a data extent that is marked as damaged, the state of the data extent is reset. The data extent can then be used. This condition provides a means for resetting the state of damaged data extents if errors are caused by a correctable problem. The SCANALL and SCANDAMAGED options are the only options that reset a damaged extent if it is found not to be damaged.

FORCEOrphandbdel

Specifies that the server forces the deletion of orphaned extents from the server database, even if they are not deleted from the cloud-container storage pool. This parameter is optional. If you specify this parameter, you must also specify the ACTION=REMOVEDAMAGED parameter. The following options are available:

Yes: Specifies that the server deletes any orphaned extents from the server database, even if they are not deleted from the cloud-container storage pool.
No: Specifies that the server keeps the orphaned extents in the server database if they cannot be deleted from the cloud-container storage pool. This value is the default.

MAXProcess

Specifies the maximum number of parallel processes to use for checking a container in a cloud-container storage pool. This parameter is optional. Enter a value in the range 1 - 99. The default value is 4.

Restriction: The server ignores this parameter when you use MAXPROCESS with the ACTION=REMOVEDAMAGED parameter.

Wait

Specifies whether the audit or verification operation is completed in the foreground or background. This parameter is optional. The following options are available:

No: Specifies that the operation is completed in the background. You can continue with other tasks when the command is processing. Messages that are related to the background process are displayed in the activity log file or the server console, depending on where the messages are logged. This value is the default.
Yes: Specifies that the operation is completed in the foreground. It might take a long time to complete the operation. The operation must complete before you can continue with other tasks. Messages are displayed in the activity log file or the server console, or both, depending on where the messages are logged.
Restriction: You cannot specify the WAIT=YES parameter from the server console.

BEGINDate

Specifies the date range value at which auditing should start. Containers that were last audited within the specified date range are audited. If you specify a time but do not specify a beginning date, the current date is used. If you do not specify a beginning and end date, all containers are audited. The default is the date before the first audit was completed for the container. This parameter is optional.

You can specify the date to begin the audit in one of the following ways:

Value	Description	Example
MM/DD/YYYY	A specific date.	09/15/2016
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 audit all containers that were audited in the last week, specify BEGINDATE=TODAY-7 or BEGINDATE= -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 containers that were audited 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 containers that were audited on the 10th day of the current month.

BEGINTime

Specifies the time range value at which auditing should start. Containers that were last audited within the specified time range are audited. If you do not specify a beginning and end time, the time range is set from 00:00:00 to 23:59:59. The default is 00:00:00. If you did not specify a date range, the default is today's date. This parameter is optional.

You can specify the date to begin the audit in one of the following ways:

Value	Description	Example
HH:MM:SS	A specific time on the specified begin date.	10:30:08
NOW	The current time on the specified begin date.	NOW
NOW+HH:MM or +HH:MM	The current time plus hours and minutes on the specified begin date.	NOW+03:00 or +03:00. If you issue this command at 9:00 with BEGINTIME=NOW+3 or BEGINTIME=+3, containers with a last audit time of 12:00 or later on the begin date are audited.
NOW-HH:MM or -HH:MM	The current time minus hours and minutes on the specified begin date.	NOW-04:00 or -04:00. If you issue this command at 9:00 with BEGINTime=NOW-3:30 or BEGINTime= -3:30, IBM Spectrum Protect™ audits containers with a last audit time of 5:30 or later on the begin date.

ENDDate

Specifies the date range value at which auditing should stop. Containers that were last audited within the specified date range are audited. If you specify a time but do not specify a value, the current date is used. If you do not specify a beginning and end date, all containers are audited. The default is the date after the last audit was completed for the container. This parameter is optional.

You can specify the date by using one of the following values:

Value	Description	Example
MM/DD/YYYY	A specific date.	09/15/2016
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 include containers that were audited up to yesterday, you can specify ENDDATE=TODAY-1 or ENDDATE= -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 containers that were audited 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 containers that were audited on the 10th day of the current month.

ENDTime

Specifies the time range value at which auditing should stop. Containers that were last audited within the specified time range are audited. If you do not specify a beginning and end time, the time range is set to 00:00:00 to 23:59:59. The default is 23:59:59. This parameter is optional.

You can specify the time using one of the following values:

Value	Description	Example
HH:MM:SS	A specific time on the specified end date.	10:30:08
NOW	The current time on the specified end date.	NOW
NOW+HH:MM or +HH:MM	The current time plus hours and minutes on the specified end date.	NOW+03:00 or +03:00. If you issue this command at 9:00 with ENDTIME=NOW+3:00 or ENDTIME= +3:00, containers with a last audit time of 12:00 or earlier on the end date you specify are audited.
NOW-HH:MM or -HH:MM	The current time minus hours and minutes on the specified end date.	NOW-03:30 or -03:30. If you issue this command at 9:00 with ENDTIME=NOW-3:30 or ENDTIME= -3:30, containers with a last audit time of 5:30 or earlier on the end date you specify are audited.

Example: Audit a specific container in a cloud-container storage pool

Audit the 42-00000my000example000container000 container in a cloud-container storage pool.

audit container 42-00000my000example000container000 action=scanall

Example: Audit a cloud-container storage pool within a specific time frame

Audit a cloud-container storage pool that is named POOL3 and only include containers from yesterday between 9:30 and 12:30.

audit container stgpool=pool3 begindate=today-1 
begintime=09:30:00 endtime=12:30:00

Table 1. Commands related to AUDIT CONTAINER
Command	Description
CANCEL PROCESS	Cancels a background server process.
QUERY CONTAINER	Displays information about a container.
QUERY DAMAGED	Displays information about damaged files.