zfs.resource.encryption.unlock

Unlock an encryption root, and the locked encryption roots below it when recursive is set.

Keys and passphrases are given per encryption root in keys, or uploaded to the input pipe as the JSON file zfs.resource.encryption.export_keys writes when key_file is set. A key the system has stored is used when none is given, and a supplied key that unlocks its encryption root is stored. zfs.resource.encryption.unlock_summary reports what an unlock would do.

Example:

{"path": "tank/secure", "keys": [{"path": "tank/secure", "passphrase": "correct horse battery staple"}]}

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: data

data

Type: object

Unlock parameters.

No Additional Properties

Path

Type: string

Path of the encryption root to unlock. A pool root that is not itself encrypted is accepted when recursive is set, which unlocks the encrypted roots below it.

Must be at least 1 characters long

Recursive

Type: boolean Default: false

Also unlock the locked encryption roots below path.

Force

Type: boolean Default: false

Rename whatever already occupies a mount path instead of failing because it exists and is not empty. Applies to every resource being unlocked; keys.X.force applies to a single one.

Key File

Type: boolean Default: false

Read keys from a JSON file uploaded to the input pipe, in the format written by zfs.resource.encryption.export_keys.

Keys

Type: array of object Default: []

Keys or passphrases for individual encryption roots.

No Additional Items
Each item of this array must be:

ZFSResourceEncryptionUnlockKey

Type: object
No Additional Properties

Path

Type: string

Path of the encryption root the key or passphrase belongs to.

Must be at least 1 characters long

Key

Default: null

A 64-character hex-encoded key for path. Must not be combined with passphrase.

Type: string

Must be at least 64 characters long

Must be at most 64 characters long

Type: null

Passphrase

Default: null

The passphrase for path. Must not be combined with key.

Type: string

Must be at least 1 characters long

Type: null

Force

Type: boolean Default: false

Rename whatever already occupies the mount path of path instead of failing because it exists and is not empty.

Recursive

Type: boolean Default: false

Also try this key or passphrase on locked encryption roots below path that have none supplied.

Start Attachments

Type: boolean Default: true

Start the services, shares and other consumers of the unlocked resources once they are mounted. The system keeps no record of resources unlocked without their attachments, so disable this only when the caller restarts services itself.

ZFSResourceEncryptionUnlockEntry

Type: object

Outcome of the unlock.

No Additional Properties

Unlocked

Type: array of string

Paths of the resources that were unlocked and mounted.

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

Failed

Type: object

Resources that could not be unlocked, keyed by path.

Each additional property must conform to the following schema

ZFSResourceEncryptionUnlockFailure

Type: object
No Additional Properties

Error


Why the resource could not be unlocked.

Type: string
Type: null

Skipped

Type: array of string

Paths below the failed resource that were not attempted because of it.

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


Required roles: ZFS_RESOURCE_WRITE