TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Datasets

The Datasets screen and widgets display information about datasets, provide access to data management functions, indicate the dataset roles, list the services using the dataset, show the encryption status, and the permissions the dataset has in place. The screen focus is on managing data storage including user and group quotas, snapshots, and other data protection measures.

Datasets Screen

The Datasets screen displays No Datasets with a Create Pool button in the center of the screen until you add a pool and the first root dataset.

Datasets Screen Without a Pool
Figure 1: Datasets Screen Without a Pool

The screen has two main sections, the dataset tree table on the left and the Details for datasetname on the right. After creating a dataset, the tree table that lists parent and child datasets (or Zvols) on the system. The Details for datasetname area displays a set of dataset widgets.

Large petabyte systems might report storage numbers inaccurately. Storage configurations with more than 9,007,199,254,740,992 bytes round the last 4 digits. For example, a system with 18,446,744,073,709,551,615 bytes reports the number as 18,446,744,073,709,552,000 bytes.
Datasets Screen With a Pool
Figure 2: Datasets Screen With a Pool

Add Zvol opens the Add Zvol screen.

Add Dataset opens the Add Dataset screen.

Begin typing the name of a dataset in the Search field to filter datasets to a short list of those matching what is typed.

Dataset Tree Table

The datasets tree table lists datasets in an expandable hierarchical structure with the root dataset first, then each direct child or non-root parent dataset follows and with their child datasets nested under them.

Click on any root or non-root parent dataset to expand the tree table. Click on any dataset to select it and display the dataset widgets for that dataset.

Dataset Tree Table
Figure 3: Dataset Tree Table

The table includes used and available storage space for that dataset, encryption status (locked, unlocked, or unencrypted), the role of that dataset, and what service uses it (i.e., the system dataset, a share, virtual machine, or application).

Tree Table Encryption Icons

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.
Tree Table Role Icons

Dataset tree table roles are represented by icons. Hover over the icons to view the description or icon label. Roles in the dataset tree correspond to the Roles widget. A dataset with an active task include an activity spinner when that task is in progress.

RoleIconDescription
System datasetDatasetRolesSystemDatasetIconIndicates the parent (root) dataset designated as the system dataset. To change the system dataset go to System Settings > Advanced Settings and edit the System Dataset Pool.
ShareDatasetRolesShareGenericIconIndicates the dataset is used by a share or that child datasets of the parent are used by shares.
SMB shareDatasetRolesSMBShareIconIndicates the dataset is used by an SMB share.
VMDatasetRolesVMIconIndicates the dataset is used by a virtual machine (VM).
AppsDatasetRolesAppsIconIndicates this dataset is used by applications and stores Kubernetes configuration and container related data.

Dataset Widgets

Each dataset has a set of information cards (widgets) that display in the Details for datasetname area of the screen. These widgets provide information grouped by functional areas. The set of widgets for a root or parent dataset differs from child datasets or datasets used by another service or with encryption.

Dataset widgets are:

Datasets Details Widget

The Dataset Details widget lists information on dataset type, sync type, compression level, case sensitivity, Atime, and ZFS deduplication settings. Path displays the full path for the selected dataset.

A root dataset path displays the pool name alone.

Dataset Details Widget Root Dataset
Figure 4: Dataset Details Widget Root Dataset
Click Here for More Information

A child dataset path displays the root dataset (pool) name and parent dataset.

Edit opens the Edit Dataset screen for the selected dataset.

Promote appears on the Dataset Details widget when you select a cloned snapshot on the dataset tree table. This option promotes the cloned child dataset and allows users to delete the parent volume that created the clone. Otherwise, you cannot delete a clone while the original volume still exists. See zfs-promote.8.

Non-root parent and child dataset versions of the card include the Delete button. To delete a root dataset, use the Disconnect/Export option on the Storage Dashboard screen.

Delete opens a window that includes information about other options or services that use the dataset, for example a parent to other datasets and the services the child datasets of a parent dataset uses. Non-root parent and child datasets include the Delete button.

