pool.dataset.unlock

Unlock dataset id (and its children if unlock_options.recursive is true).

If id dataset is not encrypted an exception will be raised. There is one exception: when id is a root dataset and unlock_options.recursive is specified, encryption validation will not be performed for id. This allow unlocking encrypted children for the entire pool id.

There are two ways to supply the key(s)/passphrase(s) for unlocking a dataset:

  1. Upload a json file which contains encrypted dataset keys (it will be read from the input pipe if unlock_options.key_file is true). The format is the one that is used for exporting encrypted dataset keys (pool.export_keys).

  2. Specify a key or a passphrase for each unlocked dataset using unlock_options.datasets.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: id

id

Type: string

The dataset ID (full path) to unlock.
Parameter 2: options

options

Type: object

Options for unlocking including force settings, recursion, and dataset-specific keys.

 No Additional Properties

Force

Type: boolean Default: false

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. This can be overridden by setting datasets.X.force boolean flag or by setting force flag. When any of these flags are set, system will rename the existing directory/file path where the dataset should be mounted resulting in successful unlock of the dataset.

Key File

Type: boolean Default: false

Whether to use a key file instead of a passphrase for unlocking encrypted datasets.

Recursive

Type: boolean Default: false

Whether to recursively unlock child datasets.

Toggle Attachments

Type: boolean Default: true

Whether attachments should be put in action after unlocking the dataset(s). Toggling attachments can theoretically lead to service interruption when daemons configurations are reloaded (this should not happen, and if this happens it should be considered a bug). As TrueNAS does not have a state for resources that should be unlocked but are still locked, disabling this option will put the system into an inconsistent state so it should really never be disabled.

Datasets

Type: array of object Default: []

List of specific datasets with their individual unlock options.

 No Additional Items
Each item of this array must be:

PoolDatasetUnlockOptionsDataset

Type: object
No Additional Properties

Force

Type: boolean Default: false

Force unlock even if the mount path already exists and is not empty.

Name

Type: string

The dataset name to unlock.

Must be at least 1 characters long

Key

Type: string

Raw hex-encoded encryption key for this dataset.

Must be at least 64 characters long

Must be at most 64 characters long

Passphrase

Type: string

Passphrase for this dataset if using passphrase-based encryption.

Must be at least 1 characters long

Recursive

Type: boolean Default: false

Apply the key or passphrase to all encrypted children.

PoolDatasetUnlock

Type: object

Results of the unlock operation including successful and failed datasets.

 No Additional Properties

Unlocked

Type: array of string

Array of dataset names that were successfully unlocked.

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

Failed

Type: object

Object containing datasets that failed to unlock and their respective error messages.


Required roles: DATASET_WRITE