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.

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.

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 issued by Local CAs, excluding certificates configured for the CipherTrust Manager interfaces

• 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

The following objects are excluded from the backup:

• Backup keys

• Cluster configuration

• DNS hosts

• NTP configuration

• HSM configuration

• Instance name

• Virtual CipherTrust Manager license

• Interface certificates

• System logs

• Proxy configuration

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.

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.

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.

1. Create the backup key

2. Create the backup

3. Check the backup status

4. Download the backup key

5. Download the backup

6. Inspect the backup key file

7. Upload the backup key

8. Inspect the backup file

9. Upload the backup

10. Restore the backup

11. Check the restore status

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"
}

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.

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"
}

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.