ZFS Properties

ZFS Properties
Prev	Chapter 5. Managing ZFS File Systems	Next

Properties are the main mechanism that you use to control the behavior of file systems, volumes, snapshots, and clones. Unless stated otherwise, the properties defined in the section apply to all the dataset types.

Properties are either read-only statistics or settable properties. Most settable properties are also inheritable. An inheritable property is a property that, when set on a parent, is propagated down to all of its descendants.

All inheritable properties have an associated source. The source indicates how a property was obtained. The source of a property can have the following values:

local: A local source indicates that the property was explicitly set on the dataset by using the zfs set command as described in Setting ZFS Properties.
inherited from dataset-name: A value of inherited from dataset-name means that the property was inherited from the named ancestor.
default: A value of default means that the property setting was not inherited or set locally. This source is a result of no ancestor having the property as source local.

The following table identifies both read-only and settable ZFS file system properties. Read-only properties are identified as such. All other properties are settable.

Table 5.1. ZFS Property Descriptions

Property Name	Type	Default Value	Description
`aclinherit`	String	`secure`	Controls how ACL entries are inherited when files and directories are created. The values are `discard`, `noallow`, `secure`, and `passthrough`. For a description of these values, see ACL Property Modes.
`aclmode`	String	`groupmask`	Controls how an ACL entry is modified during a `chmod` operation. The values are `discard`, `groupmask`, and `passthrough`. For a description of these values, see ACL Property Modes.
atime	Boolean	`on`	Controls whether the access time for files is updated when they are read. Turning this property off avoids producing write traffic when reading files and can result in significant performance gains, though it might confuse mailers and other similar utilities.
available	Number	N/A	Read-only property that identifies the amount of space available to the dataset and all its children, assuming no other activity in the pool. Because space is shared within a pool, available space can be limited by various factors including physical pool size, quotas, reservations, or other datasets within the pool. This property can also be referenced by its shortened column name, `avail`. For more information about space accounting, see ZFS Space Accounting.
checksum	String	`on`	Controls the checksum used to verify data integrity. The default value is `on`, which automatically selects an appropriate algorithm, currently `fletcher2`. The values are `on, off, fletcher2`, `fletcher4`, and `sha256`. A value of `off` disables integrity checking on user data. A value of `off` is not recommended.
compression	String	`off`	Controls the compression algorithm used for this dataset. Currently, only one algorithm, `lzjb`, exists. This property can also be referred to by its shortened column name, `compress`.
compressratio	Number	N/A	Read-only property that identifies the compression ratio achieved for this dataset, expressed as a multiplier. Compression can be turned on by running `zfs set compression=on` `dataset`. Calculated from the logical size of all files and the amount of referenced physical data. Includes explicit savings through the use of the compression property.
creation	Number	N/A	Read-only property that identifies the date and time that this dataset was created.
devices	Boolean	`on`	Controls whether device nodes found within this file system can be opened.
exec	Boolean	`on`	Controls whether programs within this file system are allowed to be executed. Also, when set to `off`, mmap(2) calls with `PROT_EXEC` are disallowed.
mounted	boolean	N/A	Read-only property that indicates whether this file system, clone, or snapshot is currently mounted. This property does not apply to volumes. Value can be either yes or no.
mountpoint	String	N/A	Controls the mount point used for this file system. When the mountpoint property is changed for a file system, the file system and any children that inherit the mount point are unmounted. If the new value is `legacy`, then they remain unmounted. Otherwise, they are automatically remounted in the new location if the property was previously `legacy` or `none`, or if they were mounted before the property was changed. In addition, any shared file systems are unshared and shared in the new location. For more information about using this property, see Managing ZFS Mount Points.
origin	String	N/A	Read-only property for cloned file systems or volumes that identifies the snapshot from which the clone was created. The origin cannot be destroyed (even with the `r` or `f` options) as long as a clone exists. Non-cloned file systems have an origin of none.
quota	Number (or `none`)	`none`	Limits the amount of space a dataset and its descendents can consume. This property enforces a hard limit on the amount of space used, including all space consumed by descendents, including file systems and snapshots. Setting a quota on a descendent of a dataset that already has a quota does not override the ancestor's quota, but rather imposes an additional limit. Quotas cannot be set on volumes, as the volsize property acts as an implicit quota. For information about setting quotas, see Setting Quotas on ZFS File Systems.
readonly	Boolean	`off`	Controls whether this dataset can be modified. When set to `on`, no modifications can be made to the dataset. This property can also be referred to by its shortened column name, `rdonly`.
recordsize	Number	`128K`	Specifies a suggested block size for files in the file system. This property can also be referred to by its shortened column name, recsize. For a detailed description, see The recordsize Property.
referenced	Number	N/A	Read-only property that identifies the amount of data accessible by this dataset, which might or might not be shared with other datasets in the pool. When a snapshot or clone is created, it initially references the same amount of space as the file system or snapshot it was created from, because its contents are identical. This property can also be referred to by its shortened column name, refer.
reservation	Number (or `none)`	`none`	The minimum amount of space guaranteed to a dataset and its descendents. When the amount of space used is below this value, the dataset is treated as if it were using the amount of space specified by its reservation. Reservations are accounted for in the parent datasets' space used, and count against the parent datasets' quotas and reservations. This property can also be referred to by its shortened column name, reserv. For more information, see Setting Reservations on ZFS File Systems.
sharenfs	String	`off`	Controls whether the file system is available over NFS, and what options are used. If set to `on`, the zfs share command is invoked with no options. Otherwise, the zfs share command is invoked with options equivalent to the contents of this property. If set to `off`, the file system is managed by using the legacy share and unshare commands and the `dfstab` file. For more information on sharing ZFS file systems, see Sharing ZFS File Systems.
setuid	Boolean	`on`	Controls whether the `setuid` bit is honored in the file system.
`snapdir`	String	`hidden`	Controls whether the `.zfs` directory is hidden or visible in the root of the file system. For more information on using snapshots, see ZFS Snapshots.
`type`	String	N/A	Read-only property that identifies the dataset type as `filesystem` (file system or clone), `volume`, or `snapshot`.
used	Number	N/A	Read-only property that identifies the amount of space consumed by the dataset and all its descendants. For a detailed description, see The used Property.
volsize	Number	N/A	For volumes, specifies the logical size of the volume. For a detailed description, see The volsize Property.
`volblocksize`	Number	8 Kbytes	For volumes, specifies the block size of the volume. The block size cannot be changed once the volume has been written, so set the block size at volume creation time. The default block size for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid. This property can also be referred to by its shortened column name, volblock.
zoned	Boolean	N/A	Indicates whether this dataset has been added to a non-global zone. If this property is set, then the mount point is not honored in the global zone, and ZFS cannot mount such a file system when requested. When a zone is first installed, this property is set for any added file systems. For more information about using ZFS with zones installed, see Using ZFS on a Solaris System With Zones Installed.

Read-Only ZFS Properties

Read-only properties are properties that can be retrieved but cannot be set. Read-only properties are not inherited. Some properties are specific to a particular type of dataset. In such cases, the particular dataset type is mentioned in the description.

The read-only properties are listed here and are described in Table 5–1.

available
creation
mounted
origin
compressratio
referenced
type
used

For detailed information, see The used Property.

For more information on space accounting, including the used, referenced, and available properties, see ZFS Space Accounting.

The used Property

The amount of space consumed by this dataset and all its descendants. This value is checked against the dataset's quota and reservation. The space used does not include the dataset's reservation, but does consider the reservation of any descendant datasets. The amount of space that a dataset consumes from its parent, as well as the amount of space that is freed if the dataset is recursively destroyed, is the greater of its space used and its reservation.

When snapshots are created, their space is initially shared between the snapshot and the file system, and possibly with previous snapshots. As the file system changes, space that was previously shared becomes unique to the snapshot, and counted in the snapshot's space used. Additionally, deleting snapshots can increase the amount of space unique to (and used by) other snapshots. For more information about snapshots and space issues, see Out of Space Behavior.

The amount of space used, available, or referenced does not take into account pending changes. Pending changes are generally accounted for within a few seconds. Committing a change to a disk using fsync(3c) or O_SYNC does not necessarily guarantee that the space usage information will be updated immediately.

Settable ZFS Properties

Settable properties are properties whose values can be both retrieved and set. Settable properties are set by using the zfs set command, as described in Setting ZFS Properties. With the exceptions of quotas and reservations, settable properties are inherited. For more information about quotas and reservations, see ZFS Quotas and Reservations.

Some settable properties are specific to a particular type of dataset. In such cases, the particular dataset type is mentioned in the description. If not specifically mentioned, a property applies to all dataset types: file systems, volumes, clones, and snapshots.

The settable properties are listed here and are described in Table 5–1.

aclinherit

For a detailed description, see ACL Property Modes.
aclmode

For a detailed description, see ACL Property Modes.
atime
checksum
compression
devices
exec
mountpoint
quota
readonly
recordsize

For a detailed description, see The recordsize Property.
reservation
sharenfs
setuid
snapdir
volsize

For a detailed description, see The volsize Property.
volblocksize
zoned

The recordsize Property

Specifies a suggested block size for files in the file system.

This property is designed solely for use with database workloads that access files in fixed-size records. ZFS automatically adjust block sizes according to internal algorithms optimized for typical access patterns. For databases that create very large files but access the files in small random chunks, these algorithms may be suboptimal. Specifying a recordsize greater than or equal to the record size of the database can result in significant performance gains. Use of this property for general purpose file systems is strongly discouraged, and may adversely affect performance. The size specified must be a power of two greater than or equal to 512 and less than or equal to 128 Kbytes. Changing the file system's recordsize only affects files created afterward. Existing files are unaffected.

This property can also be referred to by its shortened column name, recsize.

The volsize Property

The logical size of the volume. By default, creating a volume establishes a reservation for the same amount. Any changes to volsize are reflected in an equivalent change to the reservation. These checks are used to prevent unexpected behavior for users. A volume that contains less space than it claims is available can result in undefined behavior or data corruption, depending on how the volume is used. These effects can also occur when the volume size is changed while it is in use, particularly when you shrink the size. Extreme care should be used when adjusting the volume size.

Though not recommended, you can create a sparse volume by specifying the s flag to zfs create -V, or by changing the reservation once the volume has been created. A sparse volume is defined as a volume where the reservation is not equal to the volume size. For a sparse volume, changes to volsize are not reflected in the reservation.

For more information about using volumes, see Emulated Volumes.