TrueNASTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Storage Encryption

TrueNAS offers ZFS encryption for your sensitive data in datasets and zvols.

Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.

Data-at-rest encryption is available with:

The local TrueNAS system manages keys for data-at-rest. Users are responsible for storing and securing their keys. TrueNAS includes the Key Management Interface Protocol (KMIP).

Pool and Dataset Encryption

Encryption is for users storing sensitive data. Pool-level encryption applies to the root dataset that shares the same name as the pool. It does not apply encryption to the storage vdev or the disks in the pool. Child datasets or zvols must be configured to inherit encryption from the parent dataset.

TrueNAS automatically generates a root dataset when you create a pool. Select Encryption on the Pool Creation Wizard screen when you create the pool to encrypt the root dataset. The TrueNAS forces encryption for all child datasets and zvols within an encrypted root or parent dataset that are created using the TrueNAS UI. By default, child datasets inherit encryption settings from the parent. Deselect Inherit (encrypted) under Advanced Options to modify encryption configuration for the child dataset.

In TrueNAS 22.12.3 or later, you cannot create an unencrypted dataset within an encrypted pool or dataset using the TrueNAS UI. However, datasets created outside of the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured. For example, the ix-apps dataset on the pool selected for applications does not inherit encryption settings.

For more granular control, we recommend users do not configure pool-level encryption. Leave Encryption unselected on the Pool Creation Wizard screen to create a pool with an unencrypted root dataset. You can create both unencrypted and encrypted datasets within an unencrypted pool (root dataset).

If you have only one pool on your system, do not use pool-level encryption for this pool.

Can I change dataset encryption?

Before you save a new dataset, you can change the type of encryption of an encrypted dataset to key to passphrase. After you save a dataset with encryption applied you cannot change the dataset to unencrypted.

After saving a dataset with encryption, if the encryption type is set to passphrase you can change it to key type, but you cannot change from key type to passphrase.

Can I unencrypt my data? Yes, you can move encrypted data to an unencrypted pool or dataset using either rsync or replication. You can also move data from an unencrypted pool or dataset to an encrypted dataset using rsync or replication.

If your system loses power or you reboot the system, all encrypted datasets and zvols lock automatically to protect data.

Encryption Visual Cues

TrueNAS uses lock icons to indicate the encryption state of a root, parent, or child dataset in the tree table on the Datasets screen. Each icon shows a text label with the state of the dataset when you hover the mouse over the icon.

The Datasets tree table includes lock icons and descriptions that indicate the encryption state of datasets.

IconStateDescription
DatasetLockedEncryptionIconLockedDisplays for locked encrypted root, non-root parent and child datasets.
DatasetUnlockedEncryptionIconUnlockedDisplays for unlocked encrypted root, non-root parent and child datasets.
DatasetLockedByAncestorEncryptionIconLocked by ancestorDisplays for locked datasets that inherit encryption properties from the parent.
DatasetUnlockedbyAncestorEncryptIconUnlocked by ancestorDisplays for unlocked datasets that inherit encryption properties from the parent.

A dataset that inherits encryption shows the mouse hover-over label Locked by ancestor or Unlocked by ancestor.

Select an encrypted dataset to see the ZFS Encryption widget on the Datasets screen.

The dataset encryption state is unlocked until you lock it using the Lock button on the ZFS Encryption widget. After locking the dataset, the icon on the tree table changes to locked, and the Unlock button appears on the ZFS Encryption widget.

Implementing Encryption

Before creating a encrypted pool (root dataset) or dataset, decide if you want to encrypt all child datasets, zvols, and data stored on that dataset.

If your system does not have enough disks to allow you to create a second storage pool, we recommend that you not use encryption at the pool level. Instead, apply encryption at the dataset level to non-root parent or child datasets.

All pool-level encryption is key-based encryption. When prompted, download the encryption key and keep it stored in a safe place where you can back up the file. You cannot use passphrase encryption at the pool level.

You cannot change an existing dataset from encrypted to non-encrypted. You can only change the dataset encryption type (key or passphrase). After saving a dataset with encryption, if the encryption type is set to passphrase you can change it to key type, but you cannot change from key type to passphrase.

Adding Encryption to a New Pool

TrueNAS 22.12.3 or later forces encryption for all child datasets and zvols within an encrypted root or parent dataset that are using the TrueNAS UI. However, datasets created outside of the UI, such as those created programmatically or manually via shell access, might not inherit encryption unless properly configured. For more granular control and awareness, we do not recommend users configure pool-level encryption of the root dataset. Instead, create an unencrypted pool and populate it with encrypted or unencrypted child datasets, as needed.

Go to Storage and click Create Pool on the Storage Dashboard screen. You can also click Add to Pool on the Unassigned Disks widget and select the Add to New to open the Pool Creation Wizard.

