ZFS Datasets

How to create a ZFS dataset.

  7 minute read

A ZFS pool is required for creating a ZFS dataset. See Creating a new ZFS Pool.

A ZFS dataset is used in TrueNAS as a file system that is created within a data storage pool. Datasets can contain files, directories (child datasets), and have individual permissions or flags. Datasets can also be encrypted, either using the encryption created with the pool or with a separate encryption configuration. It is recommended to organize your pool with datasets before configuring data sharing, as this allows for more fine-tuning of access permissions and using different sharing protocols.

Creating a Dataset

To create a dataset in the desired pool, go to Storage > Pools.

Find the pool and top-level (root) dataset for that pool, click   and Add Dataset.

To quickly create a dataset with the default options, enter a name for the dataset and click SUBMIT.

Dataset Options

The Name and Options group are required to create the dataset. Datasets typically Inherit most of these settings from the root or parent dataset, only a dataset Name is required to be entered before clicking SUBMIT.

NamestringUnique identifier for the dataset. Cannot be changed after the dataset is created.
CommentsstringNotes about the dataset.
Syncdrop downStandard uses the sync settings that have been requested by the client software. Always waits for data writes to complete, and Disabled never waits for writes to complete.
Compression leveldrop downEncode information in less space than the original data occupies. It is recommended to choose a compression algorithm that balances disk performance with the amount of saved space:
lz4 is generally recommended as it maximizes performance and dynamically identifies the best files to compress.
zstd is the Zstandard compression algorithm that has several options for balancing speed and compression.
Similarly, gzip options range from 1 for least compression, best performance, through 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 Atimedrop downon updates the access time for files when they are read. off disables creating log traffic when reading files to maximize performance.

By default, datasets Inherit the Encryption Options from the root or parent dataset. To configure the dataset with different encryption settings, unset Inherit and choose the new Encryption Options. For detailed descriptions of the encryption options, see the Encryption article.

The Other Options generally have settings to help tune the dataset for particular data sharing protocols:

ZFS Deduplicationdrop downTransparently reuse a single copy of duplicated data to save space. Deduplication can improve storage capacity, but is RAM intensive. Compressing data is generally recommended before using deduplication. Deduplicating data is a one-way process. Deduplicated data cannot be undeduplicated!
Case Sensitivitydrop downSensitive assumes filenames are case sensitive. Insensitive assumes filenames are not case sensitive. Mixed understands both types of filenames. Cannot be changed after the dataset is created.
Share Typedrop downDefine the type of data sharing the dataset will use to optimize the dataset for that sharing protocol. Cannot be changed after the dataset is created.

Advanced Options

Clicking ADVANCED OPTIONS adds dataset quota management tools and a few additional fields to the Other Options:

Setting a quota defines the maximum allowed space for the dataset. You can also reserve a defined amount of pool space for the dataset to help prevent situations where automatically generated data like system logs consume all space on the dataset. Quotas can be configured for either the new dataset or to include all child datasets in the quota.
Quota for this datsetintegerDefine the maximum allowed space for the dataset. 0 disables quotas.
Quota warning alert at, %integerGenerate a warning level alert when consumed space reaches the defined percentage. By default, the dataset will Inherit this value from the parent dataset. Unset Inherit to change the value.
Quota critical alert at, %integerGenerate a critical level alert when consumed space reaches the defined percentage. By default, the dataset will Inherit this value from the parent dataset. Unset Inherit to change the value.
Reserved space for this datasetintegerReserve additional space for datasets that contain logs which could eventually take up all the available free space. 0 is unlimited.

Additional advanced settings are added to the Other Options. By default, many of these options Inherit their values from the parent dataset.

Read-onlydrop downOn prevents the dataset being modified. Off allows users accessing the dataset to modify its contents.
Execdrop downOn allows processes to be executed from within this dataset. Off prevents processes from executing in the dataset. It is recommended to set to On.
Snapshot directorydrop downControls visibility of the .zfs directory on the dataset. Choose between Visible or Invisible.
Copiesdrop downDuplicates ZFS user data stored on this dataset. Choose 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 Sizedrop downLogical block size in the dataset. Matching the fixed size of data, as in a database, could result in better performance.
ACL Modedrop downDetermine how chmod behaves when adjusting file ACLs. See the zfs aclmode property.
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. Setting the ACL Mode to Restricted is typically used to optimize a dataset for SMB sharing, but can 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 SizeintegerThreshold block size for including small file blocks into the special allocation class (fusion pools). Blocks smaller than or equal to this value will be assigned to the special allocation class while greater blocks will be 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 will be allocated in the special class. Before setting this property, a special class vdev must be added to the pool.

Managing Datasets

After a dataset is created, additional management options are available by going to Storage > Pools and clicking   for a dataset:

  • Add Dataset: create a new ZFS dataset that is a “child” of this dataset. Datasets can be continuously layered in this manner.
  • Add Zvol: create a new ZFS block device as a “child” of this dataset.
  • Edit Options: opens the dataset options to make adjustments to the dataset configuration. The dataset Name, Case Sensitivity, and Share Type cannot be changed.
  • Edit Permissions: opens the editor to set access permissions for this dataset. For more information on Managing ACLs, read the Dataset Management documentation.
  • User Quotas: shows options to set data or object quotas for user accounts cached on the system or user accounts that are connected to this system.
  • Group Quotas: shows options to set data or object quotas for user groups cached on the system or user groups that are connected to this system.
  • Delete Dataset: removes the dataset, all stored data, and any snapshots of the dataset from TrueNAS. Warning: this can result in unrecoverable data loss, be sure that any critical data is moved off the dataset or is otherwise obsolete.
  • Create Snapshot: takes a single manual ZFS snapshot of the dataset to provide additional data protection and mobility. Created snapshots are listed in Storage > Snapshots.

Last modified December 29, 2020: DOCS-1420 Write new "Quotas" article (0a775e97)