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.

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, and show the encryption status and the permissions the dataset has in place. The screen focuses 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 child or non-root parent dataset, and the child datasets of each nested under them.

Click on any parent dataset to expand the tree table and show nested child datasets. Select a dataset to 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 includes 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 > 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 a parent to other datasets, the window includes the services a child 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 enter the path for the dataset. Select the Confirm option 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 unlock the dataset.

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 shows the number of 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 the number of scheduled push tasks. These tasks protect or back up data, whereas 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), and lists access control user or group entries and the owner and group for the dataset.

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

Root datasets have POSIX permissions and the entries are not editable. The permission screen and widget options vary based on the ACL type.

Parent and child dataset permissions (NFSv4 or POSIX) are editable.

NFSv4 ACL type (the default ACL type) shows the user and group entries on the Permissions widget as buttons. Click to show a selectable checklist of Permissions Advanced and Flags Advanced options for that entry on the Permissions widget.

A dataset with a POSIX ACL type is only editable using the Edit button.

Edit opens the Edit ACL for ACL 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 also the system dataset, the widget includes a link to the System > Advanced Settings screen where you can manage the system dataset.

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

The Roles widget shows information about the service using the dataset and provides a link to manage that service. The information corresponds to the roles icon 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 an 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. 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, the type, and the 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 that 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 the Encryption Options setting is set to Inherit. 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 allow admin users with the right permission level to create and or modify datasets. Both screens include the same settings but you cannot change the dataset name, Dataset Preset selection, or on the Advanced Options screen, change the Case Sensitivity 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.

Add Dataset and Edit Dataset screens include the Basic Options and Advanced Options. TheBasic Options and Advanced Options screens include the Name and Options section.

Advanced Options screen settings include:

Name and Options Section

Basic Options and Advanced Options screens both show the Name and Options settings. The common settings are Parent Path, Name, and the Dataset Preset (previously known 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. Populated with the parent dataset path, adds the name given to the dataset after entering it in Name. For example, tank/shares/smbshare1.
NameEnter a unique identifier for the dataset. Names allow upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters, but TrueNAS does not allow trailing spaces after the dataset name. 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. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are:
  • Generic - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.
  • SMB - Select to optimize the dataset for SMB shares. Displays the Create SMB Share option pre-selected and SMB Name field populated with the value entered in Name. Sets the ACL to NFSv4.
  • Apps - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the ix-apps dataset for Docker storage for but separate datasets used for application data storage.
  • Multiprotocol - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. 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. Sets the ACL to NFSv4.
  • Setting cannot be edited after saving the dataset.

    Quota Management Settings

    Shows only on the Advanced Options screen. The This Dataset and This Dataset and Child Datasets sections include the same setting options. This Dataset applies the quota settings to the for the dataset you are creating or editing. This Dataset and Child Datasets applies to 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

    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.

    Quota Settings

    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

    Encryption setting options display on the Advanced Options of the Add Dataset screen but not on the Edit Dataset screen. To edit encryption settings, click Edit on the ZFS Encryption widget. This opens the Edit Encryption Options for datasetName window where you can change encryption settings for an existing dataset.

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

    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. 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.

    Add Dataset Encryption Passphrase
    Figure 21: Add Dataset Encryption Passphrase
    Encryption Settings
    SettingDescription
    Inherit (non-encrypted)Leave selected to inherit encryption from the parent dataset (encrypted/non-encrypted). Select to clear the checkmark and display the Encryption option.
    EncryptionLeave selected to show the other encryption settings and to set the encryption type as pass key or password. Select to clear the checkmark and hide the encryption settings on the Add Dataset screen.

    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.

    Other Options Section

    The Other Options tune the dataset for specific data-sharing protocols by setting 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
    Other Options Settings
    SettingDescription
    CommentEnter optional text to describe or define the dataset usage or any other information to associate 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 saving the dataset. Note: The Mixed option no longer exists.
    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 is 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 ZFS user data duplicates 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, see our ACL Primer. This advanced setting changes ACL type and mode settings configured by the Dataset Preset option. Do not make changes here if you do not understand ACLs.
    ACL ModeSelect the option that determines how chmod behaves when adjusting file ACLs. See the zfs(8) aclmode property for more information. Options are:
  • Passthrough - Only updates ACL entries that are related to the file or directory mode.
  • Restricted - 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 ACL Mode to restricted to optimize a dataset for SMB sharing, but it can also require further optimizations. For example, configuring an rsync task with this dataset could require adding --no-perms in the task Auxiliary Parameters field.
  • Metadata (Special) Small Block SizeEnter a threshold block size for small file blocks you include in 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 metadata 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

    • Zvols: 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 TrueNAS storage encryption screens.

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