DSMSERV RESTORE DB (Restore a database to its most recent state by using cloud object storage)

Edit online

IBM Storage Protect uses the cloud credentials that are provided by the DSMSERV RESTORE DB utility to obtain a device configuration file, a volume history file, and an encrypted master key file from cloud storage. These files are then used to restore the database to the most recent state that is available, based on information from cloud object storage.

The following conditions must be met:
  • An intact volume history file is available.
  • The recovery logs are available.
  • A device configuration file with the applicable device information is available.

IBM Storage Protect requests volume mounts to load the most recent backup series and then uses the recovery logs to update the database to its most recent state.

Snapshot database backups cannot be used to restore a database to its most recent state.

Attention: If the most recent volume history and device configuration files are available in the server instance home directory, cloud credentials are not required to restore the most recent database backup.

Syntax

Read syntax diagramSkip visual syntax diagram DSMSERV 1-uuser_name1-iinstance_dir-kServer12-kkey_name-ooptions_file1 -quiet RESTORE DB PReview=NoPReview=YesNoRESTOREKeys=YESRESTOREKeys=YESONLYPASSword=db_backup_passwordPROMPT=YesPROMPT=YesNoCLOUDType=AZureS3GOOGleBUCKETName=bucket_name3CLOUDUrl=cloud_urlIDentity=cloud_identity4CLOUDPAssword=cloud_password5SERVERName=server_nameKEYLocation=key_location6
Notes:
  • 1 This parameter applies only to AIX® and Linux® servers.
  • 2 This parameter applies only to Windows servers.
  • 3 The BUCKETNAME parameter is valid only if you specify CLOUDTYPE=S3 or CLOUDTYPE=GOOGLE.
  • 4 The IDENTITY parameter is valid only if you specify CLOUDTYPE=S3.
  • 5 The CLOUDPASSWORD parameter does not apply if you specify CLOUDTYPE=GOOGLE.
  • 6 The KEYLOCATION parameter is valid only if you specify CLOUDTYPE=GOOGLE.

Parameters

Linux operating systemsAIX operating systems-u user_name
Linux operating systemsAIX operating systemsSpecifies a user name to switch to after the database is restored and the server is initialized.
Linux operating systemsAIX operating systems-i instance_dir
Linux operating systemsAIX operating systemsSpecifies an instance directory to use. This instance directory becomes the current working directory of the server.
Windows operating systems-k key_name
Windows operating systemsSpecifies the name of the Windows registry key from which to retrieve information about the server. The default is SERVER1.
-o options_file
Specifies an options file to use.
Linux operating systemsAIX operating systems-quiet
Linux operating systemsAIX operating systemsSpecifies that messages to the console are suppressed.
PReview
If PREVIEW=YES, specifies that the volume history file and database backup volumes are analyzed. The system identifies the database backup volumes that best meet the criteria for restore processing. If the volume history information is consistent with the self-describing data, a message will be issued to indicate that the database backup can be used for restore processing. If the volume history information is inconsistent with the self-describing data or the backup cannot be found, error messages are issued.

If the PREVIEW parameter is not specified or set to NO, and if the volume history and self-describing data from the database backup are consistent, the restore operation proceeds.

If the PREVIEW parameter is not specified or set to NO, and the reconciliation and validation fail, the database restore operation is not completed. To resolve this issue, ensure that extra volumes are available for the database restore operation and referred to from the volume history file. Or, remove the incomplete backup series or operation so that the server selects a different preferred series or operation and continues the database restore process.

RESTOREKeys
Specifies whether to restore the database when the server master encryption key is restored. This parameter is optional. The default is YES. You can specify one of the following values:
Yes
Specifies that the server master key that is used to encrypt storage pool data is restored when the database is restored.
Only
Specifies that only the server master key is restored. The database is not restored.
PASSword
Specifies the password that is used to protect the database backup. This password was set by using the SET DBRECOVERY or the BACKUP DB command.
Attention: If you use this parameter to specify a password, the password is displayed on the command line and is not secure. If you specify a value for the PASSWORD parameter, you must also specify PROMPT=NO; otherwise, the command fails. To help protect the password, use the PROMPT=YES parameter value instead of the PASSWORD parameter to ensure that users are prompted for the password. When you use the PROMPT=YES parameter value, the password is not displayed on the command line.
If you specify a password for database backup, you must specify the same password on the RESTORE DB command to restore the database. If you specify any of the following parameter values, you must use a password with either the PROMPT=YES parameter value or the PASSWORD parameter.
  • On the DSMSERV RESTORE DB command, RESTOREKEYS=YES
  • On the DSMSERV RESTORE DB command, RESTOREKEYS=ONLY
  • On the SET DBRECOVERY command, PROTECTKEYS=YES
