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 nfsv4 Ns | Ns Sy posix
655 Controls whether ACLs are enabled and if so what type of ACL to use.
656 When this property is set to a type of ACL not supported by the current
657 platform, the behavior is the same as if it were set to
659 .Bl -tag -width "posixacl"
661 default on Linux, when a file system has the
663 property set to off then ACLs are disabled.
668 default on FreeBSD, indicates that NFSv4-style ZFS ACLs should be used.
669 These ACLs can be managed with the
673 commands on FreeBSD. The
675 ZFS ACL type is not yet supported on Linux.
677 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
678 not functional on other platforms. POSIX ACLs are stored as an extended
679 attribute and therefore will not overwrite any existing NFSv4 ACLs which
686 To obtain the best performance when setting
688 users are strongly encouraged to set the
690 property. This will result in the POSIX ACL being stored more efficiently on
691 disk. But as a consequence, all new extended attributes will only be
692 accessible from OpenZFS implementations which support the
696 property for more details.
697 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
698 Controls whether the access time for files is updated when they are read.
699 Turning this property off avoids producing write traffic when reading files and
700 can result in significant performance gains, though it might confuse mailers
701 and other similar utilities. The values
705 are equivalent to the
709 mount options. The default value is
714 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
715 If this property is set to
717 the file system cannot be mounted, and is ignored by
718 .Nm zfs Cm mount Fl a .
719 Setting this property to
721 is similar to setting the
725 except that the dataset still has a normal
727 property, which can be inherited.
728 Setting this property to
730 allows datasets to be used solely as a mechanism to inherit properties.
731 One example of setting
732 .Sy canmount Ns = Ns Sy off
733 is to have two datasets with the same
735 so that the children of both datasets appear in the same directory, but might
736 have different inherited characteristics.
740 a dataset can only be mounted and unmounted explicitly.
741 The dataset is not mounted automatically when the dataset is created or
742 imported, nor is it mounted by the
743 .Nm zfs Cm mount Fl a
744 command or unmounted by the
745 .Nm zfs Cm unmount Fl a
748 This property is not inherited.
750 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
751 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
752 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
754 Controls the checksum used to verify data integrity.
757 which automatically selects an appropriate algorithm
760 but this may change in future releases
764 disables integrity checking on user data.
767 not only disables integrity but also disables maintaining parity for user data.
768 This setting is used internally by a dump device residing on a RAID-Z pool and
769 should not be used by any other dataset.
770 Disabling checksums is
772 a recommended practice.
779 checksum algorithms require enabling the appropriate features on the pool.
780 FreeBSD does not support the
786 for more information on these algorithms.
788 Changing this property affects only newly-written data.
790 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
791 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns
792 .Sy zstd- Ns Em N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Em N
794 Controls the compression algorithm used for this dataset.
796 Setting compression to
798 indicates that the current default compression algorithm should be used.
799 The default balances compression and decompression speed, with compression ratio
800 and is expected to work well on a wide variety of workloads.
801 Unlike all other settings for this property,
803 does not select a fixed compression type.
804 As new compression algorithms are added to ZFS and enabled on a pool, the
805 default compression algorithm may change.
806 The current default compression algorithm is either
815 compression algorithm is a high-performance replacement for the
818 It features significantly faster compression and decompression, as well as a
819 moderately higher compression ratio than
821 but can only be used on pools with the
827 for details on ZFS feature flags and the
833 compression algorithm is optimized for performance while providing decent data
838 compression algorithm uses the same compression as the
843 level by using the value
850 .Pq best compression ratio .
855 .Po which is also the default for
861 compression algorithm provides both high compression ratios and good
862 performance. You can specify the
864 level by using the value
871 .Pq best compression ratio .
876 Faster speeds at the cost of the compression ratio can be requested by
879 level. This is done using
880 .Sy zstd-fast- Ns Em N ,
883 is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative
885 level. The lower the level the faster the compression - 1000 provides
886 the fastest compression and lowest compression ratio.
893 compression algorithm compresses runs of zeros.
895 This property can also be referred to by its shortened column name
897 Changing this property affects only newly-written data.
899 When any setting except
901 is selected, compression will explicitly check for blocks consisting of only
902 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
903 a hole and not compressed using the indicated compression algorithm.
905 Any block being compressed must be no larger than 7/8 of its original size
906 after compression, otherwise the compression will not be considered worthwhile
907 and the block saved uncompressed. Note that when the logical block is less than
908 8 times the disk sector size this effectively reduces the necessary compression
909 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
910 or less of their original size.
912 .Sy context Ns = Ns Sy none Ns | Ns
913 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
915 This flag sets the SELinux context for all files in the file system under
916 a mount point for that file system. See
918 for more information.
920 .Sy fscontext Ns = Ns Sy none Ns | Ns
921 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
923 This flag sets the SELinux context for the file system file system being
926 for more information.
928 .Sy defcontext Ns = Ns Sy none Ns | Ns
929 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
931 This flag sets the SELinux default context for unlabeled files. See
933 for more information.
935 .Sy rootcontext Ns = Ns Sy none Ns | Ns
936 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
938 This flag sets the SELinux context for the root inode of the file system. See
940 for more information.
941 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
942 Controls the number of copies of data stored for this dataset.
943 These copies are in addition to any redundancy provided by the pool, for
944 example, mirroring or RAID-Z.
945 The copies are stored on different disks, if possible.
946 The space used by multiple copies is charged to the associated file and dataset,
949 property and counting against quotas and reservations.
951 Changing this property only affects newly-written data.
952 Therefore, set this property at file system creation time by using the
953 .Fl o Sy copies Ns = Ns Ar N
956 Remember that ZFS will not import a pool with a missing top-level vdev. Do
958 create, for example a two-disk striped pool and set
960 on some datasets thinking you have setup redundancy for them. When a disk
961 fails you will not be able to import the pool and will have lost all of your
964 Encrypted datasets may not have
965 .Sy copies Ns = Ns Em 3
966 since the implementation stores some encryption metadata where the third copy
968 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
969 Controls whether device nodes can be opened on this file system.
976 are equivalent to the
982 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
983 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
986 Configures deduplication for a dataset. The default value is
988 The default deduplication checksum is
990 (this may change in the future). When
992 is enabled, the checksum defined here overrides the
994 property. Setting the value to
996 has the same effect as the setting
1001 ZFS will do a byte-to-byte comparison in case of two blocks having the same
1002 signature to make sure the block contents are identical. Specifying
1004 is mandatory for the
1008 Unless necessary, deduplication should NOT be enabled on a system. See the
1013 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1014 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1016 Specifies a compatibility mode or literal value for the size of dnodes in the
1017 file system. The default value is
1019 Setting this property to a value other than
1021 requires the large_dnode pool feature to be enabled.
1027 if the dataset uses the
1029 property setting and the workload makes heavy use of extended attributes. This
1030 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1031 servers, for example. Literal values are supported for cases where the optimal
1032 size is known in advance and for performance testing.
1038 if you need to receive a send stream of this dataset on a pool that doesn't
1039 enable the large_dnode feature, or if you need to import this pool on a system
1040 that doesn't support the large_dnode feature.
1042 This property can also be referred to by its shortened column name,
1045 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1046 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1047 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1049 Controls the encryption cipher suite (block cipher, key length, and mode) used
1050 for this dataset. Requires the
1052 feature to be enabled on the pool.
1055 to be set at dataset creation time.
1058 .Sy encryption Ns = Ns Sy on
1059 when creating a dataset indicates that the default encryption suite will be
1060 selected, which is currently
1062 In order to provide consistent data protection, encryption must be specified at
1063 dataset creation time and it cannot be changed afterwards.
1065 For more details and caveats about encryption see the
1068 .Xr zfs-load-key 8 .
1069 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1070 Controls what format the user's encryption key will be provided as. This
1071 property is only set when the dataset is encrypted.
1073 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1074 encryption suite) and must be randomly generated. A raw key can be generated
1075 with the following command:
1077 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1080 Passphrases must be between 8 and 512 bytes long and will be processed through
1081 PBKDF2 before being used (see the
1083 property). Even though the
1084 encryption suite cannot be changed after dataset creation, the keyformat can be
1086 .Nm zfs Cm change-key .
1088 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1090 Controls where the user's encryption key will be loaded from by default for
1094 .Nm zfs Cm mount Cm -l .
1095 This property is only set for encrypted datasets which are encryption roots. If
1096 unspecified, the default is
1099 Even though the encryption suite cannot be changed after dataset creation, the
1100 keylocation can be with either
1103 .Nm zfs Cm change-key .
1106 is selected ZFS will ask for the key at the command prompt when it is required
1107 to access the encrypted data (see
1109 for details). This setting will also allow the key to be passed in via STDIN,
1110 but users should be careful not to place keys which should be kept secret on
1111 the command line. If a file URI is selected, the key will be loaded from the
1112 specified absolute file path.
1113 .It Sy pbkdf2iters Ns = Ns Ar iterations
1114 Controls the number of PBKDF2 iterations that a
1116 encryption key should be run through when processing it into an encryption key.
1117 This property is only defined when encryption is enabled and a keyformat of
1119 is selected. The goal of PBKDF2 is to significantly increase the
1120 computational difficulty needed to brute force a user's passphrase. This is
1121 accomplished by forcing the attacker to run each passphrase through a
1122 computationally expensive hashing function many times before they arrive at the
1123 resulting key. A user who actually knows the passphrase will only have to pay
1124 this cost once. As CPUs become better at processing, this number should be
1125 raised to ensure that a brute force attack is still not possible. The current
1130 This property may be changed with
1131 .Nm zfs Cm change-key .
1132 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1133 Controls whether processes can be executed from within this file system.
1134 The default value is
1140 are equivalent to the
1145 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1146 Limits the number of filesystems and volumes that can exist under this point in
1148 The limit is not enforced if the user is allowed to change the limit.
1150 .Sy filesystem_limit
1153 a descendent of a filesystem that already has a
1154 .Sy filesystem_limit
1155 does not override the ancestor's
1156 .Sy filesystem_limit ,
1157 but rather imposes an additional limit.
1158 This feature must be enabled to be used
1160 .Xr zpool-features 5
1162 .It Sy special_small_blocks Ns = Ns Em size
1163 This value represents the threshold block size for including small file
1164 blocks into the special allocation class. Blocks smaller than or equal to this
1165 value will be assigned to the special allocation class while greater blocks
1166 will be assigned to the regular class. Valid values are zero or a power of two
1167 from 512B up to 1M. The default size is 0 which means no small file blocks
1168 will be allocated in the special class.
1170 Before setting this property, a special class vdev must be added to the
1173 for more details on the special allocation class.
1174 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1175 Controls the mount point used for this file system.
1180 for more information on how this property is used.
1184 property is changed for a file system, the file system and any children that
1185 inherit the mount point are unmounted.
1188 then they remain unmounted.
1189 Otherwise, they are automatically remounted in the new location if the property
1194 or if they were mounted before the property was changed.
1195 In addition, any shared file systems are unshared and shared in the new
1197 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1198 Controls whether the file system should be mounted with
1200 .Pq Non Blocking mandatory locks .
1201 This is used for SMB clients.
1202 Changes to this property only take effect when the file system is umounted and
1206 for more information on
1208 mounts. This property is not used on Linux.
1209 .It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
1210 Allow mounting on a busy directory or a directory which already contains
1211 files or directories.
1212 This is the default mount behavior for Linux and FreeBSD file systems.
1213 On these platforms the property is
1218 to disable overlay mounts for consistency with OpenZFS on other platforms.
1219 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1220 Controls what is cached in the primary cache
1222 If this property is set to
1224 then both user data and metadata is cached.
1225 If this property is set to
1227 then neither user data nor metadata is cached.
1228 If this property is set to
1230 then only metadata is cached.
1231 The default value is
1233 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1234 Limits the amount of space a dataset and its descendents can consume.
1235 This property enforces a hard limit on the amount of space used.
1236 This includes all space consumed by descendents, including file systems and
1238 Setting a quota on a descendent of a dataset that already has a quota does not
1239 override the ancestor's quota, but rather imposes an additional limit.
1241 Quotas cannot be set on volumes, as the
1243 property acts as an implicit quota.
1244 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1245 Limits the number of snapshots that can be created on a dataset and its
1249 on a descendent of a dataset that already has a
1251 does not override the ancestor's
1252 .Sy snapshot_limit ,
1253 but rather imposes an additional limit.
1254 The limit is not enforced if the user is allowed to change the limit.
1255 For example, this means that recursive snapshots taken from the global zone are
1256 counted against each delegated dataset within a zone.
1257 This feature must be enabled to be used
1259 .Xr zpool-features 5
1261 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1262 Limits the amount of space consumed by the specified user.
1263 User space consumption is identified by the
1264 .Sy userspace@ Ns Em user
1267 Enforcement of user quotas may be delayed by several seconds.
1268 This delay means that a user might exceed their quota before the system notices
1269 that they are over quota and begins to refuse additional writes with the
1273 .Nm zfs Cm userspace
1274 subcommand for more information.
1276 Unprivileged users can only access their own groups' space usage.
1277 The root user, or a user who has been granted the
1281 can get and set everyone's quota.
1283 This property is not available on volumes, on file systems before version 4, or
1284 on pools before version 15.
1286 .Sy userquota@ Ns Em ...
1287 properties are not displayed by
1288 .Nm zfs Cm get Sy all .
1289 The user's name must be appended after the
1291 symbol, using one of the following forms:
1299 .Em POSIX numeric ID
1306 .Sy joe.smith@mydomain
1315 Files created on Linux always have POSIX owners.
1316 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1321 but it limits the number of objects a user can create. Please refer to
1323 for more information about how objects are counted.
1324 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1325 Limits the amount of space consumed by the specified group.
1326 Group space consumption is identified by the
1327 .Sy groupused@ Ns Em group
1330 Unprivileged users can access only their own groups' space usage.
1331 The root user, or a user who has been granted the
1335 can get and set all groups' quotas.
1336 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1341 but it limits number of objects a group can consume. Please refer to
1343 for more information about how objects are counted.
1344 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1345 Limits the amount of space consumed by the specified project. Project
1346 space consumption is identified by the
1347 .Sy projectused@ Ns Em project
1348 property. Please refer to
1350 for more information about how project is identified and set/changed.
1352 The root user, or a user who has been granted the
1356 can access all projects' quota.
1357 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1362 but it limits number of objects a project can consume. Please refer to
1364 for more information about how objects are counted.
1365 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1366 Controls whether this dataset can be modified.
1367 The default value is
1373 are equivalent to the
1379 This property can also be referred to by its shortened column name,
1381 .It Sy recordsize Ns = Ns Em size
1382 Specifies a suggested block size for files in the file system.
1383 This property is designed solely for use with database workloads that access
1384 files in fixed-size records.
1385 ZFS automatically tunes block sizes according to internal algorithms optimized
1386 for typical access patterns.
1388 For databases that create very large files but access them in small random
1389 chunks, these algorithms may be suboptimal.
1392 greater than or equal to the record size of the database can result in
1393 significant performance gains.
1394 Use of this property for general purpose file systems is strongly discouraged,
1395 and may adversely affect performance.
1397 The size specified must be a power of two greater than or equal to 512 and less
1398 than or equal to 128 Kbytes.
1401 feature is enabled on the pool, the size may be up to 1 Mbyte.
1403 .Xr zpool-features 5
1404 for details on ZFS feature flags.
1406 Changing the file system's
1408 affects only files created afterward; existing files are unaffected.
1410 This property can also be referred to by its shortened column name,
1412 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1413 Controls what types of metadata are stored redundantly.
1414 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1415 the amount of user data lost is limited.
1416 This extra copy is in addition to any redundancy provided at the pool level
1417 .Pq e.g. by mirroring or RAID-Z ,
1418 and is in addition to an extra copy specified by the
1421 .Pq up to a total of 3 copies .
1422 For example if the pool is mirrored,
1423 .Sy copies Ns = Ns 2 ,
1425 .Sy redundant_metadata Ns = Ns Sy most ,
1426 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1431 ZFS stores an extra copy of all metadata.
1432 If a single on-disk block is corrupt, at worst a single block of user data
1441 ZFS stores an extra copy of most types of metadata.
1442 This can improve performance of random writes, because less metadata must be
1444 In practice, at worst about 100 blocks
1449 of user data can be lost if a single on-disk block is corrupt.
1450 The exact behavior of which metadata blocks are stored redundantly may change in
1453 The default value is
1455 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1456 Limits the amount of space a dataset can consume.
1457 This property enforces a hard limit on the amount of space used.
1458 This hard limit does not include space used by descendents, including file
1459 systems and snapshots.
1460 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1461 The minimum amount of space guaranteed to a dataset, not including its
1463 When the amount of space used is below this value, the dataset is treated as if
1464 it were taking up the amount of space specified by
1465 .Sy refreservation .
1468 reservation is accounted for in the parent datasets' space used, and counts
1469 against the parent datasets' quotas and reservations.
1473 is set, a snapshot is only allowed if there is enough free pool space outside of
1474 this reservation to accommodate the current number of
1476 bytes in the dataset.
1482 a volume is thick provisioned
1486 .Sy refreservation Ns = Ns Sy auto
1487 is only supported on volumes.
1491 .Sx Native Properties
1492 section for more information about sparse volumes.
1494 This property can also be referred to by its shortened column name,
1496 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1497 Controls the manner in which the access time is updated when
1499 is set. Turning this property on causes the access time to be updated relative
1500 to the modify or change time. Access time is only updated if the previous
1501 access time was earlier than the current modify or change time or if the
1502 existing access time hasn't been updated within the past 24 hours. The default
1509 are equivalent to the
1514 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1515 The minimum amount of space guaranteed to a dataset and its descendants.
1516 When the amount of space used is below this value, the dataset is treated as if
1517 it were taking up the amount of space specified by its reservation.
1518 Reservations are accounted for in the parent datasets' space used, and count
1519 against the parent datasets' quotas and reservations.
1521 This property can also be referred to by its shortened column name,
1523 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1524 Controls what is cached in the secondary cache
1526 If this property is set to
1528 then both user data and metadata is cached.
1529 If this property is set to
1531 then neither user data nor metadata is cached.
1532 If this property is set to
1534 then only metadata is cached.
1535 The default value is
1537 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1538 Controls whether the setuid bit is respected for the file system.
1539 The default value is
1545 are equivalent to the
1550 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1551 Controls whether the file system is shared by using
1552 .Sy Samba USERSHARES
1553 and what options are to be used. Otherwise, the file system is automatically
1554 shared and unshared with the
1558 commands. If the property is set to on, the
1560 command is invoked to create a
1563 Because SMB shares requires a resource name, a unique resource name is
1564 constructed from the dataset name. The constructed name is a copy of the
1565 dataset name except that the characters in the dataset name, which would be
1566 invalid in the resource name, are replaced with underscore (_) characters.
1567 Linux does not currently support additional options which might be available
1574 the file systems are unshared.
1576 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1577 stands for "full permissions", ie. read and write permissions) and no guest
1578 access (which means Samba must be able to authenticate a real user, system
1579 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1580 additional access control (disallow specific user specific access etc) must
1581 be done on the underlying file system.
1582 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1583 Controls whether the file system is shared via NFS, and what options are to be
1585 A file system with a
1591 command and entries in the
1594 Otherwise, the file system is automatically shared and unshared with the
1599 If the property is set to
1601 the dataset is shared using the default options:
1603 .Em sec=sys,rw,crossmnt,no_subtree_check
1607 for the meaning of the default options. Otherwise, the
1609 command is invoked with options equivalent to the contents of this property.
1613 property is changed for a dataset, the dataset and any children inheriting the
1614 property are re-shared with the new options, only if the property was previously
1616 or if they were shared before the property was changed.
1617 If the new property is
1619 the file systems are unshared.
1620 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1621 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1627 ZFS will use pool log devices
1629 to handle the requests at low latency.
1634 ZFS will not use configured pool log devices.
1635 ZFS will instead optimize synchronous operations for global pool throughput and
1636 efficient use of resources.
1637 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1638 Controls whether the volume snapshot devices under
1639 .Em /dev/zvol/<pool>
1640 are hidden or visible. The default value is
1642 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1643 Controls whether the
1645 directory is hidden or visible in the root of the file system as discussed in
1650 The default value is
1652 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1653 Controls the behavior of synchronous requests
1654 .Pq e.g. fsync, O_DSYNC .
1658 specified behavior of ensuring all synchronous requests are written to stable
1659 storage and all devices are flushed to ensure data is not cached by device
1661 .Pq this is the default .
1663 causes every file system transaction to be written and flushed before its
1664 system call returns.
1665 This has a large performance penalty.
1667 disables synchronous requests.
1668 File system transactions are only committed to stable storage periodically.
1669 This option will give the highest performance.
1670 However, it is very dangerous as ZFS would be ignoring the synchronous
1671 transaction demands of applications such as databases or NFS.
1672 Administrators should only use this option when the risks are understood.
1673 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1674 The on-disk version of this file system, which is independent of the pool
1676 This property can only be set to later supported versions.
1680 .It Sy volsize Ns = Ns Em size
1681 For volumes, specifies the logical size of the volume.
1682 By default, creating a volume establishes a reservation of equal size.
1683 For storage pools with a version number of 9 or higher, a
1688 are reflected in an equivalent change to the reservation
1694 can only be set to a multiple of
1698 The reservation is kept equal to the volume's logical size to prevent unexpected
1699 behavior for consumers.
1700 Without the reservation, the volume could run out of space, resulting in
1701 undefined behavior or data corruption, depending on how the volume is used.
1702 These effects can also occur when the volume size is changed while it is in use
1703 .Pq particularly when shrinking the size .
1704 Extreme care should be used when adjusting the volume size.
1706 Though not recommended, a
1709 .Qq thin provisioned
1711 can be created by specifying the
1714 .Nm zfs Cm create Fl V
1715 command, or by changing the value of the
1720 property on pool version 8 or earlier
1722 after the volume has been created.
1725 is a volume where the value of
1727 is less than the size of the volume plus the space required to store its
1729 Consequently, writes to a sparse volume can fail with
1731 when the pool is low on space.
1732 For a sparse volume, changes to
1734 are not reflected in the
1736 A volume that is not sparse is said to be
1737 .Qq thick provisioned .
1738 A sparse volume can become thick provisioned by setting
1742 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1743 This property specifies how volumes should be exposed to the OS.
1746 exposes volumes as fully fledged block devices, providing maximal
1747 functionality. The value
1749 is just an alias for
1751 and is kept for compatibility.
1754 hides its partitions.
1755 Volumes with property set to
1757 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
1758 that can be suitable for backup purposes.
1761 means that volumes exposition is controlled by system-wide tunable
1768 are encoded as 1, 2 and 3 respectively.
1769 The default values is
1771 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1772 Controls whether regular files should be scanned for viruses when a file is
1774 In addition to enabling this property, the virus scan service must also be
1775 enabled for virus scanning to occur.
1776 The default value is
1778 This property is not used on Linux.
1779 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1780 Controls whether extended attributes are enabled for this file system. Two
1781 styles of extended attributes are supported either directory based or system
1784 The default value of
1786 enables directory based extended attributes. This style of extended attribute
1787 imposes no practical limit on either the size or number of attributes which
1788 can be set on a file. Although under Linux the
1792 system calls limit the maximum size to 64K. This is the most compatible
1793 style of extended attribute and is supported by all OpenZFS implementations.
1795 System attribute based xattrs can be enabled by setting the value to
1797 The key advantage of this type of xattr is improved performance. Storing
1798 extended attributes as system attributes significantly decreases the amount of
1799 disk IO required. Up to 64K of data may be stored per-file in the space
1800 reserved for system attributes. If there is not enough space available for
1801 an extended attribute then it will be automatically written as a directory
1802 based xattr. System attribute based extended attributes are not accessible
1803 on platforms which do not support the
1807 The use of system attribute based xattrs is strongly encouraged for users of
1808 SELinux or POSIX ACLs. Both of these features heavily rely on extended
1809 attributes and benefit significantly from the reduced access time.
1815 are equivalent to the
1820 .It Sy jailed Ns = Ns Cm off | on
1821 Controls whether the dataset is managed from a jail. See the
1825 for more information. Jails are a FreeBSD feature and are not relevant on
1826 other platforms. The default value is
1828 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1829 Controls whether the dataset is managed from a non-global zone. Zones are a
1830 Solaris feature and are not relevant on other platforms. The default value is
1834 The following three properties cannot be changed after the file system is
1835 created, and therefore, should be set when the file system is created.
1836 If the properties are not set with the
1840 commands, these properties are inherited from the parent dataset.
1841 If the parent dataset lacks these properties due to having been created prior to
1842 these features being supported, the new file system will have the default values
1843 for these properties.
1846 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1847 .Sy insensitive Ns | Ns Sy mixed
1849 Indicates whether the file name matching algorithm used by the file system
1850 should be case-sensitive, case-insensitive, or allow a combination of both
1852 The default value for the
1860 file systems have case-sensitive file names.
1866 property indicates that the file system can support requests for both
1867 case-sensitive and case-insensitive matching behavior.
1868 Currently, case-insensitive matching behavior on a file system that supports
1869 mixed behavior is limited to the SMB server product.
1870 For more information about the
1872 value behavior, see the "ZFS Administration Guide".
1874 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1875 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1877 Indicates whether the file system should perform a
1879 normalization of file names whenever two file names are compared, and which
1880 normalization algorithm should be used.
1881 File names are always stored unmodified, names are normalized as part of any
1883 If this property is set to a legal value other than
1887 property was left unspecified, the
1889 property is automatically set to
1891 The default value of the
1895 This property cannot be changed after the file system is created.
1896 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1897 Indicates whether the file system should reject file names that include
1898 characters that are not present in the
1901 If this property is explicitly set to
1903 the normalization property must either not be explicitly set or be set to
1905 The default value for the
1909 This property cannot be changed after the file system is created.
1913 .Sy casesensitivity ,
1917 properties are also new permissions that can be assigned to non-privileged users
1918 by using the ZFS delegated administration feature.
1919 .Ss "Temporary Mount Point Properties"
1920 When a file system is mounted, either through
1922 for legacy mounts or the
1924 command for normal file systems, its mount options are set according to its
1926 The correlation between properties and mount options is as follows:
1928 PROPERTY MOUNT OPTION
1930 canmount auto/noauto
1934 relatime relatime/norelatime
1939 In addition, these options can be set on a per-mount basis using the
1941 option, without affecting the property that is stored on disk.
1942 The values specified on the command line override the values stored in the
1946 option is an alias for
1947 .Sy nodevices Ns \&, Ns Sy nosetuid .
1948 These properties are reported as
1953 If the properties are changed while the dataset is mounted, the new setting
1954 overrides any temporary settings.
1955 .Ss "User Properties"
1956 In addition to the standard native properties, ZFS supports arbitrary user
1958 User properties have no effect on ZFS behavior, but applications or
1959 administrators can use them to annotate datasets
1960 .Pq file systems, volumes, and snapshots .
1962 User property names must contain a colon
1964 character to distinguish them from native properties.
1965 They may contain lowercase letters, numbers, and the following punctuation
1974 The expected convention is that the property name is divided into two portions
1976 .Em module Ns \&: Ns Em property ,
1977 but this namespace is not enforced by ZFS.
1978 User property names can be at most 256 characters, and cannot begin with a dash
1981 When making programmatic use of user properties, it is strongly suggested to use
1986 component of property names to reduce the chance that two
1987 independently-developed packages use the same property name for different
1990 The values of user properties are arbitrary strings, are always inherited, and
1991 are never validated.
1992 All of the commands that operate on properties
1993 .Po Nm zfs Cm list ,
1998 can be used to manipulate both native properties and user properties.
2001 command to clear a user property.
2002 If the property is not defined in any parent dataset, it is removed entirely.
2003 Property values are limited to 8192 bytes.
projects / FreeBSD / FreeBSD.git / blob