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