Enter a name for the pool, select Encryption next to Name, then select the layout for the data VDEV and add the disks. A warning dialog displays after selecting Encryption.

Read the warning, select Confirm, and then click I UNDERSTAND.

A second dialog opens where you click Download Encryption Key for the pool encryption key.

Download Encryption Key on Pool Manager
Figure 1: Download Encryption Key on Pool Manager

Click Done to close the window. Move the encryption key to safe location where you can back up the file.

Add any other VDEVS to the pool you want to include, then click Save to create the pool with encryption.

Adding Encryption to a New Dataset

To add an encrypted dataset, go to Datasets.

Select dataset on the tree table where you want to add a new dataset. The default dataset selected when you open the Datasets screen is the root dataset of the first pool on the tree table list. If you have more than one pool and want to create a dataset in a pool other than the default, select the root dataset for that pool or any dataset under the root where you want to add the new dataset.

Click Add Dataset to open the Add Dataset screen, then click Advanced Options.

Enter a value in Name.

Select the Dataset Preset option you want to use. Options are:

  • Generic for non-SMB share datasets such as iSCSI and NFS share datasets or datasets not associated with application storage.
  • Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
  • SMB for datasets optimized for SMB shares.
  • Apps for datasets optimized for application storage.

Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.

SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets
ACL TypeACL ModeCase SensitivityEnable atime
GenericPOSIXn/aSensitiveInherit
SMBNFSv4RestrictedInsensitiveOn
AppsNFSv4PassthroughSensitiveOff
MultiprotocolNFSv4PassthroughSensitiveOff

To add encryption to a dataset, scroll down to Encryption Options and select the inherit checkbox to clear the checkmark. If the parent dataset is unencrypted and you want to encrypt the dataset, deselect Inherit (non-encrypted) to show the Encryption option. If the parent dataset is encrypted and you want to change the type, deselect Inherit (encrypted) to configure encryption options. To keep the dataset encryption settings from the parent, leave inherit selected.

Add Dataset Encryption Options Clear Inherit
Figure 2: Add Dataset Encryption Options Clear Inherit

Decide if you want to use the default key type encryption and if you want to let the system generate the encryption key. To use key encryption and an existing key, deselect Generate Key to display the Key field. Enter the existing key in this field.

Add Key Encryption
Figure 3: Add Key Encryption

To change to passphrase encryption, select Passphrase from the Encryption Type dropdown.

Add Passphrase Encryption
Figure 4: Add Passphrase Encryption
The passphrase must be longer than 8 and less than 512 characters.
Keep encryption keys and/or passphrases safeguarded in a secure and protected place. Losing encryption keys or passphrases can result in permanent data loss!

You can select the encryption algorithm to use from Algorithm or use the recommended default. Leave the default selection if you do not have a particular encryption standard you want to use.

What are these options? TrueNAS supports AES Galois Counter Mode (GCM) and Counter with CBC-MAC (CCM) algorithms for encryption. These algorithms provide authenticated encryption with block ciphers.

Changing Dataset (or Zvol) Encryption

You cannot add encryption to an existing dataset. You can change the encryption type for an already encrypted dataset using the Edit option on the ZFS Encryption widget for the dataset.

Save any change to the encryption key or passphrase, and update your saved passcodes and keys file, and then back up that file.

To change the encryption type, go to Datasets:

Select the encrypted dataset on the tree table, then click Edit on the ZFS Encryption widget. The Edit Encryption Options dialog for the selected dataset displays.

You must unlock a locked encrypted dataset before you can make changes.

If the dataset inherits encryption settings from a parent dataset, to change this, clear the Inherit encryption properties from parent checkbox to display the key type encryption setting options.

Edit Encryption Window - Inherited
Figure 5: Edit Encryption Window - Inherited

If the encryption type is set to passphrase, you can change the passphrase, or change Encryption Type to key. You cannot change a dataset created with a key as the encryption type to passphrase.

Key type options are Generate Key (pre-selected) or clear to display the Key field. Enter your new key in this field.

Edit Encryption Key Type
Figure 6: Edit Encryption Key Type

To change the passphrase for passphrase-encryption, enter a new passphrase in Passphrase and Confirm Passphrase.

Edit Encryption - Passphrase
Figure 7: Edit Encryption - Passphrase

Use a complex passphrase that is not easy to guess. Store in a secure location subject to regular backups.

Leave the other settings at default, then click Confirm to activate Save.

Click Save to close the window and update the ZFS Encryption widget to reflect the changes made.

Locking and Unlocking Datasets

You can only lock and unlock an encrypted dataset if it is secured with a passphrase instead of a key file. Before locking a dataset, verify that it is not currently in use.

Locking a Dataset

Select the encrypted dataset on the tree table, then click Lock on the ZFS Encryption widget to open the Lock Dataset dialog with the dataset full path name.

Lock Dataset
Figure 8: Lock Dataset

