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

.. raw:: html

    <div id="json-schema"> <span class="badge badge-dark value-type">Type: object</span><br/> <div class="accordion" id="accordionCall_parameters"> <div class="card"> <div class="card-header" id="headingCall_parameters"> <h2 class="mb-0"> <button aria-controls="Call_parameters" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters" data-toggle="collapse" onclick="setAnchor('#Call_parameters')" type="button"><span class="property-name">Call parameters</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters" class="collapse property-definition-div" data-parent="#accordionCall_parameters" id="Call_parameters"> <div class="card-body pl-5"> <span class="badge badge-dark value-type">Type: array</span><br/> <span class="badge badge-info no-additional">No Additional Items</span><h4>Tuple Validation</h4> <h5>Parameter 1: id</h5> <div class="card"> <div class="card-body items-definition" id="Call_parameters_items_i0"> <h4>id</h4><span class="badge badge-dark value-type">Type: string</span><br/> </div> </div> <h5>Parameter 2: options</h5> <div class="card"> <div class="card-body items-definition" id="Call_parameters_items_i1"> <h4>options</h4><span class="badge badge-dark value-type">Type: object</span><br/> <span class="badge badge-info no-additional">No Additional Properties</span> <div class="accordion" id="accordionCall_parameters_items_i1_force"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_force"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_force" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_force" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_force')" type="button"><span class="property-name">force</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_force" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_force" id="Call_parameters_items_i1_force"> <div class="card-body pl-5"> <h4>Force</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/> <span class="description"><p>In some cases it's possible that the provided key/passphrase is valid but the path where the dataset is supposed<br/> to be mounted after being unlocked already exists and is not empty. In this case, unlock operation would fail. This<br/> can be overridden by setting <code>datasets.X.force</code> boolean flag or by setting <code>force</code> flag. When any of these flags<br/> are set, system will rename the existing directory/file path where the dataset should be mounted resulting in<br/> successful unlock of the dataset.</p> </span> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_key_file"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_key_file"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_key_file" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_key_file" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_key_file')" type="button"><span class="property-name">key_file</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_key_file" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_key_file" id="Call_parameters_items_i1_key_file"> <div class="card-body pl-5"> <h4>Key File</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_recursive"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_recursive"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_recursive" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_recursive" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_recursive')" type="button"><span class="property-name">recursive</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_recursive" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_recursive" id="Call_parameters_items_i1_recursive"> <div class="card-body pl-5"> <h4>Recursive</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_toggle_attachments"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_toggle_attachments"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_toggle_attachments" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_toggle_attachments" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_toggle_attachments')" type="button"><span class="property-name">toggle_attachments</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_toggle_attachments" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_toggle_attachments" id="Call_parameters_items_i1_toggle_attachments"> <div class="card-body pl-5"> <h4>Toggle Attachments</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: true</span><br/> <span class="description"><p>Whether attachments should be put in action after unlocking the dataset(s). Toggling attachments can<br/> theoretically lead to service interruption when daemons configurations are reloaded (this should not happen, and if<br/> this happens it should be considered a bug). As TrueNAS does not have a state for resources that should be unlocked<br/> but are still locked, disabling this option will put the system into an inconsistent state so it should really<br/> never be disabled.</p> </span> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_datasets"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets')" type="button"><span class="property-name">datasets</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets" id="Call_parameters_items_i1_datasets"> <div class="card-body pl-5"> <h4>Datasets</h4><span class="badge badge-dark value-type">Type: array of object</span> <span class="badge badge-success default-value">Default: []</span><br/> <span class="badge badge-info no-additional">No Additional Items</span><h5>Each item of this array must be:</h5> <div class="card"> <div class="card-body items-definition" id="Call_parameters_items_i1_datasets_items"> <h4>PoolDatasetUnlockOptionsDataset</h4><span class="badge badge-dark value-type">Type: object</span><br/> <span class="badge badge-info no-additional">No Additional Properties</span> <div class="accordion" id="accordionCall_parameters_items_i1_datasets_items_force"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets_items_force"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets_items_force" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets_items_force" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets_items_force')" type="button"><span class="property-name">force</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets_items_force" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets_items_force" id="Call_parameters_items_i1_datasets_items_force"> <div class="card-body pl-5"> <h4>Force</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_datasets_items_name"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets_items_name"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets_items_name" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets_items_name" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets_items_name')" type="button"><span class="property-name">name</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets_items_name" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets_items_name" id="Call_parameters_items_i1_datasets_items_name"> <div class="card-body pl-5"> <h4>Name</h4><span class="badge badge-dark value-type">Type: string</span><br/> <p><span class="badge badge-light restriction min-length-restriction" id="Call_parameters_items_i1_datasets_items_name_minLength">Must be at least <code>1</code> characters long</span></p> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_datasets_items_key"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets_items_key"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets_items_key" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets_items_key" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets_items_key')" type="button"><span class="property-name">key</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets_items_key" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets_items_key" id="Call_parameters_items_i1_datasets_items_key"> <div class="card-body pl-5"> <h4>Key</h4><span class="badge badge-dark value-type">Type: string</span><br/> <p><span class="badge badge-light restriction min-length-restriction" id="Call_parameters_items_i1_datasets_items_key_minLength">Must be at least <code>64</code> characters long</span></p><p><span class="badge badge-light restriction max-length-restriction" id="Call_parameters_items_i1_datasets_items_key_maxLength">Must be at most <code>64</code> characters long</span></p> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_datasets_items_passphrase"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets_items_passphrase"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets_items_passphrase" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets_items_passphrase" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets_items_passphrase')" type="button"><span class="property-name">passphrase</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets_items_passphrase" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets_items_passphrase" id="Call_parameters_items_i1_datasets_items_passphrase"> <div class="card-body pl-5"> <h4>Passphrase</h4><span class="badge badge-dark value-type">Type: string</span><br/> <p><span class="badge badge-light restriction min-length-restriction" id="Call_parameters_items_i1_datasets_items_passphrase_minLength">Must be at least <code>1</code> characters long</span></p> </div> </div> </div> </div> <div class="accordion" id="accordionCall_parameters_items_i1_datasets_items_recursive"> <div class="card"> <div class="card-header" id="headingCall_parameters_items_i1_datasets_items_recursive"> <h2 class="mb-0"> <button aria-controls="Call_parameters_items_i1_datasets_items_recursive" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i1_datasets_items_recursive" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i1_datasets_items_recursive')" type="button"><span class="property-name">recursive</span></button> </h2> </div> <div aria-labelledby="headingCall_parameters_items_i1_datasets_items_recursive" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i1_datasets_items_recursive" id="Call_parameters_items_i1_datasets_items_recursive"> <div class="card-body pl-5"> <h4>Recursive</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/> <span class="description"><p>Apply the key or passphrase to all encrypted children.</p> </span> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> <div class="accordion" id="accordionReturn_value"> <div class="card"> <div class="card-header" id="headingReturn_value"> <h2 class="mb-0"> <button aria-controls="Return_value" aria-expanded="" class="btn btn-link property-name-button" data-target="#Return_value" data-toggle="collapse" onclick="setAnchor('#Return_value')" type="button"><span class="property-name">Return value</span></button> </h2> </div> <div aria-labelledby="headingReturn_value" class="collapse property-definition-div" data-parent="#accordionReturn_value" id="Return_value"> <div class="card-body pl-5"> <h4>PoolDatasetUnlock</h4><span class="badge badge-dark value-type">Type: object</span><br/> <span class="badge badge-info no-additional">No Additional Properties</span> <div class="accordion" id="accordionReturn_value_unlocked"> <div class="card"> <div class="card-header" id="headingReturn_value_unlocked"> <h2 class="mb-0"> <button aria-controls="Return_value_unlocked" aria-expanded="" class="btn btn-link property-name-button" data-target="#Return_value_unlocked" data-toggle="collapse" onclick="setAnchor('#Return_value_unlocked')" type="button"><span class="property-name">unlocked</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div aria-labelledby="headingReturn_value_unlocked" class="collapse property-definition-div" data-parent="#accordionReturn_value_unlocked" id="Return_value_unlocked"> <div class="card-body pl-5"> <h4>Unlocked</h4><span class="badge badge-dark value-type">Type: array of string</span><br/> <span class="badge badge-info no-additional">No Additional Items</span><h5>Each item of this array must be:</h5> <div class="card"> <div class="card-body items-definition" id="Return_value_unlocked_items"> <span class="badge badge-dark value-type">Type: string</span><br/> </div> </div> </div> </div> </div> </div> <div class="accordion" id="accordionReturn_value_failed"> <div class="card"> <div class="card-header" id="headingReturn_value_failed"> <h2 class="mb-0"> <button aria-controls="Return_value_failed" aria-expanded="" class="btn btn-link property-name-button" data-target="#Return_value_failed" data-toggle="collapse" onclick="setAnchor('#Return_value_failed')" type="button"><span class="property-name">failed</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div aria-labelledby="headingReturn_value_failed" class="collapse property-definition-div" data-parent="#accordionReturn_value_failed" id="Return_value_failed"> <div class="card-body pl-5"> <h4>Failed</h4><span class="badge badge-dark value-type">Type: object</span><br/> </div> </div> </div> </div> </div> </div> </div> </div> </div><br><br>

*Required roles:* DATASET_WRITE