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 this 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 about user properties, see ZFS User Properties.
Most settable properties are also inheritable. An inheritable property is a property that, when set on a parent dataset, is propagated down to all of its descendents.
All inheritable properties have an associated source that indicates how a property was obtained. The source of a property can have the following values:
- 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
- Indicates that the property was inherited from the named ancestor.
- Indicates that the property value was not inherited or set locally. This source is a result of no ancestor having the property set 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 6–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 Properties.|
|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 Properties.|
|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 similar utilities.|
|available||Number||N/A||Read-only property that identifies the amount of disk space available to a dataset and all its children, assuming no other activity in the pool. Because disk space is shared within a pool, available space can be limited by various factors including physical pool size, quotas, reservations, and other datasets within the pool.
The property abbreviation is avail.
For more information about disk space accounting, see ZFS Disk Space Accounting.
|canmount||Boolean||on||Controls whether a 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 to off, a mount point can be inherited to descendent file systems, but the file system itself is never mounted.
When the noauto option is set, a dataset can only be mounted and unmounted explicitly. The dataset is not mounted automatically when the dataset is created or imported, nor is it mounted by the zfs mount-a command or unmounted by the zfs unmount-a command.
For more information, see canmount Property.
|checksum||String||on||Controls the checksum used to verify data integrity. The default value is on, which automatically selects an appropriate algorithm, currently fletcher4. 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||Enables or disables compression for a dataset. The values are on, off, lzjb, gzip, and gzip-N. Currently, setting this property to lzjb, gzip, or gzip-N has the same effect as setting this property to on. Enabling compression on a file system with existing data only compresses new data. Existing data remains uncompressed.
The property abbreviation is compress.
|compressratio||Number||N/A||Read-only property that identifies the compression ratio achieved for a dataset, expressed as a multiplier. Compression can be enabled by the zfs set compression=on dataset command.
The value is calculated from the logical size of all files and the amount of referenced physical data. It 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. Disk 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||String||N/A||Read-only property that identifies the date and time that a dataset was created.|
|devices||Boolean||on||Controls whether device files in a file system can be opened.|
|exec||Boolean||on||Controls whether programs in a 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 a file system, clone, or snapshot is currently mounted. This property does not apply to volumes. The 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 descendents 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.
|primarycache||String||all||Controls what is cached in the primary cache (ARC). Possible values are all, none, and metadata. If set to all, both user data and metadata are cached. If set to none, neither user data nor metadata is cached. If set to metadata, only metadata is cached.|
|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 option) as long as a clone exists.
Non-cloned file systems have an origin of none.
|quota||Number (or none)||none||Limits the amount of disk space a dataset and its descendents can consume. This property enforces a hard limit on the amount of disk space used, including all space consumed by descendents, such as 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 a dataset can be modified. When set to on, no modifications can be made.
The property abbreviation is rdonly.
|recordsize||Number||128K||Specifies a suggested block size for files in a file system.
The property abbreviation is recsize. For a detailed description, see recordsize Property.
|referenced||Number||N/A||Read-only property that identifies the amount of data accessible by a 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 disk space as the file system or snapshot it was created from, because its contents are identical.
The property abbreviation is refer.
|refquota||Number (or none)||none||Sets the amount of disk space that a dataset can consume. This property enforces a hard limit on the amount of space used. This hard limit does not include disk space used by descendents, such as snapshots and clones.|
|refreservation||Number (or none)||none||Sets the minimum amount of disk space that is guaranteed to a dataset, not including descendents, such as snapshots and clones. When the amount of disk space 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 dataset's disk space used, and counts against the parent dataset's 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.
The property abbreviation is refreserv.
|reservation||Number (or none)||none||Sets the minimum amount of disk space guaranteed to a dataset and its descendents. When the amount of disk 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 dataset's disk space used, and count against the parent dataset's quotas and reservations.
The property abbreviation is reserv.
For more information, see Setting Reservations on ZFS File Systems.
|secondarycache||String||all||Controls what is cached in the secondary cache (L2ARC). Possible values are all, none, and metadata. If set to all, both user data and metadata are cached. If set to none, neither user data nor metadata is cached. If set to metadata, only metadata is cached.|
|setuid||Boolean||on||Controls whether the setuid bit is honored in a file system.|
|shareiscsi||String||off||Controls whether a ZFS volume is shared as an iSCSI target. The property values are on, off, and type=disk. You might want to set shareiscsi=on for a file system so that all ZFS volumes within the file system are shared by default. However, setting this property on a file system has no direct effect.|
|sharenfs||String||off||Controls whether a 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 about sharing ZFS file systems, see Sharing and Unsharing ZFS File Systems.
|snapdir||String||hidden||Controls whether the .zfs directory is hidden or visible in the root of the file system. For more information about using snapshots, see ZFS Snapshots and Clones.|
|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 disk space consumed by a dataset and all its descendents.
For a detailed description, see The used Property.
|usedbychildren||Number||off||Read-only property that identifies the amount of disk space that is used by children of this dataset, which would be freed if all the dataset's children were destroyed. The property abbreviation is usedchild.|
|usedbydataset||Number||off||Read-only property that identifies the amount of disk space that is used by a dataset itself, which would be freed if the dataset was destroyed, after first destroying any snapshots and removing any refreservation reservations. The property abbreviation is usedds.|
|usedbyrefreservation||Number||off||Read-only property that identifies the amount of disk space that is used by a refreservation set on a dataset, which would be freed if the refreservation was removed. The property abbreviation is usedrefreserv.|
|usedbysnapshots||Number||off||Read-only property that identifies the amount of disk space that is consumed by snapshots of a dataset. In particular, it is the amount of disk space that would be freed if all of this dataset's snapshots were destroyed. Note that this value is not simply the sum of the snapshots' used properties, because space can be shared by multiple snapshots. The property abbreviation is usedsnap.|
|version||Number||N/A||Identifies the on-disk version of a file system, which is independent of the pool version. This property can only be set to a later version that is available from the supported software release. For more information, see the zfs upgrade command.|
|volsize||Number||N/A||For volumes, specifies the logical size of the volume.
For a detailed description, see volsize Property.
|volblocksize||Number||8 KB||For volumes, specifies the block size of the volume. The block size cannot be changed after the volume has been written, so set the block size at volume creation time. The default block size for volumes is 8 KB. Any power of 2 from 512 bytes to 128 KB is valid.
The property abbreviation is volblock.
|zoned||Boolean||N/A||Indicates whether a 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.
|zattr||Boolean||on||Indicates whether extended attributes are enabled (on) or disabled (off) for this file system.|
ZFS Read-Only Native Properties
Read-only native properties can be retrieved but not set. Read-only native properties are not inherited. Some native properties are specific to a particular type of dataset. In such cases, the dataset type is mentioned in the description in Table 6–1.
The read-only native properties are listed here and described in Table 6–1.
- For detailed information, see The used Property.
For more information about disk space accounting, including the used, referenced, and available properties, see ZFS Disk Space Accounting.
The used Property
The used property is a read-only property that identifies the amount of disk space consumed by this dataset and all its descendents. This value is checked against the dataset's quota and reservation. The disk space used does not include the dataset's reservation, but does consider the reservation of any descendent datasets. The amount of disk space that a dataset consumes from its parent, as well as the amount of disk 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 disk space is initially shared between the snapshot and the file system, and possibly with previous snapshots. As the file system changes, disk space that was previously shared becomes unique to the snapshot and is counted in the snapshot's space used. The disk space that is used by a snapshot accounts for its unique data. Additionally, deleting snapshots can increase the amount of disk space unique to (and used by) other snapshots. For more information about snapshots and space issues, see Out of Space Behavior.
The amount of disk space used, available, and referenced does not include pending changes. Pending changes are generally accounted for within a few seconds. Committing a change to a disk using the fsync(3c) or O_SYNC function does not necessarily guarantee that the disk space usage information will be updated immediately.
The usedbychildren, usedbydataset, usedbyrefreservation, and usedbysnapshots property information can be displayed with the zfs list -o space command. These properties identify the used property into disk space that is consumed by descendents. For more information, see Table 6–1.
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 Setting ZFS Quotas and Reservations.
Some settable native properties are specific to a particular type of dataset. In such cases, the dataset type is mentioned in the description in Table 6–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 described in Table 6–1.
- For a detailed description, see ACL Properties.
- For a detailed description, see ACL Properties.
- For a detailed description, see recordsize Property.
- For a detailed description, see volsize Property.
If the canmount property is set to off, the file system cannot be mounted by using the zfs mount or zfs mount -a commands. Setting this property to off 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 off, establish inheritable properties for descendent file systems, but the parent file system itself is never mounted nor is it accessible to users. In this case, the parent file system is serving as a container so that you can set properties on the container, but the container itself is never accessible.
In the following example, userpool is created, and its 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 mount userpool/user1 /export/home/user1 userpool/user2 /export/home/user2
Setting the canmount property to noauto means that the dataset can only be mounted explicitly, not automatically. This value setting is used by the Oracle Solaris upgrade software so that only those datasets belonging to the active boot environment are mounted at boot time.
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 might be suboptimal. Specifying a recordsize value 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 might adversely affect performance. The size specified must be a power of 2 greater than or equal to 512 bytes and less than or equal to 128 KB. Changing the file system's recordsize value only affects files created afterward. Existing files are unaffected.
The property abbreviation is recsize.
The volsize property specifies 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 the volume is in use, particularly when you shrink the size. Use extreme care 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 after the volume has been created. A sparse volume is a volume whose 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 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 conventions:
- They must contain a colon (':') character to distinguish them from native properties.
- They must contain lowercase letters, numbers, or the following punctuation characters: ':', '+','.', '_'.
- The maximum length of a 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:
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 Oracle Corporation.
The values of user properties must conform to the following conventions:
- They must consist of arbitrary strings that are always inherited and are never validated.
- The maximum length of the user property value is 1024 characters.
# 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.
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.