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 :ref:`uploading-files`.

.. 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/>
    <span class="description"><p>The dataset ID (full path) to unlock.</p>
    </span>
    </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="description"><p>Options for unlocking including force settings, recursion, and dataset-specific keys.</p>
    </span> <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 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 <code>datasets.X.force</code> boolean flag or by setting <code>force</code> 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.</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/>
    <span class="description"><p>Whether to use a key file instead of a passphrase for unlocking encrypted datasets.</p>
    </span>
    </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/>
    <span class="description"><p>Whether to recursively unlock child datasets.</p>
    </span>
    </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     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.</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="description"><p>List of specific datasets with their individual unlock options.</p>
    </span>
    <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/>
    <span class="description"><p>Force unlock even if the mount path already exists and is not empty.</p>
    </span>
    </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/>
    <span class="description"><p>The dataset name to unlock.</p>
    </span>
    <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/>
    <span class="description"><p>Raw hex-encoded encryption key for this dataset.</p>
    </span>
    <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/>
    <span class="description"><p>Passphrase for this dataset if using passphrase-based encryption.</p>
    </span>
    <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="description"><p>Results of the unlock operation including successful and failed datasets.</p>
    </span> <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="description"><p>Array of dataset names that were successfully unlocked.</p>
    </span>
    <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/>
    <span class="description"><p>Object containing datasets that failed to unlock and their respective error messages.</p>
    </span>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div><br><br>

*Required roles:* DATASET_WRITE