Delete Window

The Delete window for a parent dataset (non-root) includes information about snapshots, shares or other services such as Kubernetes or VMs that use the dataset. If it is a parent to other datasets, the window includes the services a child dataset of this parent dataset uses.

Delete Dataset Parent Dataset
Figure 6: Delete Dataset Parent Dataset
Click Here for More Information

If a child dataset uses services the window displays the services.

If a service does not use a child dataset, the Delete window does not display a service.

The window includes a field where you type the path for the dataset and a Confirm option that you must select to activate the Delete Dataset button.

Dataset Space Management Widget

The Dataset Space Management widget displays space allocation (reserved, used, available) for all datasets. The widget displays if an encrypted dataset is unlocked. After locking the dataset this widget disappears until you unlocking the datasets.

Dataset Space Management Widget Root Dataset
Figure 9: Dataset Space Management Widget Root Dataset
Click Here for More Information

The widget donut graph provides at-a-glance information and numeric values for the space allocated and used in the selected dataset. 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.

Edit opens the Capacity Settings screen where you can set quotas for the dataset.

Manage User Quotas screen and Manage Group Quotas opens the Manage Group Quotas screen.

Data Protection Widget

The Data Protection widget displays for all datasets. It displays the number snapshots and other data protection related scheduled tasks (replication, cloud sync, rsync and snapshots) configured on the system.

Data Protection Widget
Figure 10: Data Protection Widget
Click Here for More Information

The Data Protection widget links to the tasks found on the Data Protection screen.

Create Snapshot opens the Add Snapshot screen.

Manage Snapshots opens the Snapshots screen list view where you can manage snapshots.

Manage Snapshot Tasks opens the Data Protection > Periodic Snapshot Tasks screen list view where you can manage scheduled periodic snapshot tasks.

Manage Replication Tasks opens the Data Protection > Replications Tasks screen list view where you can manage scheduled replication tasks.

Manage Cloud Sync Tasks opens the Data Protection > Cloud Sync Tasks screen list view where you can manage scheduled cloud sync tasks.

Manage Rsync Tasks opens the Data Protection > Rsync Tasks screen list view where you can manage scheduled rsync tasks.

The Snapshot counter shows the number of snapshots taken. The Snapshot Tasks counter shows the number of scheduled snapshot tasks. The Replication Tasks counter shows the number of scheduled replication tasks. The Cloud Sync Tasks and Rsync Task counters show shows the number of schedule push tasks. These tasks protect or back up data, where pull sync tasks do not and are not included in the task count.

Permissions Widget

The Permissions widget displays for all datasets. It shows the type of ACL as either NFSv4 or Unix Permissions (POSIX), lists access control items, and the owner and group for the dataset.

Permissions Widget Root Dataset
Figure 11: Permissions Widget Root Dataset
Click Here for More Information

Root dataset permissions are not editable. Permission screen and widget options vary based on the ACL type.

Parent and child dataset permissions are editable.

If the ACL type is NFSv4 (the default ACL type) the widget turns the items listed on the Permissions widget into buttons that open a configuration are where you can edit the item from the Permissions widget. The expanded item configuration area has both Permissions Advanced and Flags Advanced check-buttons you can select or deselect common NFSv4 permission options for each item type.

A dataset with a POSIX ACL type, such as the ix-applications dataset, is only editable using the Edit button. Edit opens the permission edit screen for ACL based on the type.

Roles Widget

The Roles widget displays the dataset role or the service that uses it (i.e., a share, application, virtual machine, or the system dataset). A parent dataset displays information on child datasets that a service uses. If the dataset is the also the system dataset, the widget includes a link to the System Settings > Advanced screen where you can manage the system dataset.

Roles Widget System Dataset
Figure 14: Roles Widget System Dataset
Roles Service Links

The Roles widget displays information about the service using the dataset and provides a link to manage that service. The widget roles information corresponds to the roles information in the dataset tree table.

