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.
45 .Nd Native properties and user-defined of ZFS datasets.
47 Properties are divided into two types, native properties and user-defined
52 Native properties either export internal statistics or control ZFS behavior.
53 In addition, native properties are either editable or read-only.
54 User properties have no effect on ZFS behavior, but you can use them to annotate
55 datasets in a way that is meaningful in your environment.
56 For more information about user properties, see the
60 Every dataset has a set of properties that export statistics about the dataset
61 as well as control various behaviors.
62 Properties are inherited from the parent unless overridden by the child.
63 Some properties apply only to certain types of datasets
64 .Pq file systems, volumes, or snapshots .
66 The values of numeric properties can be specified using human-readable suffixes
76 The following are all valid
79 .Li 1536M, 1.5g, 1.50GB .
81 The values of non-numeric properties are case sensitive and must be lowercase,
88 The following native properties consist of read-only statistics about the
90 These properties can be neither set, nor inherited.
91 Native properties apply to all dataset types unless otherwise noted.
92 .Bl -tag -width "usedbyrefreservation"
94 The amount of space available to the dataset and all its children, assuming that
95 there is no other activity in the pool.
96 Because space is shared within a pool, availability can be limited by any number
97 of factors, including physical pool size, quotas, reservations, or other
98 datasets within the pool.
100 This property can also be referred to by its shortened column name,
103 For non-snapshots, the compression ratio achieved for the
105 space of this dataset, expressed as a multiplier.
108 property includes descendant datasets, and, for clones, does not include the
109 space shared with the origin snapshot.
115 Compression can be turned on by running:
116 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
120 The transaction group (txg) in which the dataset was created. Bookmarks have
123 as the snapshot they are initially tied to. This property is suitable for
124 ordering a list of snapshots, e.g. for incremental send and receive.
126 The time this dataset was created.
128 For snapshots, this property is a comma-separated list of filesystems or volumes
129 which are clones of this snapshot.
132 property is this snapshot.
135 property is not empty, then this snapshot can not be destroyed
142 The roles of origin and clone can be swapped by promoting the clone with the
148 if the snapshot has been marked for deferred destroy by using the
149 .Nm zfs Cm destroy Fl d
151 Otherwise, the property is
153 .It Sy encryptionroot
154 For encrypted datasets, indicates where the dataset is currently inheriting its
155 encryption key from. Loading or unloading a key for the
157 will implicitly load / unload the key for any inheriting datasets (see
160 .Nm zfs Cm unload-key
162 Clones will always share an
163 encryption key with their origin. See the
168 .It Sy filesystem_count
169 The total number of filesystems and volumes that exist under this location in
171 This value is only available when a
173 has been set somewhere in the tree under which the dataset resides.
175 Indicates if an encryption key is currently loaded into ZFS. The possible
184 .Nm zfs Cm unload-key .
186 The 64 bit GUID of this dataset or bookmark which does not change over its
187 entire lifetime. When a snapshot is sent to another pool, the received
188 snapshot has the same GUID. Thus, the
190 is suitable to identify a snapshot across pools.
191 .It Sy logicalreferenced
192 The amount of space that is
194 accessible by this dataset.
198 The logical space ignores the effect of the
202 properties, giving a quantity closer to the amount of data that applications
204 However, it does include space consumed by metadata.
206 This property can also be referred to by its shortened column name,
209 The amount of space that is
211 consumed by this dataset and all its descendents.
215 The logical space ignores the effect of the
219 properties, giving a quantity closer to the amount of data that applications
221 However, it does include space consumed by metadata.
223 This property can also be referred to by its shortened column name,
226 For file systems, indicates whether the file system is currently mounted.
227 This property can be either
232 A unique identifier for this dataset within the pool. Unlike the dataset's
236 of a dataset is not transferred to other pools when the snapshot is copied
237 with a send/receive operation.
240 can be reused (for a new dataset) after the dataset is deleted.
242 For cloned file systems or volumes, the snapshot from which the clone was
247 .It Sy receive_resume_token
248 For filesystems or volumes which have saved partially-completed state from
250 this opaque token can be provided to
252 to resume and complete the
255 For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
257 For snapshots, this is the list of snapshot guids the snapshot is redacted with
260 The amount of data that is accessible by this dataset, which may or may not be
261 shared with other datasets in the pool.
262 When a snapshot or clone is created, it initially references the same amount of
263 space as the file system or snapshot it was created from, since its contents are
266 This property can also be referred to by its shortened column name,
268 .It Sy refcompressratio
269 The compression ratio achieved for the
271 space of this dataset, expressed as a multiplier.
275 .It Sy snapshot_count
276 The total number of snapshots that exist under this location in the dataset
278 This value is only available when a
280 has been set somewhere in the tree under which the dataset resides.
288 The amount of space consumed by this dataset and all its descendents.
289 This is the value that is checked against this dataset's quota and reservation.
290 The space used does not include this dataset's reservation, but does take into
291 account the reservations of any descendent datasets.
292 The amount of space that a dataset consumes from its parent, as well as the
293 amount of space that is freed if this dataset is recursively destroyed, is the
294 greater of its space used and its reservation.
296 The used space of a snapshot
302 is space that is referenced exclusively by this snapshot.
303 If this snapshot is destroyed, the amount of
306 Space that is shared by multiple snapshots isn't accounted for in this metric.
307 When a snapshot is destroyed, space that was previously shared with this
308 snapshot can become unique to snapshots adjacent to it, thus changing the used
309 space of those snapshots.
310 The used space of the latest snapshot can also be affected by changes in the
314 space of a snapshot is a subset of the
316 space of the snapshot.
318 The amount of space used, available, or referenced does not take into account
320 Pending changes are generally accounted for within a few seconds.
321 Committing a change to a disk using
325 does not necessarily guarantee that the space usage information is updated
330 properties decompose the
332 properties into the various reasons that space is used.
335 .Sy usedbychildren No +
336 .Sy usedbydataset No +
337 .Sy usedbyrefreservation No +
338 .Sy usedbysnapshots .
339 These properties are only available for datasets created on
343 .It Sy usedbychildren
344 The amount of space used by children of this dataset, which would be freed if
345 all the dataset's children were destroyed.
347 The amount of space used by this dataset itself, which would be freed if the
348 dataset were destroyed
349 .Po after first removing any
351 and destroying any necessary snapshots or descendents
353 .It Sy usedbyrefreservation
354 The amount of space used by a
356 set on this dataset, which would be freed if the
359 .It Sy usedbysnapshots
360 The amount of space consumed by snapshots of this dataset.
361 In particular, it is the amount of space that would be freed if all of this
362 dataset's snapshots were destroyed.
363 Note that this is not simply the sum of the snapshots'
365 properties because space can be shared by multiple snapshots.
366 .It Sy userused Ns @ Ns Em user
367 The amount of space consumed by the specified user in this dataset.
368 Space is charged to the owner of each file, as displayed by
370 The amount of space charged is displayed by
376 subcommand for more information.
378 Unprivileged users can access only their own space usage.
379 The root user, or a user who has been granted the
383 can access everyone's usage.
386 .Sy userused Ns @ Ns Em ...
387 properties are not displayed by
388 .Nm zfs Cm get Sy all .
389 The user's name must be appended after the @ symbol, using one of the following
391 .Bl -bullet -width ""
405 .Sy joe.smith@mydomain
414 Files created on Linux always have POSIX owners.
415 .It Sy userobjused Ns @ Ns Em user
418 property is similar to
420 but instead it counts the number of objects consumed by a user. This property
421 counts all objects allocated on behalf of the user, it may differ from the
422 results of system tools such as
427 is set on a file system additional objects will be created per-file to store
428 extended attributes. These additional objects are reflected in the
430 value and are counted against the user's
432 When a file system is configured to use
434 no additional internal objects are normally required.
436 This property is set to the number of user holds on this snapshot.
437 User holds are set by using the
440 .It Sy groupused Ns @ Ns Em group
441 The amount of space consumed by the specified group in this dataset.
442 Space is charged to the group of each file, as displayed by
445 .Sy userused Ns @ Ns Em user
446 property for more information.
448 Unprivileged users can only access their own groups' space usage.
449 The root user, or a user who has been granted the
453 can access all groups' usage.
454 .It Sy groupobjused Ns @ Ns Em group
455 The number of objects consumed by the specified group in this dataset.
456 Multiple objects may be charged to the group for each file when extended
457 attributes are in use. See the
458 .Sy userobjused Ns @ Ns Em user
459 property for more information.
461 Unprivileged users can only access their own groups' space usage.
462 The root user, or a user who has been granted the
466 can access all groups' usage.
467 .It Sy projectused Ns @ Ns Em project
468 The amount of space consumed by the specified project in this dataset. Project
469 is identified via the project identifier (ID) that is object-based numeral
470 attribute. An object can inherit the project ID from its parent object (if the
471 parent has the flag of inherit project ID that can be set and changed via
474 .Nm zfs project Fl s )
475 when being created. The privileged user can set and change object's project
480 anytime. Space is charged to the project of each file, as displayed by
485 .Sy userused Ns @ Ns Em user
486 property for more information.
488 The root user, or a user who has been granted the
492 can access all projects' usage.
493 .It Sy projectobjused Ns @ Ns Em project
498 but instead it counts the number of objects consumed by project. When the
501 is set on a fileset, ZFS will create additional objects per-file to store
502 extended attributes. These additional objects are reflected in the
504 value and are counted against the project's
505 .Sy projectobjquota .
506 When a filesystem is configured to use
508 no additional internal objects are required. See the
509 .Sy userobjused Ns @ Ns Em user
510 property for more information.
512 The root user, or a user who has been granted the
516 can access all projects' objects usage.
518 For volumes, specifies the block size of the volume.
521 cannot be changed once the volume has been written, so it should be set at
522 volume creation time.
525 for volumes is 8 Kbytes.
526 Any power of 2 from 512 bytes to 128 Kbytes is valid.
528 This property can also be referred to by its shortened column name,
533 by this dataset, that was written since the previous snapshot
534 .Pq i.e. that is not referenced by the previous snapshot .
535 .It Sy written Ns @ Ns Em snapshot
538 space written to this dataset since the specified snapshot.
539 This is the space that is referenced by this dataset but was not referenced by
540 the specified snapshot.
544 may be specified as a short snapshot name
545 .Po just the part after the
548 in which case it will be interpreted as a snapshot in the same filesystem as
552 may be a full snapshot name
553 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
554 which for clones may be a snapshot in the origin's filesystem
555 .Pq or the origin of the origin's filesystem, etc.
558 The following native properties can be used to change the behavior of a ZFS
562 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
563 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
565 Controls how ACEs are inherited when files and directories are created.
566 .Bl -tag -width "passthrough-x"
568 does not inherit any ACEs.
570 only inherits inheritable ACEs that specify
578 permissions when the ACE is inherited.
580 inherits all inheritable ACEs without any modifications.
589 ACEs inherit the execute permission only if the file creation mode also requests
593 When the property value is set to
595 files are created with a mode determined by the inheritable ACEs.
596 If no inheritable ACEs exist that affect the mode, then the mode is set in
597 accordance to the requested mode from the application.
601 property does not apply to POSIX ACLs.
602 .It Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns Sy passthrough
608 This property is not visible on Linux yet.
609 .Bl -tag -width "passthrough"
613 entries that do not represent the mode of the file.
615 reduces permissions granted in all
619 such that they are no greater than the group permissions specified by
622 indicates that no changes are made to the
624 other than creating or updating the necessary
626 entries to represent the new mode of the file or directory.
630 operation to return an error when used on any file or directory which has
633 whose entries can not be represented by a mode.
635 is required to change the set user ID, set group ID, or sticky bits on a file
636 or directory, as they do not have equivalent
641 on a file or directory with a non-trivial
647 you must first remove all
649 entries which do not represent the current mode.
651 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
652 Controls whether ACLs are enabled and if so what type of ACL to use.
653 This property is not visible on FreeBSD yet.
654 .Bl -tag -width "posixacl"
656 default, when a file system has the
658 property set to off then ACLs are disabled.
663 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
664 not functional on other platforms. POSIX ACLs are stored as an extended
665 attribute and therefore will not overwrite any existing NFSv4 ACLs which
669 To obtain the best performance when setting
671 users are strongly encouraged to set the
673 property. This will result in the POSIX ACL being stored more efficiently on
674 disk. But as a consequence, all new extended attributes will only be
675 accessible from OpenZFS implementations which support the
679 property for more details.
680 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
681 Controls whether the access time for files is updated when they are read.
682 Turning this property off avoids producing write traffic when reading files and
683 can result in significant performance gains, though it might confuse mailers
684 and other similar utilities. The values
688 are equivalent to the
692 mount options. The default value is
697 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
698 If this property is set to
700 the file system cannot be mounted, and is ignored by
701 .Nm zfs Cm mount Fl a .
702 Setting this property to
704 is similar to setting the
708 except that the dataset still has a normal
710 property, which can be inherited.
711 Setting this property to
713 allows datasets to be used solely as a mechanism to inherit properties.
714 One example of setting
715 .Sy canmount Ns = Ns Sy off
716 is to have two datasets with the same
718 so that the children of both datasets appear in the same directory, but might
719 have different inherited characteristics.
723 a dataset can only be mounted and unmounted explicitly.
724 The dataset is not mounted automatically when the dataset is created or
725 imported, nor is it mounted by the
726 .Nm zfs Cm mount Fl a
727 command or unmounted by the
728 .Nm zfs Cm unmount Fl a
731 This property is not inherited.
733 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
734 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
735 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
737 Controls the checksum used to verify data integrity.
740 which automatically selects an appropriate algorithm
743 but this may change in future releases
747 disables integrity checking on user data.
750 not only disables integrity but also disables maintaining parity for user data.
751 This setting is used internally by a dump device residing on a RAID-Z pool and
752 should not be used by any other dataset.
753 Disabling checksums is
755 a recommended practice.
762 checksum algorithms require enabling the appropriate features on the pool.
763 These pool features are not supported by GRUB and must not be used on the
764 pool if GRUB needs to access the pool (e.g. for /boot).
765 FreeBSD does not support the
771 for more information on these algorithms.
773 Changing this property affects only newly-written data.
775 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
776 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
778 Controls the compression algorithm used for this dataset.
780 Setting compression to
782 indicates that the current default compression algorithm should be used.
783 The default balances compression and decompression speed, with compression ratio
784 and is expected to work well on a wide variety of workloads.
785 Unlike all other settings for this property,
787 does not select a fixed compression type.
788 As new compression algorithms are added to ZFS and enabled on a pool, the
789 default compression algorithm may change.
790 The current default compression algorithm is either
799 compression algorithm is a high-performance replacement for the
802 It features significantly faster compression and decompression, as well as a
803 moderately higher compression ratio than
805 but can only be used on pools with the
811 for details on ZFS feature flags and the
817 compression algorithm is optimized for performance while providing decent data
822 compression algorithm uses the same compression as the
827 level by using the value
834 .Pq best compression ratio .
839 .Po which is also the default for
845 compression algorithm compresses runs of zeros.
847 This property can also be referred to by its shortened column name
849 Changing this property affects only newly-written data.
851 When any setting except
853 is selected, compression will explicitly check for blocks consisting of only
854 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
855 a hole and not compressed using the indicated compression algorithm.
857 Any block being compressed must be no larger than 7/8 of its original size
858 after compression, otherwise the compression will not be considered worthwhile
859 and the block saved uncompressed. Note that when the logical block is less than
860 8 times the disk sector size this effectively reduces the necessary compression
861 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
862 or less of their original size.
864 .Sy context Ns = Ns Sy none Ns | Ns
865 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
867 This flag sets the SELinux context for all files in the file system under
868 a mount point for that file system. See
870 for more information.
872 .Sy fscontext Ns = Ns Sy none Ns | Ns
873 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
875 This flag sets the SELinux context for the file system file system being
878 for more information.
880 .Sy defcontext Ns = Ns Sy none Ns | Ns
881 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
883 This flag sets the SELinux default context for unlabeled files. See
885 for more information.
887 .Sy rootcontext Ns = Ns Sy none Ns | Ns
888 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
890 This flag sets the SELinux context for the root inode of the file system. See
892 for more information.
893 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
894 Controls the number of copies of data stored for this dataset.
895 These copies are in addition to any redundancy provided by the pool, for
896 example, mirroring or RAID-Z.
897 The copies are stored on different disks, if possible.
898 The space used by multiple copies is charged to the associated file and dataset,
901 property and counting against quotas and reservations.
903 Changing this property only affects newly-written data.
904 Therefore, set this property at file system creation time by using the
905 .Fl o Sy copies Ns = Ns Ar N
908 Remember that ZFS will not import a pool with a missing top-level vdev. Do
910 create, for example a two-disk striped pool and set
912 on some datasets thinking you have setup redundancy for them. When a disk
913 fails you will not be able to import the pool and will have lost all of your
916 Encrypted datasets may not have
917 .Sy copies Ns = Ns Em 3
918 since the implementation stores some encryption metadata where the third copy
920 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
921 Controls whether device nodes can be opened on this file system.
928 are equivalent to the
934 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
935 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
938 Configures deduplication for a dataset. The default value is
940 The default deduplication checksum is
942 (this may change in the future). When
944 is enabled, the checksum defined here overrides the
946 property. Setting the value to
948 has the same effect as the setting
953 ZFS will do a byte-to-byte comparison in case of two blocks having the same
954 signature to make sure the block contents are identical. Specifying
960 Unless necessary, deduplication should NOT be enabled on a system. See the
965 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
966 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
968 Specifies a compatibility mode or literal value for the size of dnodes in the
969 file system. The default value is
971 Setting this property to a value other than
973 requires the large_dnode pool feature to be enabled.
979 if the dataset uses the
981 property setting and the workload makes heavy use of extended attributes. This
982 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
983 servers, for example. Literal values are supported for cases where the optimal
984 size is known in advance and for performance testing.
990 if you need to receive a send stream of this dataset on a pool that doesn't
991 enable the large_dnode feature, or if you need to import this pool on a system
992 that doesn't support the large_dnode feature.
994 This property can also be referred to by its shortened column name,
997 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
998 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
999 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1001 Controls the encryption cipher suite (block cipher, key length, and mode) used
1002 for this dataset. Requires the
1004 feature to be enabled on the pool.
1007 to be set at dataset creation time.
1010 .Sy encryption Ns = Ns Sy on
1011 when creating a dataset indicates that the default encryption suite will be
1012 selected, which is currently
1014 In order to provide consistent data protection, encryption must be specified at
1015 dataset creation time and it cannot be changed afterwards.
1017 For more details and caveats about encryption see the
1020 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1021 Controls what format the user's encryption key will be provided as. This
1022 property is only set when the dataset is encrypted.
1024 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1025 encryption suite) and must be randomly generated. A raw key can be generated
1026 with the following command:
1028 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1031 Passphrases must be between 8 and 512 bytes long and will be processed through
1032 PBKDF2 before being used (see the
1034 property). Even though the
1035 encryption suite cannot be changed after dataset creation, the keyformat can be
1037 .Nm zfs Cm change-key .
1039 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1041 Controls where the user's encryption key will be loaded from by default for
1045 .Nm zfs Cm mount Cm -l .
1046 This property is only set for encrypted datasets which are encryption roots. If
1047 unspecified, the default is
1050 Even though the encryption suite cannot be changed after dataset creation, the
1051 keylocation can be with either
1054 .Nm zfs Cm change-key .
1057 is selected ZFS will ask for the key at the command prompt when it is required
1058 to access the encrypted data (see
1060 for details). This setting will also allow the key to be passed in via STDIN,
1061 but users should be careful not to place keys which should be kept secret on
1062 the command line. If a file URI is selected, the key will be loaded from the
1063 specified absolute file path.
1064 .It Sy pbkdf2iters Ns = Ns Ar iterations
1065 Controls the number of PBKDF2 iterations that a
1067 encryption key should be run through when processing it into an encryption key.
1068 This property is only defined when encryption is enabled and a keyformat of
1070 is selected. The goal of PBKDF2 is to significantly increase the
1071 computational difficulty needed to brute force a user's passphrase. This is
1072 accomplished by forcing the attacker to run each passphrase through a
1073 computationally expensive hashing function many times before they arrive at the
1074 resulting key. A user who actually knows the passphrase will only have to pay
1075 this cost once. As CPUs become better at processing, this number should be
1076 raised to ensure that a brute force attack is still not possible. The current
1081 This property may be changed with
1082 .Nm zfs Cm change-key .
1083 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1084 Controls whether processes can be executed from within this file system.
1085 The default value is
1091 are equivalent to the
1096 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1097 Limits the number of filesystems and volumes that can exist under this point in
1099 The limit is not enforced if the user is allowed to change the limit.
1101 .Sy filesystem_limit
1104 a descendent of a filesystem that already has a
1105 .Sy filesystem_limit
1106 does not override the ancestor's
1107 .Sy filesystem_limit ,
1108 but rather imposes an additional limit.
1109 This feature must be enabled to be used
1111 .Xr zpool-features 5
1113 .It Sy special_small_blocks Ns = Ns Em size
1114 This value represents the threshold block size for including small file
1115 blocks into the special allocation class. Blocks smaller than or equal to this
1116 value will be assigned to the special allocation class while greater blocks
1117 will be assigned to the regular class. Valid values are zero or a power of two
1118 from 512B up to 1M. The default size is 0 which means no small file blocks
1119 will be allocated in the special class.
1121 Before setting this property, a special class vdev must be added to the
1124 for more details on the special allocation class.
1125 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1126 Controls the mount point used for this file system.
1131 for more information on how this property is used.
1135 property is changed for a file system, the file system and any children that
1136 inherit the mount point are unmounted.
1139 then they remain unmounted.
1140 Otherwise, they are automatically remounted in the new location if the property
1145 or if they were mounted before the property was changed.
1146 In addition, any shared file systems are unshared and shared in the new
1148 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1149 Controls whether the file system should be mounted with
1151 .Pq Non Blocking mandatory locks .
1152 This is used for SMB clients.
1153 Changes to this property only take effect when the file system is umounted and
1157 for more information on
1159 mounts. This property is not used on Linux.
1160 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1161 Allow mounting on a busy directory or a directory which already contains
1162 files or directories. This is the default mount behavior for Linux file systems.
1163 For consistency with OpenZFS on other platforms overlay mounts are
1167 to enable overlay mounts.
1168 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1169 Controls what is cached in the primary cache
1171 If this property is set to
1173 then both user data and metadata is cached.
1174 If this property is set to
1176 then neither user data nor metadata is cached.
1177 If this property is set to
1179 then only metadata is cached.
1180 The default value is
1182 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1183 Limits the amount of space a dataset and its descendents can consume.
1184 This property enforces a hard limit on the amount of space used.
1185 This includes all space consumed by descendents, including file systems and
1187 Setting a quota on a descendent of a dataset that already has a quota does not
1188 override the ancestor's quota, but rather imposes an additional limit.
1190 Quotas cannot be set on volumes, as the
1192 property acts as an implicit quota.
1193 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1194 Limits the number of snapshots that can be created on a dataset and its
1198 on a descendent of a dataset that already has a
1200 does not override the ancestor's
1201 .Sy snapshot_limit ,
1202 but rather imposes an additional limit.
1203 The limit is not enforced if the user is allowed to change the limit.
1204 For example, this means that recursive snapshots taken from the global zone are
1205 counted against each delegated dataset within a zone.
1206 This feature must be enabled to be used
1208 .Xr zpool-features 5
1210 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1211 Limits the amount of space consumed by the specified user.
1212 User space consumption is identified by the
1213 .Sy userspace@ Ns Em user
1216 Enforcement of user quotas may be delayed by several seconds.
1217 This delay means that a user might exceed their quota before the system notices
1218 that they are over quota and begins to refuse additional writes with the
1222 .Nm zfs Cm userspace
1223 subcommand for more information.
1225 Unprivileged users can only access their own groups' space usage.
1226 The root user, or a user who has been granted the
1230 can get and set everyone's quota.
1232 This property is not available on volumes, on file systems before version 4, or
1233 on pools before version 15.
1235 .Sy userquota@ Ns Em ...
1236 properties are not displayed by
1237 .Nm zfs Cm get Sy all .
1238 The user's name must be appended after the
1240 symbol, using one of the following forms:
1248 .Em POSIX numeric ID
1255 .Sy joe.smith@mydomain
1264 Files created on Linux always have POSIX owners.
1265 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1270 but it limits the number of objects a user can create. Please refer to
1272 for more information about how objects are counted.
1273 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1274 Limits the amount of space consumed by the specified group.
1275 Group space consumption is identified by the
1276 .Sy groupused@ Ns Em group
1279 Unprivileged users can access only their own groups' space usage.
1280 The root user, or a user who has been granted the
1284 can get and set all groups' quotas.
1285 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1290 but it limits number of objects a group can consume. Please refer to
1292 for more information about how objects are counted.
1293 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1294 Limits the amount of space consumed by the specified project. Project
1295 space consumption is identified by the
1296 .Sy projectused@ Ns Em project
1297 property. Please refer to
1299 for more information about how project is identified and set/changed.
1301 The root user, or a user who has been granted the
1305 can access all projects' quota.
1306 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1311 but it limits number of objects a project can consume. Please refer to
1313 for more information about how objects are counted.
1314 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1315 Controls whether this dataset can be modified.
1316 The default value is
1322 are equivalent to the
1328 This property can also be referred to by its shortened column name,
1330 .It Sy recordsize Ns = Ns Em size
1331 Specifies a suggested block size for files in the file system.
1332 This property is designed solely for use with database workloads that access
1333 files in fixed-size records.
1334 ZFS automatically tunes block sizes according to internal algorithms optimized
1335 for typical access patterns.
1337 For databases that create very large files but access them in small random
1338 chunks, these algorithms may be suboptimal.
1341 greater than or equal to the record size of the database can result in
1342 significant performance gains.
1343 Use of this property for general purpose file systems is strongly discouraged,
1344 and may adversely affect performance.
1346 The size specified must be a power of two greater than or equal to 512 and less
1347 than or equal to 128 Kbytes.
1350 feature is enabled on the pool, the size may be up to 1 Mbyte.
1352 .Xr zpool-features 5
1353 for details on ZFS feature flags.
1355 Changing the file system's
1357 affects only files created afterward; existing files are unaffected.
1359 This property can also be referred to by its shortened column name,
1361 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1362 Controls what types of metadata are stored redundantly.
1363 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1364 the amount of user data lost is limited.
1365 This extra copy is in addition to any redundancy provided at the pool level
1366 .Pq e.g. by mirroring or RAID-Z ,
1367 and is in addition to an extra copy specified by the
1370 .Pq up to a total of 3 copies .
1371 For example if the pool is mirrored,
1372 .Sy copies Ns = Ns 2 ,
1374 .Sy redundant_metadata Ns = Ns Sy most ,
1375 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1380 ZFS stores an extra copy of all metadata.
1381 If a single on-disk block is corrupt, at worst a single block of user data
1390 ZFS stores an extra copy of most types of metadata.
1391 This can improve performance of random writes, because less metadata must be
1393 In practice, at worst about 100 blocks
1398 of user data can be lost if a single on-disk block is corrupt.
1399 The exact behavior of which metadata blocks are stored redundantly may change in
1402 The default value is
1404 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1405 Limits the amount of space a dataset can consume.
1406 This property enforces a hard limit on the amount of space used.
1407 This hard limit does not include space used by descendents, including file
1408 systems and snapshots.
1409 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1410 The minimum amount of space guaranteed to a dataset, not including its
1412 When the amount of space used is below this value, the dataset is treated as if
1413 it were taking up the amount of space specified by
1414 .Sy refreservation .
1417 reservation is accounted for in the parent datasets' space used, and counts
1418 against the parent datasets' quotas and reservations.
1422 is set, a snapshot is only allowed if there is enough free pool space outside of
1423 this reservation to accommodate the current number of
1425 bytes in the dataset.
1431 a volume is thick provisioned
1435 .Sy refreservation Ns = Ns Sy auto
1436 is only supported on volumes.
1440 .Sx Native Properties
1441 section for more information about sparse volumes.
1443 This property can also be referred to by its shortened column name,
1445 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1446 Controls the manner in which the access time is updated when
1448 is set. Turning this property on causes the access time to be updated relative
1449 to the modify or change time. Access time is only updated if the previous
1450 access time was earlier than the current modify or change time or if the
1451 existing access time hasn't been updated within the past 24 hours. The default
1458 are equivalent to the
1463 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1464 The minimum amount of space guaranteed to a dataset and its descendants.
1465 When the amount of space used is below this value, the dataset is treated as if
1466 it were taking up the amount of space specified by its reservation.
1467 Reservations are accounted for in the parent datasets' space used, and count
1468 against the parent datasets' quotas and reservations.
1470 This property can also be referred to by its shortened column name,
1472 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1473 Controls what is cached in the secondary cache
1475 If this property is set to
1477 then both user data and metadata is cached.
1478 If this property is set to
1480 then neither user data nor metadata is cached.
1481 If this property is set to
1483 then only metadata is cached.
1484 The default value is
1486 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1487 Controls whether the setuid bit is respected for the file system.
1488 The default value is
1494 are equivalent to the
1499 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1500 Controls whether the file system is shared by using
1501 .Sy Samba USERSHARES
1502 and what options are to be used. Otherwise, the file system is automatically
1503 shared and unshared with the
1507 commands. If the property is set to on, the
1509 command is invoked to create a
1512 Because SMB shares requires a resource name, a unique resource name is
1513 constructed from the dataset name. The constructed name is a copy of the
1514 dataset name except that the characters in the dataset name, which would be
1515 invalid in the resource name, are replaced with underscore (_) characters.
1516 Linux does not currently support additional options which might be available
1523 the file systems are unshared.
1525 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1526 stands for "full permissions", ie. read and write permissions) and no guest
1527 access (which means Samba must be able to authenticate a real user, system
1528 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1529 additional access control (disallow specific user specific access etc) must
1530 be done on the underlying file system.
1531 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1532 Controls whether the file system is shared via NFS, and what options are to be
1534 A file system with a
1540 command and entries in the
1543 Otherwise, the file system is automatically shared and unshared with the
1548 If the property is set to
1550 the dataset is shared using the default options:
1552 .Em sec=sys,rw,crossmnt,no_subtree_check
1556 for the meaning of the default options. Otherwise, the
1558 command is invoked with options equivalent to the contents of this property.
1562 property is changed for a dataset, the dataset and any children inheriting the
1563 property are re-shared with the new options, only if the property was previously
1565 or if they were shared before the property was changed.
1566 If the new property is
1568 the file systems are unshared.
1569 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1570 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1576 ZFS will use pool log devices
1578 to handle the requests at low latency.
1583 ZFS will not use configured pool log devices.
1584 ZFS will instead optimize synchronous operations for global pool throughput and
1585 efficient use of resources.
1586 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1587 Controls whether the volume snapshot devices under
1588 .Em /dev/zvol/<pool>
1589 are hidden or visible. The default value is
1591 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1592 Controls whether the
1594 directory is hidden or visible in the root of the file system as discussed in
1599 The default value is
1601 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1602 Controls the behavior of synchronous requests
1603 .Pq e.g. fsync, O_DSYNC .
1607 specified behavior of ensuring all synchronous requests are written to stable
1608 storage and all devices are flushed to ensure data is not cached by device
1610 .Pq this is the default .
1612 causes every file system transaction to be written and flushed before its
1613 system call returns.
1614 This has a large performance penalty.
1616 disables synchronous requests.
1617 File system transactions are only committed to stable storage periodically.
1618 This option will give the highest performance.
1619 However, it is very dangerous as ZFS would be ignoring the synchronous
1620 transaction demands of applications such as databases or NFS.
1621 Administrators should only use this option when the risks are understood.
1622 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1623 The on-disk version of this file system, which is independent of the pool
1625 This property can only be set to later supported versions.
1629 .It Sy volsize Ns = Ns Em size
1630 For volumes, specifies the logical size of the volume.
1631 By default, creating a volume establishes a reservation of equal size.
1632 For storage pools with a version number of 9 or higher, a
1637 are reflected in an equivalent change to the reservation
1643 can only be set to a multiple of
1647 The reservation is kept equal to the volume's logical size to prevent unexpected
1648 behavior for consumers.
1649 Without the reservation, the volume could run out of space, resulting in
1650 undefined behavior or data corruption, depending on how the volume is used.
1651 These effects can also occur when the volume size is changed while it is in use
1652 .Pq particularly when shrinking the size .
1653 Extreme care should be used when adjusting the volume size.
1655 Though not recommended, a
1658 .Qq thin provisioned
1660 can be created by specifying the
1663 .Nm zfs Cm create Fl V
1664 command, or by changing the value of the
1669 property on pool version 8 or earlier
1671 after the volume has been created.
1674 is a volume where the value of
1676 is less than the size of the volume plus the space required to store its
1678 Consequently, writes to a sparse volume can fail with
1680 when the pool is low on space.
1681 For a sparse volume, changes to
1683 are not reflected in the
1685 A volume that is not sparse is said to be
1686 .Qq thick provisioned .
1687 A sparse volume can become thick provisioned by setting
1691 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1692 This property specifies how volumes should be exposed to the OS.
1695 exposes volumes as fully fledged block devices, providing maximal
1696 functionality. The value
1698 is just an alias for
1700 and is kept for compatibility.
1703 hides its partitions.
1704 Volumes with property set to
1706 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
1707 that can be suitable for backup purposes.
1710 means that volumes exposition is controlled by system-wide tunable
1717 are encoded as 1, 2 and 3 respectively.
1718 The default values is
1720 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1721 Controls whether regular files should be scanned for viruses when a file is
1723 In addition to enabling this property, the virus scan service must also be
1724 enabled for virus scanning to occur.
1725 The default value is
1727 This property is not used on Linux.
1728 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1729 Controls whether extended attributes are enabled for this file system. Two
1730 styles of extended attributes are supported either directory based or system
1733 The default value of
1735 enables directory based extended attributes. This style of extended attribute
1736 imposes no practical limit on either the size or number of attributes which
1737 can be set on a file. Although under Linux the
1741 system calls limit the maximum size to 64K. This is the most compatible
1742 style of extended attribute and is supported by all OpenZFS implementations.
1744 System attribute based xattrs can be enabled by setting the value to
1746 The key advantage of this type of xattr is improved performance. Storing
1747 extended attributes as system attributes significantly decreases the amount of
1748 disk IO required. Up to 64K of data may be stored per-file in the space
1749 reserved for system attributes. If there is not enough space available for
1750 an extended attribute then it will be automatically written as a directory
1751 based xattr. System attribute based extended attributes are not accessible
1752 on platforms which do not support the
1756 The use of system attribute based xattrs is strongly encouraged for users of
1757 SELinux or POSIX ACLs. Both of these features heavily rely of extended
1758 attributes and benefit significantly from the reduced access time.
1764 are equivalent to the
1769 .It Sy jailed Ns = Ns Cm off | on
1770 Controls whether the dataset is managed from a jail. See the
1774 for more information. Jails are a FreeBSD feature and are not relevant on
1775 other platforms. The default value is
1777 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1778 Controls whether the dataset is managed from a non-global zone. Zones are a
1779 Solaris feature and are not relevant on other platforms. The default value is
1783 The following three properties cannot be changed after the file system is
1784 created, and therefore, should be set when the file system is created.
1785 If the properties are not set with the
1789 commands, these properties are inherited from the parent dataset.
1790 If the parent dataset lacks these properties due to having been created prior to
1791 these features being supported, the new file system will have the default values
1792 for these properties.
1795 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1796 .Sy insensitive Ns | Ns Sy mixed
1798 Indicates whether the file name matching algorithm used by the file system
1799 should be case-sensitive, case-insensitive, or allow a combination of both
1801 The default value for the
1809 file systems have case-sensitive file names.
1815 property indicates that the file system can support requests for both
1816 case-sensitive and case-insensitive matching behavior.
1817 Currently, case-insensitive matching behavior on a file system that supports
1818 mixed behavior is limited to the SMB server product.
1819 For more information about the
1821 value behavior, see the "ZFS Administration Guide".
1823 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1824 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1826 Indicates whether the file system should perform a
1828 normalization of file names whenever two file names are compared, and which
1829 normalization algorithm should be used.
1830 File names are always stored unmodified, names are normalized as part of any
1832 If this property is set to a legal value other than
1836 property was left unspecified, the
1838 property is automatically set to
1840 The default value of the
1844 This property cannot be changed after the file system is created.
1845 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1846 Indicates whether the file system should reject file names that include
1847 characters that are not present in the
1850 If this property is explicitly set to
1852 the normalization property must either not be explicitly set or be set to
1854 The default value for the
1858 This property cannot be changed after the file system is created.
1862 .Sy casesensitivity ,
1866 properties are also new permissions that can be assigned to non-privileged users
1867 by using the ZFS delegated administration feature.
1868 .Ss "Temporary Mount Point Properties"
1869 When a file system is mounted, either through
1871 for legacy mounts or the
1873 command for normal file systems, its mount options are set according to its
1875 The correlation between properties and mount options is as follows:
1877 PROPERTY MOUNT OPTION
1879 canmount auto/noauto
1883 relatime relatime/norelatime
1888 In addition, these options can be set on a per-mount basis using the
1890 option, without affecting the property that is stored on disk.
1891 The values specified on the command line override the values stored in the
1895 option is an alias for
1896 .Sy nodevices Ns \&, Ns Sy nosetuid .
1897 These properties are reported as
1902 If the properties are changed while the dataset is mounted, the new setting
1903 overrides any temporary settings.
1904 .Ss "User Properties"
1905 In addition to the standard native properties, ZFS supports arbitrary user
1907 User properties have no effect on ZFS behavior, but applications or
1908 administrators can use them to annotate datasets
1909 .Pq file systems, volumes, and snapshots .
1911 User property names must contain a colon
1913 character to distinguish them from native properties.
1914 They may contain lowercase letters, numbers, and the following punctuation
1923 The expected convention is that the property name is divided into two portions
1925 .Em module Ns \&: Ns Em property ,
1926 but this namespace is not enforced by ZFS.
1927 User property names can be at most 256 characters, and cannot begin with a dash
1930 When making programmatic use of user properties, it is strongly suggested to use
1935 component of property names to reduce the chance that two
1936 independently-developed packages use the same property name for different
1939 The values of user properties are arbitrary strings, are always inherited, and
1940 are never validated.
1941 All of the commands that operate on properties
1942 .Po Nm zfs Cm list ,
1947 can be used to manipulate both native properties and user properties.
1950 command to clear a user property.
1951 If the property is not defined in any parent dataset, it is removed entirely.
1952 Property values are limited to 8192 bytes.
projects / mirror_zfs.git / blob