Introducing ZFS Properties

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.

ZFS Read-Only Native Properties
Settable ZFS Native Properties
ZFS User Properties

Properties are divided into two types, native properties and user defined properties. Native properties either export internal statistics or control ZFS file system behavior. In addition, native properties are either settable or read-only. User properties have no effect on ZFS file system behavior, but you can use them to annotate datasets in a way that is meaningful in your environment. For more information on user properties, see ZFS User 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 descendents.

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 native ZFS file system properties. Read-only native properties are identified as such. All other native properties listed in this table are settable. For information about user properties, see ZFS User Properties.

Table 5-1 ZFS Native 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.
`canmount`	Boolean	on	Controls whether the given file system can be mounted with the `zfs` `mount` command. This property can be set on any file system and the property itself is not inheritable. However, when this property is set, a mountpoint can be inherited to descendent file systems, but the file system itself is never mounted. For more information, see The `canmount` Property.
`casesensitivity`	String	`sensitive`	This property indicates whether the file name matching algorithm used by the file system should be `casesensitive`, `caseinsensitive`, or allow a combination of both styles of matching (`mixed`). The default value for this property is `sensitive`. Traditionally, UNIX and POSIX file systems have case-sensitive file names. The `mixed` value for this property indicates the file system can support requests for both case-sensitive and case-insensitive matching behavior. Currently, case-insensitive matching behavior on a file system that supports mixed behavior is limited to the Solaris CIFS server product. For more information about using the `mixed` value, see The `casesensitivity` Property. Regardless of the `casesensitivity` property setting, the file system preserves the case of the name specified to create a file. This property cannot be changed after the file system is created.
`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, you can select `lzjb`, `gzip`, or `gzip-`N. Enabling compression on a file system with existing data only compresses new data. Existing data remains uncompressed. 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.
`copies`	Number	1	Sets the number of copies of user data per file system. Available values are 1, 2 or 3. These copies are in addition to any pool-level redundancy. Space used by multiple copies of user data is charged to the corresponding file and dataset and counts against quotas and reservations. In addition, the `used` property is updated when multiple copies are enabled. Consider setting this property when the file system is created because changing this property on an existing file system only affects newly written data.
`creation`	Number	N/A	Read-only property that identifies the date and time that this dataset was created.
`devices`	Boolean	`on`	Controls the ability to open device files in the file system.
`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.
`nbmand`	Boolean	off	Controls whether the file system should be mounted with `nbmand` (Non-blocking mandatory) locks. This property is for CIFS clients only. Changes to this property only take effect when the file system is unmounted and remounted.
`normalization`	String	None	This property indicates whether a file system should perform a unicode normalization of file names whenever two file names are compared, and which normalization algorithm should be used. File names are always stored unmodified, names are normalized as part of any comparison process. If this property is set to a legal value other than `none`, and the `utf8only` property was left unspecified, the `utf8only` property is automatically set to `on`. The default value of the `normalization` property is `none`. This property cannot be changed after the file system is created.
`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`.
`refquota`	Number (or none)	none	Sets the amount of space that a dataset can consume. This property enforces a hard limit on the amount of space used. This hard limit does not include space used by descendents, such as snapshots and clones.
`refreservation`	Number (or none)	`none`	Sets the minimum amount of space that is guaranteed to a dataset, not including descendents, such as snapshots and clones. When the amount of space that is used is below this value, the dataset is treated as if it were taking up the amount of space specified by `refreservation`. The `refreservation` reservation is accounted for in the parent datasets' space used, and counts against the parent datasets' quotas and reservations. If `refreservation` is set, a snapshot is only allowed if enough free pool space is available outside of this reservation to accommodate the current number of referenced bytes in the dataset. This property can also be referred to by its shortened column name, `refreserv`.
`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.
`setuid`	Boolean	`on`	Controls whether the `setuid` bit is honored in the file system.
`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 and Unsharing ZFS File Systems.
`sharesmb`	Boolean	off	Controls whether the file system is shared by using the Solaris CIFS service, and what options are to be used. A file system with the `sharesmb` property set to `off` is managed through traditional tools, such as the `sharemgr` command. Otherwise, the file system is automatically shared and unshared by using the `zfs share` and `zfs unshare` commands. If the property is set to `on`, the `sharemgr` command is invoked with no options. Otherwise, the `sharemgr` command is invoked with options that are equivalent to the contents of this property.
`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 Overview of 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 descendents. For a detailed description, see The `used` Property.
`utf8only`	Boolean	Off	This property indicates whether a file system should reject file names that include characters that are not present in the UTF-8 character code set. If this property is explicitly set to `off`, the `normalization` property must either not be explicitly set or be set to `none`. The default value for the `utf8only` property is `off`. This property cannot be changed after the file system is created.
`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`.
`vscan`	Boolean	Off	Controls whether regular files should be scanned for viruses when a file is opened and closed. In addition to enabling this property, a virus scanning service must also be enabled for virus scanning to occur. The default value is `off`.
`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.
`xattr`	Boolean	`on`	Indicates whether extended attributes are enabled or disabled for this file system. The default value is `on`.

ZFS Read-Only Native Properties

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

The read-only native 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 descendents. 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 descendent 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 Native Properties

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

