From 01e26aab1e2bfa3ee1e1ac099741e9749ce13199 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Thu, 9 Jan 2025 15:35:01 -0500 Subject: [PATCH] PD-1648 / 25.04 / Pd 1648 update encryption documentation (#3421) * Update EncryptionUISCALE.md * Update EncryptionSCALE.md * Update EncryptionSCALE.md * Update _index.md * Update EncryptionUISCALE.md * Update PoolCreateWizardScreens.md * Create EncryptionRootLevel.md * Update EncryptionWarning.md * Update DatasetsSCALE.md * Update EncryptionSCALE.md * Update CreatePoolWizard.md * Update _index.md * Update ZvolsScreensScale.md * Update CreatePool.md --------- Co-authored-by: linzibelle --- .../SCALETutorials/Datasets/DatasetsSCALE.md | 4 +- .../Datasets/EncryptionSCALE.md | 91 ++++++++++--------- .../Storage/CreatePoolWizard.md | 3 + .../SystemSettings/Advanced/_index.md | 2 +- .../Datasets/EncryptionUISCALE.md | 18 +++- .../Datasets/ZvolsScreensScale.md | 40 ++++---- .../SCALE/SCALEUIReference/Datasets/_index.md | 4 +- .../Storage/PoolCreateWizardScreens.md | 11 ++- static/includes/CreatePool.md | 4 +- static/includes/EncryptionRootLevel.md | 8 ++ static/includes/EncryptionWarning.md | 7 +- 11 files changed, 112 insertions(+), 80 deletions(-) create mode 100644 static/includes/EncryptionRootLevel.md diff --git a/content/SCALE/SCALETutorials/Datasets/DatasetsSCALE.md b/content/SCALE/SCALETutorials/Datasets/DatasetsSCALE.md index 5a4a853fdf..e62ddf0d1c 100644 --- a/content/SCALE/SCALETutorials/Datasets/DatasetsSCALE.md +++ b/content/SCALE/SCALETutorials/Datasets/DatasetsSCALE.md @@ -24,8 +24,8 @@ A TrueNAS *dataset* is a file system within a data storage pool. Datasets can contain files, directories, and child datasets, and have individual permissions or flags. Datasets can also be [encrypted]({{< relref "EncryptionSCALE.md" >}}). -TrueNAS automatically encrypts datasets created in encrypted pools, but you can change the encryption type from key to passphrase. -You can create an encrypted dataset if the pool is not encrypted and set the type as either key or passphrase. +In TrueNAS 22.12.3 or later, the TrueNAS UI requires encryption for child datasets created in encrypted parent datasets, but you can change the encryption type from key to passphrase. +You can create an encrypted dataset if the parent is not encrypted and set the type as either key or passphrase. We recommend organizing your pool with datasets before configuring [data sharing]({{< relref "/SCALE/SCALEUIReference/Shares/_index.md" >}}), as this allows for more fine-tuning of access permissions and using different sharing protocols. diff --git a/content/SCALE/SCALETutorials/Datasets/EncryptionSCALE.md b/content/SCALE/SCALETutorials/Datasets/EncryptionSCALE.md index 783614dde5..f1abfd22fa 100644 --- a/content/SCALE/SCALETutorials/Datasets/EncryptionSCALE.md +++ b/content/SCALE/SCALETutorials/Datasets/EncryptionSCALE.md @@ -18,7 +18,7 @@ keywords: - data sharing --- -TrueNAS offers ZFS encryption for your sensitive data in pools and datasets or Zvols. +TrueNAS offers ZFS encryption for your sensitive data in datasets and zvols. {{< include file="/static/includes/EncryptionBackupKeys.md" >}} @@ -36,20 +36,20 @@ TrueNAS includes the [Key Management Interface Protocol (KMIP)](https://docs.oas {{< include file="/static/includes/EncryptionWarning.md" >}} TrueNAS automatically generates a root dataset when you create a pool. -This root dataset inherits the encryption state of the pool through the **Encryption** option on the **[Pool Creation Wizard]({{< relref "PoolCreateWizardScreens.md" >}})** screen when you create the pool. -Because encryption is inherited from the parent, all data within that pool is encrypted. -Selecting the **Encryption** option for the pool (root dataset) forces encryption for all datasets and zvols created within the root dataset. +Select **Encryption** on the **[Pool Creation Wizard]({{< relref "PoolCreateWizardScreens.md" >}})** 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. -You cannot create an unencrypted dataset within an encrypted pool or dataset. -This change does not affect existing datasets created in earlier releases of TrueNAS but does affect new datasets created in 22.12.3 and later releases. +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]({{< relref "/content/TrueNASApps/_index.md #ix-apps-dataset" >}}) on the pool selected for applications does not inherit encryption settings. -Leave the **Encryption** option on the **Pool Creation Wizard** screen cleared to create an unencrypted pool. +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 create an encrypted dataset within an unencrypted dataset, all datasets or zvol created within that encrypted dataset are automatically encrypted. -Using encryption ensures secure data sharing and storage. - -If you have only one pool on your system, do not select the **Encryption** option for this pool. +If you have only one pool on your system, do not use pool-level encryption for this pool. {{< expand "Can I change dataset encryption?" "v" >}} Before you save a new dataset, you can change the type of encryption of an encrypted dataset to key to passphrase. @@ -63,10 +63,11 @@ You can also move data from an unencrypted pool or dataset to an encrypted datas {{< /expand >}} {{< hint type=important >}} -If your system loses power or you reboot the system, the datasets, zvols, and all data in an encrypted pool automatically lock to protect the data in that encrypted pool. +If your system loses power or you reboot the system, all encrypted datasets and zvols lock automatically to protect data. {{< /hint >}} ### 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]({{< relref "/SCALE/SCALEUIReference/Datasets/_index.md" >}})** screen. Each icon shows a text label with the state of the dataset when you hover the mouse over the icon. @@ -80,18 +81,24 @@ The dataset encryption state is unlocked until you lock it using the **Lock** bu 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 pool with encryption decide if you want to encrypt all datasets, zvols, and data stored on the pool. -{{< hint type=warning >}} -You cannot change a pool from encrypted to non-encrypted. You can only change the dataset encryption type (key or passphrase) for the encrypted pool. -{{< /hint >}} +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. -{{< hint type=important >}} + 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. +{{< hint type=important >}} +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. {{< /hint >}} + ### Adding Encryption to a New Pool + +{{< include file="/static/includes/EncryptionRootLevel.md" >}} + 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**. @@ -110,6 +117,7 @@ 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. @@ -124,28 +132,22 @@ Select the **Dataset Preset** option you want to use. Options are: {{< include file="/static/includes/DatasetPresetOptions.md" >}} 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, clear the checkmark to show the **Encryption** option. -If the parent dataset is encrypted and you want to change the type, clearing the checkmark shows the other encryption options. -To keep the dataset encryption settings from the parent, leave inherited checkmarked. +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. {{< trueimage src="/images/SCALE/Datasets/AddDatasetEncryptionOptionsInheritCleared.png" alt="Add Dataset Encryption Options Clear Inherit" id="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 your key, clear the **Generate key** checkbox to display the **Key** field. Enter your key in this field. +To use key encryption and an existing key, deselect **Generate Key** to display the **Key** field. +Enter the existing key in this field. {{< trueimage src="/images/SCALE/Datasets/AddDatasetEncryptionKeyfromNonEncrypted.png" alt="Add Key Encryption" id="Add Key Encryption" >}} -To change to passphrase encryption, click the down arrow and select **Passphrase** from the **Encryption Type** dropdown. +To change to passphrase encryption, select **Passphrase** from the **Encryption Type** dropdown. {{< trueimage src="/images/SCALE/Datasets/AddDatasetEncryptionOptionsPassphrase.png" alt="Add Passphrase Encryption" id="Add Passphrase Encryption" >}} -You can select the encryption algorithm to use from the **Encryption Standard** dropdown list of options or use the recommended default. -Leave the default selection if you do not have a particular encryption standard you want to use. -{{< expand "What are these options?" "v" >}} -TrueNAS supports AES [Galois Counter Mode (GCM)](https://csrc.nist.gov/publications/detail/sp/800-38d/final) and [Counter with CBC-MAC (CCM)](https://tools.ietf.org/html/rfc3610) algorithms for encryption. -These algorithms provide authenticated encryption with block ciphers. -{{< /expand >}} - {{< hint type=note >}} The passphrase must be longer than 8 and less than 512 characters. {{< /hint >}} @@ -155,7 +157,15 @@ Keep encryption keys and/or passphrases safeguarded in a secure and protected pl Losing encryption keys or passphrases can result in permanent data loss! {{< /hint >}} +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. +{{< expand "What are these options?" "v" >}} +TrueNAS supports AES [Galois Counter Mode (GCM)](https://csrc.nist.gov/publications/detail/sp/800-38d/final) and [Counter with CBC-MAC (CCM)](https://tools.ietf.org/html/rfc3610) algorithms for encryption. +These algorithms provide authenticated encryption with block ciphers. +{{< /expand >}} + ### 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. @@ -192,12 +202,14 @@ 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 + {{< hint type=important >}} 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. {{< /hint >}} ### 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. {{< trueimage src="/images/SCALE/Datasets/LockDatasetDialog.png" alt="Lock Dataset" id="Lock Dataset" >}} @@ -211,6 +223,7 @@ You *cannot* use locked datasets. {{< /hint >}} ### 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. @@ -232,26 +245,18 @@ Click **CLOSE**. TrueNAS displays the dataset with the unlocked icon. ## Encrypting a Zvol -Encryption is for securing sensitive data. - -{{< hint type=note >}} -You can only encrypt a Zvol if you create the Zvol from a dataset with encryption. -{{< /hint >}} {{< include file="/static/includes/EncryptionBackupKeys.md" >}} -Zvols inherit encryption settings from the parent dataset. +To encrypt a Zvol, select a parent dataset and then [create a new Zvol]({{< relref "AddManageZvols.md" >}}). +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. -To encrypt a Zvol, select a dataset configured with encryption and then [create a new Zvol]({{< relref "AddManageZvols.md" >}}). -Next, go to **Datasets** and click on the Zvol. +Next, go to **Datasets** and click on the Zvol and locate the **ZFS Encryption** widget. {{< trueimage src="/images/SCALE/Datasets/ZFSEncryptionWidgetRootDataset.png" alt="ZFS Encryption Widget Root Dataset" id="ZFS Encryption Widget" >}} -If you do not see the **ZFS Encryption** widget, you created the Zvol from an unencrypted dataset. Delete the Zvol and start over. - -The Zvol is encrypted with settings inherited from the parent dataset. - -To change inherited encryption properties from passphrase to key, or enter a new key or passphrase, select the zvol, then click **Edit** on the **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. {{< trueimage src="/images/SCALE/Datasets/EditEncryptionDialogForZvol.png" alt="Edit Zvol Encryption" id="Edit Zvol Encryption" >}} @@ -264,6 +269,7 @@ Save any change to the encryption key or passphrase, update your saved passcodes {{< /hint >}} ## 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. @@ -280,6 +286,7 @@ A passphrase is a user-defined string at least eight characters long that is req The **pbkdf2iters** is the number of password-based key derivation function 2 ([PBKDF2](https://tools.ietf.org/html/rfc2898#appendix-A.2)) 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. {{< include file="/static/includes/ReplicatedEncryptedUnlock.md" >}} diff --git a/content/SCALE/SCALETutorials/Storage/CreatePoolWizard.md b/content/SCALE/SCALETutorials/Storage/CreatePoolWizard.md index defeecc1bc..ebaa8a43ad 100644 --- a/content/SCALE/SCALETutorials/Storage/CreatePoolWizard.md +++ b/content/SCALE/SCALETutorials/Storage/CreatePoolWizard.md @@ -33,6 +33,9 @@ We strongly recommend that you review your available system resources and plan y * Maximizing pool performance entails installing and allocating high-speed SSD drives to a pool. Security requirements can mean the pool must be created with [ZFS encryption]({{< relref "EncryptionSCALE.md" >}}). +However, we recommend that users create pools as unencrypted and then encrypt some or all of of the child datasets, as needed. + +{{< include file="/static/includes/EncryptionRootLevel.md" >}} RAIDz pool layouts are well-suited for general use cases and especially smaller (<10) data VDEVS or storage scenarios that involve storing multitudes of small data blocks. diff --git a/content/SCALE/SCALETutorials/SystemSettings/Advanced/_index.md b/content/SCALE/SCALETutorials/SystemSettings/Advanced/_index.md index d85b20d4e2..9f068f83a4 100644 --- a/content/SCALE/SCALETutorials/SystemSettings/Advanced/_index.md +++ b/content/SCALE/SCALETutorials/SystemSettings/Advanced/_index.md @@ -71,7 +71,7 @@ It also stores Samba4 metadata, such as the user and group cache and share-level If the system has one pool, TrueNAS configures that pool as the system dataset pool. If your system has more than one pool, you can set the system dataset pool using the **Select Pool** dropdown. -Users can move the system dataset to an unencrypted pool, or an encrypted pool without passphrases. +Users can move the system dataset to an unencrypted pool or a key-encrypted pool. ![SystemDatasetPoolConfigScreen](/images/SCALE/SystemSettings/SystemStorageConfigScreen.png "TrueNAS Advanced Settings System Dataset Pool Screen") diff --git a/content/SCALE/SCALEUIReference/Datasets/EncryptionUISCALE.md b/content/SCALE/SCALEUIReference/Datasets/EncryptionUISCALE.md index 8658367c39..14d4671040 100644 --- a/content/SCALE/SCALEUIReference/Datasets/EncryptionUISCALE.md +++ b/content/SCALE/SCALEUIReference/Datasets/EncryptionUISCALE.md @@ -18,30 +18,42 @@ Datasets, root, non-root parent, and child, or zvols with encryption include the {{< include file="/static/includes/EncryptionIconsSCALE.md" >}} -## Pool Encryption +## Dataset Encryption + The **Encryption** option on the **[Pool Manager]({{< relref "PoolCreateWizardScreens.md" >}})** screen sets encryption for the pool and root dataset. + +{{< include file="/static/includes/EncryptionRootLevel.md" >}} + The **Download Encryption Key** warning window displays when you create the pool. It downloads a JSON file to your downloads folder. {{< trueimage src="/images/SCALE/Storage/DownloadPoolEncryptionKey.png" alt="Download Pool Encryption Key" id="Download Pool Encryption Key" >}} +The [**Encryption Options** settings]({{< relref "/scale/scaleuireference/datasets/_index.md #encryption-options-section" >}}) under **Advanced Options** on the **Add Dataset** screen configure encryption for that dataset. + +{{< trueimage src="/images/SCALE/Datasets/AddDatasetBasicEncryptionAndOtherOptions.png" alt="Add Dataset Encryption Options Key" id="Add Dataset Encryption Options Key" >}} + ## Export Key Options + The **ZFS Encryption** widget for root datasets with encryption includes the **Export All Keys** and **Export Key** options. It does not include the **Lock** option. If a dataset is encrypted using a key, the **ZFS Encryption** widget for that dataset includes the **Export Key** option. ### Export All Keys Dialog + **Export All Keys** opens a confirmation dialog with the **Download Keys** option that exports a JSON file of all encryption keys to the system download folder. {{< trueimage src="/images/SCALE/Datasets/ExportAllKeysDialog.png" alt="Export All Keys" id="Export All Keys" >}} ### Export Key Dialog + **Export Key** opens a dialog with the key for the selected dataset and the **Download Key** option that exports a JSON file with the encryption key to your system download folder. {{< trueimage src="/images/SCALE/Datasets/ExportKeyDialog.png" alt="Export Key" id="Export Key" >}} ## Edit Encryption Options Window -Encryption type and options are set for a dataset when it is first created and are inherited from the root dataset. + +Encryption type and options are set for a dataset when it is first created or are inherited from the root dataset. The **Edit Encryption Options for *datasetname*** displays the current encryption option settings for the selected encrypted dataset. Use to change the encryption type from or to key or passphrase, and the related settings. @@ -55,6 +67,7 @@ The encryption settings options are the same as those on **Add Dataset > Encrypt {{< /expand >}} ## Lock Dataset Dialog + **Lock** displays on encrypted non-root parent or child datasets **ZFS Encryption** widgets. An encrypted child that inherits encryption from a non-root parent does not see the **Lock** option on its **ZFS Encryption** widget because the lock state is controlled by the parent dataset for that child dataset. The locked icon for child datasets that inherit encryption is the locked by ancestor icon. @@ -67,6 +80,7 @@ The locked icon for child datasets that inherit encryption is the locked by ance After locking a dataset, the **ZFS Encryption** screen displays **Locked** as the **Current State** and adds the **Unlock** option. ## Unlock Datasets Screen + **Unlock** on the **ZFS Encryption** widget displays for locked datasets that are not child datasets that inherit encryption from the parent dataset. **Unlock** opens the **Unlock Datasets** screen, which allows you to unlock the selected dataset and child datasets simultaneously. diff --git a/content/SCALE/SCALEUIReference/Datasets/ZvolsScreensScale.md b/content/SCALE/SCALEUIReference/Datasets/ZvolsScreensScale.md index 44649fdc81..bc5977e347 100644 --- a/content/SCALE/SCALEUIReference/Datasets/ZvolsScreensScale.md +++ b/content/SCALE/SCALEUIReference/Datasets/ZvolsScreensScale.md @@ -9,22 +9,22 @@ tags: - storage --- -The zvol screens and widgets, accessed from the **Datasets** screen, allow you to add or edit a zvol and manage the volume storage. +The zvol screens and widgets, accessed from the **Datasets** screen, allow you to add or edit a zvol and manage the volume storage. Zvols are listed on the **Datasets** screen tree table. {{< trueimage src="/images/SCALE/Datasets/DatasetsScreenWithZvolWidgets.png" alt="Dataset Tree Table and Zvol Widgets" id="Dataset Tree Table and Zvol Widgets" >}} -The tree table includes storage space used and available for that zvol (or dataset), encryption status (locked, unlocked, or unencrypted), and the role of that zvol or dataset or what service uses it (i.e., the system dataset, a share, virtual machine, or application). +The tree table includes storage space used and available for that zvol (or dataset), encryption status (locked, unlocked, or unencrypted), and the role of that zvol or dataset or what service uses it (i.e., the system dataset, a share, virtual machine, or application). **Add Zvol** displays after you select a root, non-root parent, or child dataset. It does not display if you select an existing zvol. Click on any root or non-root parent dataset to expand the tree table. Click on any zvol to select it and display the widgets for that zvol. ## Zvol Widgets -Each zvol has a set of information cards (widgets) that display in the **Details for *zvolname*** area of the screen and provide information grouped by functional areas. -**Add Zvol** opens the **Add Zvol** screen. +Each zvol has a set of information cards (widgets) that display in the **Details for *zvolname*** area of the screen and provide information grouped by functional areas. +**Add Zvol** opens the **Add Zvol** screen. Dataset widgets are: -* **[Zvol Details](#zvol-details-widget)** +* **[Zvol Details](#zvol-details-widget)** * **[Zvol Space Management](#zvol-space-management-widget)** * **[Data Protection](#data-protection-widget)** * **[ZFS Encryption](#zfs-encryption-widget)** @@ -37,12 +37,12 @@ The **Zvol Details** widget lists information on volume type, and the sync, comp **Edit** opens the **[Edit Zvol](#add-and-edit-zvol-screens)** screen for the selected zvol. -**[Delete](#delete-dataset)** opens the **Delete zvol** dialog. +**[Delete](#delete-dataset)** opens the **Delete zvol** dialog. #### Delete Zvol -The **Delete Zvol** dialog shows information about other options or services that use the zvol. It also shows the services child datasets use. +The **Delete Zvol** dialog shows information about other options or services that use the zvol. It also shows the services child datasets use. This includes information about snapshots, shares, or if used, other services such as Kubernetes or VMs that use the dataset. -Parent and child datasets include the **Delete** button. +Parent and child datasets include the **Delete** button. {{< trueimage src="/images/SCALE/Datasets/DeleteZvolWindow.png" alt="Delete Zvol" id="Delete Zvol" >}} @@ -50,9 +50,9 @@ The window includes a field where you type the path for the zvol, and a **Confir ### Zvol Space Management Widget The **Zvol Space Management** widget displays space allocation (reserved, used, available) for the zvol. -The widget displays after unlocking encrypted zvols. -The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected zvol. -This includes data written and space allocated to child datasets of this dataset. +The widget displays after unlocking encrypted zvols. +The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected zvol. +This includes data written and space allocated to child datasets of this dataset. It provides access to quota configuration options for the parent dataset and the child dataset of the parent, and for users and groups with access to the dataset. {{< trueimage src="/images/SCALE/Datasets/ZvolSpaceManagementWidget.png" alt="Zvol Space Management Widget" id="Zvol Space Management Widget" >}} @@ -74,9 +74,9 @@ The **Export Key** option displays if the zvol uses key encryption. For more details on encryption windows and functions see [Encryption Settings]({{< relref "EncryptionUISCALE.md" >}}). ### Data Protection Widget -The **Data Protection** widget displays for all datasets or zvols. -It shows information for the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system. -It provides access to the tasks found on the **Data Protection** screen through links. +The **Data Protection** widget displays for all datasets or zvols. +It shows information for the number of snapshots and other data protection-related scheduled tasks (replication, cloud sync, rsync, and snapshots) configured on the system. +It provides access to the tasks found on the **Data Protection** screen through links. {{< trueimage src="/images/SCALE/Datasets/DataProtectionWidget.png" alt="Data Protection Widget" id="Data Protection Widget" >}} @@ -94,9 +94,9 @@ It provides access to the tasks found on the **Data Protection** screen through ## Add and Edit Zvol Screens The **Add Zvol** and **Edit Zvol** screens allow admin users with the right permission level to create and modify zvols. -Both screens include the same settings but you cannot change the zvol name, **Block Size**, or select the **Sparse** option after you click **Save** on the **Add Zvol** screen. +Both screens include the same settings but you cannot change the zvol name, **Block Size**, or select the **Sparse** option after you click **Save** on the **Add Zvol** screen. -After adding a zvol, click **Edit** on the **Zvol Details** widget to open the **Edit Zvol** screen. +After adding a zvol, click **Edit** on the **Zvol Details** widget to open the **Edit Zvol** screen. To edit encryption options, click **Edit** on the **ZFS Encryption** widget. {{< trueimage src="/images/SCALE/Datasets/AddZvolScreen.png" alt="Add Zvol Screen" id="Add Zvol Screen" >}} @@ -127,7 +127,7 @@ This table shows the minimum recommended volume block size values by configurati Use this table to change the **Block size** value. {{< truetable >}} -| Configuration | Number of Drives | Optimal Block Size | +| Configuration | Number of Drives | Optimal Block Size | |---------------|------------------|--------------------| | Mirror | N/A | 16k | | Raidz-1 | 3 | 16k | @@ -153,11 +153,11 @@ See the OpenZFS handbook [workload tuning chapter](https://openzfs.github.io/ope {{< include file="/static/includes/StorageCompressionLevelsScale.md" >}} ### Encryption Options -**Encryption Options** only display on the **Add Zvol** screen. +**Encryption Options** only display on the **Add Zvol** screen. To change encryption settings, use the **Edit** button on the **ZFS Encryption** widget. -The default setting is **Inherit**. Clearing the checkbox displays the key encryption options. -Clear the **Inherit(*non-encrypted*)** checkbox to display additional settings. +The default setting is **Inherit**. Clearing the checkbox displays the encryption options. +Clear the **Inherit (*non-encrypted*)** checkbox to display additional settings. {{< trueimage src="/images/SCALE/Datasets/AddZvolEncryptionOptionsKey.png" alt="Add Zvol Encryption Options Clear Inherit" id="Add Zvol Encryption Options Clear Inherit" >}} diff --git a/content/SCALE/SCALEUIReference/Datasets/_index.md b/content/SCALE/SCALEUIReference/Datasets/_index.md index 9bcbbf2224..f43a8707c8 100644 --- a/content/SCALE/SCALEUIReference/Datasets/_index.md +++ b/content/SCALE/SCALEUIReference/Datasets/_index.md @@ -302,7 +302,7 @@ Encryption setting options display on the **Advanced Options** of the **Add Data To edit encryption settings, click **Edit** on the [**ZFS Encryption** widget](#zfs-encryption-widget). This opens the **Edit Encryption Options for *datasetName*** window where you can change encryption settings for an existing dataset. -{{< trueimage src="/images/SCALE/Datasets/AddDatasetBasicEncryptionAndOtherOptions.png" alt="Add Dataset Encryption Options Clear Inherit" id="Add Dataset Encryption Options Clear Inherit" >}} +{{< trueimage src="/images/SCALE/Datasets/AddDatasetBasicEncryptionAndOtherOptions.png" alt="Add Dataset Encryption Options Key" id="Add Dataset Encryption Options Key" >}} If you create an unencrypted dataset, the default setting is **Inherit (Non-Encrypted)**, and you can create encrypted or unencrypted child datasets under it. If you create an encrypted dataset, the default setting is **Inherit (Encryption)**, and all child datasets created under it are encrypted. @@ -311,7 +311,7 @@ The default **Inherit** option is pre-selected. Clear the **Encryption** option (pre-selected) checkbox to show the key type encryption settings. Select **Passphrase** in **Encryption Type** to show other settings. -{{< trueimage src="/images/SCALE/Datasets/AddDatasetEncryptionPassphrase.png" alt="Add Dataset Encryption Passphrase" id="Add Dataset Encryption Passphrase" >}} +{{< trueimage src="/images/SCALE/Datasets/AddDatasetEncryptionPassphrase.png" alt="Add Dataset Encryption Options Passphrase" id="Add Dataset Encryption Options Passphrase" >}} {{< expand "Encryption Settings" "v" >}} {{< truetable >}} diff --git a/content/SCALE/SCALEUIReference/Storage/PoolCreateWizardScreens.md b/content/SCALE/SCALEUIReference/Storage/PoolCreateWizardScreens.md index 76e813a4a3..b8f61a8d3a 100644 --- a/content/SCALE/SCALEUIReference/Storage/PoolCreateWizardScreens.md +++ b/content/SCALE/SCALEUIReference/Storage/PoolCreateWizardScreens.md @@ -39,20 +39,21 @@ The **General Info** area includes two default settings, **Name** and **Encrypti {{< trueimage src="/images/SCALE/Storage/PoolCreationWizardGeneralInfo.png" alt="Pool Creation Wizard General Info" id="Pool Creation Wizard General Info" >}} -**Name** is a required field. +**Name** is a required field. Enter a pool name of up to 50 characters in length that follows [ZFS naming conventions](https://docs.oracle.com/cd/E23824_01/html/821-1448/gbcpt.html). Use lower-case alpha characters to avoid potential problems with sharing protocols. Names can include numbers and special characters such as underscore (_), hyphen (-), colon (:), or a period (.). **Encryption** applies key-type encryption to the pool. -Select to enable [ZFS encryption](https://zfsonlinux.org/manpages/0.8.3/man8/zfs.8.html) for the pool and all datasets (or zvols) created within the pool. + +{{< include file="/static/includes/EncryptionRootLevel.md" >}} + +Select to enable [ZFS encryption](https://zfsonlinux.org/manpages/0.8.3/man8/zfs.8.html) for the pool and all datasets (or zvols) within the pool created using the TrueNAS UI. See [Storage Encryption]({{< relref "EncryptionScale.md" >}}) for more information on using TrueNAS storage encryption. An encryption warning dialog displays with a **Confirm** checkbox. Select to enable the **I Understand** button. **I Understand** allows you to continue adding the pool with encryption applied. {{< hint type="Warning" >}} -Applying encryption at the pool level also encrypts all datasets (and zvols) within the pool. - Keep the encryption key file in a safe location where you perform regular backups. Losing the encryption key file results in lost data you cannot recover. {{< /hint >}} @@ -106,7 +107,7 @@ Use the **Log** wizard screen to configure a log VDEV. ZFS log devices can impro {{< trueimage src="/images/SCALE/Storage/PoolCreationWizardLogScreen.png" alt="Pool Creation Wizard Log Screen" id="Pool Creation Wizard Log Screen" >}} {{< expand "Common Pool Creation Wizard Settings" "v" >}} -The **Layout** dropdown list includes the **Stripe** or **Mirror** types. +The **Layout** dropdown list includes the **Stripe** or **Mirror** types. {{< include file="/static/includes/PoolCreationWizardCommonSettings.md" >}} {{< /expand >}} diff --git a/static/includes/CreatePool.md b/static/includes/CreatePool.md index afdfea5eaf..b5c91b76fc 100644 --- a/static/includes/CreatePool.md +++ b/static/includes/CreatePool.md @@ -21,7 +21,7 @@ You can rename your enclosure on the [Enclosure Screen]({{< relref "EnclosureScr {{< /hint >}} 2. (Enterprise systems only) Select the **Enclosure Option** to apply the dispersal strategy of your choice. Only shows for iXsystems-provided systems with expansion shelves. - + {{< trueimage src="/images/SCALE/Storage/PoolCreationWizardEnclosureOptionsScreen.png" alt="Pool Creation Wizard Enclosure Options" id="Pool Creation Wizard Enclosure Options" >}} **No Enclosure Dispersal Strategy** does not apply a dispersal strategy in how the system adds disks by size and type to the pool VDEVs created when using the **Automated Disk Selection** option. @@ -43,7 +43,7 @@ You can rename your enclosure on the [Enclosure Screen]({{< relref "EnclosureScr **dRAID** layouts do not show the **Manual Disk Selection** button but do show additional **Automated Disk Selection** fields. When configuring a **dRAID** data VDEV, first choose a **Disk Size** then select a **Data Devices** number. The remaining fields update based on the **Data Devices** and **dRAID** layout selections. - + {{< include file="/static/includes/dRaidGroupLayout.md" >}} Click **Save And Go To Review** if you do not want to add other VDEV types to the pool, or click **Next** to move to the next wizard screens. diff --git a/static/includes/EncryptionRootLevel.md b/static/includes/EncryptionRootLevel.md new file mode 100644 index 0000000000..5b7371fcbc --- /dev/null +++ b/static/includes/EncryptionRootLevel.md @@ -0,0 +1,8 @@ + + +{{< hint type=important title="Pool-level Encryption is Not Recommended" >}} +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. +{{< /hint >}} diff --git a/static/includes/EncryptionWarning.md b/static/includes/EncryptionWarning.md index c6bc5276cf..6b24fa4f02 100644 --- a/static/includes/EncryptionWarning.md +++ b/static/includes/EncryptionWarning.md @@ -1,9 +1,8 @@ {{< hint type=important >}} - Encryption is for users storing sensitive data. -Pool-level encryption does not apply to the storage pool or the disks in the pool. -It only applies to the root dataset that shares the same name as the pool. -Child datasets or zvols inherit encryption from the parent dataset. +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. {{< /hint >}}