| .\" |
| .\" 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 http://www.opensolaris.org/os/licensing. |
| .\" 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 July 21, 2022 |
| .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, 1.5g, 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 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 8 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 |
| .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 , |
| and |
| .Sy edonr |
| checksum algorithms require enabling the appropriate features on the pool. |
| .Fx |
| does not support the |
| .Sy edonr |
| algorithm. |
| .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 |
| Setting compression to |
| .Sy on |
| 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 [1-9,10,20,30,...,100,500,1000] which maps to a negative |
| .Sy zstd |
| level. |
| The lower the level the faster the compression - |
| .Ar 1000 No provides the fastest compression and lowest compression ratio. |
| .Sy zstd-fast |
| is equivalent to |
| .Sy zstd-fast-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 |
| Any block being compressed must be no larger than 7/8 of its original size |
| after compression, otherwise the compression will not be considered worthwhile |
| and the block saved uncompressed. |
| Note that when the logical block is less than |
| 8 times the disk sector size this effectively reduces the necessary compression |
| ratio; for example, 8kB blocks on disks with 4kB disk sectors must compress to 1/2 |
| or less of their original size. |
| .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 |
| .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 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 Em </absolute/file/path> Ns | Ns Sy https:// Ns Em <address> | Ns Sy http:// Ns Em <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 |
| .Ev SSL_CA_CERT_FILE |
| environment variable can be set to set the location |
| of the concatenated certificate store. |
| The |
| .Ev SSL_CA_CERT_PATH |
| environment variable can be set to override the location |
| of the directory containing the certificate authority bundle. |
| The |
| .Ev SSL_CLIENT_CERT_FILE |
| and |
| .Ev 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 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 512B up to 1M. |
| 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 , |
| or if they were mounted before the property was changed. |
| In addition, any shared file systems are unshared and shared in the new |
| location. |
| .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 . |
| This is used for SMB clients. |
| Changes to this property only take effect when the file system is umounted and |
| remounted. |
| Support for these locks is scarce and not described by POSIX. |
| .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 512B |
| and less than or equal to |
| .Ar 128kB . |
| If the |
| .Sy large_blocks |
| feature is enabled on the pool, the size may be up to |
| .Ar 1MB . |
| See |
| .Xr zpool-features 7 |
| for details on ZFS feature flags. |
| .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 off . |
| 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 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, system |
| passwd/shadow, LDAP or smbpasswd based) by default. |
| This means that any additional access control |
| (disallow specific user specific access etc) must be done on the underlying file system. |
| .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 |
| 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. |
| .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 hidden Ns | Ns Sy visible |
| Controls whether the |
| .Pa .zfs |
| directory is 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 on Linux. |
| .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off 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 |
| The default value of |
| .Sy on |
| enables directory based extended attributes. |
| 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 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 . |
| The key advantage of this type of xattr is improved performance. |
| Storing extended attributes as system attributes |
| significantly decreases the amount of disk IO required. |
| Up to 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. |
| .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 are not relevant on other platforms. |
| The default value is |
| .Sy off . |
| .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether the dataset is managed from a non-global zone. |
| Zones are a Solaris feature and are not relevant on other platforms. |
| The default value is |
| .Sy off . |
| .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. |