Use the Force unmount option only if you are certain no one is currently accessing the dataset. Force unmount boots anyone using the dataset (e.g. someone accessing a share) so you can lock it. Click Confirm to activate Lock, then click Lock.

You cannot use locked datasets.

Unlocking a Dataset

To unlock a dataset, go to Datasets then select the locked dataset on the tree table. Click Unlock on the ZFS Encryption widget to open the Unlock Dataset screen.

Dataset Unlock Screen
Figure 9: Dataset Unlock Screen

Enter the key if key-encrypted, or the passphrase into Dataset Passphrase and click Save.

Select Unlock Child Encrypted Roots to unlock all locked child datasets if they use the same passphrase.

Select Force if the dataset mount path exists but is not empty. When this happens, the unlock operation fails. Using Force allows the system to rename the existing directory and file where the dataset should mount. This prevents the mount operation from failing. A confirmation dialog displays.

Continue Dataset Unlock Confirmation
Figure 10: Continue Dataset Unlock Confirmation

Click CONTINUE to confirm you want to unlock the datasets. Click CLOSE to exit and keep the datasets locked. A second confirmation dialog opens confirming the datasets unlocked. Click CLOSE. TrueNAS displays the dataset with the unlocked icon.

Encrypting a Zvol

Users are responsible for backing up and securing encryption keys and passphrases! Losing the ability to decrypt data is similar to a catastrophic data loss.

To encrypt a Zvol, select a parent dataset and then create a new Zvol. If the parent dataset is encrypted, select Inherit (encrypted) under Encryption Options. If the parent dataset is not encrypted, deselect Inherit (non-encrypted), select Encryption, and then configure the Encryption Type and related settings.

Next, go to Datasets and click on the Zvol and locate the ZFS Encryption widget.

ZFS Encryption Widget Root Dataset
Figure 11: ZFS Encryption Widget

To change encryption properties from passphrase to key or enter a new key or passphrase, select the zvol, then click Edit on the ZFS Encryption widget.

Edit Zvol Encryption
Figure 12: Edit Zvol Encryption

If Encryption Type is set to Key, type an encryption key into the Key field or select Generate Key. If using Passphrase, enter a passphrase of eight to 512 characters. Use a passphrase complex enough to not easily guess. After making any changes, select Confirm, and then click Save.

Save any change to the encryption key or passphrase, update your saved passcodes and keys file, and back up the file.

Managing Encryption Credentials

There are two ways to manage the encryption credentials, with a key file or passphrase. Creating a new encrypted pool automatically generates a new key file and prompts users to download it.

Always back up the key file to a safe and secure location.
To manually back up a root dataset key file, click Export Key on the ZFS Encryption widget.

Edit Root Dataset Encryption Keys
Figure 13: Edit Root Dataset Encryption Keys

See Changing Dataset-Level Encryption for more information on changing encryption settings.

A passphrase is a user-defined string at least eight characters long that is required to decrypt the dataset. A passphrase is a user-defined string of eight to 512 characters that is required to decrypt the dataset. The pbkdf2iters is the number of password-based key derivation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Users must enter a number greater than 100000.

Unlocking a Replicated Encrypted Dataset or Zvol Without a Passphrase

TrueNAS users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special JSON manifest to unlock each child dataset/zvol with a unique key.

Method 1: Construct JSON Manifest.

  1. Replicate every encrypted dataset you want to replicate with properties.

  2. Export key for every child dataset that has a unique key.

  3. For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this: {"tank/share01": "57112db4be777d93fa7b76138a68b790d46d6858569bf9d13e32eb9fda72146b"}

  4. Save this file with the extension .json.

  5. On the remote system, unlock the dataset(s) using properly constructed json files.

Method 2: Replicate Encrypted Dataset/zvol Without Properties.

Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.

  1. Go to Data Protection and click ADD in the Replication Tasks window.

  2. Click Advanced Replication Creation.

  3. Fill out the form as needed and make sure Include Dataset Properties is NOT checked.

  4. Click Save.

Method 3: Replicate Key Encrypted Dataset/zvol.

  1. Go to Datasets on the system you are replicating from. Select the dataset encrypted with a key, then click Export Key on the ZFS Encryption widget to export the key for the dataset.

  2. Apply the JSON key file or key code to the dataset on the system you replicated the dataset to.

    Option 1: Download the key file and open it in a text editor. Change the pool name/dataset part of the string to the pool name/dataset for the receiving system. For example, replicating from tank1/dataset1 on the replicate-from system to tank2/dataset2 on the replicate-to system.

    Option 2: Copy the key code provided in the Key for dataset window.

  3. On the system receiving the replicated pool/dataset, select the receiving dataset and click Unlock.

  4. Unlock the dataset. Either clear the Unlock with Key file checkbox, paste the key code into the Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that you edited.

  5. Click Save.

  6. Click Continue.