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