Some settable native properties are specific to a particular type of dataset. In such cases, the particular dataset type is mentioned in the description in Table 5-1. 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
canmount
casesensitivity
checksum
compression
copies
devices
exec
mountpoint
nbmand
normalization
quota
readonly
recordsize
For a detailed description, see The recordsize Property.
refquota
refreservation
reservation
sharenfs
sharesmb
setuid
snapdir
vscan
utf8only
volsize
For a detailed description, see The volsize Property.
volblocksize
zoned

The `canmount` Property

If this property is set to no, the file system cannot be mounted by using the zfs mount or zfs mount -a commands. This property is similar to setting the mountpoint property to none, except that the dataset still has a normal mountpoint property that can be inherited. For example, you can set this property to no, establish inheritable properties for descendent file systems, but the file system itself is never mounted nor it is accessible to users. In this case, the parent file system with this property set to no is serving as a container so that you can set attributes on the container, but the container itself is never accessible.

In the following example, userpool is created and the canmount property is set to off. Mount points for descendent user file systems are set to one common mount point, /export/home. Properties that are set on the parent file system are inherited by descendent file systems, but the parent file system itself is never mounted.

# zpool create userpool mirror c0t5d0 c1t6d0
# zfs set canmount=off userpool
# zfs set mountpoint=/export/home userpool
# zfs set compression=on userpool
# zfs create userpool/user1
# zfs create userpool/user2
# zfs list -r userpool
NAME             USED  AVAIL  REFER  MOUNTPOINT
userpool         140K  8.24G  24.5K  /export/home
userpool/user1  24.5K  8.24G  24.5K  /export/home/user1
userpool/user2  24.5K  8.24G  24.5K  /export/home/user2

The `casesensitivity` Property

This property indicates whether the file name matching algorithm used by the file system should be casesensitive, caseinsensitive, or allow a combination of both styles of matching (mixed).

When a case-insensitive matching request is made of a mixed sensitivity file system, the behavior is generally the same as would be expected of a purely case-insensitive file system. The difference is that a mixed sensitivity file system might contain directories with multiple names that are unique from a case-sensitive perspective, but not unique from the case-insensitive perspective.

For example, a directory might contain files foo, Foo, and FOO. If a request is made to case-insensitively match any of the possible forms of foo, (for example foo, FOO, FoO, fOo, and so on) one of the three existing files is chosen as the match by the matching algorithm. Exactly which file the algorithm chooses as a match is not guaranteed, but what is guaranteed is that the same file is chosen as a match for any of the forms of foo. The file chosen as a case-insensitive match for foo, FOO, foO, Foo, and so on, is always the same, so long as the directory remains unchanged.

The utf8only, normalization, and casesensitivity properties are also new permissions that can be assigned to non-privileged users by using ZFS delegated administration. For more information, see Delegating ZFS Permissions.

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 `sharesmb` Property

This property enabled sharing of ZFS file systems with the Solaris CIFS service, and identifies options to be used.

Because SMB shares requires a resource name, a unique resource name is constructed from the dataset name. The constructed name is a copy of the dataset name except that the characters in the dataset name, which would be illegal in the resource name, are replaced with underscore (_) characters. A pseudo property name is also supported that allows you to replace the dataset name with a specific name. The specific name is then used to replace the prefix dataset in the case of inheritance.

For example, if the dataset, data/home/john, is set to name=john, then data/home/john has a resource name of john. If a child dataset of data/home/john/backups exists, it has a resource name of john_backups. When the sharesmb property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously set to off, or if they were shared before the property was changed. If the new property is set to off, the file systems are unshared.

For examples of using the sharesmb property, see Sharing ZFS Files in a Solaris CIFS Environment.

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

ZFS User Properties

In addition to the standard native properties, ZFS supports arbitrary user properties. User properties have no effect on ZFS behavior, but you can use them to annotate datasets with information that is meaningful in your environment.

User property names must conform to the following characteristics:

Contain a colon (':') character to distinguish them from native properties.
Contain lowercase letters, numbers, and the following punctuation characters: ':', + ,'.', '_'.
Maximum user property name is 256 characters.

The expected convention is that the property name is divided into the following two components but this namespace is not enforced by ZFS:

module:property

When making programmatic use of user properties, use a reversed DNS domain name for the module component of property names to reduce the chance that two independently-developed packages will use the same property name for different purposes. Property names that begin with "com.sun." are reserved for use by Sun Microsystems.

The values of user properties have the following characteristics:

Arbitrary strings that are always inherited and are never validated.
Maximum user property value is 1024 characters.

For example:

# zfs set dept:users=finance userpool/user1
# zfs set dept:users=general userpool/user2
# zfs set dept:users=itops userpool/user3

All of the commands that operate on properties, such as zfs list, zfs get, zfs set, and so on, can be used to manipulate both native properties and user properties.

For example:

zfs get -r dept:users userpool
NAME            PROPERTY    VALUE           SOURCE
userpool        dept:users  all             local
userpool/user1  dept:users  finance         local
userpool/user2  dept:users  general         local
userpool/user3  dept:users  itops           local

To clear a user property, use the zfs inherit command. For example:

# zfs inherit -r dept:users userpool

If the property is not defined in any parent dataset, it is removed entirely.