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

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: id

id

Type: string

Parameter 2: options

options

Type: object
No Additional Properties

force

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

Key File

Type: boolean Default: false

recursive

Recursive

Type: boolean Default: false

toggle_attachments

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

Datasets

Type: array of object Default: []
No Additional Items

Each item of this array must be:

PoolDatasetUnlockOptionsDataset

Type: object
No Additional Properties

force

Force

Type: boolean Default: false

name Required

Name

Type: string

Must be at least 1 characters long

key

Key

Type: string

Must be at least 64 characters long

Must be at most 64 characters long

passphrase

Passphrase

Type: string

Must be at least 1 characters long

recursive

Recursive

Type: boolean Default: false

Apply the key or passphrase to all encrypted children.

Return value

PoolDatasetUnlock

Type: object
No Additional Properties

unlocked Required

Unlocked

Type: array of string
No Additional Items

Each item of this array must be:

Type: string

failed Required

Failed

Type: object

Required roles: DATASET_WRITE