# 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.

This method is a job.

This job CAN be used with file upload. See Uploading a File.

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