Backup Run REST Service

Use the Backup Run REST Service to run the backup task to create backup files. The backup files contain critical data for the current state of the IBM Security Guardium Key Lifecycle Manager server.

You can run only one backup or restore task at a time. Sufficient disk space must be available to contain the backup files.

The timestamp on a backup file has a Greenwich Mean Time (GMT) offset represented in RFC 822 format. The file name contains a +hhmm or -hhmm element to specify a time zone ahead of or behind GMT. For example, a file name might be sklm_v2.7.0.0_20160123144220-0800_backup.jar, where -0800 indicates that the time zone is 8 hours behind GMT.
Note: Backup success messages are system wide. Two administrators might run backup tasks that overlap in time. During this interval, the administrator who starts a second task that fails might see a false success message from the first backup task.
Operation
POST
URL
https://host:port/rest/v1/ckms/backups

By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify this default port.

Request

Request Parameters
Parameter Description
host Specify the IP address or hostname of the IBM Security Guardium Key Lifecycle Manager server.
port Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests.
Request Headers
Header name Value
Content-Type application/json
Accept application/json
Authorization SKLMAuth userAuthId=<authIdValue>
Accept-Language Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de.
Request body

JSON Object with the following specification.

JSON property name Description
backupDirectory

Specify the directory where you want to store the JAR files. The JAR files contain backup data for IBM Security Guardium Key Lifecycle Manager. You must specify the full path to the directory. This directory must be in the SKLM_DATA directory.

If the backup is successful, the value that you specify is written as the value of the tklm.backup.dir property in the SKLMConfig.properties file. Follow these guidelines to run the backup task:
  • If no prior successful backup was run, and you do not specify a value for this parameter, the default directory is SKLM_HOME/data.
  • Do not create the backup file in the same directory that contains the database backup.
databaseBackupDirectory
Optional parameter. A directory in the IBM Security Guardium Key Lifecycle Manager database that contains temporary backup data for IBM Security Guardium Key Lifecycle Manager. If no parameter is specified, the directory that is used is the value of the tklm.backup.db2.dir property in the datastore.properties file. The file is located in the WAS_HOME\products\sklm\config directory, or a temporary system directory if the directory specified by the tklm.backup.db2.dir property does not exist.
Note: Use this parameter only when you want to configure IBM Security Guardium Key Lifecycle Manager for high performance backup and restore operations (enableHighScaleBackup property is set to true in the Server Configuration property file).

Specify the parameter value without a space character.

description

You can include more information about the purpose or use of the backup file.

password You must specify this parameter for the following conditions:
  • When password-based encryption is used for the backups.
  • When an external master keystore (for example, HSM) is configured and the password-based encryption is used for the backups.
    Note: If the backup encryption method is based on external master keystore, you need not specify the password. For more information, see HSM-based encryption for backups.

Specify a password to encrypt data in the backup file. For more information, see Password policy.

You can use a different password for each backup file. When you restore a backup file, you must provide the password that was used to encrypt file during the backup operation.

replica

Specifies whether the backup file that is generated can be used as a replication backup to directly restore on a clone.

By default, the backup cannot be used as a replication backup. The default value of the parameter is n.

To use the backup as a replication backup, specify the parameter value as y.
Note: When you specify the value of the replica parameter as y, the replication configuration file is not backed up.

Response

Response Headers
Header name Value and description
Status Code
200 OK
The request was successful. The response body contains the requested representation.
400 Bad Request
The authentication information was not provided in the correct format.
401 Unauthorized
The authentication credentials were missing or incorrect.
404 Not Found Error
The processing of the request fails.
500 Internal Server Error
The processing of the request fails because of an unexpected condition on the server.
Content-Type application/json
Content-Language Locale for the response message.
Success response body

JSON object with the following specification.

JSON property name Description
code Returns the code that is specified by the status property.
status Returns the status message that indicates whether the backup was successful.
-1
State is unknown. The task is not run since the last time the IBM Security Guardium Key Lifecycle Manager server started.
0
The backup task succeeded.
1
The backup task failed.
2
Backup task succeeded with a warning.
Error Response Body

JSON object with the following specification.

JSON property name Description
code Returns the application error code.
message Returns a message that describes the error.
Note: Backup Run REST Service returns the 500 Internal Server Error response when a backup operation fails. In the response body, you can see only the status message without status code 1.

Examples

Service request to run a backup task
POST https://localhost:port/SKLM/rest/v1/ckms/backups
{"password":"passw0rd"}
Success response
Status Code : 200 OK
Content-Language: en
{"code":"0","status":"Backup operation succeeded."}
Service request with incorrect backup directory
POST https://localhost:port/SKLM/rest/v1/ckms/backups
{"backupDirectory": "backup",
  "description": "Backup file 1",
  "databaseBackupDirectory": "string",
  "password": "Backupfile@123",
  "replica": "n"} 
}'
Error response
{
  "code": "CTGKM0901E",
  "message": "CTGKM0901E Backup operation fails because the backup directory cannot be resolved. Specify a valid backup directory name and path, and retry the operation."
}