The Roles widget for a dataset with no share shows two links, one to create an SMB share and the other to create and NFS share.

RoleLink IncludedDescription
System datasetManage Advanced SettingsSelect the option to configure the System Dataset
AppsManage Apps SettingsDisplays Kubernetes is using the dataset. Select the option to Choose Pool from the Settings dropdown list on the Applications screen.
Dataset with no shareCreate SMB Share
Create NFS Share
Opens either the Add SMB or Add NFS share screen to configure the share.
SMB shareManage SMB SharesDisplays the name of the SMB share using the dataset. Select the snare on the Sharing SMB screen to edit it.
Other shareLink to the share type screenDisplays the name of the share using the dataset. Select the on the share screen (NFS or iSCSI) to edit it.
Multiprotocol shareManage SMB Shares
Manage NFS Shares
Displays the name of the SMB and NFS share using the dataset. Each link opens the Sharing SMB or Sharing NFS screens. Click on the share to edit it.
VMManage VM SettingsDisplays the name of the VM using the dataset(Zvol). Select it on the Virtual Machines screen to edit it.

ZFS Encryption Widget

The ZFS Encryption widget displays for datasets configured with encryption but the options in the widget vary based on the type of dataset (root, non-root parent, or child dataset). It includes the current state of the dataset encryption, the encryption root, type and algorithm used.

ZFS Encryption Widget Root Dataset
Figure 15: ZFS Encryption Widget Root Dataset
Click Here for More Information

The ZFS Encryption widget displays the Lock or Unlock options are not available on the root dataset or a child dataset of a non-root parent it inherits encryption settings from. The root dataset ZFS Encryption widget includes the Export All Keys and the Export Key options, and the Edit option to change encryption settings. Parent or child dataset ZFS Encryption widgets include the options to Lock and Unlock the dataset and to Edit the encryption settings.

Child dataset ZFS Encryption widgets include the Go to Encryption Root when you select Inherit as its Encryption Options setting. The non-root parent dataset controls the state of the child dataset.

Edit opens the Edit Encryption Options for dataset window for the selected dataset.

For more details on encryption windows and functions see Encryption Settings.

Add and Edit Dataset Screens

The Add Dataset and Edit Dataset screens include the same settings but you cannot change the dataset Name, Dataset Preset or Case Sensitivity (advanced option) settings after you click Save on the Add Dataset screen.

After adding a dataset, click Edit on the Dataset Details widget to open the Edit Dataset screen. To edit encryption options, click Edit on the ZFS Encryption widget. To edit dataset permissions, click Edit on the Permissions widget.

There are two screen options on the Add Dataset and Edit Dataset screens, Basic Options and Advanced Options.

The Add Dataset screen Basic Options and Advanced Options screens include the Name and Options section. The Advanced Options also includes the quota management tools for the current dataset (This Dataset) and any children of the current dataset (This Dataset and Child Datasets), Encryption Options, and Other Options.

The Edit Dataset screen shows the dataset Name field, but to edit dataset settings, click Advanced Options.

Name and Options Section

These Add Dataset screen settings show on both the Basic Options and Advanced Options screens. The common settings are Dataset Path, Name, and the Dataset Preset (previsouly know as the share type).

