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.
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.
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]
22 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
23 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
24 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
25 .\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
26 .\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
27 .\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org>
28 .\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org>
29 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
30 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
31 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
32 .\" Copyright (c) 2014 Integros [integros.com]
33 .\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved.
34 .\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org>
35 .\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved.
36 .\" Copyright 2019 Richard Laager. All rights reserved.
37 .\" Copyright 2018 Nexenta Systems, Inc.
38 .\" Copyright 2019 Joyent, Inc.
39 .\" Copyright (c) 2019, Kjeld Schouten-Lebbing
46 .Nd Native properties and user-defined of ZFS datasets.
48 Properties are divided into two types, native properties and user-defined
53 Native properties either export internal statistics or control ZFS behavior.
54 In addition, native properties are either editable or read-only.
55 User properties have no effect on ZFS behavior, but you can use them to annotate
56 datasets in a way that is meaningful in your environment.
57 For more information about user properties, see the
61 Every dataset has a set of properties that export statistics about the dataset
62 as well as control various behaviors.
63 Properties are inherited from the parent unless overridden by the child.
64 Some properties apply only to certain types of datasets
65 .Pq file systems, volumes, or snapshots .
67 The values of numeric properties can be specified using human-readable suffixes
77 The following are all valid
80 .Li 1536M, 1.5g, 1.50GB .
82 The values of non-numeric properties are case sensitive and must be lowercase,
89 The following native properties consist of read-only statistics about the
91 These properties can be neither set, nor inherited.
92 Native properties apply to all dataset types unless otherwise noted.
93 .Bl -tag -width "usedbyrefreservation"
95 The amount of space available to the dataset and all its children, assuming that
96 there is no other activity in the pool.
97 Because space is shared within a pool, availability can be limited by any number
98 of factors, including physical pool size, quotas, reservations, or other
99 datasets within the pool.
101 This property can also be referred to by its shortened column name,
104 For non-snapshots, the compression ratio achieved for the
106 space of this dataset, expressed as a multiplier.
109 property includes descendant datasets, and, for clones, does not include the
110 space shared with the origin snapshot.
116 Compression can be turned on by running:
117 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
121 The transaction group (txg) in which the dataset was created. Bookmarks have
124 as the snapshot they are initially tied to. This property is suitable for
125 ordering a list of snapshots, e.g. for incremental send and receive.
127 The time this dataset was created.
129 For snapshots, this property is a comma-separated list of filesystems or volumes
130 which are clones of this snapshot.
133 property is this snapshot.
136 property is not empty, then this snapshot can not be destroyed
143 The roles of origin and clone can be swapped by promoting the clone with the
149 if the snapshot has been marked for deferred destroy by using the
150 .Nm zfs Cm destroy Fl d
152 Otherwise, the property is
154 .It Sy encryptionroot
155 For encrypted datasets, indicates where the dataset is currently inheriting its
156 encryption key from. Loading or unloading a key for the
158 will implicitly load / unload the key for any inheriting datasets (see
161 .Nm zfs Cm unload-key
163 Clones will always share an
164 encryption key with their origin. See the
169 .It Sy filesystem_count
170 The total number of filesystems and volumes that exist under this location in
172 This value is only available when a
174 has been set somewhere in the tree under which the dataset resides.
176 Indicates if an encryption key is currently loaded into ZFS. The possible
185 .Nm zfs Cm unload-key .
187 The 64 bit GUID of this dataset or bookmark which does not change over its
188 entire lifetime. When a snapshot is sent to another pool, the received
189 snapshot has the same GUID. Thus, the
191 is suitable to identify a snapshot across pools.
192 .It Sy logicalreferenced
193 The amount of space that is
195 accessible by this dataset.
199 The logical space ignores the effect of the
203 properties, giving a quantity closer to the amount of data that applications
205 However, it does include space consumed by metadata.
207 This property can also be referred to by its shortened column name,
210 The amount of space that is
212 consumed by this dataset and all its descendents.
216 The logical space ignores the effect of the
220 properties, giving a quantity closer to the amount of data that applications
222 However, it does include space consumed by metadata.
224 This property can also be referred to by its shortened column name,
227 For file systems, indicates whether the file system is currently mounted.
228 This property can be either
233 A unique identifier for this dataset within the pool. Unlike the dataset's
237 of a dataset is not transferred to other pools when the snapshot is copied
238 with a send/receive operation.
241 can be reused (for a new dataset) after the dataset is deleted.
243 For cloned file systems or volumes, the snapshot from which the clone was
248 .It Sy receive_resume_token
249 For filesystems or volumes which have saved partially-completed state from
251 this opaque token can be provided to
253 to resume and complete the
256 For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
258 For snapshots, this is the list of snapshot guids the snapshot is redacted with
261 The amount of data that is accessible by this dataset, which may or may not be
262 shared with other datasets in the pool.
263 When a snapshot or clone is created, it initially references the same amount of
264 space as the file system or snapshot it was created from, since its contents are
267 This property can also be referred to by its shortened column name,
269 .It Sy refcompressratio
270 The compression ratio achieved for the
272 space of this dataset, expressed as a multiplier.
276 .It Sy snapshot_count
277 The total number of snapshots that exist under this location in the dataset
279 This value is only available when a
281 has been set somewhere in the tree under which the dataset resides.
290 The amount of space consumed by this dataset and all its descendents.
291 This is the value that is checked against this dataset's quota and reservation.
292 The space used does not include this dataset's reservation, but does take into
293 account the reservations of any descendent datasets.
294 The amount of space that a dataset consumes from its parent, as well as the
295 amount of space that is freed if this dataset is recursively destroyed, is the
296 greater of its space used and its reservation.
298 The used space of a snapshot
304 is space that is referenced exclusively by this snapshot.
305 If this snapshot is destroyed, the amount of
308 Space that is shared by multiple snapshots isn't accounted for in this metric.
309 When a snapshot is destroyed, space that was previously shared with this
310 snapshot can become unique to snapshots adjacent to it, thus changing the used
311 space of those snapshots.
312 The used space of the latest snapshot can also be affected by changes in the
316 space of a snapshot is a subset of the
318 space of the snapshot.
320 The amount of space used, available, or referenced does not take into account
322 Pending changes are generally accounted for within a few seconds.
323 Committing a change to a disk using
327 does not necessarily guarantee that the space usage information is updated
332 properties decompose the
334 properties into the various reasons that space is used.
337 .Sy usedbychildren No +
338 .Sy usedbydataset No +
339 .Sy usedbyrefreservation No +
340 .Sy usedbysnapshots .
341 These properties are only available for datasets created on
345 .It Sy usedbychildren
346 The amount of space used by children of this dataset, which would be freed if
347 all the dataset's children were destroyed.
349 The amount of space used by this dataset itself, which would be freed if the
350 dataset were destroyed
351 .Po after first removing any
353 and destroying any necessary snapshots or descendents
355 .It Sy usedbyrefreservation
356 The amount of space used by a
358 set on this dataset, which would be freed if the
361 .It Sy usedbysnapshots
362 The amount of space consumed by snapshots of this dataset.
363 In particular, it is the amount of space that would be freed if all of this
364 dataset's snapshots were destroyed.
365 Note that this is not simply the sum of the snapshots'
367 properties because space can be shared by multiple snapshots.
368 .It Sy userused Ns @ Ns Em user
369 The amount of space consumed by the specified user in this dataset.
370 Space is charged to the owner of each file, as displayed by
372 The amount of space charged is displayed by
378 subcommand for more information.
380 Unprivileged users can access only their own space usage.
381 The root user, or a user who has been granted the
385 can access everyone's usage.
388 .Sy userused Ns @ Ns Em ...
389 properties are not displayed by
390 .Nm zfs Cm get Sy all .
391 The user's name must be appended after the @ symbol, using one of the following
393 .Bl -bullet -width ""
407 .Sy joe.smith@mydomain
416 Files created on Linux always have POSIX owners.
417 .It Sy userobjused Ns @ Ns Em user
420 property is similar to
422 but instead it counts the number of objects consumed by a user. This property
423 counts all objects allocated on behalf of the user, it may differ from the
424 results of system tools such as
429 is set on a file system additional objects will be created per-file to store
430 extended attributes. These additional objects are reflected in the
432 value and are counted against the user's
434 When a file system is configured to use
436 no additional internal objects are normally required.
438 This property is set to the number of user holds on this snapshot.
439 User holds are set by using the
442 .It Sy groupused Ns @ Ns Em group
443 The amount of space consumed by the specified group in this dataset.
444 Space is charged to the group of each file, as displayed by
447 .Sy userused Ns @ Ns Em user
448 property for more information.
450 Unprivileged users can only access their own groups' space usage.
451 The root user, or a user who has been granted the
455 can access all groups' usage.
456 .It Sy groupobjused Ns @ Ns Em group
457 The number of objects consumed by the specified group in this dataset.
458 Multiple objects may be charged to the group for each file when extended
459 attributes are in use. See the
460 .Sy userobjused Ns @ Ns Em user
461 property for more information.
463 Unprivileged users can only access their own groups' space usage.
464 The root user, or a user who has been granted the
468 can access all groups' usage.
469 .It Sy projectused Ns @ Ns Em project
470 The amount of space consumed by the specified project in this dataset. Project
471 is identified via the project identifier (ID) that is object-based numeral
472 attribute. An object can inherit the project ID from its parent object (if the
473 parent has the flag of inherit project ID that can be set and changed via
476 .Nm zfs project Fl s )
477 when being created. The privileged user can set and change object's project
482 anytime. Space is charged to the project of each file, as displayed by
487 .Sy userused Ns @ Ns Em user
488 property for more information.
490 The root user, or a user who has been granted the
494 can access all projects' usage.
495 .It Sy projectobjused Ns @ Ns Em project
500 but instead it counts the number of objects consumed by project. When the
503 is set on a fileset, ZFS will create additional objects per-file to store
504 extended attributes. These additional objects are reflected in the
506 value and are counted against the project's
507 .Sy projectobjquota .
508 When a filesystem is configured to use
510 no additional internal objects are required. See the
511 .Sy userobjused Ns @ Ns Em user
512 property for more information.
514 The root user, or a user who has been granted the
518 can access all projects' objects usage.
520 For volumes, specifies the block size of the volume.
523 cannot be changed once the volume has been written, so it should be set at
524 volume creation time.
527 for volumes is 8 Kbytes.
528 Any power of 2 from 512 bytes to 128 Kbytes is valid.
530 This property can also be referred to by its shortened column name,
535 by this dataset, that was written since the previous snapshot
536 .Pq i.e. that is not referenced by the previous snapshot .
537 .It Sy written Ns @ Ns Em snapshot
540 space written to this dataset since the specified snapshot.
541 This is the space that is referenced by this dataset but was not referenced by
542 the specified snapshot.
546 may be specified as a short snapshot name
547 .Po just the part after the
550 in which case it will be interpreted as a snapshot in the same filesystem as
554 may be a full snapshot name
555 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
556 which for clones may be a snapshot in the origin's filesystem
557 .Pq or the origin of the origin's filesystem, etc.
560 The following native properties can be used to change the behavior of a ZFS
564 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
565 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
567 Controls how ACEs are inherited when files and directories are created.
568 .Bl -tag -width "passthrough-x"
570 does not inherit any ACEs.
572 only inherits inheritable ACEs that specify
580 permissions when the ACE is inherited.
582 inherits all inheritable ACEs without any modifications.
591 ACEs inherit the execute permission only if the file creation mode also requests
595 When the property value is set to
597 files are created with a mode determined by the inheritable ACEs.
598 If no inheritable ACEs exist that affect the mode, then the mode is set in
599 accordance to the requested mode from the application.
603 property does not apply to POSIX ACLs.
605 .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
606 .Sy passthrough Ns | Ns Sy restricted Ns
608 Controls how an ACL is modified during chmod(2) and how inherited ACEs
609 are modified by the file creation mode.
610 .Bl -tag -width "passthrough"
614 except for those representing
615 the mode of the file or directory requested by
618 reduces permissions granted in all
622 such that they are no greater than the group permissions specified by
625 indicates that no changes are made to the
627 other than creating or updating the necessary
629 entries to represent the new mode of the file or directory.
633 operation to return an error when used on any file or directory which has
636 whose entries can not be represented by a mode.
638 is required to change the set user ID, set group ID, or sticky bits on a file
639 or directory, as they do not have equivalent
644 on a file or directory with a non-trivial
650 you must first remove all
652 entries which do not represent the current mode.
654 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy posix
655 Controls whether ACLs are enabled and if so what type of ACL to use.
656 This property is not visible on FreeBSD yet.
657 .Bl -tag -width "posixacl"
659 default, when a file system has the
661 property set to off then ACLs are disabled.
666 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
667 not functional on other platforms. POSIX ACLs are stored as an extended
668 attribute and therefore will not overwrite any existing NFSv4 ACLs which
675 To obtain the best performance when setting
677 users are strongly encouraged to set the
679 property. This will result in the POSIX ACL being stored more efficiently on
680 disk. But as a consequence, all new extended attributes will only be
681 accessible from OpenZFS implementations which support the
685 property for more details.
686 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
687 Controls whether the access time for files is updated when they are read.
688 Turning this property off avoids producing write traffic when reading files and
689 can result in significant performance gains, though it might confuse mailers
690 and other similar utilities. The values
694 are equivalent to the
698 mount options. The default value is
703 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
704 If this property is set to
706 the file system cannot be mounted, and is ignored by
707 .Nm zfs Cm mount Fl a .
708 Setting this property to
710 is similar to setting the
714 except that the dataset still has a normal
716 property, which can be inherited.
717 Setting this property to
719 allows datasets to be used solely as a mechanism to inherit properties.
720 One example of setting
721 .Sy canmount Ns = Ns Sy off
722 is to have two datasets with the same
724 so that the children of both datasets appear in the same directory, but might
725 have different inherited characteristics.
729 a dataset can only be mounted and unmounted explicitly.
730 The dataset is not mounted automatically when the dataset is created or
731 imported, nor is it mounted by the
732 .Nm zfs Cm mount Fl a
733 command or unmounted by the
734 .Nm zfs Cm unmount Fl a
737 This property is not inherited.
739 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
740 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
741 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
743 Controls the checksum used to verify data integrity.
746 which automatically selects an appropriate algorithm
749 but this may change in future releases
753 disables integrity checking on user data.
756 not only disables integrity but also disables maintaining parity for user data.
757 This setting is used internally by a dump device residing on a RAID-Z pool and
758 should not be used by any other dataset.
759 Disabling checksums is
761 a recommended practice.
768 checksum algorithms require enabling the appropriate features on the pool.
769 FreeBSD does not support the
775 for more information on these algorithms.
777 Changing this property affects only newly-written data.
779 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
780 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns
781 .Sy zstd- Ns Em N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Em N
783 Controls the compression algorithm used for this dataset.
785 Setting compression to
787 indicates that the current default compression algorithm should be used.
788 The default balances compression and decompression speed, with compression ratio
789 and is expected to work well on a wide variety of workloads.
790 Unlike all other settings for this property,
792 does not select a fixed compression type.
793 As new compression algorithms are added to ZFS and enabled on a pool, the
794 default compression algorithm may change.
795 The current default compression algorithm is either
804 compression algorithm is a high-performance replacement for the
807 It features significantly faster compression and decompression, as well as a
808 moderately higher compression ratio than
810 but can only be used on pools with the
816 for details on ZFS feature flags and the
822 compression algorithm is optimized for performance while providing decent data
827 compression algorithm uses the same compression as the
832 level by using the value
839 .Pq best compression ratio .
844 .Po which is also the default for
850 compression algorithm provides both high compression ratios and good
851 performance. You can specify the
853 level by using the value
860 .Pq best compression ratio .
865 Faster speeds at the cost of the compression ratio can be requested by
868 level. This is done using
869 .Sy zstd-fast- Ns Em N ,
872 is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative
874 level. The lower the level the faster the compression - 1000 provides
875 the fastest compression and lowest compression ratio.
882 compression algorithm compresses runs of zeros.
884 This property can also be referred to by its shortened column name
886 Changing this property affects only newly-written data.
888 When any setting except
890 is selected, compression will explicitly check for blocks consisting of only
891 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
892 a hole and not compressed using the indicated compression algorithm.
894 Any block being compressed must be no larger than 7/8 of its original size
895 after compression, otherwise the compression will not be considered worthwhile
896 and the block saved uncompressed. Note that when the logical block is less than
897 8 times the disk sector size this effectively reduces the necessary compression
898 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
899 or less of their original size.
901 .Sy context Ns = Ns Sy none Ns | Ns
902 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
904 This flag sets the SELinux context for all files in the file system under
905 a mount point for that file system. See
907 for more information.
909 .Sy fscontext Ns = Ns Sy none Ns | Ns
910 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
912 This flag sets the SELinux context for the file system file system being
915 for more information.
917 .Sy defcontext Ns = Ns Sy none Ns | Ns
918 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
920 This flag sets the SELinux default context for unlabeled files. See
922 for more information.
924 .Sy rootcontext Ns = Ns Sy none Ns | Ns
925 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
927 This flag sets the SELinux context for the root inode of the file system. See
929 for more information.
930 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
931 Controls the number of copies of data stored for this dataset.
932 These copies are in addition to any redundancy provided by the pool, for
933 example, mirroring or RAID-Z.
934 The copies are stored on different disks, if possible.
935 The space used by multiple copies is charged to the associated file and dataset,
938 property and counting against quotas and reservations.
940 Changing this property only affects newly-written data.
941 Therefore, set this property at file system creation time by using the
942 .Fl o Sy copies Ns = Ns Ar N
945 Remember that ZFS will not import a pool with a missing top-level vdev. Do
947 create, for example a two-disk striped pool and set
949 on some datasets thinking you have setup redundancy for them. When a disk
950 fails you will not be able to import the pool and will have lost all of your
953 Encrypted datasets may not have
954 .Sy copies Ns = Ns Em 3
955 since the implementation stores some encryption metadata where the third copy
957 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
958 Controls whether device nodes can be opened on this file system.
965 are equivalent to the
971 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
972 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
975 Configures deduplication for a dataset. The default value is
977 The default deduplication checksum is
979 (this may change in the future). When
981 is enabled, the checksum defined here overrides the
983 property. Setting the value to
985 has the same effect as the setting
990 ZFS will do a byte-to-byte comparison in case of two blocks having the same
991 signature to make sure the block contents are identical. Specifying
997 Unless necessary, deduplication should NOT be enabled on a system. See the
1002 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1003 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1005 Specifies a compatibility mode or literal value for the size of dnodes in the
1006 file system. The default value is
1008 Setting this property to a value other than
1010 requires the large_dnode pool feature to be enabled.
1016 if the dataset uses the
1018 property setting and the workload makes heavy use of extended attributes. This
1019 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1020 servers, for example. Literal values are supported for cases where the optimal
1021 size is known in advance and for performance testing.
1027 if you need to receive a send stream of this dataset on a pool that doesn't
1028 enable the large_dnode feature, or if you need to import this pool on a system
1029 that doesn't support the large_dnode feature.
1031 This property can also be referred to by its shortened column name,
1034 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1035 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1036 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1038 Controls the encryption cipher suite (block cipher, key length, and mode) used
1039 for this dataset. Requires the
1041 feature to be enabled on the pool.
1044 to be set at dataset creation time.
1047 .Sy encryption Ns = Ns Sy on
1048 when creating a dataset indicates that the default encryption suite will be
1049 selected, which is currently
1051 In order to provide consistent data protection, encryption must be specified at
1052 dataset creation time and it cannot be changed afterwards.
1054 For more details and caveats about encryption see the
1057 .Xr zfs-load-key 8 .
1058 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1059 Controls what format the user's encryption key will be provided as. This
1060 property is only set when the dataset is encrypted.
1062 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1063 encryption suite) and must be randomly generated. A raw key can be generated
1064 with the following command:
1066 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1069 Passphrases must be between 8 and 512 bytes long and will be processed through
1070 PBKDF2 before being used (see the
1072 property). Even though the
1073 encryption suite cannot be changed after dataset creation, the keyformat can be
1075 .Nm zfs Cm change-key .
1077 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1079 Controls where the user's encryption key will be loaded from by default for
1083 .Nm zfs Cm mount Cm -l .
1084 This property is only set for encrypted datasets which are encryption roots. If
1085 unspecified, the default is
1088 Even though the encryption suite cannot be changed after dataset creation, the
1089 keylocation can be with either
1092 .Nm zfs Cm change-key .
1095 is selected ZFS will ask for the key at the command prompt when it is required
1096 to access the encrypted data (see
1098 for details). This setting will also allow the key to be passed in via STDIN,
1099 but users should be careful not to place keys which should be kept secret on
1100 the command line. If a file URI is selected, the key will be loaded from the
1101 specified absolute file path.
1102 .It Sy pbkdf2iters Ns = Ns Ar iterations
1103 Controls the number of PBKDF2 iterations that a
1105 encryption key should be run through when processing it into an encryption key.
1106 This property is only defined when encryption is enabled and a keyformat of
1108 is selected. The goal of PBKDF2 is to significantly increase the
1109 computational difficulty needed to brute force a user's passphrase. This is
1110 accomplished by forcing the attacker to run each passphrase through a
1111 computationally expensive hashing function many times before they arrive at the
1112 resulting key. A user who actually knows the passphrase will only have to pay
1113 this cost once. As CPUs become better at processing, this number should be
1114 raised to ensure that a brute force attack is still not possible. The current
1119 This property may be changed with
1120 .Nm zfs Cm change-key .
1121 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1122 Controls whether processes can be executed from within this file system.
1123 The default value is
1129 are equivalent to the
1134 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1135 Limits the number of filesystems and volumes that can exist under this point in
1137 The limit is not enforced if the user is allowed to change the limit.
1139 .Sy filesystem_limit
1142 a descendent of a filesystem that already has a
1143 .Sy filesystem_limit
1144 does not override the ancestor's
1145 .Sy filesystem_limit ,
1146 but rather imposes an additional limit.
1147 This feature must be enabled to be used
1149 .Xr zpool-features 5
1151 .It Sy special_small_blocks Ns = Ns Em size
1152 This value represents the threshold block size for including small file
1153 blocks into the special allocation class. Blocks smaller than or equal to this
1154 value will be assigned to the special allocation class while greater blocks
1155 will be assigned to the regular class. Valid values are zero or a power of two
1156 from 512B up to 1M. The default size is 0 which means no small file blocks
1157 will be allocated in the special class.
1159 Before setting this property, a special class vdev must be added to the
1162 for more details on the special allocation class.
1163 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1164 Controls the mount point used for this file system.
1169 for more information on how this property is used.
1173 property is changed for a file system, the file system and any children that
1174 inherit the mount point are unmounted.
1177 then they remain unmounted.
1178 Otherwise, they are automatically remounted in the new location if the property
1183 or if they were mounted before the property was changed.
1184 In addition, any shared file systems are unshared and shared in the new
1186 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1187 Controls whether the file system should be mounted with
1189 .Pq Non Blocking mandatory locks .
1190 This is used for SMB clients.
1191 Changes to this property only take effect when the file system is umounted and
1195 for more information on
1197 mounts. This property is not used on Linux.
1198 .It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
1199 Allow mounting on a busy directory or a directory which already contains
1200 files or directories.
1201 This is the default mount behavior for Linux and FreeBSD file systems.
1202 On these platforms the property is
1207 to disable overlay mounts for consistency with OpenZFS on other platforms.
1208 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1209 Controls what is cached in the primary cache
1211 If this property is set to
1213 then both user data and metadata is cached.
1214 If this property is set to
1216 then neither user data nor metadata is cached.
1217 If this property is set to
1219 then only metadata is cached.
1220 The default value is
1222 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1223 Limits the amount of space a dataset and its descendents can consume.
1224 This property enforces a hard limit on the amount of space used.
1225 This includes all space consumed by descendents, including file systems and
1227 Setting a quota on a descendent of a dataset that already has a quota does not
1228 override the ancestor's quota, but rather imposes an additional limit.
1230 Quotas cannot be set on volumes, as the
1232 property acts as an implicit quota.
1233 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1234 Limits the number of snapshots that can be created on a dataset and its
1238 on a descendent of a dataset that already has a
1240 does not override the ancestor's
1241 .Sy snapshot_limit ,
1242 but rather imposes an additional limit.
1243 The limit is not enforced if the user is allowed to change the limit.
1244 For example, this means that recursive snapshots taken from the global zone are
1245 counted against each delegated dataset within a zone.
1246 This feature must be enabled to be used
1248 .Xr zpool-features 5
1250 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1251 Limits the amount of space consumed by the specified user.
1252 User space consumption is identified by the
1253 .Sy userspace@ Ns Em user
1256 Enforcement of user quotas may be delayed by several seconds.
1257 This delay means that a user might exceed their quota before the system notices
1258 that they are over quota and begins to refuse additional writes with the
1262 .Nm zfs Cm userspace
1263 subcommand for more information.
1265 Unprivileged users can only access their own groups' space usage.
1266 The root user, or a user who has been granted the
1270 can get and set everyone's quota.
1272 This property is not available on volumes, on file systems before version 4, or
1273 on pools before version 15.
1275 .Sy userquota@ Ns Em ...
1276 properties are not displayed by
1277 .Nm zfs Cm get Sy all .
1278 The user's name must be appended after the
1280 symbol, using one of the following forms:
1288 .Em POSIX numeric ID
1295 .Sy joe.smith@mydomain
1304 Files created on Linux always have POSIX owners.
1305 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1310 but it limits the number of objects a user can create. Please refer to
1312 for more information about how objects are counted.
1313 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1314 Limits the amount of space consumed by the specified group.
1315 Group space consumption is identified by the
1316 .Sy groupused@ Ns Em group
1319 Unprivileged users can access only their own groups' space usage.
1320 The root user, or a user who has been granted the
1324 can get and set all groups' quotas.
1325 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1330 but it limits number of objects a group can consume. Please refer to
1332 for more information about how objects are counted.
1333 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1334 Limits the amount of space consumed by the specified project. Project
1335 space consumption is identified by the
1336 .Sy projectused@ Ns Em project
1337 property. Please refer to
1339 for more information about how project is identified and set/changed.
1341 The root user, or a user who has been granted the
1345 can access all projects' quota.
1346 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1351 but it limits number of objects a project can consume. Please refer to
1353 for more information about how objects are counted.
1354 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1355 Controls whether this dataset can be modified.
1356 The default value is
1362 are equivalent to the
1368 This property can also be referred to by its shortened column name,
1370 .It Sy recordsize Ns = Ns Em size
1371 Specifies a suggested block size for files in the file system.
1372 This property is designed solely for use with database workloads that access
1373 files in fixed-size records.
1374 ZFS automatically tunes block sizes according to internal algorithms optimized
1375 for typical access patterns.
1377 For databases that create very large files but access them in small random
1378 chunks, these algorithms may be suboptimal.
1381 greater than or equal to the record size of the database can result in
1382 significant performance gains.
1383 Use of this property for general purpose file systems is strongly discouraged,
1384 and may adversely affect performance.
1386 The size specified must be a power of two greater than or equal to 512 and less
1387 than or equal to 128 Kbytes.
1390 feature is enabled on the pool, the size may be up to 1 Mbyte.
1392 .Xr zpool-features 5
1393 for details on ZFS feature flags.
1395 Changing the file system's
1397 affects only files created afterward; existing files are unaffected.
1399 This property can also be referred to by its shortened column name,
1401 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1402 Controls what types of metadata are stored redundantly.
1403 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1404 the amount of user data lost is limited.
1405 This extra copy is in addition to any redundancy provided at the pool level
1406 .Pq e.g. by mirroring or RAID-Z ,
1407 and is in addition to an extra copy specified by the
1410 .Pq up to a total of 3 copies .
1411 For example if the pool is mirrored,
1412 .Sy copies Ns = Ns 2 ,
1414 .Sy redundant_metadata Ns = Ns Sy most ,
1415 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1420 ZFS stores an extra copy of all metadata.
1421 If a single on-disk block is corrupt, at worst a single block of user data
1430 ZFS stores an extra copy of most types of metadata.
1431 This can improve performance of random writes, because less metadata must be
1433 In practice, at worst about 100 blocks
1438 of user data can be lost if a single on-disk block is corrupt.
1439 The exact behavior of which metadata blocks are stored redundantly may change in
1442 The default value is
1444 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1445 Limits the amount of space a dataset can consume.
1446 This property enforces a hard limit on the amount of space used.
1447 This hard limit does not include space used by descendents, including file
1448 systems and snapshots.
1449 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1450 The minimum amount of space guaranteed to a dataset, not including its
1452 When the amount of space used is below this value, the dataset is treated as if
1453 it were taking up the amount of space specified by
1454 .Sy refreservation .
1457 reservation is accounted for in the parent datasets' space used, and counts
1458 against the parent datasets' quotas and reservations.
1462 is set, a snapshot is only allowed if there is enough free pool space outside of
1463 this reservation to accommodate the current number of
1465 bytes in the dataset.
1471 a volume is thick provisioned
1475 .Sy refreservation Ns = Ns Sy auto
1476 is only supported on volumes.
1480 .Sx Native Properties
1481 section for more information about sparse volumes.
1483 This property can also be referred to by its shortened column name,
1485 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1486 Controls the manner in which the access time is updated when
1488 is set. Turning this property on causes the access time to be updated relative
1489 to the modify or change time. Access time is only updated if the previous
1490 access time was earlier than the current modify or change time or if the
1491 existing access time hasn't been updated within the past 24 hours. The default
1498 are equivalent to the
1503 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1504 The minimum amount of space guaranteed to a dataset and its descendants.
1505 When the amount of space used is below this value, the dataset is treated as if
1506 it were taking up the amount of space specified by its reservation.
1507 Reservations are accounted for in the parent datasets' space used, and count
1508 against the parent datasets' quotas and reservations.
1510 This property can also be referred to by its shortened column name,
1512 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1513 Controls what is cached in the secondary cache
1515 If this property is set to
1517 then both user data and metadata is cached.
1518 If this property is set to
1520 then neither user data nor metadata is cached.
1521 If this property is set to
1523 then only metadata is cached.
1524 The default value is
1526 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1527 Controls whether the setuid bit is respected for the file system.
1528 The default value is
1534 are equivalent to the
1539 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1540 Controls whether the file system is shared by using
1541 .Sy Samba USERSHARES
1542 and what options are to be used. Otherwise, the file system is automatically
1543 shared and unshared with the
1547 commands. If the property is set to on, the
1549 command is invoked to create a
1552 Because SMB shares requires a resource name, a unique resource name is
1553 constructed from the dataset name. The constructed name is a copy of the
1554 dataset name except that the characters in the dataset name, which would be
1555 invalid in the resource name, are replaced with underscore (_) characters.
1556 Linux does not currently support additional options which might be available
1563 the file systems are unshared.
1565 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1566 stands for "full permissions", ie. read and write permissions) and no guest
1567 access (which means Samba must be able to authenticate a real user, system
1568 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1569 additional access control (disallow specific user specific access etc) must
1570 be done on the underlying file system.
1571 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1572 Controls whether the file system is shared via NFS, and what options are to be
1574 A file system with a
1580 command and entries in the
1583 Otherwise, the file system is automatically shared and unshared with the
1588 If the property is set to
1590 the dataset is shared using the default options:
1592 .Em sec=sys,rw,crossmnt,no_subtree_check
1596 for the meaning of the default options. Otherwise, the
1598 command is invoked with options equivalent to the contents of this property.
1602 property is changed for a dataset, the dataset and any children inheriting the
1603 property are re-shared with the new options, only if the property was previously
1605 or if they were shared before the property was changed.
1606 If the new property is
1608 the file systems are unshared.
1609 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1610 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1616 ZFS will use pool log devices
1618 to handle the requests at low latency.
1623 ZFS will not use configured pool log devices.
1624 ZFS will instead optimize synchronous operations for global pool throughput and
1625 efficient use of resources.
1626 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1627 Controls whether the volume snapshot devices under
1628 .Em /dev/zvol/<pool>
1629 are hidden or visible. The default value is
1631 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1632 Controls whether the
1634 directory is hidden or visible in the root of the file system as discussed in
1639 The default value is
1641 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1642 Controls the behavior of synchronous requests
1643 .Pq e.g. fsync, O_DSYNC .
1647 specified behavior of ensuring all synchronous requests are written to stable
1648 storage and all devices are flushed to ensure data is not cached by device
1650 .Pq this is the default .
1652 causes every file system transaction to be written and flushed before its
1653 system call returns.
1654 This has a large performance penalty.
1656 disables synchronous requests.
1657 File system transactions are only committed to stable storage periodically.
1658 This option will give the highest performance.
1659 However, it is very dangerous as ZFS would be ignoring the synchronous
1660 transaction demands of applications such as databases or NFS.
1661 Administrators should only use this option when the risks are understood.
1662 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1663 The on-disk version of this file system, which is independent of the pool
1665 This property can only be set to later supported versions.
1669 .It Sy volsize Ns = Ns Em size
1670 For volumes, specifies the logical size of the volume.
1671 By default, creating a volume establishes a reservation of equal size.
1672 For storage pools with a version number of 9 or higher, a
1677 are reflected in an equivalent change to the reservation
1683 can only be set to a multiple of
1687 The reservation is kept equal to the volume's logical size to prevent unexpected
1688 behavior for consumers.
1689 Without the reservation, the volume could run out of space, resulting in
1690 undefined behavior or data corruption, depending on how the volume is used.
1691 These effects can also occur when the volume size is changed while it is in use
1692 .Pq particularly when shrinking the size .
1693 Extreme care should be used when adjusting the volume size.
1695 Though not recommended, a
1698 .Qq thin provisioned
1700 can be created by specifying the
1703 .Nm zfs Cm create Fl V
1704 command, or by changing the value of the
1709 property on pool version 8 or earlier
1711 after the volume has been created.
1714 is a volume where the value of
1716 is less than the size of the volume plus the space required to store its
1718 Consequently, writes to a sparse volume can fail with
1720 when the pool is low on space.
1721 For a sparse volume, changes to
1723 are not reflected in the
1725 A volume that is not sparse is said to be
1726 .Qq thick provisioned .
1727 A sparse volume can become thick provisioned by setting
1731 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1732 This property specifies how volumes should be exposed to the OS.
1735 exposes volumes as fully fledged block devices, providing maximal
1736 functionality. The value
1738 is just an alias for
1740 and is kept for compatibility.
1743 hides its partitions.
1744 Volumes with property set to
1746 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
1747 that can be suitable for backup purposes.
1750 means that volumes exposition is controlled by system-wide tunable
1757 are encoded as 1, 2 and 3 respectively.
1758 The default values is
1760 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1761 Controls whether regular files should be scanned for viruses when a file is
1763 In addition to enabling this property, the virus scan service must also be
1764 enabled for virus scanning to occur.
1765 The default value is
1767 This property is not used on Linux.
1768 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1769 Controls whether extended attributes are enabled for this file system. Two
1770 styles of extended attributes are supported either directory based or system
1773 The default value of
1775 enables directory based extended attributes. This style of extended attribute
1776 imposes no practical limit on either the size or number of attributes which
1777 can be set on a file. Although under Linux the
1781 system calls limit the maximum size to 64K. This is the most compatible
1782 style of extended attribute and is supported by all OpenZFS implementations.
1784 System attribute based xattrs can be enabled by setting the value to
1786 The key advantage of this type of xattr is improved performance. Storing
1787 extended attributes as system attributes significantly decreases the amount of
1788 disk IO required. Up to 64K of data may be stored per-file in the space
1789 reserved for system attributes. If there is not enough space available for
1790 an extended attribute then it will be automatically written as a directory
1791 based xattr. System attribute based extended attributes are not accessible
1792 on platforms which do not support the
1796 The use of system attribute based xattrs is strongly encouraged for users of
1797 SELinux or POSIX ACLs. Both of these features heavily rely of extended
1798 attributes and benefit significantly from the reduced access time.
1804 are equivalent to the
1809 .It Sy jailed Ns = Ns Cm off | on
1810 Controls whether the dataset is managed from a jail. See the
1814 for more information. Jails are a FreeBSD feature and are not relevant on
1815 other platforms. The default value is
1817 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1818 Controls whether the dataset is managed from a non-global zone. Zones are a
1819 Solaris feature and are not relevant on other platforms. The default value is
1823 The following three properties cannot be changed after the file system is
1824 created, and therefore, should be set when the file system is created.
1825 If the properties are not set with the
1829 commands, these properties are inherited from the parent dataset.
1830 If the parent dataset lacks these properties due to having been created prior to
1831 these features being supported, the new file system will have the default values
1832 for these properties.
1835 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1836 .Sy insensitive Ns | Ns Sy mixed
1838 Indicates whether the file name matching algorithm used by the file system
1839 should be case-sensitive, case-insensitive, or allow a combination of both
1841 The default value for the
1849 file systems have case-sensitive file names.
1855 property indicates that the file system can support requests for both
1856 case-sensitive and case-insensitive matching behavior.
1857 Currently, case-insensitive matching behavior on a file system that supports
1858 mixed behavior is limited to the SMB server product.
1859 For more information about the
1861 value behavior, see the "ZFS Administration Guide".
1863 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1864 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1866 Indicates whether the file system should perform a
1868 normalization of file names whenever two file names are compared, and which
1869 normalization algorithm should be used.
1870 File names are always stored unmodified, names are normalized as part of any
1872 If this property is set to a legal value other than
1876 property was left unspecified, the
1878 property is automatically set to
1880 The default value of the
1884 This property cannot be changed after the file system is created.
1885 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1886 Indicates whether the file system should reject file names that include
1887 characters that are not present in the
1890 If this property is explicitly set to
1892 the normalization property must either not be explicitly set or be set to
1894 The default value for the
1898 This property cannot be changed after the file system is created.
1902 .Sy casesensitivity ,
1906 properties are also new permissions that can be assigned to non-privileged users
1907 by using the ZFS delegated administration feature.
1908 .Ss "Temporary Mount Point Properties"
1909 When a file system is mounted, either through
1911 for legacy mounts or the
1913 command for normal file systems, its mount options are set according to its
1915 The correlation between properties and mount options is as follows:
1917 PROPERTY MOUNT OPTION
1919 canmount auto/noauto
1923 relatime relatime/norelatime
1928 In addition, these options can be set on a per-mount basis using the
1930 option, without affecting the property that is stored on disk.
1931 The values specified on the command line override the values stored in the
1935 option is an alias for
1936 .Sy nodevices Ns \&, Ns Sy nosetuid .
1937 These properties are reported as
1942 If the properties are changed while the dataset is mounted, the new setting
1943 overrides any temporary settings.
1944 .Ss "User Properties"
1945 In addition to the standard native properties, ZFS supports arbitrary user
1947 User properties have no effect on ZFS behavior, but applications or
1948 administrators can use them to annotate datasets
1949 .Pq file systems, volumes, and snapshots .
1951 User property names must contain a colon
1953 character to distinguish them from native properties.
1954 They may contain lowercase letters, numbers, and the following punctuation
1963 The expected convention is that the property name is divided into two portions
1965 .Em module Ns \&: Ns Em property ,
1966 but this namespace is not enforced by ZFS.
1967 User property names can be at most 256 characters, and cannot begin with a dash
1970 When making programmatic use of user properties, it is strongly suggested to use
1975 component of property names to reduce the chance that two
1976 independently-developed packages use the same property name for different
1979 The values of user properties are arbitrary strings, are always inherited, and
1980 are never validated.
1981 All of the commands that operate on properties
1982 .Po Nm zfs Cm list ,
1987 can be used to manipulate both native properties and user properties.
1990 command to clear a user property.
1991 If the property is not defined in any parent dataset, it is removed entirely.
1992 Property values are limited to 8192 bytes.
projects / FreeBSD / FreeBSD.git / blob