xref: /freebsd/sys/contrib/openzfs/man/man7/zfsprops.7 (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
1.\"
2.\" CDDL HEADER START
3.\"
4.\" The contents of this file are subject to the terms of the
5.\" Common Development and Distribution License (the "License").
6.\" You may not use this file except in compliance with the License.
7.\"
8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9.\" or http://www.opensolaris.org/os/licensing.
10.\" See the License for the specific language governing permissions
11.\" and limitations under the License.
12.\"
13.\" When distributing Covered Code, include this CDDL HEADER in each
14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15.\" If applicable, add the following below this CDDL HEADER, with the
16.\" fields enclosed by brackets "[]" replaced with your own identifying
17.\" information: Portions Copyright [yyyy] [name of copyright owner]
18.\"
19.\" CDDL HEADER END
20.\"
21.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
22.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
23.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
24.\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
25.\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
26.\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org>
27.\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org>
28.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
29.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
30.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
31.\" Copyright (c) 2014 Integros [integros.com]
32.\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved.
33.\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org>
34.\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved.
35.\" Copyright 2019 Richard Laager. All rights reserved.
36.\" Copyright 2018 Nexenta Systems, Inc.
37.\" Copyright 2019 Joyent, Inc.
38.\" Copyright (c) 2019, Kjeld Schouten-Lebbing
39.\"
40.Dd May 24, 2021
41.Dt ZFSPROPS 7
42.Os
43.
44.Sh NAME
45.Nm zfsprops
46.Nd native and user-defined properties of ZFS datasets
47.
48.Sh DESCRIPTION
49Properties are divided into two types, native properties and user-defined
50.Po or
51.Qq user
52.Pc
53properties.
54Native properties either export internal statistics or control ZFS behavior.
55In addition, native properties are either editable or read-only.
56User properties have no effect on ZFS behavior, but you can use them to annotate
57datasets in a way that is meaningful in your environment.
58For more information about user properties, see the
59.Sx User Properties
60section, below.
61.
62.Ss Native Properties
63Every dataset has a set of properties that export statistics about the dataset
64as well as control various behaviors.
65Properties are inherited from the parent unless overridden by the child.
66Some properties apply only to certain types of datasets
67.Pq file systems, volumes, or snapshots .
68.Pp
69The values of numeric properties can be specified using human-readable suffixes
70.Po for example,
71.Sy k ,
72.Sy KB ,
73.Sy M ,
74.Sy Gb ,
75and so forth, up to
76.Sy Z
77for zettabyte
78.Pc .
79The following are all valid
80.Pq and equal
81specifications:
82.Li 1536M, 1.5g, 1.50GB .
83.Pp
84The values of non-numeric properties are case sensitive and must be lowercase,
85except for
86.Sy mountpoint ,
87.Sy sharenfs ,
88and
89.Sy sharesmb .
90.Pp
91The following native properties consist of read-only statistics about the
92dataset.
93These properties can be neither set, nor inherited.
94Native properties apply to all dataset types unless otherwise noted.
95.Bl -tag -width "usedbyrefreservation"
96.It Sy available
97The amount of space available to the dataset and all its children, assuming that
98there is no other activity in the pool.
99Because space is shared within a pool, availability can be limited by any number
100of factors, including physical pool size, quotas, reservations, or other
101datasets within the pool.
102.Pp
103This property can also be referred to by its shortened column name,
104.Sy avail .
105.It Sy compressratio
106For non-snapshots, the compression ratio achieved for the
107.Sy used
108space of this dataset, expressed as a multiplier.
109The
110.Sy used
111property includes descendant datasets, and, for clones, does not include the
112space shared with the origin snapshot.
113For snapshots, the
114.Sy compressratio
115is the same as the
116.Sy refcompressratio
117property.
118Compression can be turned on by running:
119.Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
120The default value is
121.Sy off .
122.It Sy createtxg
123The transaction group (txg) in which the dataset was created.
124Bookmarks have the same
125.Sy createtxg
126as the snapshot they are initially tied to.
127This property is suitable for ordering a list of snapshots,
128e.g. for incremental send and receive.
129.It Sy creation
130The time this dataset was created.
131.It Sy clones
132For snapshots, this property is a comma-separated list of filesystems or volumes
133which are clones of this snapshot.
134The clones'
135.Sy origin
136property is this snapshot.
137If the
138.Sy clones
139property is not empty, then this snapshot can not be destroyed
140.Po even with the
141.Fl r
142or
143.Fl f
144options
145.Pc .
146The roles of origin and clone can be swapped by promoting the clone with the
147.Nm zfs Cm promote
148command.
149.It Sy defer_destroy
150This property is
151.Sy on
152if the snapshot has been marked for deferred destroy by using the
153.Nm zfs Cm destroy Fl d
154command.
155Otherwise, the property is
156.Sy off .
157.It Sy encryptionroot
158For encrypted datasets, indicates where the dataset is currently inheriting its
159encryption key from.
160Loading or unloading a key for the
161.Sy encryptionroot
162will implicitly load / unload the key for any inheriting datasets (see
163.Nm zfs Cm load-key
164and
165.Nm zfs Cm unload-key
166for details).
167Clones will always share an
168encryption key with their origin.
169See the
170.Sx Encryption
171section of
172.Xr zfs-load-key 8
173for details.
174.It Sy filesystem_count
175The total number of filesystems and volumes that exist under this location in
176the dataset tree.
177This value is only available when a
178.Sy filesystem_limit
179has been set somewhere in the tree under which the dataset resides.
180.It Sy keystatus
181Indicates if an encryption key is currently loaded into ZFS.
182The possible values are
183.Sy none ,
184.Sy available ,
185and
186.Sy unavailable .
187See
188.Nm zfs Cm load-key
189and
190.Nm zfs Cm unload-key .
191.It Sy guid
192The 64 bit GUID of this dataset or bookmark which does not change over its
193entire lifetime.
194When a snapshot is sent to another pool, the received snapshot has the same GUID.
195Thus, the
196.Sy guid
197is suitable to identify a snapshot across pools.
198.It Sy logicalreferenced
199The amount of space that is
200.Qq logically
201accessible by this dataset.
202See the
203.Sy referenced
204property.
205The logical space ignores the effect of the
206.Sy compression
207and
208.Sy copies
209properties, giving a quantity closer to the amount of data that applications
210see.
211However, it does include space consumed by metadata.
212.Pp
213This property can also be referred to by its shortened column name,
214.Sy lrefer .
215.It Sy logicalused
216The amount of space that is
217.Qq logically
218consumed by this dataset and all its descendents.
219See the
220.Sy used
221property.
222The logical space ignores the effect of the
223.Sy compression
224and
225.Sy copies
226properties, giving a quantity closer to the amount of data that applications
227see.
228However, it does include space consumed by metadata.
229.Pp
230This property can also be referred to by its shortened column name,
231.Sy lused .
232.It Sy mounted
233For file systems, indicates whether the file system is currently mounted.
234This property can be either
235.Sy yes
236or
237.Sy no .
238.It Sy objsetid
239A unique identifier for this dataset within the pool.
240Unlike the dataset's
241.Sy guid , No the Sy objsetid
242of a dataset is not transferred to other pools when the snapshot is copied
243with a send/receive operation.
244The
245.Sy objsetid
246can be reused (for a new dataset) after the dataset is deleted.
247.It Sy origin
248For cloned file systems or volumes, the snapshot from which the clone was
249created.
250See also the
251.Sy clones
252property.
253.It Sy receive_resume_token
254For filesystems or volumes which have saved partially-completed state from
255.Nm zfs Cm receive Fl s ,
256this opaque token can be provided to
257.Nm zfs Cm send Fl t
258to resume and complete the
259.Nm zfs Cm receive .
260.It Sy redact_snaps
261For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
262list for.
263For snapshots, this is the list of snapshot guids the snapshot is redacted with
264respect to.
265.It Sy referenced
266The amount of data that is accessible by this dataset, which may or may not be
267shared with other datasets in the pool.
268When a snapshot or clone is created, it initially references the same amount of
269space as the file system or snapshot it was created from, since its contents are
270identical.
271.Pp
272This property can also be referred to by its shortened column name,
273.Sy refer .
274.It Sy refcompressratio
275The compression ratio achieved for the
276.Sy referenced
277space of this dataset, expressed as a multiplier.
278See also the
279.Sy compressratio
280property.
281.It Sy snapshot_count
282The total number of snapshots that exist under this location in the dataset
283tree.
284This value is only available when a
285.Sy snapshot_limit
286has been set somewhere in the tree under which the dataset resides.
287.It Sy type
288The type of dataset:
289.Sy filesystem ,
290.Sy volume ,
291.Sy snapshot ,
292or
293.Sy bookmark .
294.It Sy used
295The amount of space consumed by this dataset and all its descendents.
296This is the value that is checked against this dataset's quota and reservation.
297The space used does not include this dataset's reservation, but does take into
298account the reservations of any descendent datasets.
299The amount of space that a dataset consumes from its parent, as well as the
300amount of space that is freed if this dataset is recursively destroyed, is the
301greater of its space used and its reservation.
302.Pp
303The used space of a snapshot
304.Po see the
305.Sx Snapshots
306section of
307.Xr zfsconcepts 7
308.Pc
309is space that is referenced exclusively by this snapshot.
310If this snapshot is destroyed, the amount of
311.Sy used
312space will be freed.
313Space that is shared by multiple snapshots isn't accounted for in this metric.
314When a snapshot is destroyed, space that was previously shared with this
315snapshot can become unique to snapshots adjacent to it, thus changing the used
316space of those snapshots.
317The used space of the latest snapshot can also be affected by changes in the
318file system.
319Note that the
320.Sy used
321space of a snapshot is a subset of the
322.Sy written
323space of the snapshot.
324.Pp
325The amount of space used, available, or referenced does not take into account
326pending changes.
327Pending changes are generally accounted for within a few seconds.
328Committing a change to a disk using
329.Xr fsync 2
330or
331.Sy O_SYNC
332does not necessarily guarantee that the space usage information is updated
333immediately.
334.It Sy usedby*
335The
336.Sy usedby*
337properties decompose the
338.Sy used
339properties into the various reasons that space is used.
340Specifically,
341.Sy used No =
342.Sy usedbychildren No +
343.Sy usedbydataset No +
344.Sy usedbyrefreservation No +
345.Sy usedbysnapshots .
346These properties are only available for datasets created on
347.Nm zpool
348.Qo version 13 Qc
349pools.
350.It Sy usedbychildren
351The amount of space used by children of this dataset, which would be freed if
352all the dataset's children were destroyed.
353.It Sy usedbydataset
354The amount of space used by this dataset itself, which would be freed if the
355dataset were destroyed
356.Po after first removing any
357.Sy refreservation
358and destroying any necessary snapshots or descendents
359.Pc .
360.It Sy usedbyrefreservation
361The amount of space used by a
362.Sy refreservation
363set on this dataset, which would be freed if the
364.Sy refreservation
365was removed.
366.It Sy usedbysnapshots
367The amount of space consumed by snapshots of this dataset.
368In particular, it is the amount of space that would be freed if all of this
369dataset's snapshots were destroyed.
370Note that this is not simply the sum of the snapshots'
371.Sy used
372properties because space can be shared by multiple snapshots.
373.It Sy userused Ns @ Ns Ar user
374The amount of space consumed by the specified user in this dataset.
375Space is charged to the owner of each file, as displayed by
376.Nm ls Fl l .
377The amount of space charged is displayed by
378.Nm du No and Nm ls Fl s .
379See the
380.Nm zfs Cm userspace
381command for more information.
382.Pp
383Unprivileged users can access only their own space usage.
384The root user, or a user who has been granted the
385.Sy userused
386privilege with
387.Nm zfs Cm allow ,
388can access everyone's usage.
389.Pp
390The
391.Sy userused Ns @ Ns Ar ...
392properties are not displayed by
393.Nm zfs Cm get Sy all .
394The user's name must be appended after the
395.Sy @
396symbol, using one of the following forms:
397.Bl -bullet -compact -offset 4n
398.It
399POSIX name
400.Pq Qq joe
401.It
402POSIX numeric ID
403.Pq Qq 789
404.It
405SID name
406.Pq Qq joe.smith@mydomain
407.It
408SID numeric ID
409.Pq Qq S-1-123-456-789
410.El
411.Pp
412Files created on Linux always have POSIX owners.
413.It Sy userobjused Ns @ Ns Ar user
414The
415.Sy userobjused
416property is similar to
417.Sy userused
418but instead it counts the number of objects consumed by a user.
419This property counts all objects allocated on behalf of the user,
420it may differ from the results of system tools such as
421.Nm df Fl i .
422.Pp
423When the property
424.Sy xattr Ns = Ns Sy on
425is set on a file system additional objects will be created per-file to store
426extended attributes.
427These additional objects are reflected in the
428.Sy userobjused
429value and are counted against the user's
430.Sy userobjquota .
431When a file system is configured to use
432.Sy xattr Ns = Ns Sy sa
433no additional internal objects are normally required.
434.It Sy userrefs
435This property is set to the number of user holds on this snapshot.
436User holds are set by using the
437.Nm zfs Cm hold
438command.
439.It Sy groupused Ns @ Ns Ar group
440The amount of space consumed by the specified group in this dataset.
441Space is charged to the group of each file, as displayed by
442.Nm ls Fl l .
443See the
444.Sy userused Ns @ Ns Ar user
445property for more information.
446.Pp
447Unprivileged users can only access their own groups' space usage.
448The root user, or a user who has been granted the
449.Sy groupused
450privilege with
451.Nm zfs Cm allow ,
452can access all groups' usage.
453.It Sy groupobjused Ns @ Ns Ar group
454The number of objects consumed by the specified group in this dataset.
455Multiple objects may be charged to the group for each file when extended
456attributes are in use.
457See the
458.Sy userobjused Ns @ Ns Ar user
459property for more information.
460.Pp
461Unprivileged users can only access their own groups' space usage.
462The root user, or a user who has been granted the
463.Sy groupobjused
464privilege with
465.Nm zfs Cm allow ,
466can access all groups' usage.
467.It Sy projectused Ns @ Ns Ar project
468The amount of space consumed by the specified project in this dataset.
469Project is identified via the project identifier (ID) that is object-based
470numeral attribute.
471An object can inherit the project ID from its parent object (if the
472parent has the flag of inherit project ID that can be set and changed via
473.Nm chattr Fl /+P
474or
475.Nm zfs project Fl s )
476when being created.
477The privileged user can set and change object's project
478ID via
479.Nm chattr Fl p
480or
481.Nm zfs project Fl s
482anytime.
483Space is charged to the project of each file, as displayed by
484.Nm lsattr Fl p
485or
486.Nm zfs project .
487See the
488.Sy userused Ns @ Ns Ar user
489property for more information.
490.Pp
491The root user, or a user who has been granted the
492.Sy projectused
493privilege with
494.Nm zfs allow ,
495can access all projects' usage.
496.It Sy projectobjused Ns @ Ns Ar project
497The
498.Sy projectobjused
499is similar to
500.Sy projectused
501but instead it counts the number of objects consumed by project.
502When the property
503.Sy xattr Ns = Ns Sy on
504is set on a fileset, ZFS will create additional objects per-file to store
505extended attributes.
506These additional objects are reflected in the
507.Sy projectobjused
508value and are counted against the project's
509.Sy projectobjquota .
510When a filesystem is configured to use
511.Sy xattr Ns = Ns Sy sa
512no additional internal objects are required.
513See the
514.Sy userobjused Ns @ Ns Ar user
515property for more information.
516.Pp
517The root user, or a user who has been granted the
518.Sy projectobjused
519privilege with
520.Nm zfs allow ,
521can access all projects' objects usage.
522.It Sy volblocksize
523For volumes, specifies the block size of the volume.
524The
525.Sy blocksize
526cannot be changed once the volume has been written, so it should be set at
527volume creation time.
528The default
529.Sy blocksize
530for volumes is 16 Kbytes.
531Any power of 2 from 512 bytes to 128 Kbytes is valid.
532.Pp
533This property can also be referred to by its shortened column name,
534.Sy volblock .
535.It Sy written
536The amount of space
537.Sy referenced
538by this dataset, that was written since the previous snapshot
539.Pq i.e. that is not referenced by the previous snapshot .
540.It Sy written Ns @ Ns Ar snapshot
541The amount of
542.Sy referenced
543space written to this dataset since the specified snapshot.
544This is the space that is referenced by this dataset but was not referenced by
545the specified snapshot.
546.Pp
547The
548.Ar snapshot
549may be specified as a short snapshot name
550.Pq just the part after the Sy @ ,
551in which case it will be interpreted as a snapshot in the same filesystem as
552this dataset.
553The
554.Ar snapshot
555may be a full snapshot name
556.Pq Ar filesystem Ns @ Ns Ar snapshot ,
557which for clones may be a snapshot in the origin's filesystem
558.Pq or the origin of the origin's filesystem, etc.
559.El
560.Pp
561The following native properties can be used to change the behavior of a ZFS
562dataset.
563.Bl -tag -width ""
564.It Xo
565.Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
566.Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
567.Xc
568Controls how ACEs are inherited when files and directories are created.
569.Bl -tag -compact -offset 4n -width "passthrough-x"
570.It Sy discard
571does not inherit any ACEs.
572.It Sy noallow
573only inherits inheritable ACEs that specify
574.Qq deny
575permissions.
576.It Sy restricted
577default, removes the
578.Sy write_acl
579and
580.Sy write_owner
581permissions when the ACE is inherited.
582.It Sy passthrough
583inherits all inheritable ACEs without any modifications.
584.It Sy passthrough-x
585same meaning as
586.Sy passthrough ,
587except that the
588.Sy owner@ , group@ , No and Sy everyone@
589ACEs inherit the execute permission only if the file creation mode also requests
590the execute bit.
591.El
592.Pp
593When the property value is set to
594.Sy passthrough ,
595files are created with a mode determined by the inheritable ACEs.
596If no inheritable ACEs exist that affect the mode, then the mode is set in
597accordance to the requested mode from the application.
598.Pp
599The
600.Sy aclinherit
601property does not apply to POSIX ACLs.
602.It Xo
603.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
604.Sy passthrough Ns | Ns Sy restricted Ns
605.Xc
606Controls how an ACL is modified during chmod(2) and how inherited ACEs
607are modified by the file creation mode:
608.Bl -tag -compact -offset 4n -width "passthrough"
609.It Sy discard
610default, deletes all
611.Sy ACEs
612except for those representing
613the mode of the file or directory requested by
614.Xr chmod 2 .
615.It Sy groupmask
616reduces permissions granted in all
617.Sy ALLOW
618entries found in the
619.Sy ACL
620such that they are no greater than the group permissions specified by
621.Xr chmod 2 .
622.It Sy passthrough
623indicates that no changes are made to the ACL other than creating or updating
624the necessary ACL entries to represent the new mode of the file or directory.
625.It Sy restricted
626will cause the
627.Xr chmod 2
628operation to return an error when used on any file or directory which has
629a non-trivial ACL whose entries can not be represented by a mode.
630.Xr chmod 2
631is required to change the set user ID, set group ID, or sticky bits on a file
632or directory, as they do not have equivalent ACL entries.
633In order to use
634.Xr chmod 2
635on a file or directory with a non-trivial ACL when
636.Sy aclmode
637is set to
638.Sy restricted ,
639you must first remove all ACL entries which do not represent the current mode.
640.El
641.It Sy acltype Ns = Ns Sy off Ns | Ns Sy nfsv4 Ns | Ns Sy posix
642Controls whether ACLs are enabled and if so what type of ACL to use.
643When this property is set to a type of ACL not supported by the current
644platform, the behavior is the same as if it were set to
645.Sy off .
646.Bl -tag -compact -offset 4n -width "posixacl"
647.It Sy off
648default on Linux, when a file system has the
649.Sy acltype
650property set to off then ACLs are disabled.
651.It Sy noacl
652an alias for
653.Sy off
654.It Sy nfsv4
655default on
656.Fx ,
657indicates that NFSv4-style ZFS ACLs should be used.
658These ACLs can be managed with the
659.Xr getfacl 1
660and
661.Xr setfacl 1 .
662The
663.Sy nfsv4
664ZFS ACL type is not yet supported on Linux.
665.It Sy posix
666indicates POSIX ACLs should be used.
667POSIX ACLs are specific to Linux and are not functional on other platforms.
668POSIX ACLs are stored as an extended
669attribute and therefore will not overwrite any existing NFSv4 ACLs which
670may be set.
671.It Sy posixacl
672an alias for
673.Sy posix
674.El
675.Pp
676To obtain the best performance when setting
677.Sy posix
678users are strongly encouraged to set the
679.Sy xattr Ns = Ns Sy sa
680property.
681This will result in the POSIX ACL being stored more efficiently on disk.
682But as a consequence, all new extended attributes will only be
683accessible from OpenZFS implementations which support the
684.Sy xattr Ns = Ns Sy sa
685property.
686See the
687.Sy xattr
688property for more details.
689.It Sy atime Ns = Ns Sy on Ns | Ns Sy off
690Controls whether the access time for files is updated when they are read.
691Turning this property off avoids producing write traffic when reading files and
692can result in significant performance gains, though it might confuse mailers
693and other similar utilities.
694The values
695.Sy on
696and
697.Sy off
698are equivalent to the
699.Sy atime
700and
701.Sy noatime
702mount options.
703The default value is
704.Sy on .
705See also
706.Sy relatime
707below.
708.It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
709If this property is set to
710.Sy off ,
711the file system cannot be mounted, and is ignored by
712.Nm zfs Cm mount Fl a .
713Setting this property to
714.Sy off
715is similar to setting the
716.Sy mountpoint
717property to
718.Sy none ,
719except that the dataset still has a normal
720.Sy mountpoint
721property, which can be inherited.
722Setting this property to
723.Sy off
724allows datasets to be used solely as a mechanism to inherit properties.
725One example of setting
726.Sy canmount Ns = Ns Sy off
727is to have two datasets with the same
728.Sy mountpoint ,
729so that the children of both datasets appear in the same directory, but might
730have different inherited characteristics.
731.Pp
732When set to
733.Sy noauto ,
734a dataset can only be mounted and unmounted explicitly.
735The dataset is not mounted automatically when the dataset is created or
736imported, nor is it mounted by the
737.Nm zfs Cm mount Fl a
738command or unmounted by the
739.Nm zfs Cm unmount Fl a
740command.
741.Pp
742This property is not inherited.
743.It Xo
744.Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
745.Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
746.Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
747.Xc
748Controls the checksum used to verify data integrity.
749The default value is
750.Sy on ,
751which automatically selects an appropriate algorithm
752.Po currently,
753.Sy fletcher4 ,
754but this may change in future releases
755.Pc .
756The value
757.Sy off
758disables integrity checking on user data.
759The value
760.Sy noparity
761not only disables integrity but also disables maintaining parity for user data.
762This setting is used internally by a dump device residing on a RAID-Z pool and
763should not be used by any other dataset.
764Disabling checksums is
765.Em NOT
766a recommended practice.
767.Pp
768The
769.Sy sha512 ,
770.Sy skein ,
771and
772.Sy edonr
773checksum algorithms require enabling the appropriate features on the pool.
774.Fx
775does not support the
776.Sy edonr
777algorithm.
778.Pp
779Please see
780.Xr zpool-features 7
781for more information on these algorithms.
782.Pp
783Changing this property affects only newly-written data.
784.It Xo
785.Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
786.Sy gzip- Ns Ar N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns
787.Sy zstd- Ns Ar N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Ar N
788.Xc
789Controls the compression algorithm used for this dataset.
790.Pp
791Setting compression to
792.Sy on
793indicates that the current default compression algorithm should be used.
794The default balances compression and decompression speed, with compression ratio
795and is expected to work well on a wide variety of workloads.
796Unlike all other settings for this property,
797.Sy on
798does not select a fixed compression type.
799As new compression algorithms are added to ZFS and enabled on a pool, the
800default compression algorithm may change.
801The current default compression algorithm is either
802.Sy lzjb
803or, if the
804.Sy lz4_compress
805feature is enabled,
806.Sy lz4 .
807.Pp
808The
809.Sy lz4
810compression algorithm is a high-performance replacement for the
811.Sy lzjb
812algorithm.
813It features significantly faster compression and decompression, as well as a
814moderately higher compression ratio than
815.Sy lzjb ,
816but can only be used on pools with the
817.Sy lz4_compress
818feature set to
819.Sy enabled .
820See
821.Xr zpool-features 7
822for details on ZFS feature flags and the
823.Sy lz4_compress
824feature.
825.Pp
826The
827.Sy lzjb
828compression algorithm is optimized for performance while providing decent data
829compression.
830.Pp
831The
832.Sy gzip
833compression algorithm uses the same compression as the
834.Xr gzip 1
835command.
836You can specify the
837.Sy gzip
838level by using the value
839.Sy gzip- Ns Ar N ,
840where
841.Ar N
842is an integer from 1
843.Pq fastest
844to 9
845.Pq best compression ratio .
846Currently,
847.Sy gzip
848is equivalent to
849.Sy gzip-6
850.Po which is also the default for
851.Xr gzip 1
852.Pc .
853.Pp
854The
855.Sy zstd
856compression algorithm provides both high compression ratios and good performance.
857You can specify the
858.Sy zstd
859level by using the value
860.Sy zstd- Ns Ar N ,
861where
862.Ar N
863is an integer from 1
864.Pq fastest
865to 19
866.Pq best compression ratio .
867.Sy zstd
868is equivalent to
869.Sy zstd-3 .
870.Pp
871Faster speeds at the cost of the compression ratio can be requested by
872setting a negative
873.Sy zstd
874level.
875This is done using
876.Sy zstd-fast- Ns Ar N ,
877where
878.Ar N
879is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative
880.Sy zstd
881level.
882The lower the level the faster the compression -
883.Ar 1000 No provides the fastest compression and lowest compression ratio.
884.Sy zstd-fast
885is equivalent to
886.Sy zstd-fast-1 .
887.Pp
888The
889.Sy zle
890compression algorithm compresses runs of zeros.
891.Pp
892This property can also be referred to by its shortened column name
893.Sy compress .
894Changing this property affects only newly-written data.
895.Pp
896When any setting except
897.Sy off
898is selected, compression will explicitly check for blocks consisting of only
899zeroes (the NUL byte).
900When a zero-filled block is detected, it is stored as
901a hole and not compressed using the indicated compression algorithm.
902.Pp
903Any block being compressed must be no larger than 7/8 of its original size
904after compression, otherwise the compression will not be considered worthwhile
905and the block saved uncompressed.
906Note that when the logical block is less than
9078 times the disk sector size this effectively reduces the necessary compression
908ratio; for example, 8kB blocks on disks with 4kB disk sectors must compress to 1/2
909or less of their original size.
910.It Xo
911.Sy context Ns = Ns Sy none Ns | Ns
912.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level
913.Xc
914This flag sets the SELinux context for all files in the file system under
915a mount point for that file system.
916See
917.Xr selinux 8
918for more information.
919.It Xo
920.Sy fscontext Ns = Ns Sy none Ns | Ns
921.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level
922.Xc
923This flag sets the SELinux context for the file system file system being
924mounted.
925See
926.Xr selinux 8
927for more information.
928.It Xo
929.Sy defcontext Ns = Ns Sy none Ns | Ns
930.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level
931.Xc
932This flag sets the SELinux default context for unlabeled files.
933See
934.Xr selinux 8
935for more information.
936.It Xo
937.Sy rootcontext Ns = Ns Sy none Ns | Ns
938.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level
939.Xc
940This flag sets the SELinux context for the root inode of the file system.
941See
942.Xr selinux 8
943for more information.
944.It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
945Controls the number of copies of data stored for this dataset.
946These copies are in addition to any redundancy provided by the pool, for
947example, mirroring or RAID-Z.
948The copies are stored on different disks, if possible.
949The space used by multiple copies is charged to the associated file and dataset,
950changing the
951.Sy used
952property and counting against quotas and reservations.
953.Pp
954Changing this property only affects newly-written data.
955Therefore, set this property at file system creation time by using the
956.Fl o Sy copies Ns = Ns Ar N
957option.
958.Pp
959Remember that ZFS will not import a pool with a missing top-level vdev.
960Do
961.Em NOT
962create, for example a two-disk striped pool and set
963.Sy copies Ns = Ns Ar 2
964on some datasets thinking you have setup redundancy for them.
965When a disk fails you will not be able to import the pool
966and will have lost all of your data.
967.Pp
968Encrypted datasets may not have
969.Sy copies Ns = Ns Ar 3
970since the implementation stores some encryption metadata where the third copy
971would normally be.
972.It Sy devices Ns = Ns Sy on Ns | Ns Sy off
973Controls whether device nodes can be opened on this file system.
974The default value is
975.Sy on .
976The values
977.Sy on
978and
979.Sy off
980are equivalent to the
981.Sy dev
982and
983.Sy nodev
984mount options.
985.It Xo
986.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
987.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
988.Sy edonr , Ns Sy verify
989.Xc
990Configures deduplication for a dataset.
991The default value is
992.Sy off .
993The default deduplication checksum is
994.Sy sha256
995(this may change in the future).
996When
997.Sy dedup
998is enabled, the checksum defined here overrides the
999.Sy checksum
1000property.
1001Setting the value to
1002.Sy verify
1003has the same effect as the setting
1004.Sy sha256 , Ns Sy verify .
1005.Pp
1006If set to
1007.Sy verify ,
1008ZFS will do a byte-to-byte comparison in case of two blocks having the same
1009signature to make sure the block contents are identical.
1010Specifying
1011.Sy verify
1012is mandatory for the
1013.Sy edonr
1014algorithm.
1015.Pp
1016Unless necessary, deduplication should
1017.Em not
1018be enabled on a system.
1019See the
1020.Sx Deduplication
1021section of
1022.Xr zfsconcepts 7 .
1023.It Xo
1024.Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1025.Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1026.Xc
1027Specifies a compatibility mode or literal value for the size of dnodes in the
1028file system.
1029The default value is
1030.Sy legacy .
1031Setting this property to a value other than
1032.Sy legacy No requires the Sy large_dnode No pool feature to be enabled.
1033.Pp
1034Consider setting
1035.Sy dnodesize
1036to
1037.Sy auto
1038if the dataset uses the
1039.Sy xattr Ns = Ns Sy sa
1040property setting and the workload makes heavy use of extended attributes.
1041This
1042may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1043servers, for example.
1044Literal values are supported for cases where the optimal
1045size is known in advance and for performance testing.
1046.Pp
1047Leave
1048.Sy dnodesize
1049set to
1050.Sy legacy
1051if you need to receive a send stream of this dataset on a pool that doesn't
1052enable the
1053.Sy large_dnode
1054feature, or if you need to import this pool on a system that doesn't support the
1055.Sy large_dnode No feature.
1056.Pp
1057This property can also be referred to by its shortened column name,
1058.Sy dnsize .
1059.It Xo
1060.Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1061.Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1062.Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1063.Xc
1064Controls the encryption cipher suite (block cipher, key length, and mode) used
1065for this dataset.
1066Requires the
1067.Sy encryption
1068feature to be enabled on the pool.
1069Requires a
1070.Sy keyformat
1071to be set at dataset creation time.
1072.Pp
1073Selecting
1074.Sy encryption Ns = Ns Sy on
1075when creating a dataset indicates that the default encryption suite will be
1076selected, which is currently
1077.Sy aes-256-gcm .
1078In order to provide consistent data protection, encryption must be specified at
1079dataset creation time and it cannot be changed afterwards.
1080.Pp
1081For more details and caveats about encryption see the
1082.Sx Encryption
1083section of
1084.Xr zfs-load-key 8 .
1085.It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1086Controls what format the user's encryption key will be provided as.
1087This property is only set when the dataset is encrypted.
1088.Pp
1089Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1090encryption suite) and must be randomly generated.
1091A raw key can be generated with the following command:
1092.Dl # Nm dd Sy if=/dev/urandom bs=32 count=1 Sy of= Ns Pa /path/to/output/key
1093.Pp
1094Passphrases must be between 8 and 512 bytes long and will be processed through
1095PBKDF2 before being used (see the
1096.Sy pbkdf2iters
1097property).
1098Even though the encryption suite cannot be changed after dataset creation,
1099the keyformat can be with
1100.Nm zfs Cm change-key .
1101.It Xo
1102.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
1103.Xc
1104Controls where the user's encryption key will be loaded from by default for
1105commands such as
1106.Nm zfs Cm load-key
1107and
1108.Nm zfs Cm mount Fl l .
1109This property is only set for encrypted datasets which are encryption roots.
1110If unspecified, the default is
1111.Sy prompt .
1112.Pp
1113Even though the encryption suite cannot be changed after dataset creation, the
1114keylocation can be with either
1115.Nm zfs Cm set
1116or
1117.Nm zfs Cm change-key .
1118If
1119.Sy prompt
1120is selected ZFS will ask for the key at the command prompt when it is required
1121to access the encrypted data (see
1122.Nm zfs Cm load-key
1123for details).
1124This setting will also allow the key to be passed in via the standard input stream,
1125but users should be careful not to place keys which should be kept secret on
1126the command line.
1127If a file URI is selected, the key will be loaded from the
1128specified absolute file path.
1129If an HTTPS or HTTP URL is selected, it will be GETted using
1130.Xr fetch 3 ,
1131libcurl, or nothing, depending on compile-time configuration and run-time availability.
1132The
1133.Sy SSL_CA_CERT_FILE
1134environment variable can be set to set the location
1135of the concatenated certificate store.
1136The
1137.Sy SSL_CA_CERT_PATH
1138environment variable can be set to override the location
1139of the directory containing the certificate authority bundle.
1140The
1141.Sy SSL_CLIENT_CERT_FILE
1142and
1143.Sy SSL_CLIENT_KEY_FILE
1144environment variables can be set to configure the path
1145to the client certificate and its key.
1146.It Sy pbkdf2iters Ns = Ns Ar iterations
1147Controls the number of PBKDF2 iterations that a
1148.Sy passphrase
1149encryption key should be run through when processing it into an encryption key.
1150This property is only defined when encryption is enabled and a keyformat of
1151.Sy passphrase
1152is selected.
1153The goal of PBKDF2 is to significantly increase the
1154computational difficulty needed to brute force a user's passphrase.
1155This is accomplished by forcing the attacker to run each passphrase through a
1156computationally expensive hashing function many times before they arrive at the
1157resulting key.
1158A user who actually knows the passphrase will only have to pay this cost once.
1159As CPUs become better at processing, this number should be
1160raised to ensure that a brute force attack is still not possible.
1161The current default is
1162.Sy 350000
1163and the minimum is
1164.Sy 100000 .
1165This property may be changed with
1166.Nm zfs Cm change-key .
1167.It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1168Controls whether processes can be executed from within this file system.
1169The default value is
1170.Sy on .
1171The values
1172.Sy on
1173and
1174.Sy off
1175are equivalent to the
1176.Sy exec
1177and
1178.Sy noexec
1179mount options.
1180.It Sy filesystem_limit Ns = Ns Ar count Ns | Ns Sy none
1181Limits the number of filesystems and volumes that can exist under this point in
1182the dataset tree.
1183The limit is not enforced if the user is allowed to change the limit.
1184Setting a
1185.Sy filesystem_limit
1186to
1187.Sy on
1188a descendent of a filesystem that already has a
1189.Sy filesystem_limit
1190does not override the ancestor's
1191.Sy filesystem_limit ,
1192but rather imposes an additional limit.
1193This feature must be enabled to be used
1194.Po see
1195.Xr zpool-features 7
1196.Pc .
1197.It Sy special_small_blocks Ns = Ns Ar size
1198This value represents the threshold block size for including small file
1199blocks into the special allocation class.
1200Blocks smaller than or equal to this
1201value will be assigned to the special allocation class while greater blocks
1202will be assigned to the regular class.
1203Valid values are zero or a power of two from 512B up to 1M.
1204The default size is 0 which means no small file blocks
1205will be allocated in the special class.
1206.Pp
1207Before setting this property, a special class vdev must be added to the
1208pool.
1209See
1210.Xr zpoolconcepts 7
1211for more details on the special allocation class.
1212.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1213Controls the mount point used for this file system.
1214See the
1215.Sx Mount Points
1216section of
1217.Xr zfsconcepts 7
1218for more information on how this property is used.
1219.Pp
1220When the
1221.Sy mountpoint
1222property is changed for a file system, the file system and any children that
1223inherit the mount point are unmounted.
1224If the new value is
1225.Sy legacy ,
1226then they remain unmounted.
1227Otherwise, they are automatically remounted in the new location if the property
1228was previously
1229.Sy legacy
1230or
1231.Sy none ,
1232or if they were mounted before the property was changed.
1233In addition, any shared file systems are unshared and shared in the new
1234location.
1235.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1236Controls whether the file system should be mounted with
1237.Sy nbmand
1238.Pq Non-blocking mandatory locks .
1239This is used for SMB clients.
1240Changes to this property only take effect when the file system is umounted and
1241remounted.
1242Support for these locks is scarce and not described by POSIX.
1243.It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
1244Allow mounting on a busy directory or a directory which already contains
1245files or directories.
1246This is the default mount behavior for Linux and
1247.Fx
1248file systems.
1249On these platforms the property is
1250.Sy on
1251by default.
1252Set to
1253.Sy off
1254to disable overlay mounts for consistency with OpenZFS on other platforms.
1255.It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1256Controls what is cached in the primary cache
1257.Pq ARC .
1258If this property is set to
1259.Sy all ,
1260then both user data and metadata is cached.
1261If this property is set to
1262.Sy none ,
1263then neither user data nor metadata is cached.
1264If this property is set to
1265.Sy metadata ,
1266then only metadata is cached.
1267The default value is
1268.Sy all .
1269.It Sy quota Ns = Ns Ar size Ns | Ns Sy none
1270Limits the amount of space a dataset and its descendents can consume.
1271This property enforces a hard limit on the amount of space used.
1272This includes all space consumed by descendents, including file systems and
1273snapshots.
1274Setting a quota on a descendent of a dataset that already has a quota does not
1275override the ancestor's quota, but rather imposes an additional limit.
1276.Pp
1277Quotas cannot be set on volumes, as the
1278.Sy volsize
1279property acts as an implicit quota.
1280.It Sy snapshot_limit Ns = Ns Ar count Ns | Ns Sy none
1281Limits the number of snapshots that can be created on a dataset and its
1282descendents.
1283Setting a
1284.Sy snapshot_limit
1285on a descendent of a dataset that already has a
1286.Sy snapshot_limit
1287does not override the ancestor's
1288.Sy snapshot_limit ,
1289but rather imposes an additional limit.
1290The limit is not enforced if the user is allowed to change the limit.
1291For example, this means that recursive snapshots taken from the global zone are
1292counted against each delegated dataset within a zone.
1293This feature must be enabled to be used
1294.Po see
1295.Xr zpool-features 7
1296.Pc .
1297.It Sy userquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none
1298Limits the amount of space consumed by the specified user.
1299User space consumption is identified by the
1300.Sy userspace@ Ns Ar user
1301property.
1302.Pp
1303Enforcement of user quotas may be delayed by several seconds.
1304This delay means that a user might exceed their quota before the system notices
1305that they are over quota and begins to refuse additional writes with the
1306.Er EDQUOT
1307error message.
1308See the
1309.Nm zfs Cm userspace
1310command for more information.
1311.Pp
1312Unprivileged users can only access their own groups' space usage.
1313The root user, or a user who has been granted the
1314.Sy userquota
1315privilege with
1316.Nm zfs Cm allow ,
1317can get and set everyone's quota.
1318.Pp
1319This property is not available on volumes, on file systems before version 4, or
1320on pools before version 15.
1321The
1322.Sy userquota@ Ns Ar ...
1323properties are not displayed by
1324.Nm zfs Cm get Sy all .
1325The user's name must be appended after the
1326.Sy @
1327symbol, using one of the following forms:
1328.Bl -bullet -compact -offset 4n
1329.It
1330POSIX name
1331.Pq Qq joe
1332.It
1333POSIX numeric ID
1334.Pq Qq 789
1335.It
1336SID name
1337.Pq Qq joe.smith@mydomain
1338.It
1339SID numeric ID
1340.Pq Qq S-1-123-456-789
1341.El
1342.Pp
1343Files created on Linux always have POSIX owners.
1344.It Sy userobjquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none
1345The
1346.Sy userobjquota
1347is similar to
1348.Sy userquota
1349but it limits the number of objects a user can create.
1350Please refer to
1351.Sy userobjused
1352for more information about how objects are counted.
1353.It Sy groupquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none
1354Limits the amount of space consumed by the specified group.
1355Group space consumption is identified by the
1356.Sy groupused@ Ns Ar group
1357property.
1358.Pp
1359Unprivileged users can access only their own groups' space usage.
1360The root user, or a user who has been granted the
1361.Sy groupquota
1362privilege with
1363.Nm zfs Cm allow ,
1364can get and set all groups' quotas.
1365.It Sy groupobjquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none
1366The
1367.Sy groupobjquota
1368is similar to
1369.Sy groupquota
1370but it limits number of objects a group can consume.
1371Please refer to
1372.Sy userobjused
1373for more information about how objects are counted.
1374.It Sy projectquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none
1375Limits the amount of space consumed by the specified project.
1376Project space consumption is identified by the
1377.Sy projectused@ Ns Ar project
1378property.
1379Please refer to
1380.Sy projectused
1381for more information about how project is identified and set/changed.
1382.Pp
1383The root user, or a user who has been granted the
1384.Sy projectquota
1385privilege with
1386.Nm zfs allow ,
1387can access all projects' quota.
1388.It Sy projectobjquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none
1389The
1390.Sy projectobjquota
1391is similar to
1392.Sy projectquota
1393but it limits number of objects a project can consume.
1394Please refer to
1395.Sy userobjused
1396for more information about how objects are counted.
1397.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1398Controls whether this dataset can be modified.
1399The default value is
1400.Sy off .
1401The values
1402.Sy on
1403and
1404.Sy off
1405are equivalent to the
1406.Sy ro
1407and
1408.Sy rw
1409mount options.
1410.Pp
1411This property can also be referred to by its shortened column name,
1412.Sy rdonly .
1413.It Sy recordsize Ns = Ns Ar size
1414Specifies a suggested block size for files in the file system.
1415This property is designed solely for use with database workloads that access
1416files in fixed-size records.
1417ZFS automatically tunes block sizes according to internal algorithms optimized
1418for typical access patterns.
1419.Pp
1420For databases that create very large files but access them in small random
1421chunks, these algorithms may be suboptimal.
1422Specifying a
1423.Sy recordsize
1424greater than or equal to the record size of the database can result in
1425significant performance gains.
1426Use of this property for general purpose file systems is strongly discouraged,
1427and may adversely affect performance.
1428.Pp
1429The size specified must be a power of two greater than or equal to
1430.Ar 512B
1431and less than or equal to
1432.Ar 128kB .
1433If the
1434.Sy large_blocks
1435feature is enabled on the pool, the size may be up to
1436.Ar 1MB .
1437See
1438.Xr zpool-features 7
1439for details on ZFS feature flags.
1440.Pp
1441Changing the file system's
1442.Sy recordsize
1443affects only files created afterward; existing files are unaffected.
1444.Pp
1445This property can also be referred to by its shortened column name,
1446.Sy recsize .
1447.It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1448Controls what types of metadata are stored redundantly.
1449ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1450the amount of user data lost is limited.
1451This extra copy is in addition to any redundancy provided at the pool level
1452.Pq e.g. by mirroring or RAID-Z ,
1453and is in addition to an extra copy specified by the
1454.Sy copies
1455property
1456.Pq up to a total of 3 copies .
1457For example if the pool is mirrored,
1458.Sy copies Ns = Ns 2 ,
1459and
1460.Sy redundant_metadata Ns = Ns Sy most ,
1461then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1462metadata.
1463.Pp
1464When set to
1465.Sy all ,
1466ZFS stores an extra copy of all metadata.
1467If a single on-disk block is corrupt, at worst a single block of user data
1468.Po which is
1469.Sy recordsize
1470bytes long
1471.Pc
1472can be lost.
1473.Pp
1474When set to
1475.Sy most ,
1476ZFS stores an extra copy of most types of metadata.
1477This can improve performance of random writes, because less metadata must be
1478written.
1479In practice, at worst about 100 blocks
1480.Po of
1481.Sy recordsize
1482bytes each
1483.Pc
1484of user data can be lost if a single on-disk block is corrupt.
1485The exact behavior of which metadata blocks are stored redundantly may change in
1486future releases.
1487.Pp
1488The default value is
1489.Sy all .
1490.It Sy refquota Ns = Ns Ar size Ns | Ns Sy none
1491Limits the amount of space a dataset can consume.
1492This property enforces a hard limit on the amount of space used.
1493This hard limit does not include space used by descendents, including file
1494systems and snapshots.
1495.It Sy refreservation Ns = Ns Ar size Ns | Ns Sy none Ns | Ns Sy auto
1496The minimum amount of space guaranteed to a dataset, not including its
1497descendents.
1498When the amount of space used is below this value, the dataset is treated as if
1499it were taking up the amount of space specified by
1500.Sy refreservation .
1501The
1502.Sy refreservation
1503reservation is accounted for in the parent datasets' space used, and counts
1504against the parent datasets' quotas and reservations.
1505.Pp
1506If
1507.Sy refreservation
1508is set, a snapshot is only allowed if there is enough free pool space outside of
1509this reservation to accommodate the current number of
1510.Qq referenced
1511bytes in the dataset.
1512.Pp
1513If
1514.Sy refreservation
1515is set to
1516.Sy auto ,
1517a volume is thick provisioned
1518.Po or
1519.Qq not sparse
1520.Pc .
1521.Sy refreservation Ns = Ns Sy auto
1522is only supported on volumes.
1523See
1524.Sy volsize
1525in the
1526.Sx Native Properties
1527section for more information about sparse volumes.
1528.Pp
1529This property can also be referred to by its shortened column name,
1530.Sy refreserv .
1531.It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1532Controls the manner in which the access time is updated when
1533.Sy atime Ns = Ns Sy on
1534is set.
1535Turning this property on causes the access time to be updated relative
1536to the modify or change time.
1537Access time is only updated if the previous
1538access time was earlier than the current modify or change time or if the
1539existing access time hasn't been updated within the past 24 hours.
1540The default value is
1541.Sy off .
1542The values
1543.Sy on
1544and
1545.Sy off
1546are equivalent to the
1547.Sy relatime
1548and
1549.Sy norelatime
1550mount options.
1551.It Sy reservation Ns = Ns Ar size Ns | Ns Sy none
1552The minimum amount of space guaranteed to a dataset and its descendants.
1553When the amount of space used is below this value, the dataset is treated as if
1554it were taking up the amount of space specified by its reservation.
1555Reservations are accounted for in the parent datasets' space used, and count
1556against the parent datasets' quotas and reservations.
1557.Pp
1558This property can also be referred to by its shortened column name,
1559.Sy reserv .
1560.It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1561Controls what is cached in the secondary cache
1562.Pq L2ARC .
1563If this property is set to
1564.Sy all ,
1565then both user data and metadata is cached.
1566If this property is set to
1567.Sy none ,
1568then neither user data nor metadata is cached.
1569If this property is set to
1570.Sy metadata ,
1571then only metadata is cached.
1572The default value is
1573.Sy all .
1574.It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1575Controls whether the setuid bit is respected for the file system.
1576The default value is
1577.Sy on .
1578The values
1579.Sy on
1580and
1581.Sy off
1582are equivalent to the
1583.Sy suid
1584and
1585.Sy nosuid
1586mount options.
1587.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts
1588Controls whether the file system is shared by using
1589.Sy Samba USERSHARES
1590and what options are to be used.
1591Otherwise, the file system is automatically shared and unshared with the
1592.Nm zfs Cm share
1593and
1594.Nm zfs Cm unshare
1595commands.
1596If the property is set to on, the
1597.Xr net 8
1598command is invoked to create a
1599.Sy USERSHARE .
1600.Pp
1601Because SMB shares requires a resource name, a unique resource name is
1602constructed from the dataset name.
1603The constructed name is a copy of the
1604dataset name except that the characters in the dataset name, which would be
1605invalid in the resource name, are replaced with underscore (_) characters.
1606Linux does not currently support additional options which might be available
1607on Solaris.
1608.Pp
1609If the
1610.Sy sharesmb
1611property is set to
1612.Sy off ,
1613the file systems are unshared.
1614.Pp
1615The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1616stands for "full permissions", i.e. read and write permissions) and no guest
1617access (which means Samba must be able to authenticate a real user, system
1618passwd/shadow, LDAP or smbpasswd based) by default.
1619This means that any additional access control
1620(disallow specific user specific access etc) must be done on the underlying file system.
1621.It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts
1622Controls whether the file system is shared via NFS, and what options are to be
1623used.
1624A file system with a
1625.Sy sharenfs
1626property of
1627.Sy off
1628is managed with the
1629.Xr exportfs 8
1630command and entries in the
1631.Pa /etc/exports
1632file.
1633Otherwise, the file system is automatically shared and unshared with the
1634.Nm zfs Cm share
1635and
1636.Nm zfs Cm unshare
1637commands.
1638If the property is set to
1639.Sy on ,
1640the dataset is shared using the default options:
1641.Dl sec=sys,rw,crossmnt,no_subtree_check
1642.Pp
1643Please note that the options are comma-separated, unlike those found in
1644.Xr exports 5 .
1645This is done to negate the need for quoting, as well as to make parsing
1646with scripts easier.
1647.Pp
1648See
1649.Xr exports 5
1650for the meaning of the default options.
1651Otherwise, the
1652.Xr exportfs 8
1653command is invoked with options equivalent to the contents of this property.
1654.Pp
1655When the
1656.Sy sharenfs
1657property is changed for a dataset, the dataset and any children inheriting the
1658property are re-shared with the new options, only if the property was previously
1659.Sy off ,
1660or if they were shared before the property was changed.
1661If the new property is
1662.Sy off ,
1663the file systems are unshared.
1664.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1665Provide a hint to ZFS about handling of synchronous requests in this dataset.
1666If
1667.Sy logbias
1668is set to
1669.Sy latency
1670.Pq the default ,
1671ZFS will use pool log devices
1672.Pq if configured
1673to handle the requests at low latency.
1674If
1675.Sy logbias
1676is set to
1677.Sy throughput ,
1678ZFS will not use configured pool log devices.
1679ZFS will instead optimize synchronous operations for global pool throughput and
1680efficient use of resources.
1681.It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1682Controls whether the volume snapshot devices under
1683.Pa /dev/zvol/ Ns Aq Ar pool
1684are hidden or visible.
1685The default value is
1686.Sy hidden .
1687.It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1688Controls whether the
1689.Pa .zfs
1690directory is hidden or visible in the root of the file system as discussed in
1691the
1692.Sx Snapshots
1693section of
1694.Xr zfsconcepts 7 .
1695The default value is
1696.Sy hidden .
1697.It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1698Controls the behavior of synchronous requests
1699.Pq e.g. fsync, O_DSYNC .
1700.Sy standard
1701is the POSIX-specified behavior of ensuring all synchronous requests
1702are written to stable storage and all devices are flushed to ensure
1703data is not cached by device controllers
1704.Pq this is the default .
1705.Sy always
1706causes every file system transaction to be written and flushed before its
1707system call returns.
1708This has a large performance penalty.
1709.Sy disabled
1710disables synchronous requests.
1711File system transactions are only committed to stable storage periodically.
1712This option will give the highest performance.
1713However, it is very dangerous as ZFS would be ignoring the synchronous
1714transaction demands of applications such as databases or NFS.
1715Administrators should only use this option when the risks are understood.
1716.It Sy version Ns = Ns Ar N Ns | Ns Sy current
1717The on-disk version of this file system, which is independent of the pool
1718version.
1719This property can only be set to later supported versions.
1720See the
1721.Nm zfs Cm upgrade
1722command.
1723.It Sy volsize Ns = Ns Ar size
1724For volumes, specifies the logical size of the volume.
1725By default, creating a volume establishes a reservation of equal size.
1726For storage pools with a version number of 9 or higher, a
1727.Sy refreservation
1728is set instead.
1729Any changes to
1730.Sy volsize
1731are reflected in an equivalent change to the reservation
1732.Pq or Sy refreservation .
1733The
1734.Sy volsize
1735can only be set to a multiple of
1736.Sy volblocksize ,
1737and cannot be zero.
1738.Pp
1739The reservation is kept equal to the volume's logical size to prevent unexpected
1740behavior for consumers.
1741Without the reservation, the volume could run out of space, resulting in
1742undefined behavior or data corruption, depending on how the volume is used.
1743These effects can also occur when the volume size is changed while it is in use
1744.Pq particularly when shrinking the size .
1745Extreme care should be used when adjusting the volume size.
1746.Pp
1747Though not recommended, a
1748.Qq sparse volume
1749.Po also known as
1750.Qq thin provisioned
1751.Pc
1752can be created by specifying the
1753.Fl s
1754option to the
1755.Nm zfs Cm create Fl V
1756command, or by changing the value of the
1757.Sy refreservation
1758property
1759.Po or
1760.Sy reservation
1761property on pool version 8 or earlier
1762.Pc
1763after the volume has been created.
1764A
1765.Qq sparse volume
1766is a volume where the value of
1767.Sy refreservation
1768is less than the size of the volume plus the space required to store its
1769metadata.
1770Consequently, writes to a sparse volume can fail with
1771.Er ENOSPC
1772when the pool is low on space.
1773For a sparse volume, changes to
1774.Sy volsize
1775are not reflected in the
1776.Sy refreservation .
1777A volume that is not sparse is said to be
1778.Qq thick provisioned .
1779A sparse volume can become thick provisioned by setting
1780.Sy refreservation
1781to
1782.Sy auto .
1783.It Sy volmode Ns = Ns Sy default Ns | Ns Sy full Ns | Ns Sy geom Ns | Ns Sy dev Ns | Ns Sy none
1784This property specifies how volumes should be exposed to the OS.
1785Setting it to
1786.Sy full
1787exposes volumes as fully fledged block devices, providing maximal
1788functionality.
1789The value
1790.Sy geom
1791is just an alias for
1792.Sy full
1793and is kept for compatibility.
1794Setting it to
1795.Sy dev
1796hides its partitions.
1797Volumes with property set to
1798.Sy none
1799are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
1800that can be suitable for backup purposes.
1801Value
1802.Sy default
1803means that volumes exposition is controlled by system-wide tunable
1804.Sy zvol_volmode ,
1805where
1806.Sy full ,
1807.Sy dev
1808and
1809.Sy none
1810are encoded as 1, 2 and 3 respectively.
1811The default value is
1812.Sy full .
1813.It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1814Controls whether regular files should be scanned for viruses when a file is
1815opened and closed.
1816In addition to enabling this property, the virus scan service must also be
1817enabled for virus scanning to occur.
1818The default value is
1819.Sy off .
1820This property is not used by OpenZFS.
1821.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1822Controls whether extended attributes are enabled for this file system.
1823Two styles of extended attributes are supported: either directory based
1824or system attribute based.
1825.Pp
1826The default value of
1827.Sy on
1828enables directory based extended attributes.
1829This style of extended attribute imposes no practical limit
1830on either the size or number of attributes which can be set on a file.
1831Although under Linux the
1832.Xr getxattr 2
1833and
1834.Xr setxattr 2
1835system calls limit the maximum size to 64K.
1836This is the most compatible
1837style of extended attribute and is supported by all ZFS implementations.
1838.Pp
1839System attribute based xattrs can be enabled by setting the value to
1840.Sy sa .
1841The key advantage of this type of xattr is improved performance.
1842Storing extended attributes as system attributes
1843significantly decreases the amount of disk IO required.
1844Up to 64K of data may be stored per-file in the space reserved for system attributes.
1845If there is not enough space available for an extended attribute
1846then it will be automatically written as a directory based xattr.
1847System attribute based extended attributes are not accessible
1848on platforms which do not support the
1849.Sy xattr Ns = Ns Sy sa
1850feature.
1851OpenZFS supports
1852.Sy xattr Ns = Ns Sy sa
1853on both
1854.Fx
1855and Linux.
1856.Pp
1857The use of system attribute based xattrs is strongly encouraged for users of
1858SELinux or POSIX ACLs.
1859Both of these features heavily rely on extended
1860attributes and benefit significantly from the reduced access time.
1861.Pp
1862The values
1863.Sy on
1864and
1865.Sy off
1866are equivalent to the
1867.Sy xattr
1868and
1869.Sy noxattr
1870mount options.
1871.It Sy jailed Ns = Ns Sy off Ns | Ns Sy on
1872Controls whether the dataset is managed from a jail.
1873See
1874.Xr zfs-jail 8
1875for more information.
1876Jails are a
1877.Fx
1878feature and are not relevant on other platforms.
1879The default value is
1880.Sy off .
1881.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1882Controls whether the dataset is managed from a non-global zone.
1883Zones are a Solaris feature and are not relevant on other platforms.
1884The default value is
1885.Sy off .
1886.El
1887.Pp
1888The following three properties cannot be changed after the file system is
1889created, and therefore, should be set when the file system is created.
1890If the properties are not set with the
1891.Nm zfs Cm create
1892or
1893.Nm zpool Cm create
1894commands, these properties are inherited from the parent dataset.
1895If the parent dataset lacks these properties due to having been created prior to
1896these features being supported, the new file system will have the default values
1897for these properties.
1898.Bl -tag -width ""
1899.It Xo
1900.Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1901.Sy insensitive Ns | Ns Sy mixed
1902.Xc
1903Indicates whether the file name matching algorithm used by the file system
1904should be case-sensitive, case-insensitive, or allow a combination of both
1905styles of matching.
1906The default value for the
1907.Sy casesensitivity
1908property is
1909.Sy sensitive .
1910Traditionally,
1911.Ux
1912and POSIX file systems have case-sensitive file names.
1913.Pp
1914The
1915.Sy mixed
1916value for the
1917.Sy casesensitivity
1918property indicates that the file system can support requests for both
1919case-sensitive and case-insensitive matching behavior.
1920Currently, case-insensitive matching behavior on a file system that supports
1921mixed behavior is limited to the SMB server product.
1922For more information about the
1923.Sy mixed
1924value behavior, see the "ZFS Administration Guide".
1925.It Xo
1926.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1927.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1928.Xc
1929Indicates whether the file system should perform a
1930.Sy unicode
1931normalization of file names whenever two file names are compared, and which
1932normalization algorithm should be used.
1933File names are always stored unmodified, names are normalized as part of any
1934comparison process.
1935If this property is set to a legal value other than
1936.Sy none ,
1937and the
1938.Sy utf8only
1939property was left unspecified, the
1940.Sy utf8only
1941property is automatically set to
1942.Sy on .
1943The default value of the
1944.Sy normalization
1945property is
1946.Sy none .
1947This property cannot be changed after the file system is created.
1948.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1949Indicates whether the file system should reject file names that include
1950characters that are not present in the
1951.Sy UTF-8
1952character code set.
1953If this property is explicitly set to
1954.Sy off ,
1955the normalization property must either not be explicitly set or be set to
1956.Sy none .
1957The default value for the
1958.Sy utf8only
1959property is
1960.Sy off .
1961This property cannot be changed after the file system is created.
1962.El
1963.Pp
1964The
1965.Sy casesensitivity ,
1966.Sy normalization ,
1967and
1968.Sy utf8only
1969properties are also new permissions that can be assigned to non-privileged users
1970by using the ZFS delegated administration feature.
1971.
1972.Ss Temporary Mount Point Properties
1973When a file system is mounted, either through
1974.Xr mount 8
1975for legacy mounts or the
1976.Nm zfs Cm mount
1977command for normal file systems, its mount options are set according to its
1978properties.
1979The correlation between properties and mount options is as follows:
1980.Bl -tag -compact -offset Ds -width "rootcontext="
1981.It Sy atime
1982atime/noatime
1983.It Sy canmount
1984auto/noauto
1985.It Sy devices
1986dev/nodev
1987.It Sy exec
1988exec/noexec
1989.It Sy readonly
1990ro/rw
1991.It Sy relatime
1992relatime/norelatime
1993.It Sy setuid
1994suid/nosuid
1995.It Sy xattr
1996xattr/noxattr
1997.It Sy nbmand
1998mand/nomand
1999.It Sy context Ns =
2000context=
2001.It Sy fscontext Ns =
2002fscontext=
2003.It Sy defcontext Ns =
2004defcontext=
2005.It Sy rootcontext Ns =
2006rootcontext=
2007.El
2008.Pp
2009In addition, these options can be set on a per-mount basis using the
2010.Fl o
2011option, without affecting the property that is stored on disk.
2012The values specified on the command line override the values stored in the
2013dataset.
2014The
2015.Sy nosuid
2016option is an alias for
2017.Sy nodevices , Ns Sy nosetuid .
2018These properties are reported as
2019.Qq temporary
2020by the
2021.Nm zfs Cm get
2022command.
2023If the properties are changed while the dataset is mounted, the new setting
2024overrides any temporary settings.
2025.
2026.Ss User Properties
2027In addition to the standard native properties, ZFS supports arbitrary user
2028properties.
2029User properties have no effect on ZFS behavior, but applications or
2030administrators can use them to annotate datasets
2031.Pq file systems, volumes, and snapshots .
2032.Pp
2033User property names must contain a colon
2034.Pq Qq Sy \&:
2035character to distinguish them from native properties.
2036They may contain lowercase letters, numbers, and the following punctuation
2037characters: colon
2038.Pq Qq Sy \&: ,
2039dash
2040.Pq Qq Sy - ,
2041period
2042.Pq Qq Sy \&. ,
2043and underscore
2044.Pq Qq Sy _ .
2045The expected convention is that the property name is divided into two portions
2046such as
2047.Ar module : Ns Ar property ,
2048but this namespace is not enforced by ZFS.
2049User property names can be at most 256 characters, and cannot begin with a dash
2050.Pq Qq Sy - .
2051.Pp
2052When making programmatic use of user properties, it is strongly suggested to use
2053a reversed DNS domain name for the
2054.Ar module
2055component of property names to reduce the chance that two
2056independently-developed packages use the same property name for different
2057purposes.
2058.Pp
2059The values of user properties are arbitrary strings, are always inherited, and
2060are never validated.
2061All of the commands that operate on properties
2062.Po Nm zfs Cm list ,
2063.Nm zfs Cm get ,
2064.Nm zfs Cm set ,
2065and so forth
2066.Pc
2067can be used to manipulate both native properties and user properties.
2068Use the
2069.Nm zfs Cm inherit
2070command to clear a user property.
2071If the property is not defined in any parent dataset, it is removed entirely.
2072Property values are limited to 8192 bytes.
2073