Add Dataset Name and Options
Figure 18: Add Dataset Name and Options
Name and Options Settings
SettingDescription
Parent pathRead-only field that displays the dataset path. The root dataset path includes the only the name of the root dataset. Child datasets include the root dataset/parent dataset in the path.
NameEnter a unique identifier for the dataset. TrueNAS does not allow dataset names to have trailing spaces. Dataset names can have upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters. You cannot change the dataset name after clicking Save. The Name field on the Edit Dataset screen shows the path.
Dataset PresetSelect the option from the dropdown list to define the type of data sharing the dataset uses to optimize the dataset for that sharing protocol. Options are:
  • Generic - Select for all other share types.
  • SMB - Select if using with an SMB share and to optimize it for SMB shares. Displays the Create SMB Share option pre-selected and SMB Name field populated with the value entered in Name.
  • Apps - Select if creating a dataset to work an application and to optimize the dataset for use by any application. If you plan to deploy container applications, the system automatically creates the ix-applications dataset but this is not used for application data storage.
  • Multiprotocol - Select if configuring a multi-protocol or mixed-mode NFS and SMB protocols for sharing data. This allows clients to use either protocol to access the same data. Displays the Create NFS Share and Create SMB Share options pre-selected and the SMB Name field populated with the value entered in Name. See Multiprotcol Shares for more information.
  • This setting is not editable after saving the dataset.

    Quota Management Settings

    The This Dataset and This Dataset and Child Datasets sections include the same setting options. This Dataset applies the quota settings to the just the dataset and This Dataset and Child Datasets applies to both the dataset and any children of the dataset. These settings also display on the Capacity Settings screen.

    Add Dataset Advanced Quota Options
    Figure 19: Add Dataset Advanced Quota Options
    Click Here for More Information

    Setting a quota defines the maximum allowed space for the dataset or the dataset and child datasets. You can also reserve a defined amount of pool space to prevent automatically generated data like system logs from consuming all of the dataset space. You can configure quotas for only the new dataset or include all child datasets.

    SettingDescription
    Quota for this dataset
    Quota for this dataset and all children
    Enter a value to define the maximum allowed space for the dataset. 0 disables quotas.
    Quota warning alert at, %Enter a percentage value to generate a warning level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
    Quota critical alert at, %Enter a percentage value to generate a critical level alert when consumed space reaches the defined level. By default, the dataset inherits this value from the parent dataset. Clear the Inherit checkbox to change the value.
    Reserved space for this dataset
    Reserved space for this dataset and all children
    Enter a value to reserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.

    Encryption Options Section

    The encryption setting options display on the Add Dataset screen Advanced Options and, if editing a dataset, on the Edit Encryption Options for datasetName window. To change encryption settings for an existing dataset, click Edit on the ZFS Encryption widget.

    Add Dataset Encryption Options Clear Inherit
    Figure 20: Add Dataset Encryption Options Clear Inherit
    Click Here for Move Information

    If you create an unencrypted dataset, the default setting is Inherit (Unencrypted). If you create an encrypted dataset, the default setting is Inherit (Encryption). The default Inherit options is pre-seletected.

    Clear the Encryption option (pre-selected)checkbox to show key type encryption options.

    Select Passphrase as the Encryption Type to show other settings.

    SettingDescription
    Inherit (non-encrypted)Leave selected to inherit encryption from the parent dataset (encrypted/non-encrypted). If created under an encrypted root dataset of an encrypted pool, leave selected to apply encryption to all child datasets created under it. Select to clear the checkmark and display the pre-selected Encryption option and additional encryption options. Clear both the Inherit and Encryption options to remove all encryption settings, however, you can create an encrypted dataset if the pool is/root dataset is unencrypted but you cannot create an unencrypted dataset if the pool/root dataset is encrypted!
    EncryptionLeave selected to show the other encryption settings to select the encryption type as pass key or password. Select to clear the checkmark and remove the encryption settings from the Add Dataset screen. If the root dataset is not encrypted, leaving Inherit (non-encrypted) selected is the same as clearing the Encryption checkbox.

    SettingDescription
    Encryption TypeSelect the option for the type of encryption to secure the dataset from the dropdown list. Select Key to use key-based encryption and display the Generate Key option. Select Passphrase to enter a user-defined passphrase to secure the dataset. This displays two additional Passphrase fields to enter and confirm the passphrase and the pbkdf2iters field.
    Generate keySelected by default to have the system randomly generate an encryption key for securing this dataset. Clearing the checkbox displays the Key field and requires you to enter an encryption key you define. Warning! The encryption key is the only means to decrypt the information stored in this dataset. Store encryption keys in a secure location! Creating a new key file invalidates any previously downloaded key file for this dataset. Delete any previous key file backups and back up the new key file.
    KeyEnter or paste a string to use as the encryption key for this dataset.
    AlgorithmDisplays for both key and passphrase encryption types. Select the mathematical instruction set that determines how plaintext converts into ciphertext from the dropdown list of options. See Advanced Encryption Standard (AES) for more details.
    Passphrase
    Confirm Passphrase
    Enter the alpha-numeric string or phrase you want to use to secure the dataset.
    pbkdf2itersEnter the number of password-based key deviation function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-force attacks. Entering a number larger than 100000 is required. See PBKDF2 for more details.

    See the list of Related Encryption Articles at the bottom of this article for more on encryption.

    Other Options Section

    The Other Options help tune the dataset for specific data sharing protocols. Included are compression level and sync type options, ACL type and mode, and other settings.

    Add Dataset Advanced Other Options
    Figure 22: Add Dataset Advanced Other Options
    Click Here for More Information
    SettingDescription
    CommentEnter optional text to describe or define the dataset usage or any other information to assoicate with the dataset.
    SyncSelect the sync setting option from the dropdown list. Options are:
  • Standard uses the sync settings requested by the client software.
  • Always waits for data writes to complete.
  • Disabled never waits for writes to complete.
  • Compression levelSelect the compression algorithm to use from the dropdown list. Options encode information in less space than the original data occupies. We recommend choosing a compression algorithm that balances disk performance with the amount of space saved. Options include:
  • LZ4 is generally recommended as it maximizes performance and dynamically identifies the best files to compress.
  • ZSTD is the Zstandard compression algorithm with several options for balancing speed and compression.
  • Gzip options range from 1 for least compression with best performance or 9 for maximum compression with greatest performance impact.
  • ZLE is a fast algorithm that only eliminates runs of zeroes.
  • LZJB is a legacy algorithm that is not recommended for use.
  • Enable AtimeSelect the access time for files option from the dropdown list. Access time can result in significant performance gains. Inherit uses the access time setting of the parent or the root dataset. On updates the access time for files when they are read. Off disables creating log traffic when reading files to maximize performance.
    ZFS DeduplicationSelect the option from the dropdown list to transparently reuse a single copy of duplicated data to save space. Options are:
  • Inherit - Select to use the parent or root dataset settings.
  • On - Select to use deduplication.
  • Off - Select to not use deduplication.
  • Verify - Select to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical.
  • Deduplication can improve storage capacity, but is RAM intensive. Compressing data is recommended before using deduplication.
    Deduplicating data is a one-way process. You cannot undo deduplicated data!
    Case SensitivitySelect the option from the dropdown list. Options are:
  • Sensitive assumes file names are case sensitive.
  • Insensitive assumes file names are not case sensitive.
  • You cannot change case sensitivity after the saving the dataset.
    ChecksumSelect the checksum option from the dropdown list. Options:
  • Inherit - Select to use the parent setting.
  • On - Select to use checksum without specifying the variant.
  • FLETCHER2 (deprecated) or FLETCHER4 - Select to use a position-dependent checksum that uses two checksums to determine single-bit errors in messages transmitted over network channels or ZFS streams.
  • SHA256 (default for dedupted datasets) or SHA512 - Select to use a sequence of numbers and letters to check the copy of a downloaded update file is identical to the original.
  • SKEIN Not supported for a file system on boot pools.
  • EDNOR not supported for file systems on boot pools and Edon-R requires verification when used with dedup so it automatically uses verify.
  • SettingDescription
    Read-onlySelect the option to allow or prevent dataset modification from the dropdown list. On prevents modifying the dataset. Off allows users accessing the dataset to modify its contents.
    ExecSelect the option for executing processes from within the dataset from the dropdown list. On allows executing processes from within this dataset. Off prevents executing processes from with the dataset. We recommend setting it to On.
    Snapshot directorySelect the option to controls visibility of the .zfs directory on the dataset from the dropdown list. Select either Visible or Invisible.
    SnapdevSelect the option that controls whether the volume snapshot devices under /dev/zvol/poolname are hidden or visible from the dropdown list. Options are Inherit (hidden), Visible and Hidden (default value).
    CopiesSelect the number of duplicate of ZFS user data stored on this dataset from the dropdown list. Select between 1, 2, or 3 redundant data copies. This can improve data protection and retention, but is not a substitute for storage pools with disk redundancy.
    Record SizeSelect the logical block size in the dataset from the dropdown list of options. Matching the fixed size of data, as in a database, can result in better performance.
    ACL TypeSelect the access control list type from the dropdown list of options. Options are:
  • Inherit - Select to preserve ACL type from the parent dataset.
  • Off - Select to use neither NFSv4 or POSIX protocols.
  • NFSv4 -Select to cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with TrueNAS Core, FreeBSD, or other non-Linux ZFS implementations.
  • POSIX - Select when an organization data backup target does not support native NFSv4 ACLs. Since the Linux platform used POSIX for a long time, many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSv4 ACLs.
  • All datasets within an SMB share path must have identical ACL types. For a more in-depth explanation of ACLs and configurations in TrueNAS SCALE, see our ACL Primer.
    ACL ModeSelect the option that determines how chmod behaves when adjusting file ACLs from the dropdown list. See the zfs(8) aclmode property. Options are:
  • Passthrough that only updates ACL entries that are related to the file or directory mode.
  • Restricted that does not allow chmod to make changes to files or directories with a non-trivial ACL. An ACL is trivial if it can be fully expressed as a file mode without losing any access rules. Set the ACL Mode to restricted to optimize a dataset for SMB sharing, but it can require further optimizations. For example, configuring an rsync task with this dataset could require adding --no-perms in the task Auxiliary Parameters field.
  • Case SensitivitySelect the option that sets whether file names are case sensitive. Options are:
  • Sensitive = Select to assume file names are case sensitive.
  • Insensitive - Select to assume file names are not case sensitive. Note: The Mixed option no longer exists.
  • Metadata (Special) Small Block SizeEnter a threshold block size for including small file blocks into the special allocation class (fusion pools). Blocks smaller than or equal to this value are assigned to the special allocation class while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. The default size 0 means no small file blocks are allocated in the special class. Before setting this property, you must add a special class VDEV to the pool.

    Data Compression Algorithms

    Select the compression algorithm that best suits your needs from the Compression dropdown list of options.

    LZ4 maximizes performance and dynamically identifies the best files to compress. LZ4 provides lightning-fast compression/decompression speeds and comes coupled with a high-speed decoder. This makes it one of the best Linux compression tools for enterprise customers.

    ZSTD offers highly configurable compression speeds, with a very fast decoder.

    Gzip is a standard UNIX compression tool widely used for Linux. It is compatible with every GNU software which makes it a good tool for remote engineers and seasoned Linux users. It offers the maximum compression with the greatest performance impact. The higher the compression level implemented the greater the impact on CPU usage levels. Use with caution especially at higher levels.

    ZLE or Zero Length Encoding, leaves normal data alone but only compresses continuous runs of zeros.

    LZJB compresses crash dumps and data in ZFS. LZJB is optimized for performance while providing decent compression. LZ4 compresses roughly 50% faster than LZJB when operating on compressible data, and is greater than three times faster for uncompressible data. LZJB was the original algorithm used by ZFS but it is now deprecated.

    Contents

    • Zvol: Provides information on the settings and functions found on the Zvol screens and widgets.

      • Capacity Settings: Provides information on the quota settings and functions found on the Capacity Settings screen.

        • Snapshots: Provides information on the settings and functions found on the Snapshots screen.

          • User and Group Quotas : Provides information on the settings and functions found on the User and Group Quota screens.

            • Encryption Settings: Provides information on the settings and functions found on the SCALE storage encryption screens.

              • Permissions: Describes the ACL permissions screens, settings for POSIX and NFSv4 ACLs, and the conditions that result in additional setting options.