pool.dataset.encryption_summary

Retrieve summary of all encrypted roots under id.

Keys/passphrase can be supplied to check if the keys are valid.

Example output: [
{ “name”: “vol”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: true, “locked”: true, “unlock_error”: null, “unlock_successful”: true }, {

“name”: “vol/c1/d1”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Provided key is invalid”, “unlock_successful”: false }, { “name”: “vol/c”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Key not provided”, “unlock_successful”: false }, { “name”: “vol/c/d2”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Child cannot be unlocked when parent “vol/c” is locked and provided key is invalid”, “unlock_successful”: false }

]

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: id

id

Type: string
Parameter 2: options

options

Type: object
No Additional Properties

Key File

Type: boolean Default: false

Force

Type: boolean Default: false

Datasets

Type: array of object Default: []
No Additional Items
Each item of this array must be:

PoolDatasetEncryptionSummaryOptionsDataset

Type: object
No Additional Properties

Force

Type: boolean Default: false

Name

Type: string

Must be at least 1 characters long

Key

Type: string

Must be at least 64 characters long

Must be at most 64 characters long

Passphrase

Type: string

Must be at least 1 characters long

Result

Type: array of object
No Additional Items
Each item of this array must be:

PoolDatasetEncryptionSummary

Type: object

There are 2 keys which show if a recursive unlock operation is done for id, which dataset will be unlocked and if
not why it won't be unlocked. The keys namely are unlock_successful and unlock_error. The former is a boolean
value showing if unlock would succeed/fail. The latter is description why it failed if it failed.

In some cases it's possible that the provided key/passphrase is valid but the path where the dataset is supposed to
be mounted after being unlocked already exists and is not empty. In this case, unlock operation would fail and
unlock_error will reflect this error appropriately. This can be overridden by setting options.datasets.X.force
boolean flag or by setting options.force flag. In practice, when the dataset is going to be unlocked and these
flags have been provided to pool.dataset.unlock, system will rename the directory/file path where the dataset
should be mounted resulting in successful unlock of the dataset.

If a dataset is already unlocked, it will show up as true for "unlocksuccessful" regardless of what key user
provided as the unlock keys in the output are to reflect what a real unlock operation would behave. If user is
interested in seeing if a provided key is valid or not, then the key to look out for in the output is "validkey"
which based on what system has in database or if a user provided one, validates the key and sets a boolean value
for the dataset.

 No Additional Properties

Name

Type: string

Key Format

Type: string

Key Present In Database

Type: boolean

Valid Key

Type: boolean

Locked

Type: boolean

Unlock Error


Type: string
Type: null

Unlock Successful

Type: boolean


Required roles: DATASET_READ