PROMPT
Specifies whether to prompt the user for the password that is used to protect the database backup.
Yes
Specifies that the server prompts the user for the password that is used to protect the database backup. This setting helps to protect the password and is the default when a password is required.
No
Specifies that the server does not prompt the user for the password. Instead, the server uses the password that is specified by using the PASSWORD parameter. If you use the PASSWORD parameter along with the PROMPT=NO parameter value, the password is displayed on the command line, and unauthorized users might access the password. If you specify the PASSWORD parameter, you must also specify the PROMPT=NO parameter value.
CLOUDType
Specifies the type of cloud environment in which to look for the required configuration files. This parameter is optional.
AZure
Specifies that the connection uses a Microsoft Azure cloud computing system.
S3
Specifies that the connection uses a cloud computing system with the Simple Storage Service (S3) protocol, such as IBM Cloud Object Storage or Amazon Web Services (AWS) S3.
GOOGle
Specifies that the connection uses a Google Cloud Storage cloud computing system.
BUCKETName
Specifies the name for an AWS S3 or Google Cloud Storage bucket or an IBM Cloud Object Storage vault in which to look for the required configuration files. This parameter is required and is valid only if you specify CLOUDTYPE=S3 or CLOUDTYPE=GOOGLE. If you specified CLOUDTYPE=Azure, do not specify the BUCKETNAME parameter.
The bucket must exist and have reading, writing, and listing permissions.
CLOUDUrl
Specifies the URL of the object storage environment in which to look for the required configuration files. If you specified CLOUDTYPE=GOOGLE, do not specify the CLOUDURL parameter. Based on your cloud provider, you can use a blob service endpoint, region endpoint URL, an Accesser IP address, a public authentication endpoint, or a similar value for this parameter. Ensure that you include the protocol, such as https:// or http://, at the beginning of the URL. The maximum length of the web address is 870 characters. This parameter is required to retrieve configuration files from object storage.
For IBM Cloud Object Storage users: To optimize performance, use multiple Accessers. To use more than one IBM Cloud Object Storage Accesser, list the Accesser IP addresses separated by a vertical bar (|), with no spaces, surrounded by quotation marks, as in the following example:
cloudurl="accesser_url1|accesser_url2|accesser_url3"
IDentity
Specifies the user ID for the cloud that is specified in the CLOUDURL parameter. This parameter is required and valid only if you specify CLOUDTYPE=S3. If you specified CLOUDTYPE=Azure or CLOUDTYPE=GOOGLE, do not specify the IDENTITY parameter. Based on your cloud provider, you can use an access key ID, a user name, a tenant name and user name, or a similar value. The maximum length of the user ID is 255 characters.
Tip: To specify a tenant name and user name, use the following format:
tenant_name.user_name
CLOUDPAssword
Specifies the password for the cloud that is specified in the CLOUDURL parameter. If you specified CLOUDTYPE=GOOGLE, do not specify the CLOUDPASSWORD parameter. Based on your cloud provider, you can use a shared access signature (SAS) token, secret access key, an API key, a password, or a similar value for this parameter. This parameter is required to retrieve configuration files from cloud object storage. The maximum length of the password is 255 characters. If the password contains special characters, enclose it in double quotation marks (").
Attention: If you use this parameter to specify a password, the password is displayed on the command line and is not secure. If you specify a value for the CLOUDPASSWORD parameter, you must also specify PROMPT=NO; otherwise, the command fails. To help protect the password, use the PROMPT=YES parameter value instead of the CLOUDPASSWORD parameter to ensure that users are prompted for the password. When you use the PROMPT=YES parameter value, the password is not displayed on the command line.
SERVERName
Specifies the name of the server that you are restoring. This parameter applies only to retrieving configuration files from cloud object storage. The server name and globally unique identifier (GUID) might be required to determine the location of the configuration files in object storage. The parameter is required only if database backup volumes from more than one server are in the same bucket in object storage. If database backups from multiple servers are in the same bucket and this parameter is not specified, you are prompted to select the correct location for your database backup.

This value can be either the server name or the server name plus the server GUID separated by a hyphen. For example, if your server is named server1 and your server GUID is fcbid280a8bd11e8g77b54e1adee4e87, this value can be server1 or server1-fcbid280a8bd11e8g77b54e1adee4e87. The maximum length of the name is 85 characters.

KEYLocation
Specifies the name of the file that contains the Google Cloud Storage service account key in JavaScript Object Notation (JSON) format. This parameter is required and is valid only if you specify CLOUDTYPE=GOOGLE. If you specified CLOUDTYPE=AZURE or CLOUDTYPE=S3, do not specify the KEYLOCATION parameter.
The restore operation requires that the key location file is in the location that is specified by the device configuration file. If the key location changed and no longer matches the location that was specified in the original device configuration file, change the Google Cloud Storage key file to the location that is specified in the device configuration file and retry the restore operation.

Example: Restore the database to its most recent state

Restore the database to its most recent state.
 dsmserv restore db

Example: In a disaster recovery scenario, obtain required configuration files from cloud object storage

Restore the server database by using object storage to obtain required configuration files, issue the following command on one line:
dsmserv restore db cloudtype=s3 
bucketname=cloudbucket cloudurl=http://123.234.123.234 
identity=admin:admin cloudpassword="protect&8991" 
servername=server1-fcbid280a8bd11e8g77b54e1adee4e87

Example: Restore the server master key without restoring the database

Restore the server master key without restoring the database by issuing the following command:
dsmserv restore db restorekeys=only