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