Backups
Backups are generated on the appliance and are stored there until deleted. They can be downloaded from the appliance and uploaded back to the same or to another appliance. When a backup is created, it is always encrypted with a backup key. If a backup key is not specified, the default backup key is used to encrypt the backup. This backup key is required to restore the backup file.
Backups and backup keys are not automatically copied to other nodes in a cluster. They only exist on a node where they are created or copied to. Backups are treated as resources and are controlled through the API, ksctl, and GUI.
CipherTrust Manager supports system backups and domain scoped backups.
Note
Backup jobs can also be scheduled to run periodically in the background. Refer to Scheduling Backups for details.
System Backups
System backups are a snapshot of the database in an appliance at a point in time. They are created on the appliance, and after creation, they can be used to:
Restore the appliance to a previous state
Transfer the backup to another appliance to restore on that appliance
Create a new appliance with the backup
A backup can optionally be tied to an HSM for increased protection of the data. This means that the backup can only be restored to an appliance that contains the same HSM root key as was used when the backup was taken. Unless the appliances share the same HSM partition and therefore also the HSM root key, a backup tied to the HSM cannot be restored to any other appliance. Also, if the HSM is tampered and the HSM root key is deleted, a backup tied to that HSM cannot be restored. This feature improves the protection of backup files, but requires careful management of the HSM root key used for the backup, otherwise, the data loss is possible.
CipherTrust Manager users (such as Application Administrators), who are authorized to perform backup, can perform system backups and restores. Domain administrators are not authorized to perform system backups.
Note
System backups cannot be restored on a cluster node. The cluster Remove/Rebuild method should be used to restore a system backup.
Backup contents
A system backup includes the following:
All domain resources
Keys, key attributes, and key links
Users, groups, and their relationships
Local CAs
External CAs
Certificates
Policies
Cluster information
Audit records
Syslog connections
Resources of all supported applications: Keys & Access Management, Admin Settings, Data Discovery, ProtectDB, ProtectFile, ProtectV, ProtectApp, and KMIP
Release compatibility
CipherTrust Manager backups are forward compatible to the next three versions of backups. For example, a backup of release 1.6.1 can be restored to 1.7, 1.8, and 1.9.1 instances. Backward compatibility is not supported. For example, a backup of release 1.6.1 can be restored to a 1.7 instance, however, a backup of release 1.7 cannot be restored to a 1.6.1 instance.
Domain Scoped Backups
Domain scoped backup and restore is the ability to back up user-specified resources partially and incrementally from a domain. They are created on the appliance, and after creation, can be used to:
Restore the resources on the same domain to its previous state
Restore on a different domain in the same appliance
Transfer to another appliance to restore on a different domain
CipherTrust Manager users (such as Domain Administrators), who are authorized to perform backup, can perform domain scoped backup and restore. Application Administrators can perform backup and restore operations of domain scoped backup of root domain only, not other sub-domains.
Note
Domain scoped backups can be restored on any clustered node.
Backup contents
Domain scoped backups include the following:
- Keys, key attributes, and key links
Release compatibility
Domain scoped backups can be restored to the same or higher versions of the CipherTrust Manager.
Note
Domain scoped backups cannot be tied to an HSM.
Typical Backup and Restore Operations
The following are typical backup operations using the ksctl. If you are using the API, refer to the API playground for details.
Create the backup key
Backups are automatically encrypted by a backup key at the time of their creation. If no key is specified, the default backup key is used. If needed, a new backup key can be created and optionally set as the default backup key.
Backup keys can be of two types:
System scoped keys to encrypt only system backups
Domain scoped keys to encrypt only domain scoped backups
To create a system backup key
To create a system backup key, run ksctl backupkeys create. If not specified, the default scope is system.
Example:
$ ksctl backupkeys create
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "2",
"id": "5dac1d33-9c2d-4fc1-9793-961052d73a29",
"createdAt": "2020-04-07T08:17:54.600032599Z",
"isDefault": false
}
To create a system backup key and set it as the default key, run ksctl backupkeys create --scope system --default.
Example:
$ ksctl backupkeys create --scope system --default
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "2",
"id": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"createdAt": "2020-04-07T08:21:59.139786694Z",
"isDefault": true
}
To create a domain scoped backup key
To create a domain scoped backup key, run ksctl backupkeys create --scope domain. Here, --scope domain specifies that the key is domain scoped. The scope flag must be used for creating domain scoped backup keys.
Example:
$ ksctl backupkeys create --scope domain
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "2",
"id": "88f47a71-a1d7-41ae-af49-736862f4f625",
"createdAt": "2020-04-07T08:31:29.314569058Z",
"isDefault": false
}
To create a domain scoped backup key and set it as the default key, run ksctl backupkeys create --scope domain --default.
Example:
$ ksctl backupkeys create --scope domain --default
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "2",
"id": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"createdAt": "2020-04-07T08:24:13.648719582Z",
"isDefault": true
}
To view the list of available backup keys
Run the command ksctl backupkeys list.
Example:
$ ksctl backupkeys list
{
"skip": 0,
"limit": 10,
"total": 2,
"resources": [
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "2",
"id": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"createdAt": "2020-04-07T08:21:59.139786694Z",
"isDefault": true
},
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "2",
"id": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"createdAt": "2020-04-07T08:24:13.648719582Z",
"isDefault": true
}
]
}
Create the backup
Create the system and domain scoped backups using the ksctl.
To create a system backup
To create a system backup, run ksctl backup create. If an encryption key is not specified when creating a backup, the backup is encrypted by the default backup key. You can check the status of the backup by running the ksctl backup status command. Refer to Check the backup status for details.
Example:
$ ksctl backup create
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "v1.1.4",
"id": "245d3336-21fa-4a34-9498-c0b64fa4d322",
"createdAt": "2020-04-07T08:33:44.687970269Z",
"status": "In Progress",
"tiedToHSM": false,
"backupKey": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"productVersion": "v1.10.0-beta4.4388"
}
When a backup is initiated, it status becomes "In Progress". It may take a while until the status becomes "Completed". When a backup operation is "In Progress", another backup or restore operation cannot be initiated.
To create a system backup by specifying the scope as system, run ksctl backup create --scope system.
Example:
$ ksctl backup create --scope system
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "v1.1.4",
"id": "06c7d57d-2749-4285-8c60-c2778c911cd2",
"createdAt": "2020-04-07T08:34:49.914616905Z",
"status": "In Progress",
"tiedToHSM": false,
"backupKey": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"productVersion": "v1.10.0-beta4.4388"
}
Note
A system level backup can optionally be tied to the HSM during creation by passing the flag --tied-to-hsm. The backup can only be restored to instances that use the same HSM partition. This option is invalid for domain scoped backups.
To initiate a system level backup tied to the HSM, run the command: $ ksctl backup create --scope system --tied-to-hsm --description <description>
To create a domain scoped backup
When creating a domain scoped backup, specify the scope as domain. To create a domain scoped backup, run ksctl backup create --scope domain. You can check the status of the backup by running the ksctl backup status command. Refer to check the backup status for details.
Here, --scope domain specifies that the backup is domain scoped. The scope flag must be used for creating domain scoped backups.
Note
To perform the backup operation in a sub-domain, you need to log on to the domain or use the --domain flag.
Example:
$ ksctl backup create --scope domain
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "v1.1.4",
"id": "762d15f3-4eba-4cd7-960c-c50a84a52b48",
"createdAt": "2020-04-07T08:36:34.667280981Z",
"status": "In Progress",
"tiedToHSM": false,
"backupKey": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"productVersion": "v1.10.0-beta4.4388"
}
Note
When creating a domain scoped backup, use filters to select resources. Filters specify selection criteria to include only certain resources in the backup from the requester's domain. Filter criteria include the resource type and its matching attribute values in JSON format for querying the resources.
- Filters apply to domain scoped backups only.
To use filters, run either of the following commands:
ksctl backup create --scope domain --filters <filters-json>ksctl backup create --scope domain --filters-jsonfile <file-name-containing-filters-json>
Refer to the API playground for details on filters.
To view the list of available backups
To view the list of available backups, run ksctl backup list.
Example:
$ ksctl backup list
{
"skip": 0,
"limit": 10,
"total": 2,
"resources": [
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "v1.1.4",
"id": "06c7d57d-2749-4285-8c60-c2778c911cd2",
"createdAt": "2020-04-07T08:34:49.914616905Z",
"status": "Completed",
"tiedToHSM": false,
"backupKey": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"productVersion": "v1.10.0-beta4.4388"
},
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "v1.1.4",
"id": "762d15f3-4eba-4cd7-960c-c50a84a52b48",
"createdAt": "2020-04-07T08:36:34.667280981Z",
"status": "Completed",
"tiedToHSM": false,
"backupKey": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"productVersion": "v1.10.0-beta4.4388"
}
]
}
To view the details of a backup
To view the details of a backup, run ksctl backup get --id "backupID". The status of the backup is given in the response. A status of "Completed" indicates that the backup is successful.
Example:
$ ksctl backup get --id "762d15f3-4eba-4cd7-960c-c50a84a52b48"
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "v1.1.4",
"id": "762d15f3-4eba-4cd7-960c-c50a84a52b48",
"createdAt": "2020-04-07T08:36:34.667280981Z",
"status": "Completed",
"tiedToHSM": false,
"backupKey": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"productVersion": "v1.10.0-beta4.4388"
}
Check the backup status
Initiating a backup begins an asynchronous operation on the appliance. Only one backup or restore operation can be performed at a time. If you try to perform another operation until the previous is complete, the operation will fail.
To view the status of the last backup, run the command ksctl backup status. The status of the backup is given in the response.
Example:
$ ksctl backup status
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"operation": "Backup create",
"id": "f6b55640-ddec-49d0-893b-4f33f0809bf0",
"started": "2020-04-10T00:27:01.078766633Z",
"status": "In Progress"
}
In the output above, the status of the backup is In Progress.
Download the backup key
The key with which the backup is encrypted must be transferred to the appliance where the backup will be restored. The backup key is required for the restore. To transfer a backup key, it must be downloaded using the command ksctl backupkeys download. After the key is downloaded, it can be uploaded to the appliance to restore the backup.
To download the backup key
Run the command ksctl backupkeys download --id "<backupkeyID>" --file "<file-to-store-key>". The same command is used to the download system scoped and domain scoped backup keys.
Here:
"<backupkeyID>": ID of the backup key to download."<file-to-store-key>": Name of the file to store the backup key.
Specify a password for the backup key when prompted.
Example - download system backup key:
$ ksctl backupkeys download --id "c05b638d-2eea-4651-9937-7bee49a95f6b" --file "sysbkkey.txt" Password is required for backupkey. Please provide the backupkey password:
Download the backup
The backup must be transferred to the appliance where it will be restored. To transfer a backup, it must be downloaded by using the command ksctl backup download. After the backup is downloaded, it can be uploaded to the appliance for restore.
To download the backup
To download a backup, run the command ksctl backup download --id "<backupID>" --file "<backup-file>".
Here,
"<backupID>": ID of the backup to download."<backup-file>": Name of the file to store the backup.
Example - download system backup:
$ ksctl backup download --id "245d3336-21fa-4a34-9498-c0b64fa4d322" --file "backup-file.txt"
Inspect the backup key file
Before uploading the backup key file, inspect it by reviewing its metadata. To inspect the backup key file, run the command ksctl backupkeys inspect --file "<backup-key-file>".
Example - system backup key file:
$ backupkeys inspect --file "sysbkkey.txt"
{
"version": 2,
"keyid": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"createdAt": "2020-04-07T08:21:59.139786694Z"
}
Example - domain scoped backup key file:
$ backupkeys inspect --file "domainbkkey.txt"
{
"version": 2,
"keyid": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"createdAt": "2020-04-07T08:24:13.648719582Z"
}
Upload the backup key
Upload the backup key to the appliance where the backup will be restored.
To upload the system backup key
Run the command ksctl backupkeys upload --file "<backup-key-file>". Here, <backup-key-file> represents the name of the system backup key file.
Specify the password of the backup key when prompted.
Example:
$ ksctl backupkeys upload --file "sysbkkey.txt"
Please provide the backupkey password:
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "2",
"id": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"createdAt": "2020-04-07T08:21:59.139786694Z",
"isDefault": false
}
To upload the domain scoped backup key
Run the command ksctl backupkeys upload --scope domain --file "<backup-key-file>".
Here,
--scope domain: Scope of the backup key is domain. The scope flag must be used for uploading domain scoped backup keys.<backup-key-file>: Name of the domain scoped backup key file.
Specify the password of the domain scoped backup key when prompted.
Example:
$ ksctl backupkeys upload --scope domain --file "domainbkkey.txt"
Please provide the backupkey password:
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "2",
"id": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"createdAt": "2020-04-07T08:24:13.648719582Z",
"isDefault": false
}
Inspect the backup file
Before uploading the backup file, inspect the file by reviewing its metadata. To inspect the backup file, run the command ksctl backup inspect --file "<backup-file>".
Example - system backup file:
$ ksctl backup inspect --file "backup-file.txt"
{
"version": "v1.1.4",
"createdAt": "2020-04-07T08:33:44.687970269Z",
"scope": "system",
"domainID": "",
"backupKeyId": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"isEncrypted": true,
"creatorAccount": "kylo:kylo:admin:accounts:kylo",
"isHSMBacked": false,
"description": "",
"checksum": "9f19ab202f860cfa5de7fcbe70872a0aea1ee91af9092c80cb89939c35aea994",
"mkekChecksum": "d1fe06afe54bfe5f242323b42c640b218a76fae91e7bb0baf10720b47a39be20",
"productVersion": "v1.10.0-beta4.4388",
"id": "245d3336-21fa-4a34-9498-c0b64fa4d322"
}
Example - domain scoped backup file:
$ ksct backup inspect --file "domain-backup-file.txt"
{
"version": "v1.1.4",
"createdAt": "2020-04-07T08:36:34.667280981Z",
"scope": "domain",
"domainID": "00000000-0000-0000-0000-000000000000",
"backupKeyId": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"isEncrypted": true,
"creatorAccount": "kylo:kylo:admin:accounts:kylo",
"isHSMBacked": false,
"description": "",
"checksum": "1c1a58b2ead4f09fceb67297603dbf01e40a8bec6d812e78a64287afa9619f8f",
"mkekChecksum": "12f700ed4f872bd93864cfd7f9d162574025d3ee30ec2c08ccf13362c899a837",
"productVersion": "v1.10.0-beta4.4388",
"id": "762d15f3-4eba-4cd7-960c-c50a84a52b48"
}
Upload the backup
Upload the backup to the appliance where it will be restored.
To upload the system backup
Run the command ksctl backup upload --file "<backup-file>". Here, <backup-file> represents the name of the system backup file.
Example:
$ ksctl backup upload --file "backup-file.txt"
{
"scope": "system",
"account": "kylo:kylo:admin:accounts:kylo",
"version": "v1.1.4",
"id": "245d3336-21fa-4a34-9498-c0b64fa4d322",
"createdAt": "2020-04-07T08:33:44.687970269Z",
"status": "Completed",
"tiedToHSM": false,
"backupKey": "c05b638d-2eea-4651-9937-7bee49a95f6b",
"productVersion": "v1.10.0-beta4.4388
}
To upload the domain scoped backup
Run the command ksctl backup upload --scope domain --file "<domain-backup-file>".
Here,
--scope domain: Scope of the backup is domain. The scope flag must be used for uploading domain scoped backups.<domain-backup-file>: Name of the domain scoped backup file.
Example:
$ ksctl backup upload --scope domain --file "domain-backup-file.txt"
{
"scope": "domain",
"account": "kylo:kylo:admin:accounts:kylo",
"domainID": "00000000-0000-0000-0000-000000000000",
"version": "2",
"id": "2f91020c-5fb7-4709-aca4-f4ce1ba9a54a",
"createdAt": "2020-04-07T08:24:13.648719582Z",
"isDefault": false
}
Restore the backup
After the backup and the backup key are uploaded to the appliance, you can restore the backup on the appliance. Check the restore status by running the ksctl backup status command. Refer to check the restore status.
To restore the backup
Run the command ksctl backup restore --id "<backupID>". Here, <backupID> specifies the ID of the backup to restore.
System services will restart after the system backup is restored. Restore of the domain scoped backup does not restart the system services.
Example:
$ ksctl backup restore --id "245d3336-21fa-4a34-9498-c0b64fa4d322"
{
"version": "v1.1.4",
"id": "245d3336-21fa-4a34-9498-c0b64fa4d322",
"createdAt": "2020-04-07T08:33:44.687970269Z",
"status": "Completed",
"tiedToHSM": false
}
Check the restore status
After performing the backup restore, you can check the status of the operation. To view the status of the restore, run the command ksctl backup status. The status of the restore is given in the response.
Example:
$ ksctl backup status
{
"account": "kylo:kylo:admin:accounts:kylo",
"id": "f6b55640-ddec-49d0-893b-4f33f0809bf0",
"createdAt": "0001-01-01T00:00:00Z",,
"status": "In Progress",
"tiedToHSM": false
}
In the output above, the status of the restore is In Progress.
Note
It is normal to get an error like the following for status when the system services are restarting after the system backup is restored:
*Error: Server error. HTTP status code: 500*
