zfsprops.7 (68126B)
- .\"
- .\" CDDL HEADER START
- .\"
- .\" The contents of this file are subject to the terms of the
- .\" Common Development and Distribution License (the "License").
- .\" You may not use this file except in compliance with the License.
- .\"
- .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
- .\" or https://opensource.org/licenses/CDDL-1.0.
- .\" See the License for the specific language governing permissions
- .\" and limitations under the License.
- .\"
- .\" When distributing Covered Code, include this CDDL HEADER in each
- .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
- .\" If applicable, add the following below this CDDL HEADER, with the
- .\" fields enclosed by brackets "[]" replaced with your own identifying
- .\" information: Portions Copyright [yyyy] [name of copyright owner]
- .\"
- .\" CDDL HEADER END
- .\"
- .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
- .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
- .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
- .\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
- .\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
- .\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org>
- .\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org>
- .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
- .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
- .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
- .\" Copyright (c) 2014 Integros [integros.com]
- .\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved.
- .\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org>
- .\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved.
- .\" Copyright 2019 Richard Laager. All rights reserved.
- .\" Copyright 2018 Nexenta Systems, Inc.
- .\" Copyright 2019 Joyent, Inc.
- .\" Copyright (c) 2019, Kjeld Schouten-Lebbing
- .\" Copyright (c) 2022 Hewlett Packard Enterprise Development LP.
- .\"
- .Dd June 29, 2024
- .Dt ZFSPROPS 7
- .Os
- .
- .Sh NAME
- .Nm zfsprops
- .Nd native and user-defined properties of ZFS datasets
- .
- .Sh DESCRIPTION
- Properties are divided into two types, native properties and user-defined
- .Po or
- .Qq user
- .Pc
- properties.
- Native properties either export internal statistics or control ZFS behavior.
- In addition, native properties are either editable or read-only.
- User properties have no effect on ZFS 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 the
- .Sx User Properties
- section, below.
- .
- .Ss Native Properties
- Every dataset has a set of properties that export statistics about the dataset
- as well as control various behaviors.
- Properties are inherited from the parent unless overridden by the child.
- Some properties apply only to certain types of datasets
- .Pq file systems, volumes, or snapshots .
- .Pp
- The values of numeric properties can be specified using human-readable suffixes
- .Po for example,
- .Sy k ,
- .Sy KB ,
- .Sy M ,
- .Sy Gb ,
- and so forth, up to
- .Sy Z
- for zettabyte
- .Pc .
- The following are all valid
- .Pq and equal
- specifications:
- .Li 1536M ,
- .Li 1.5g ,
- .Li 1.50GB .
- .Pp
- The values of non-numeric properties are case sensitive and must be lowercase,
- except for
- .Sy mountpoint ,
- .Sy sharenfs ,
- and
- .Sy sharesmb .
- .Pp
- The following native properties consist of read-only statistics about the
- dataset.
- These properties can be neither set, nor inherited.
- Native properties apply to all dataset types unless otherwise noted.
- .Bl -tag -width "usedbyrefreservation"
- .It Sy available
- The amount of space available to the dataset and all its children, assuming that
- there is no other activity in the pool.
- Because space is shared within a pool, availability can be limited by any number
- of factors, including physical pool size, quotas, reservations, or other
- datasets within the pool.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy avail .
- .It Sy compressratio
- For non-snapshots, the compression ratio achieved for the
- .Sy used
- space of this dataset, expressed as a multiplier.
- The
- .Sy used
- property includes descendant datasets, and, for clones, does not include the
- space shared with the origin snapshot.
- For snapshots, the
- .Sy compressratio
- is the same as the
- .Sy refcompressratio
- property.
- Compression can be turned on by running:
- .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
- The default value is
- .Sy off .
- .It Sy createtxg
- The transaction group (txg) in which the dataset was created.
- Bookmarks have the same
- .Sy createtxg
- as the snapshot they are initially tied to.
- This property is suitable for ordering a list of snapshots,
- e.g. for incremental send and receive.
- .It Sy creation
- The time this dataset was created.
- .It Sy clones
- For snapshots, this property is a comma-separated list of filesystems or volumes
- which are clones of this snapshot.
- The clones'
- .Sy origin
- property is this snapshot.
- If the
- .Sy clones
- property is not empty, then this snapshot can not be destroyed
- .Po even with the
- .Fl r
- or
- .Fl f
- options
- .Pc .
- The roles of origin and clone can be swapped by promoting the clone with the
- .Nm zfs Cm promote
- command.
- .It Sy defer_destroy
- This property is
- .Sy on
- if the snapshot has been marked for deferred destroy by using the
- .Nm zfs Cm destroy Fl d
- command.
- Otherwise, the property is
- .Sy off .
- .It Sy encryptionroot
- For encrypted datasets, indicates where the dataset is currently inheriting its
- encryption key from.
- Loading or unloading a key for the
- .Sy encryptionroot
- will implicitly load / unload the key for any inheriting datasets (see
- .Nm zfs Cm load-key
- and
- .Nm zfs Cm unload-key
- for details).
- Clones will always share an
- encryption key with their origin.
- See the
- .Sx Encryption
- section of
- .Xr zfs-load-key 8
- for details.
- .It Sy filesystem_count
- The total number of filesystems and volumes that exist under this location in
- the dataset tree.
- This value is only available when a
- .Sy filesystem_limit
- has been set somewhere in the tree under which the dataset resides.
- .It Sy keystatus
- Indicates if an encryption key is currently loaded into ZFS.
- The possible values are
- .Sy none ,
- .Sy available ,
- and
- .Sy unavailable .
- See
- .Nm zfs Cm load-key
- and
- .Nm zfs Cm unload-key .
- .It Sy guid
- The 64 bit GUID of this dataset or bookmark which does not change over its
- entire lifetime.
- When a snapshot is sent to another pool, the received snapshot has the same
- GUID.
- Thus, the
- .Sy guid
- is suitable to identify a snapshot across pools.
- .It Sy logicalreferenced
- The amount of space that is
- .Qq logically
- accessible by this dataset.
- See the
- .Sy referenced
- property.
- The logical space ignores the effect of the
- .Sy compression
- and
- .Sy copies
- properties, giving a quantity closer to the amount of data that applications
- see.
- However, it does include space consumed by metadata.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy lrefer .
- .It Sy logicalused
- The amount of space that is
- .Qq logically
- consumed by this dataset and all its descendents.
- See the
- .Sy used
- property.
- The logical space ignores the effect of the
- .Sy compression
- and
- .Sy copies
- properties, giving a quantity closer to the amount of data that applications
- see.
- However, it does include space consumed by metadata.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy lused .
- .It Sy mounted
- For file systems, indicates whether the file system is currently mounted.
- This property can be either
- .Sy yes
- or
- .Sy no .
- .It Sy objsetid
- A unique identifier for this dataset within the pool.
- Unlike the dataset's
- .Sy guid , No the Sy objsetid
- of a dataset is not transferred to other pools when the snapshot is copied
- with a send/receive operation.
- The
- .Sy objsetid
- can be reused (for a new dataset) after the dataset is deleted.
- .It Sy origin
- For cloned file systems or volumes, the snapshot from which the clone was
- created.
- See also the
- .Sy clones
- property.
- .It Sy receive_resume_token
- For filesystems or volumes which have saved partially-completed state from
- .Nm zfs Cm receive Fl s ,
- this opaque token can be provided to
- .Nm zfs Cm send Fl t
- to resume and complete the
- .Nm zfs Cm receive .
- .It Sy redact_snaps
- For bookmarks, this is the list of snapshot guids the bookmark contains a
- redaction
- list for.
- For snapshots, this is the list of snapshot guids the snapshot is redacted with
- respect to.
- .It Sy referenced
- The amount of data that is accessible by this dataset, which may or may 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, since its contents are
- identical.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy refer .
- .It Sy refcompressratio
- The compression ratio achieved for the
- .Sy referenced
- space of this dataset, expressed as a multiplier.
- See also the
- .Sy compressratio
- property.
- .It Sy snapshot_count
- The total number of snapshots that exist under this location in the dataset
- tree.
- This value is only available when a
- .Sy snapshot_limit
- has been set somewhere in the tree under which the dataset resides.
- .It Sy type
- The type of dataset:
- .Sy filesystem ,
- .Sy volume ,
- .Sy snapshot ,
- or
- .Sy bookmark .
- .It Sy used
- The amount of space consumed by this dataset and all its descendents.
- This is the value that is checked against this dataset's quota and reservation.
- The space used does not include this dataset's reservation, but does take into
- account the reservations 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 this dataset is recursively destroyed, is the
- greater of its space used and its reservation.
- .Pp
- The used space of a snapshot
- .Po see the
- .Sx Snapshots
- section of
- .Xr zfsconcepts 7
- .Pc
- is space that is referenced exclusively by this snapshot.
- If this snapshot is destroyed, the amount of
- .Sy used
- space will be freed.
- Space that is shared by multiple snapshots isn't accounted for in this metric.
- When a snapshot is destroyed, space that was previously shared with this
- snapshot can become unique to snapshots adjacent to it, thus changing the used
- space of those snapshots.
- The used space of the latest snapshot can also be affected by changes in the
- file system.
- Note that the
- .Sy used
- space of a snapshot is a subset of the
- .Sy written
- space of the snapshot.
- .Pp
- 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
- .Xr fsync 2
- or
- .Sy O_SYNC
- does not necessarily guarantee that the space usage information is updated
- immediately.
- .It Sy usedby*
- The
- .Sy usedby*
- properties decompose the
- .Sy used
- properties into the various reasons that space is used.
- Specifically,
- .Sy used No =
- .Sy usedbychildren No +
- .Sy usedbydataset No +
- .Sy usedbyrefreservation No +
- .Sy usedbysnapshots .
- These properties are only available for datasets created on
- .Nm zpool
- .Qo version 13 Qc
- pools.
- .It Sy usedbychildren
- The amount of space used by children of this dataset, which would be freed if
- all the dataset's children were destroyed.
- .It Sy usedbydataset
- The amount of space used by this dataset itself, which would be freed if the
- dataset were destroyed
- .Po after first removing any
- .Sy refreservation
- and destroying any necessary snapshots or descendents
- .Pc .
- .It Sy usedbyrefreservation
- The amount of space used by a
- .Sy refreservation
- set on this dataset, which would be freed if the
- .Sy refreservation
- was removed.
- .It Sy usedbysnapshots
- The amount of space consumed by snapshots of this dataset.
- In particular, it is the amount of space that would be freed if all of this
- dataset's snapshots were destroyed.
- Note that this is not simply the sum of the snapshots'
- .Sy used
- properties because space can be shared by multiple snapshots.
- .It Sy userused Ns @ Ns Ar user
- The amount of space consumed by the specified user in this dataset.
- Space is charged to the owner of each file, as displayed by
- .Nm ls Fl l .
- The amount of space charged is displayed by
- .Nm du No and Nm ls Fl s .
- See the
- .Nm zfs Cm userspace
- command for more information.
- .Pp
- Unprivileged users can access only their own space usage.
- The root user, or a user who has been granted the
- .Sy userused
- privilege with
- .Nm zfs Cm allow ,
- can access everyone's usage.
- .Pp
- The
- .Sy userused Ns @ Ns Ar …
- properties are not displayed by
- .Nm zfs Cm get Sy all .
- The user's name must be appended after the
- .Sy @
- symbol, using one of the following forms:
- .Bl -bullet -compact -offset 4n
- .It
- POSIX name
- .Pq Qq joe
- .It
- POSIX numeric ID
- .Pq Qq 789
- .It
- SID name
- .Pq Qq joe.smith@mydomain
- .It
- SID numeric ID
- .Pq Qq S-1-123-456-789
- .El
- .Pp
- Files created on Linux always have POSIX owners.
- .It Sy userobjused Ns @ Ns Ar user
- The
- .Sy userobjused
- property is similar to
- .Sy userused
- but instead it counts the number of objects consumed by a user.
- This property counts all objects allocated on behalf of the user,
- it may differ from the results of system tools such as
- .Nm df Fl i .
- .Pp
- When the property
- .Sy xattr Ns = Ns Sy on
- is set on a file system additional objects will be created per-file to store
- extended attributes.
- These additional objects are reflected in the
- .Sy userobjused
- value and are counted against the user's
- .Sy userobjquota .
- When a file system is configured to use
- .Sy xattr Ns = Ns Sy sa
- no additional internal objects are normally required.
- .It Sy userrefs
- This property is set to the number of user holds on this snapshot.
- User holds are set by using the
- .Nm zfs Cm hold
- command.
- .It Sy groupused Ns @ Ns Ar group
- The amount of space consumed by the specified group in this dataset.
- Space is charged to the group of each file, as displayed by
- .Nm ls Fl l .
- See the
- .Sy userused Ns @ Ns Ar user
- property for more information.
- .Pp
- Unprivileged users can only access their own groups' space usage.
- The root user, or a user who has been granted the
- .Sy groupused
- privilege with
- .Nm zfs Cm allow ,
- can access all groups' usage.
- .It Sy groupobjused Ns @ Ns Ar group
- The number of objects consumed by the specified group in this dataset.
- Multiple objects may be charged to the group for each file when extended
- attributes are in use.
- See the
- .Sy userobjused Ns @ Ns Ar user
- property for more information.
- .Pp
- Unprivileged users can only access their own groups' space usage.
- The root user, or a user who has been granted the
- .Sy groupobjused
- privilege with
- .Nm zfs Cm allow ,
- can access all groups' usage.
- .It Sy projectused Ns @ Ns Ar project
- The amount of space consumed by the specified project in this dataset.
- Project is identified via the project identifier (ID) that is object-based
- numeral attribute.
- An object can inherit the project ID from its parent object (if the
- parent has the flag of inherit project ID that can be set and changed via
- .Nm chattr Fl /+P
- or
- .Nm zfs project Fl s )
- when being created.
- The privileged user can set and change object's project
- ID via
- .Nm chattr Fl p
- or
- .Nm zfs project Fl s
- anytime.
- Space is charged to the project of each file, as displayed by
- .Nm lsattr Fl p
- or
- .Nm zfs project .
- See the
- .Sy userused Ns @ Ns Ar user
- property for more information.
- .Pp
- The root user, or a user who has been granted the
- .Sy projectused
- privilege with
- .Nm zfs allow ,
- can access all projects' usage.
- .It Sy projectobjused Ns @ Ns Ar project
- The
- .Sy projectobjused
- is similar to
- .Sy projectused
- but instead it counts the number of objects consumed by project.
- When the property
- .Sy xattr Ns = Ns Sy on
- is set on a fileset, ZFS will create additional objects per-file to store
- extended attributes.
- These additional objects are reflected in the
- .Sy projectobjused
- value and are counted against the project's
- .Sy projectobjquota .
- When a filesystem is configured to use
- .Sy xattr Ns = Ns Sy sa
- no additional internal objects are required.
- See the
- .Sy userobjused Ns @ Ns Ar user
- property for more information.
- .Pp
- The root user, or a user who has been granted the
- .Sy projectobjused
- privilege with
- .Nm zfs allow ,
- can access all projects' objects usage.
- .It Sy snapshots_changed
- Provides a mechanism to quickly determine whether snapshot list has
- changed without having to mount a dataset or iterate the snapshot list.
- Specifies the time at which a snapshot for a dataset was last
- created or deleted.
- .Pp
- This allows us to be more efficient how often we query snapshots.
- The property is persistent across mount and unmount operations only if the
- .Sy extensible_dataset
- feature is enabled.
- .It Sy volblocksize
- For volumes, specifies the block size of the volume.
- The
- .Sy blocksize
- cannot be changed once the volume has been written, so it should be set at
- volume creation time.
- The default
- .Sy blocksize
- for volumes is 16 Kbytes.
- Any power of 2 from 512 bytes to 128 Kbytes is valid.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy volblock .
- .It Sy written
- The amount of space
- .Sy referenced
- by this dataset, that was written since the previous snapshot
- .Pq i.e. that is not referenced by the previous snapshot .
- .It Sy written Ns @ Ns Ar snapshot
- The amount of
- .Sy referenced
- space written to this dataset since the specified snapshot.
- This is the space that is referenced by this dataset but was not referenced by
- the specified snapshot.
- .Pp
- The
- .Ar snapshot
- may be specified as a short snapshot name
- .Pq just the part after the Sy @ ,
- in which case it will be interpreted as a snapshot in the same filesystem as
- this dataset.
- The
- .Ar snapshot
- may be a full snapshot name
- .Pq Ar filesystem Ns @ Ns Ar snapshot ,
- which for clones may be a snapshot in the origin's filesystem
- .Pq or the origin of the origin's filesystem, etc.
- .El
- .Pp
- The following native properties can be used to change the behavior of a ZFS
- dataset.
- .Bl -tag -width ""
- .It Xo
- .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
- .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
- .Xc
- Controls how ACEs are inherited when files and directories are created.
- .Bl -tag -compact -offset 4n -width "passthrough-x"
- .It Sy discard
- does not inherit any ACEs.
- .It Sy noallow
- only inherits inheritable ACEs that specify
- .Qq deny
- permissions.
- .It Sy restricted
- default, removes the
- .Sy write_acl
- and
- .Sy write_owner
- permissions when the ACE is inherited.
- .It Sy passthrough
- inherits all inheritable ACEs without any modifications.
- .It Sy passthrough-x
- same meaning as
- .Sy passthrough ,
- except that the
- .Sy owner@ , group@ , No and Sy everyone@
- ACEs inherit the execute permission only if the file creation mode also requests
- the execute bit.
- .El
- .Pp
- When the property value is set to
- .Sy passthrough ,
- files are created with a mode determined by the inheritable ACEs.
- If no inheritable ACEs exist that affect the mode, then the mode is set in
- accordance to the requested mode from the application.
- .Pp
- The
- .Sy aclinherit
- property does not apply to POSIX ACLs.
- .It Xo
- .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
- .Sy passthrough Ns | Ns Sy restricted Ns
- .Xc
- Controls how an ACL is modified during chmod(2) and how inherited ACEs
- are modified by the file creation mode:
- .Bl -tag -compact -offset 4n -width "passthrough"
- .It Sy discard
- default, deletes all
- .Sy ACEs
- except for those representing
- the mode of the file or directory requested by
- .Xr chmod 2 .
- .It Sy groupmask
- reduces permissions granted in all
- .Sy ALLOW
- entries found in the
- .Sy ACL
- such that they are no greater than the group permissions specified by
- .Xr chmod 2 .
- .It Sy passthrough
- indicates that no changes are made to the ACL other than creating or updating
- the necessary ACL entries to represent the new mode of the file or directory.
- .It Sy restricted
- will cause the
- .Xr chmod 2
- operation to return an error when used on any file or directory which has
- a non-trivial ACL whose entries can not be represented by a mode.
- .Xr chmod 2
- is required to change the set user ID, set group ID, or sticky bits on a file
- or directory, as they do not have equivalent ACL entries.
- In order to use
- .Xr chmod 2
- on a file or directory with a non-trivial ACL when
- .Sy aclmode
- is set to
- .Sy restricted ,
- you must first remove all ACL entries which do not represent the current mode.
- .El
- .It Sy acltype Ns = Ns Sy off Ns | Ns Sy nfsv4 Ns | Ns Sy posix
- Controls whether ACLs are enabled and if so what type of ACL to use.
- When this property is set to a type of ACL not supported by the current
- platform, the behavior is the same as if it were set to
- .Sy off .
- .Bl -tag -compact -offset 4n -width "posixacl"
- .It Sy off
- default on Linux, when a file system has the
- .Sy acltype
- property set to off then ACLs are disabled.
- .It Sy noacl
- an alias for
- .Sy off
- .It Sy nfsv4
- default on
- .Fx ,
- indicates that NFSv4-style ZFS ACLs should be used.
- These ACLs can be managed with the
- .Xr getfacl 1
- and
- .Xr setfacl 1 .
- The
- .Sy nfsv4
- ZFS ACL type is not yet supported on Linux.
- .It Sy posix
- indicates POSIX ACLs should be used.
- POSIX ACLs are specific to Linux and are not functional on other platforms.
- POSIX ACLs are stored as an extended
- attribute and therefore will not overwrite any existing NFSv4 ACLs which
- may be set.
- .It Sy posixacl
- an alias for
- .Sy posix
- .El
- .Pp
- To obtain the best performance when setting
- .Sy posix
- users are strongly encouraged to set the
- .Sy xattr Ns = Ns Sy sa
- property.
- This will result in the POSIX ACL being stored more efficiently on disk.
- But as a consequence, all new extended attributes will only be
- accessible from OpenZFS implementations which support the
- .Sy xattr Ns = Ns Sy sa
- property.
- See the
- .Sy xattr
- property for more details.
- .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
- 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.
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy atime
- and
- .Sy noatime
- mount options.
- The default value is
- .Sy on .
- See also
- .Sy relatime
- below.
- .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
- If this property is set to
- .Sy off ,
- the file system cannot be mounted, and is ignored by
- .Nm zfs Cm mount Fl a .
- Setting this property to
- .Sy off
- is similar to setting the
- .Sy mountpoint
- property to
- .Sy none ,
- except that the dataset still has a normal
- .Sy mountpoint
- property, which can be inherited.
- Setting this property to
- .Sy off
- allows datasets to be used solely as a mechanism to inherit properties.
- One example of setting
- .Sy canmount Ns = Ns Sy off
- is to have two datasets with the same
- .Sy mountpoint ,
- so that the children of both datasets appear in the same directory, but might
- have different inherited characteristics.
- .Pp
- When set to
- .Sy noauto ,
- 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
- .Nm zfs Cm mount Fl a
- command or unmounted by the
- .Nm zfs Cm unmount Fl a
- command.
- .Pp
- This property is not inherited.
- .It Xo
- .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
- .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
- .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr Ns | Ns Sy blake3
- .Xc
- Controls the checksum used to verify data integrity.
- The default value is
- .Sy on ,
- which automatically selects an appropriate algorithm
- .Po currently,
- .Sy fletcher4 ,
- but this may change in future releases
- .Pc .
- The value
- .Sy off
- disables integrity checking on user data.
- The value
- .Sy noparity
- not only disables integrity but also disables maintaining parity for user data.
- This setting is used internally by a dump device residing on a RAID-Z pool and
- should not be used by any other dataset.
- Disabling checksums is
- .Em NOT
- a recommended practice.
- .Pp
- The
- .Sy sha512 ,
- .Sy skein ,
- .Sy edonr ,
- and
- .Sy blake3
- checksum algorithms require enabling the appropriate features on the pool.
- .Pp
- Please see
- .Xr zpool-features 7
- for more information on these algorithms.
- .Pp
- Changing this property affects only newly-written data.
- .It Xo
- .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
- .Sy gzip- Ns Ar N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns
- .Sy zstd- Ns Ar N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Ar N
- .Xc
- Controls the compression algorithm used for this dataset.
- .Pp
- When set to
- .Sy on
- (the default), indicates that the current default compression algorithm should
- be used.
- The default balances compression and decompression speed, with compression ratio
- and is expected to work well on a wide variety of workloads.
- Unlike all other settings for this property,
- .Sy on
- does not select a fixed compression type.
- As new compression algorithms are added to ZFS and enabled on a pool, the
- default compression algorithm may change.
- The current default compression algorithm is either
- .Sy lzjb
- or, if the
- .Sy lz4_compress
- feature is enabled,
- .Sy lz4 .
- .Pp
- The
- .Sy lz4
- compression algorithm is a high-performance replacement for the
- .Sy lzjb
- algorithm.
- It features significantly faster compression and decompression, as well as a
- moderately higher compression ratio than
- .Sy lzjb ,
- but can only be used on pools with the
- .Sy lz4_compress
- feature set to
- .Sy enabled .
- See
- .Xr zpool-features 7
- for details on ZFS feature flags and the
- .Sy lz4_compress
- feature.
- .Pp
- The
- .Sy lzjb
- compression algorithm is optimized for performance while providing decent data
- compression.
- .Pp
- The
- .Sy gzip
- compression algorithm uses the same compression as the
- .Xr gzip 1
- command.
- You can specify the
- .Sy gzip
- level by using the value
- .Sy gzip- Ns Ar N ,
- where
- .Ar N
- is an integer from 1
- .Pq fastest
- to 9
- .Pq best compression ratio .
- Currently,
- .Sy gzip
- is equivalent to
- .Sy gzip-6
- .Po which is also the default for
- .Xr gzip 1
- .Pc .
- .Pp
- The
- .Sy zstd
- compression algorithm provides both high compression ratios and good
- performance.
- You can specify the
- .Sy zstd
- level by using the value
- .Sy zstd- Ns Ar N ,
- where
- .Ar N
- is an integer from 1
- .Pq fastest
- to 19
- .Pq best compression ratio .
- .Sy zstd
- is equivalent to
- .Sy zstd-3 .
- .Pp
- Faster speeds at the cost of the compression ratio can be requested by
- setting a negative
- .Sy zstd
- level.
- This is done using
- .Sy zstd-fast- Ns Ar N ,
- where
- .Ar N
- is an integer in
- .Bq Sy 1 Ns - Ns Sy 10 , 20 , 30 , No … , Sy 100 , 500 , 1000
- which maps to a negative
- .Sy zstd
- level.
- The lower the level the faster the compression \(em
- .Sy 1000
- provides the fastest compression and lowest compression ratio.
- .Sy zstd-fast
- is equivalent to
- .Sy zstd-fast- Ns Ar 1 .
- .Pp
- The
- .Sy zle
- compression algorithm compresses runs of zeros.
- .Pp
- This property can also be referred to by its shortened column name
- .Sy compress .
- Changing this property affects only newly-written data.
- .Pp
- When any setting except
- .Sy off
- is selected, compression will explicitly check for blocks consisting of only
- zeroes (the NUL byte).
- When a zero-filled block is detected, it is stored as
- a hole and not compressed using the indicated compression algorithm.
- .Pp
- All blocks are allocated as a whole number of sectors
- .Pq chunks of 2^ Ns Sy ashift No bytes , e.g . Sy 512B No or Sy 4KB .
- Compression may result in a non-sector-aligned size, which will be rounded up
- to a whole number of sectors.
- If compression saves less than one whole sector,
- the block will be stored uncompressed.
- Therefore, blocks whose logical size is a small number of sectors will
- experience less compression
- (e.g. for
- .Sy recordsize Ns = Ns Sy 16K
- with
- .Sy 4K
- sectors, which have 4 sectors per block,
- compression needs to save at least 25% to actually save space on disk).
- .Pp
- There is
- .Sy 12.5%
- default compression threshold in addition to sector rounding.
- .It Xo
- .Sy context Ns = Ns Sy none Ns | Ns
- .Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level
- .Xc
- This flag sets the SELinux context for all files in the file system under
- a mount point for that file system.
- See
- .Xr selinux 8
- for more information.
- .It Xo
- .Sy fscontext Ns = Ns Sy none Ns | Ns
- .Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level
- .Xc
- This flag sets the SELinux context for the file system file system being
- mounted.
- See
- .Xr selinux 8
- for more information.
- .It Xo
- .Sy defcontext Ns = Ns Sy none Ns | Ns
- .Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level
- .Xc
- This flag sets the SELinux default context for unlabeled files.
- See
- .Xr selinux 8
- for more information.
- .It Xo
- .Sy rootcontext Ns = Ns Sy none Ns | Ns
- .Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level
- .Xc
- This flag sets the SELinux context for the root inode of the file system.
- See
- .Xr selinux 8
- for more information.
- .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
- Controls the number of copies of data stored for this dataset.
- These copies are in addition to any redundancy provided by the pool, for
- example, mirroring or RAID-Z.
- The copies are stored on different disks, if possible.
- The space used by multiple copies is charged to the associated file and dataset,
- changing the
- .Sy used
- property and counting against quotas and reservations.
- .Pp
- Changing this property only affects newly-written data.
- Therefore, set this property at file system creation time by using the
- .Fl o Sy copies Ns = Ns Ar N
- option.
- .Pp
- Remember that ZFS will not import a pool with a missing top-level vdev.
- Do
- .Em NOT
- create, for example a two-disk striped pool and set
- .Sy copies Ns = Ns Ar 2
- on some datasets thinking you have setup redundancy for them.
- When a disk fails you will not be able to import the pool
- and will have lost all of your data.
- .Pp
- Encrypted datasets may not have
- .Sy copies Ns = Ns Ar 3
- since the implementation stores some encryption metadata where the third copy
- would normally be.
- .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
- Controls whether device nodes can be opened on this file system.
- The default value is
- .Sy on .
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy dev
- and
- .Sy nodev
- mount options.
- .It Xo
- .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
- .Sy sha256 Ns Oo , Ns Sy verify Oc Ns | Ns Sy sha512 Ns Oo , Ns Sy verify Oc Ns | Ns Sy skein Ns Oo , Ns Sy verify Oc Ns | Ns
- .Sy edonr , Ns Sy verify Ns | Ns Sy blake3 Ns Oo , Ns Sy verify Oc Ns
- .Xc
- Configures deduplication for a dataset.
- The default value is
- .Sy off .
- The default deduplication checksum is
- .Sy sha256
- (this may change in the future).
- When
- .Sy dedup
- is enabled, the checksum defined here overrides the
- .Sy checksum
- property.
- Setting the value to
- .Sy verify
- has the same effect as the setting
- .Sy sha256 , Ns Sy verify .
- .Pp
- If set to
- .Sy verify ,
- ZFS will do a byte-to-byte comparison in case of two blocks having the same
- signature to make sure the block contents are identical.
- Specifying
- .Sy verify
- is mandatory for the
- .Sy edonr
- algorithm.
- .Pp
- Unless necessary, deduplication should
- .Em not
- be enabled on a system.
- See the
- .Sx Deduplication
- section of
- .Xr zfsconcepts 7 .
- .It Xo
- .Sy direct Ns = Ns Sy disabled Ns | Ns Sy standard Ns | Ns Sy always
- .Xc
- Controls the behavior of Direct I/O requests
- .Pq e.g. Dv O_DIRECT .
- The
- .Sy standard
- behavior for Direct I/O requests is to bypass the ARC when possible.
- These requests will not be cached and performance will be limited by the
- raw speed of the underlying disks
- .Pq Dv this is the default .
- .Sy always
- causes every properly aligned read or write to be treated as a direct request.
- .Sy disabled
- causes the O_DIRECT flag to be silently ignored and all direct requests will
- be handled by the ARC.
- This is the default behavior for OpenZFS 2.2 and prior releases.
- .Pp
- Bypassing the ARC requires that a direct request be correctly aligned.
- For write requests the starting offset and size of the request must be
- .Sy recordsize Ns
- -aligned, if not then the unaligned portion of the request will be silently
- redirected through the ARC.
- For read requests there is no
- .Sy recordsize
- alignment restriction on either the starting offset or size.
- All direct requests must use a page-aligned memory buffer and the request
- size must be a multiple of the page size or an error is returned.
- .Pp
- Concurrently mixing buffered and direct requests to overlapping regions of
- a file can decrease performance.
- However, the resulting file will always be coherent.
- For example, a direct read after a buffered write will return the data
- from the buffered write.
- Furthermore, if an application uses
- .Xr mmap 2
- based file access then in order to maintain coherency all direct requests
- are converted to buffered requests while the file is mapped.
- Currently Direct I/O is not supported with zvols.
- If dedup is enabled on a dataset, Direct I/O writes will not check for
- deduplication.
- Deduplication and Direct I/O writes are currently incompatible.
- .It Xo
- .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
- .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
- .Xc
- Specifies a compatibility mode or literal value for the size of dnodes in the
- file system.
- The default value is
- .Sy legacy .
- Setting this property to a value other than
- .Sy legacy No requires the Sy large_dnode No pool feature to be enabled .
- .Pp
- Consider setting
- .Sy dnodesize
- to
- .Sy auto
- if the dataset uses the
- .Sy xattr Ns = Ns Sy sa
- property setting and the workload makes heavy use of extended attributes.
- This
- may be applicable to SELinux-enabled systems, Lustre servers, and Samba
- servers, for example.
- Literal values are supported for cases where the optimal
- size is known in advance and for performance testing.
- .Pp
- Leave
- .Sy dnodesize
- set to
- .Sy legacy
- if you need to receive a send stream of this dataset on a pool that doesn't
- enable the
- .Sy large_dnode
- feature, or if you need to import this pool on a system that doesn't support the
- .Sy large_dnode No feature .
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy dnsize .
- .It Xo
- .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
- .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
- .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
- .Xc
- Controls the encryption cipher suite (block cipher, key length, and mode) used
- for this dataset.
- Requires the
- .Sy encryption
- feature to be enabled on the pool.
- Requires a
- .Sy keyformat
- to be set at dataset creation time.
- .Pp
- Selecting
- .Sy encryption Ns = Ns Sy on
- when creating a dataset indicates that the default encryption suite will be
- selected, which is currently
- .Sy aes-256-gcm .
- In order to provide consistent data protection, encryption must be specified at
- dataset creation time and it cannot be changed afterwards.
- .Pp
- For more details and caveats about encryption see the
- .Sx Encryption
- section of
- .Xr zfs-load-key 8 .
- .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
- Controls what format the user's encryption key will be provided as.
- This property is only set when the dataset is encrypted.
- .Pp
- Raw keys and hex keys must be 32 bytes long (regardless of the chosen
- encryption suite) and must be randomly generated.
- A raw key can be generated with the following command:
- .Dl # Nm dd Sy if=/dev/urandom bs=32 count=1 Sy of= Ns Pa /path/to/output/key
- .Pp
- Passphrases must be between 8 and 512 bytes long and will be processed through
- PBKDF2 before being used (see the
- .Sy pbkdf2iters
- property).
- Even though the encryption suite cannot be changed after dataset creation,
- the keyformat can be with
- .Nm zfs Cm change-key .
- .It Xo
- .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Ar /absolute/file/path Ns | Ns Sy https:// Ns Ar address Ns | Ns Sy http:// Ns Ar address
- .Xc
- Controls where the user's encryption key will be loaded from by default for
- commands such as
- .Nm zfs Cm load-key
- and
- .Nm zfs Cm mount Fl l .
- This property is only set for encrypted datasets which are encryption roots.
- If unspecified, the default is
- .Sy prompt .
- .Pp
- Even though the encryption suite cannot be changed after dataset creation, the
- keylocation can be with either
- .Nm zfs Cm set
- or
- .Nm zfs Cm change-key .
- If
- .Sy prompt
- is selected ZFS will ask for the key at the command prompt when it is required
- to access the encrypted data (see
- .Nm zfs Cm load-key
- for details).
- This setting will also allow the key to be passed in via the standard input
- stream,
- but users should be careful not to place keys which should be kept secret on
- the command line.
- If a file URI is selected, the key will be loaded from the
- specified absolute file path.
- If an HTTPS or HTTP URL is selected, it will be GETted using
- .Xr fetch 3 ,
- libcurl, or nothing, depending on compile-time configuration and run-time
- availability.
- The
- .Sy SSL_CA_CERT_FILE
- environment variable can be set to set the location
- of the concatenated certificate store.
- The
- .Sy SSL_CA_CERT_PATH
- environment variable can be set to override the location
- of the directory containing the certificate authority bundle.
- The
- .Sy SSL_CLIENT_CERT_FILE
- and
- .Sy SSL_CLIENT_KEY_FILE
- environment variables can be set to configure the path
- to the client certificate and its key.
- .It Sy pbkdf2iters Ns = Ns Ar iterations
- Controls the number of PBKDF2 iterations that a
- .Sy passphrase
- encryption key should be run through when processing it into an encryption key.
- This property is only defined when encryption is enabled and a keyformat of
- .Sy passphrase
- is selected.
- The goal of PBKDF2 is to significantly increase the
- computational difficulty needed to brute force a user's passphrase.
- This is accomplished by forcing the attacker to run each passphrase through a
- computationally expensive hashing function many times before they arrive at the
- resulting key.
- A user who actually knows the passphrase will only have to pay this cost once.
- As CPUs become better at processing, this number should be
- raised to ensure that a brute force attack is still not possible.
- The current default is
- .Sy 350000
- and the minimum is
- .Sy 100000 .
- This property may be changed with
- .Nm zfs Cm change-key .
- .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
- Controls whether processes can be executed from within this file system.
- The default value is
- .Sy on .
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy exec
- and
- .Sy noexec
- mount options.
- .It Sy volthreading Ns = Ns Sy on Ns | Ns Sy off
- Controls internal zvol threading.
- The value
- .Sy off
- disables zvol threading, and zvol relies on application threads.
- The default value is
- .Sy on ,
- which enables threading within a zvol.
- Please note that this property will be overridden by
- .Sy zvol_request_sync
- module parameter.
- This property is only applicable to Linux.
- .It Sy filesystem_limit Ns = Ns Ar count Ns | Ns Sy none
- Limits the number of filesystems and volumes that can exist under this point in
- the dataset tree.
- The limit is not enforced if the user is allowed to change the limit.
- Setting a
- .Sy filesystem_limit
- to
- .Sy on
- a descendent of a filesystem that already has a
- .Sy filesystem_limit
- does not override the ancestor's
- .Sy filesystem_limit ,
- but rather imposes an additional limit.
- This feature must be enabled to be used
- .Po see
- .Xr zpool-features 7
- .Pc .
- .It Sy special_small_blocks Ns = Ns Ar size
- This value represents the threshold block size for including small file
- blocks into the special allocation class.
- 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 512 up to 1048576 (1 MiB).
- The default size is 0 which means no small file blocks
- will be allocated in the special class.
- .Pp
- Before setting this property, a special class vdev must be added to the
- pool.
- See
- .Xr zpoolconcepts 7
- for more details on the special allocation class.
- .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
- Controls the mount point used for this file system.
- See the
- .Sx Mount Points
- section of
- .Xr zfsconcepts 7
- for more information on how this property is used.
- .Pp
- When the
- .Sy 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
- .Sy legacy ,
- then they remain unmounted.
- Otherwise, they are automatically remounted in the new location if the property
- was previously
- .Sy legacy
- or
- .Sy none .
- In addition, any shared file systems are unshared and shared in the new
- location.
- .Pp
- When the
- .Sy mountpoint
- property is set with
- .Nm zfs Cm set Fl u
- , the
- .Sy mountpoint
- property is updated but dataset is not mounted or unmounted and remains
- as it was before.
- .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
- Controls whether the file system should be mounted with
- .Sy nbmand
- .Pq Non-blocking mandatory locks .
- Changes to this property only take effect when the file system is umounted and
- remounted.
- This was only supported by Linux prior to 5.15, and was buggy there,
- and is not supported by
- .Fx .
- On Solaris it's used for SMB clients.
- .It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
- Allow mounting on a busy directory or a directory which already contains
- files or directories.
- This is the default mount behavior for Linux and
- .Fx
- file systems.
- On these platforms the property is
- .Sy on
- by default.
- Set to
- .Sy off
- to disable overlay mounts for consistency with OpenZFS on other platforms.
- .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
- Controls what is cached in the primary cache
- .Pq ARC .
- If this property is set to
- .Sy all ,
- then both user data and metadata is cached.
- If this property is set to
- .Sy none ,
- then neither user data nor metadata is cached.
- If this property is set to
- .Sy metadata ,
- then only metadata is cached.
- The default value is
- .Sy all .
- .It Sy quota Ns = Ns Ar size Ns | Ns Sy 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.
- This includes 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.
- .Pp
- Quotas cannot be set on volumes, as the
- .Sy volsize
- property acts as an implicit quota.
- .It Sy snapshot_limit Ns = Ns Ar count Ns | Ns Sy none
- Limits the number of snapshots that can be created on a dataset and its
- descendents.
- Setting a
- .Sy snapshot_limit
- on a descendent of a dataset that already has a
- .Sy snapshot_limit
- does not override the ancestor's
- .Sy snapshot_limit ,
- but rather imposes an additional limit.
- The limit is not enforced if the user is allowed to change the limit.
- For example, this means that recursive snapshots taken from the global zone are
- counted against each delegated dataset within a zone.
- This feature must be enabled to be used
- .Po see
- .Xr zpool-features 7
- .Pc .
- .It Sy userquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none
- Limits the amount of space consumed by the specified user.
- User space consumption is identified by the
- .Sy userspace@ Ns Ar user
- property.
- .Pp
- Enforcement of user quotas may be delayed by several seconds.
- This delay means that a user might exceed their quota before the system notices
- that they are over quota and begins to refuse additional writes with the
- .Er EDQUOT
- error message.
- See the
- .Nm zfs Cm userspace
- command for more information.
- .Pp
- Unprivileged users can only access their own groups' space usage.
- The root user, or a user who has been granted the
- .Sy userquota
- privilege with
- .Nm zfs Cm allow ,
- can get and set everyone's quota.
- .Pp
- This property is not available on volumes, on file systems before version 4, or
- on pools before version 15.
- The
- .Sy userquota@ Ns Ar …
- properties are not displayed by
- .Nm zfs Cm get Sy all .
- The user's name must be appended after the
- .Sy @
- symbol, using one of the following forms:
- .Bl -bullet -compact -offset 4n
- .It
- POSIX name
- .Pq Qq joe
- .It
- POSIX numeric ID
- .Pq Qq 789
- .It
- SID name
- .Pq Qq joe.smith@mydomain
- .It
- SID numeric ID
- .Pq Qq S-1-123-456-789
- .El
- .Pp
- Files created on Linux always have POSIX owners.
- .It Sy userobjquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none
- The
- .Sy userobjquota
- is similar to
- .Sy userquota
- but it limits the number of objects a user can create.
- Please refer to
- .Sy userobjused
- for more information about how objects are counted.
- .It Sy groupquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none
- Limits the amount of space consumed by the specified group.
- Group space consumption is identified by the
- .Sy groupused@ Ns Ar group
- property.
- .Pp
- Unprivileged users can access only their own groups' space usage.
- The root user, or a user who has been granted the
- .Sy groupquota
- privilege with
- .Nm zfs Cm allow ,
- can get and set all groups' quotas.
- .It Sy groupobjquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none
- The
- .Sy groupobjquota
- is similar to
- .Sy groupquota
- but it limits number of objects a group can consume.
- Please refer to
- .Sy userobjused
- for more information about how objects are counted.
- .It Sy projectquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none
- Limits the amount of space consumed by the specified project.
- Project space consumption is identified by the
- .Sy projectused@ Ns Ar project
- property.
- Please refer to
- .Sy projectused
- for more information about how project is identified and set/changed.
- .Pp
- The root user, or a user who has been granted the
- .Sy projectquota
- privilege with
- .Nm zfs allow ,
- can access all projects' quota.
- .It Sy projectobjquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none
- The
- .Sy projectobjquota
- is similar to
- .Sy projectquota
- but it limits number of objects a project can consume.
- Please refer to
- .Sy userobjused
- for more information about how objects are counted.
- .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
- Controls whether this dataset can be modified.
- The default value is
- .Sy off .
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy ro
- and
- .Sy rw
- mount options.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy rdonly .
- .It Sy recordsize Ns = Ns Ar size
- 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 tunes block sizes according to internal algorithms optimized
- for typical access patterns.
- .Pp
- For databases that create very large files but access them in small random
- chunks, these algorithms may be suboptimal.
- Specifying a
- .Sy 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.
- .Pp
- The size specified must be a power of two greater than or equal to
- .Ar 512 B
- and less than or equal to
- .Ar 128 KiB .
- If the
- .Sy large_blocks
- feature is enabled on the pool, the size may be up to
- .Ar 16 MiB .
- See
- .Xr zpool-features 7
- for details on ZFS feature flags.
- .Pp
- However, blocks larger than
- .Ar 1 MiB
- can have an impact on i/o latency (e.g. tying up a spinning disk for
- ~300ms), and also potentially on the memory allocator.
- .Pp
- Note that maximum size is still limited by default to
- .Ar 1 MiB
- on x86_32, see
- .Sy zfs_max_recordsize
- module parameter.
- .Pp
- Changing the file system's
- .Sy recordsize
- affects only files created afterward; existing files are unaffected.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy recsize .
- .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most Ns | Ns Sy some Ns | Ns Sy none
- Controls what types of metadata are stored redundantly.
- ZFS stores an extra copy of metadata, so that if a single block is corrupted,
- the amount of user data lost is limited.
- This extra copy is in addition to any redundancy provided at the pool level
- .Pq e.g. by mirroring or RAID-Z ,
- and is in addition to an extra copy specified by the
- .Sy copies
- property
- .Pq up to a total of 3 copies .
- For example if the pool is mirrored,
- .Sy copies Ns = Ns 2 ,
- and
- .Sy redundant_metadata Ns = Ns Sy most ,
- then ZFS stores 6 copies of most metadata, and 4 copies of data and some
- metadata.
- .Pp
- When set to
- .Sy all ,
- ZFS stores an extra copy of all metadata.
- If a single on-disk block is corrupt, at worst a single block of user data
- .Po which is
- .Sy recordsize
- bytes long
- .Pc
- can be lost.
- .Pp
- When set to
- .Sy most ,
- ZFS stores an extra copy of most types of metadata.
- This can improve performance of random writes, because less metadata must be
- written.
- In practice, at worst about 1000 blocks
- .Po of
- .Sy recordsize
- bytes each
- .Pc
- of user data can be lost if a single on-disk block is corrupt.
- The exact behavior of which metadata blocks are stored redundantly may change in
- future releases.
- .Pp
- When set to
- .Sy some ,
- ZFS stores an extra copy of only critical metadata.
- This can improve file create performance since less metadata
- needs to be written.
- If a single on-disk block is corrupt, at worst a single user file can be lost.
- .Pp
- When set to
- .Sy none ,
- ZFS does not store any copies of metadata redundantly.
- If a single on-disk block is corrupt, an entire dataset can be lost.
- .Pp
- The default value is
- .Sy all .
- .It Sy refquota Ns = Ns Ar size Ns | Ns Sy none
- Limits the amount of space 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, including file
- systems and snapshots.
- .It Sy refreservation Ns = Ns Ar size Ns | Ns Sy none Ns | Ns Sy auto
- The minimum amount of space guaranteed to a dataset, not including its
- descendents.
- When the amount of space used is below this value, the dataset is treated as if
- it were taking up the amount of space specified by
- .Sy refreservation .
- The
- .Sy refreservation
- reservation is accounted for in the parent datasets' space used, and counts
- against the parent datasets' quotas and reservations.
- .Pp
- If
- .Sy refreservation
- is set, a snapshot is only allowed if there is enough free pool space outside of
- this reservation to accommodate the current number of
- .Qq referenced
- bytes in the dataset.
- .Pp
- If
- .Sy refreservation
- is set to
- .Sy auto ,
- a volume is thick provisioned
- .Po or
- .Qq not sparse
- .Pc .
- .Sy refreservation Ns = Ns Sy auto
- is only supported on volumes.
- See
- .Sy volsize
- in the
- .Sx Native Properties
- section for more information about sparse volumes.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy refreserv .
- .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
- Controls the manner in which the access time is updated when
- .Sy atime Ns = Ns Sy on
- is set.
- Turning this property on causes the access time to be updated relative
- to the modify or change time.
- Access time is only updated if the previous
- access time was earlier than the current modify or change time or if the
- existing access time hasn't been updated within the past 24 hours.
- The default value is
- .Sy on .
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy relatime
- and
- .Sy norelatime
- mount options.
- .It Sy reservation Ns = Ns Ar size Ns | Ns Sy none
- The minimum amount of space guaranteed to a dataset and its descendants.
- When the amount of space used is below this value, the dataset is treated as if
- it were taking up 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.
- .Pp
- This property can also be referred to by its shortened column name,
- .Sy reserv .
- .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
- Controls what is cached in the secondary cache
- .Pq L2ARC .
- If this property is set to
- .Sy all ,
- then both user data and metadata is cached.
- If this property is set to
- .Sy none ,
- then neither user data nor metadata is cached.
- If this property is set to
- .Sy metadata ,
- then only metadata is cached.
- The default value is
- .Sy all .
- .It Sy prefetch Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
- Controls what speculative prefetch does.
- If this property is set to
- .Sy all ,
- then both user data and metadata are prefetched.
- If this property is set to
- .Sy none ,
- then neither user data nor metadata are prefetched.
- If this property is set to
- .Sy metadata ,
- then only metadata are prefetched.
- The default value is
- .Sy all .
- .Pp
- Please note that the module parameter zfs_prefetch_disable=1 can
- be used to totally disable speculative prefetch, bypassing anything
- this property does.
- .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
- Controls whether the setuid bit is respected for the file system.
- The default value is
- .Sy on .
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy suid
- and
- .Sy nosuid
- mount options.
- .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts
- Controls whether the file system is shared by using
- .Sy Samba USERSHARES
- and what options are to be used.
- Otherwise, the file system is automatically shared and unshared with the
- .Nm zfs Cm share
- and
- .Nm zfs Cm unshare
- commands.
- If the property is set to on, the
- .Xr net 8
- command is invoked to create a
- .Sy USERSHARE .
- .Pp
- 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
- invalid in the resource name, are replaced with underscore (_) characters.
- Linux does not currently support additional options which might be available
- on Solaris.
- .Pp
- If the
- .Sy sharesmb
- property is set to
- .Sy off ,
- the file systems are unshared.
- .Pp
- The share is created with the ACL (Access Control List) "Everyone:F" ("F"
- stands for "full permissions", i.e. read and write permissions) and no guest
- access (which means Samba must be able to authenticate a real user \(em
- .Xr passwd 5 Ns / Ns Xr shadow 5 Ns - ,
- LDAP- or
- .Xr smbpasswd 5 Ns -based )
- by default.
- This means that any additional access control
- (disallow specific user specific access etc) must be done on the underlying file
- system.
- .Pp
- When the
- .Sy sharesmb
- property is updated with
- .Nm zfs Cm set Fl u
- , the property is set to desired value, but the operation to share, reshare
- or unshare the the dataset is not performed.
- .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts
- Controls whether the file system is shared via NFS, and what options are to be
- used.
- A file system with a
- .Sy sharenfs
- property of
- .Sy off
- is managed with the
- .Xr exportfs 8
- command and entries in the
- .Pa /etc/exports
- file.
- Otherwise, the file system is automatically shared and unshared with the
- .Nm zfs Cm share
- and
- .Nm zfs Cm unshare
- commands.
- If the property is set to
- .Sy on ,
- the dataset is shared using the default options:
- .Dl sec=sys,rw,crossmnt,no_subtree_check
- .Pp
- Please note that the options are comma-separated, unlike those found in
- .Xr exports 5 .
- This is done to negate the need for quoting, as well as to make parsing
- with scripts easier.
- .Pp
- For
- .Fx ,
- there may be multiple sets of options separated by semicolon(s).
- Each set of options must apply to different hosts or networks and each
- set of options will create a separate line for
- .Xr exports 5 .
- Any semicolon separated option set that consists entirely of whitespace
- will be ignored.
- This use of semicolons is only for
- .Fx
- at this time.
- .Pp
- See
- .Xr exports 5
- for the meaning of the default options.
- Otherwise, the
- .Xr exportfs 8
- command is invoked with options equivalent to the contents of this property.
- .Pp
- When the
- .Sy sharenfs
- 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
- .Sy off ,
- or if they were shared before the property was changed.
- If the new property is
- .Sy off ,
- the file systems are unshared.
- .Pp
- When the
- .Sy sharenfs
- property is updated with
- .Nm zfs Cm set Fl u
- , the property is set to desired value, but the operation to share, reshare
- or unshare the the dataset is not performed.
- .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
- Provide a hint to ZFS about handling of synchronous requests in this dataset.
- If
- .Sy logbias
- is set to
- .Sy latency
- .Pq the default ,
- ZFS will use pool log devices
- .Pq if configured
- to handle the requests at low latency.
- If
- .Sy logbias
- is set to
- .Sy throughput ,
- ZFS will not use configured pool log devices.
- ZFS will instead optimize synchronous operations for global pool throughput and
- efficient use of resources.
- .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
- Controls whether the volume snapshot devices under
- .Pa /dev/zvol/ Ns Aq Ar pool
- are hidden or visible.
- The default value is
- .Sy hidden .
- .It Sy snapdir Ns = Ns Sy disabled Ns | Ns Sy hidden Ns | Ns Sy visible
- Controls whether the
- .Pa .zfs
- directory is disabled, hidden or visible in the root of the file system as
- discussed in the
- .Sx Snapshots
- section of
- .Xr zfsconcepts 7 .
- The default value is
- .Sy hidden .
- .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
- Controls the behavior of synchronous requests
- .Pq e.g. fsync, O_DSYNC .
- .Sy standard
- is the POSIX-specified behavior of ensuring all synchronous requests
- are written to stable storage and all devices are flushed to ensure
- data is not cached by device controllers
- .Pq this is the default .
- .Sy always
- causes every file system transaction to be written and flushed before its
- system call returns.
- This has a large performance penalty.
- .Sy disabled
- disables synchronous requests.
- File system transactions are only committed to stable storage periodically.
- This option will give the highest performance.
- However, it is very dangerous as ZFS would be ignoring the synchronous
- transaction demands of applications such as databases or NFS.
- Administrators should only use this option when the risks are understood.
- .It Sy version Ns = Ns Ar N Ns | Ns Sy current
- The on-disk version of this file system, which is independent of the pool
- version.
- This property can only be set to later supported versions.
- See the
- .Nm zfs Cm upgrade
- command.
- .It Sy volsize Ns = Ns Ar size
- For volumes, specifies the logical size of the volume.
- By default, creating a volume establishes a reservation of equal size.
- For storage pools with a version number of 9 or higher, a
- .Sy refreservation
- is set instead.
- Any changes to
- .Sy volsize
- are reflected in an equivalent change to the reservation
- .Pq or Sy refreservation .
- The
- .Sy volsize
- can only be set to a multiple of
- .Sy volblocksize ,
- and cannot be zero.
- .Pp
- The reservation is kept equal to the volume's logical size to prevent unexpected
- behavior for consumers.
- Without the reservation, the volume could run out of space, resulting 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
- .Pq particularly when shrinking the size .
- Extreme care should be used when adjusting the volume size.
- .Pp
- Though not recommended, a
- .Qq sparse volume
- .Po also known as
- .Qq thin provisioned
- .Pc
- can be created by specifying the
- .Fl s
- option to the
- .Nm zfs Cm create Fl V
- command, or by changing the value of the
- .Sy refreservation
- property
- .Po or
- .Sy reservation
- property on pool version 8 or earlier
- .Pc
- after the volume has been created.
- A
- .Qq sparse volume
- is a volume where the value of
- .Sy refreservation
- is less than the size of the volume plus the space required to store its
- metadata.
- Consequently, writes to a sparse volume can fail with
- .Er ENOSPC
- when the pool is low on space.
- For a sparse volume, changes to
- .Sy volsize
- are not reflected in the
- .Sy refreservation .
- A volume that is not sparse is said to be
- .Qq thick provisioned .
- A sparse volume can become thick provisioned by setting
- .Sy refreservation
- to
- .Sy auto .
- .It Sy volmode Ns = Ns Sy default Ns | Ns Sy full Ns | Ns Sy geom Ns | Ns Sy dev Ns | Ns Sy none
- This property specifies how volumes should be exposed to the OS.
- Setting it to
- .Sy full
- exposes volumes as fully fledged block devices, providing maximal
- functionality.
- The value
- .Sy geom
- is just an alias for
- .Sy full
- and is kept for compatibility.
- Setting it to
- .Sy dev
- hides its partitions.
- Volumes with property set to
- .Sy none
- are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
- that can be suitable for backup purposes.
- Value
- .Sy default
- means that volumes exposition is controlled by system-wide tunable
- .Sy zvol_volmode ,
- where
- .Sy full ,
- .Sy dev
- and
- .Sy none
- are encoded as 1, 2 and 3 respectively.
- The default value is
- .Sy full .
- .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
- Controls whether regular files should be scanned for viruses when a file is
- opened and closed.
- In addition to enabling this property, the virus scan service must also be
- enabled for virus scanning to occur.
- The default value is
- .Sy off .
- This property is not used by OpenZFS.
- .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy dir Ns | Ns Sy sa
- Controls whether extended attributes are enabled for this file system.
- Two styles of extended attributes are supported: either directory-based
- or system-attribute-based.
- .Pp
- Directory-based extended attributes can be enabled by setting the value to
- .Sy dir .
- This style of extended attribute imposes no practical limit
- on either the size or number of attributes which can be set on a file.
- Although under Linux the
- .Xr getxattr 2
- and
- .Xr setxattr 2
- system calls limit the maximum size to
- .Sy 64K .
- This is the most compatible
- style of extended attribute and is supported by all ZFS implementations.
- .Pp
- System-attribute-based xattrs can be enabled by setting the value to
- .Sy sa
- (default and equal to
- .Sy on
- ) .
- The key advantage of this type of xattr is improved performance.
- Storing extended attributes as system attributes
- significantly decreases the amount of disk I/O required.
- Up to
- .Sy 64K
- of data may be stored per-file in the space reserved for system attributes.
- If there is not enough space available for an extended attribute
- then it will be automatically written as a directory-based xattr.
- System-attribute-based extended attributes are not accessible
- on platforms which do not support the
- .Sy xattr Ns = Ns Sy sa
- feature.
- OpenZFS supports
- .Sy xattr Ns = Ns Sy sa
- on both
- .Fx
- and Linux.
- .Pp
- The use of system-attribute-based xattrs is strongly encouraged for users of
- SELinux or POSIX ACLs.
- Both of these features heavily rely on extended
- attributes and benefit significantly from the reduced access time.
- .Pp
- The values
- .Sy on
- and
- .Sy off
- are equivalent to the
- .Sy xattr
- and
- .Sy noxattr
- mount options.
- .It Sy jailed Ns = Ns Sy off Ns | Ns Sy on
- Controls whether the dataset is managed from a jail.
- See
- .Xr zfs-jail 8
- for more information.
- Jails are a
- .Fx
- feature and this property is not available on other platforms.
- .It Sy zoned Ns = Ns Sy off Ns | Ns Sy on
- Controls whether the dataset is managed from a non-global zone or namespace.
- See
- .Xr zfs-zone 8
- for more information.
- Zoning is a
- Linux
- feature and this property is not available on other platforms.
- .El
- .Pp
- The following three properties cannot be changed after the file system is
- created, and therefore, should be set when the file system is created.
- If the properties are not set with the
- .Nm zfs Cm create
- or
- .Nm zpool Cm create
- commands, these properties are inherited from the parent dataset.
- If the parent dataset lacks these properties due to having been created prior to
- these features being supported, the new file system will have the default values
- for these properties.
- .Bl -tag -width ""
- .It Xo
- .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
- .Sy insensitive Ns | Ns Sy mixed
- .Xc
- Indicates whether the file name matching algorithm used by the file system
- should be case-sensitive, case-insensitive, or allow a combination of both
- styles of matching.
- The default value for the
- .Sy casesensitivity
- property is
- .Sy sensitive .
- Traditionally,
- .Ux
- and POSIX file systems have case-sensitive file names.
- .Pp
- The
- .Sy mixed
- value for the
- .Sy casesensitivity
- property indicates that 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 SMB server product.
- For more information about the
- .Sy mixed
- value behavior, see the "ZFS Administration Guide".
- .It Xo
- .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
- .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
- .Xc
- Indicates whether the file system should perform a
- .Sy 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
- .Sy none ,
- and the
- .Sy utf8only
- property was left unspecified, the
- .Sy utf8only
- property is automatically set to
- .Sy on .
- The default value of the
- .Sy normalization
- property is
- .Sy none .
- This property cannot be changed after the file system is created.
- .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
- Indicates whether the file system should reject file names that include
- characters that are not present in the
- .Sy UTF-8
- character code set.
- If this property is explicitly set to
- .Sy off ,
- the normalization property must either not be explicitly set or be set to
- .Sy none .
- The default value for the
- .Sy utf8only
- property is
- .Sy off .
- This property cannot be changed after the file system is created.
- .El
- .Pp
- The
- .Sy casesensitivity ,
- .Sy normalization ,
- and
- .Sy utf8only
- properties are also new permissions that can be assigned to non-privileged users
- by using the ZFS delegated administration feature.
- .
- .Ss Temporary Mount Point Properties
- When a file system is mounted, either through
- .Xr mount 8
- for legacy mounts or the
- .Nm zfs Cm mount
- command for normal file systems, its mount options are set according to its
- properties.
- The correlation between properties and mount options is as follows:
- .Bl -tag -compact -offset Ds -width "rootcontext="
- .It Sy atime
- atime/noatime
- .It Sy canmount
- auto/noauto
- .It Sy devices
- dev/nodev
- .It Sy exec
- exec/noexec
- .It Sy readonly
- ro/rw
- .It Sy relatime
- relatime/norelatime
- .It Sy setuid
- suid/nosuid
- .It Sy xattr
- xattr/noxattr
- .It Sy nbmand
- mand/nomand
- .It Sy context Ns =
- context=
- .It Sy fscontext Ns =
- fscontext=
- .It Sy defcontext Ns =
- defcontext=
- .It Sy rootcontext Ns =
- rootcontext=
- .El
- .Pp
- In addition, these options can be set on a per-mount basis using the
- .Fl o
- option, without affecting the property that is stored on disk.
- The values specified on the command line override the values stored in the
- dataset.
- The
- .Sy nosuid
- option is an alias for
- .Sy nodevices , Ns Sy nosetuid .
- These properties are reported as
- .Qq temporary
- by the
- .Nm zfs Cm get
- command.
- If the properties are changed while the dataset is mounted, the new setting
- overrides any temporary settings.
- .
- .Ss User Properties
- In addition to the standard native properties, ZFS supports arbitrary user
- properties.
- User properties have no effect on ZFS behavior, but applications or
- administrators can use them to annotate datasets
- .Pq file systems, volumes, and snapshots .
- .Pp
- User property names must contain a colon
- .Pq Qq Sy \&:
- character to distinguish them from native properties.
- They may contain lowercase letters, numbers, and the following punctuation
- characters: colon
- .Pq Qq Sy \&: ,
- dash
- .Pq Qq Sy - ,
- period
- .Pq Qq Sy \&. ,
- and underscore
- .Pq Qq Sy _ .
- The expected convention is that the property name is divided into two portions
- such as
- .Ar module : Ns Ar property ,
- but this namespace is not enforced by ZFS.
- User property names can be at most 256 characters, and cannot begin with a dash
- .Pq Qq Sy - .
- .Pp
- When making programmatic use of user properties, it is strongly suggested to use
- a reversed DNS domain name for the
- .Ar module
- component of property names to reduce the chance that two
- independently-developed packages use the same property name for different
- purposes.
- .Pp
- The values of user properties are arbitrary strings, are always inherited, and
- are never validated.
- All of the commands that operate on properties
- .Po Nm zfs Cm list ,
- .Nm zfs Cm get ,
- .Nm zfs Cm set ,
- and so forth
- .Pc
- can be used to manipulate both native properties and user properties.
- Use the
- .Nm zfs Cm inherit
- command to clear a user property.
- If the property is not defined in any parent dataset, it is removed entirely.
- Property values are limited to 8192 bytes.