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.
603 .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
604 .Sy passthrough Ns | Ns Sy restricted Ns
606 Controls how an ACL is modified during chmod(2) and how inherited ACEs
607 are modified by the file creation mode.
608 .Bl -tag -width "passthrough"
612 except for those representing
613 the mode of the file or directory requested by
616 reduces permissions granted in all
620 such that they are no greater than the group permissions specified by
623 indicates that no changes are made to the
625 other than creating or updating the necessary
627 entries to represent the new mode of the file or directory.
631 operation to return an error when used on any file or directory which has
634 whose entries can not be represented by a mode.
636 is required to change the set user ID, set group ID, or sticky bits on a file
637 or directory, as they do not have equivalent
642 on a file or directory with a non-trivial
648 you must first remove all
650 entries which do not represent the current mode.
652 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
653 Controls whether ACLs are enabled and if so what type of ACL to use.
654 This property is not visible on FreeBSD yet.
655 .Bl -tag -width "posixacl"
657 default, when a file system has the
659 property set to off then ACLs are disabled.
664 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
665 not functional on other platforms. POSIX ACLs are stored as an extended
666 attribute and therefore will not overwrite any existing NFSv4 ACLs which
670 To obtain the best performance when setting
672 users are strongly encouraged to set the
674 property. This will result in the POSIX ACL being stored more efficiently on
675 disk. But as a consequence, all new extended attributes will only be
676 accessible from OpenZFS implementations which support the
680 property for more details.
681 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
682 Controls whether the access time for files is updated when they are read.
683 Turning this property off avoids producing write traffic when reading files and
684 can result in significant performance gains, though it might confuse mailers
685 and other similar utilities. The values
689 are equivalent to the
693 mount options. The default value is
698 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
699 If this property is set to
701 the file system cannot be mounted, and is ignored by
702 .Nm zfs Cm mount Fl a .
703 Setting this property to
705 is similar to setting the
709 except that the dataset still has a normal
711 property, which can be inherited.
712 Setting this property to
714 allows datasets to be used solely as a mechanism to inherit properties.
715 One example of setting
716 .Sy canmount Ns = Ns Sy off
717 is to have two datasets with the same
719 so that the children of both datasets appear in the same directory, but might
720 have different inherited characteristics.
724 a dataset can only be mounted and unmounted explicitly.
725 The dataset is not mounted automatically when the dataset is created or
726 imported, nor is it mounted by the
727 .Nm zfs Cm mount Fl a
728 command or unmounted by the
729 .Nm zfs Cm unmount Fl a
732 This property is not inherited.
734 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
735 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
736 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
738 Controls the checksum used to verify data integrity.
741 which automatically selects an appropriate algorithm
744 but this may change in future releases
748 disables integrity checking on user data.
751 not only disables integrity but also disables maintaining parity for user data.
752 This setting is used internally by a dump device residing on a RAID-Z pool and
753 should not be used by any other dataset.
754 Disabling checksums is
756 a recommended practice.
763 checksum algorithms require enabling the appropriate features on the pool.
764 These pool features are not supported by GRUB and must not be used on the
765 pool if GRUB needs to access the pool (e.g. for /boot).
766 FreeBSD does not support the
772 for more information on these algorithms.
774 Changing this property affects only newly-written data.
776 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
777 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
779 Controls the compression algorithm used for this dataset.
781 Setting compression to
783 indicates that the current default compression algorithm should be used.
784 The default balances compression and decompression speed, with compression ratio
785 and is expected to work well on a wide variety of workloads.
786 Unlike all other settings for this property,
788 does not select a fixed compression type.
789 As new compression algorithms are added to ZFS and enabled on a pool, the
790 default compression algorithm may change.
791 The current default compression algorithm is either
800 compression algorithm is a high-performance replacement for the
803 It features significantly faster compression and decompression, as well as a
804 moderately higher compression ratio than
806 but can only be used on pools with the
812 for details on ZFS feature flags and the
818 compression algorithm is optimized for performance while providing decent data
823 compression algorithm uses the same compression as the
828 level by using the value
835 .Pq best compression ratio .
840 .Po which is also the default for
846 compression algorithm compresses runs of zeros.
848 This property can also be referred to by its shortened column name
850 Changing this property affects only newly-written data.
852 When any setting except
854 is selected, compression will explicitly check for blocks consisting of only
855 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
856 a hole and not compressed using the indicated compression algorithm.
858 Any block being compressed must be no larger than 7/8 of its original size
859 after compression, otherwise the compression will not be considered worthwhile
860 and the block saved uncompressed. Note that when the logical block is less than
861 8 times the disk sector size this effectively reduces the necessary compression
862 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
863 or less of their original size.
865 .Sy context Ns = Ns Sy none Ns | Ns
866 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
868 This flag sets the SELinux context for all files in the file system under
869 a mount point for that file system. See
871 for more information.
873 .Sy fscontext Ns = Ns Sy none Ns | Ns
874 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
876 This flag sets the SELinux context for the file system file system being
879 for more information.
881 .Sy defcontext Ns = Ns Sy none Ns | Ns
882 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
884 This flag sets the SELinux default context for unlabeled files. See
886 for more information.
888 .Sy rootcontext Ns = Ns Sy none Ns | Ns
889 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
891 This flag sets the SELinux context for the root inode of the file system. See
893 for more information.
894 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
895 Controls the number of copies of data stored for this dataset.
896 These copies are in addition to any redundancy provided by the pool, for
897 example, mirroring or RAID-Z.
898 The copies are stored on different disks, if possible.
899 The space used by multiple copies is charged to the associated file and dataset,
902 property and counting against quotas and reservations.
904 Changing this property only affects newly-written data.
905 Therefore, set this property at file system creation time by using the
906 .Fl o Sy copies Ns = Ns Ar N
909 Remember that ZFS will not import a pool with a missing top-level vdev. Do
911 create, for example a two-disk striped pool and set
913 on some datasets thinking you have setup redundancy for them. When a disk
914 fails you will not be able to import the pool and will have lost all of your
917 Encrypted datasets may not have
918 .Sy copies Ns = Ns Em 3
919 since the implementation stores some encryption metadata where the third copy
921 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
922 Controls whether device nodes can be opened on this file system.
929 are equivalent to the
935 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
936 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
939 Configures deduplication for a dataset. The default value is
941 The default deduplication checksum is
943 (this may change in the future). When
945 is enabled, the checksum defined here overrides the
947 property. Setting the value to
949 has the same effect as the setting
954 ZFS will do a byte-to-byte comparison in case of two blocks having the same
955 signature to make sure the block contents are identical. Specifying
961 Unless necessary, deduplication should NOT be enabled on a system. See the
966 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
967 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
969 Specifies a compatibility mode or literal value for the size of dnodes in the
970 file system. The default value is
972 Setting this property to a value other than
974 requires the large_dnode pool feature to be enabled.
980 if the dataset uses the
982 property setting and the workload makes heavy use of extended attributes. This
983 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
984 servers, for example. Literal values are supported for cases where the optimal
985 size is known in advance and for performance testing.
991 if you need to receive a send stream of this dataset on a pool that doesn't
992 enable the large_dnode feature, or if you need to import this pool on a system
993 that doesn't support the large_dnode feature.
995 This property can also be referred to by its shortened column name,
998 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
999 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1000 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1002 Controls the encryption cipher suite (block cipher, key length, and mode) used
1003 for this dataset. Requires the
1005 feature to be enabled on the pool.
1008 to be set at dataset creation time.
1011 .Sy encryption Ns = Ns Sy on
1012 when creating a dataset indicates that the default encryption suite will be
1013 selected, which is currently
1015 In order to provide consistent data protection, encryption must be specified at
1016 dataset creation time and it cannot be changed afterwards.
1018 For more details and caveats about encryption see the
1021 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1022 Controls what format the user's encryption key will be provided as. This
1023 property is only set when the dataset is encrypted.
1025 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1026 encryption suite) and must be randomly generated. A raw key can be generated
1027 with the following command:
1029 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1032 Passphrases must be between 8 and 512 bytes long and will be processed through
1033 PBKDF2 before being used (see the
1035 property). Even though the
1036 encryption suite cannot be changed after dataset creation, the keyformat can be
1038 .Nm zfs Cm change-key .
1040 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1042 Controls where the user's encryption key will be loaded from by default for
1046 .Nm zfs Cm mount Cm -l .
1047 This property is only set for encrypted datasets which are encryption roots. If
1048 unspecified, the default is
1051 Even though the encryption suite cannot be changed after dataset creation, the
1052 keylocation can be with either
1055 .Nm zfs Cm change-key .
1058 is selected ZFS will ask for the key at the command prompt when it is required
1059 to access the encrypted data (see
1061 for details). This setting will also allow the key to be passed in via STDIN,
1062 but users should be careful not to place keys which should be kept secret on
1063 the command line. If a file URI is selected, the key will be loaded from the
1064 specified absolute file path.
1065 .It Sy pbkdf2iters Ns = Ns Ar iterations
1066 Controls the number of PBKDF2 iterations that a
1068 encryption key should be run through when processing it into an encryption key.
1069 This property is only defined when encryption is enabled and a keyformat of
1071 is selected. The goal of PBKDF2 is to significantly increase the
1072 computational difficulty needed to brute force a user's passphrase. This is
1073 accomplished by forcing the attacker to run each passphrase through a
1074 computationally expensive hashing function many times before they arrive at the
1075 resulting key. A user who actually knows the passphrase will only have to pay
1076 this cost once. As CPUs become better at processing, this number should be
1077 raised to ensure that a brute force attack is still not possible. The current
1082 This property may be changed with
1083 .Nm zfs Cm change-key .
1084 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1085 Controls whether processes can be executed from within this file system.
1086 The default value is
1092 are equivalent to the
1097 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1098 Limits the number of filesystems and volumes that can exist under this point in
1100 The limit is not enforced if the user is allowed to change the limit.
1102 .Sy filesystem_limit
1105 a descendent of a filesystem that already has a
1106 .Sy filesystem_limit
1107 does not override the ancestor's
1108 .Sy filesystem_limit ,
1109 but rather imposes an additional limit.
1110 This feature must be enabled to be used
1112 .Xr zpool-features 5
1114 .It Sy special_small_blocks Ns = Ns Em size
1115 This value represents the threshold block size for including small file
1116 blocks into the special allocation class. Blocks smaller than or equal to this
1117 value will be assigned to the special allocation class while greater blocks
1118 will be assigned to the regular class. Valid values are zero or a power of two
1119 from 512B up to 1M. The default size is 0 which means no small file blocks
1120 will be allocated in the special class.
1122 Before setting this property, a special class vdev must be added to the
1125 for more details on the special allocation class.
1126 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1127 Controls the mount point used for this file system.
1132 for more information on how this property is used.
1136 property is changed for a file system, the file system and any children that
1137 inherit the mount point are unmounted.
1140 then they remain unmounted.
1141 Otherwise, they are automatically remounted in the new location if the property
1146 or if they were mounted before the property was changed.
1147 In addition, any shared file systems are unshared and shared in the new
1149 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1150 Controls whether the file system should be mounted with
1152 .Pq Non Blocking mandatory locks .
1153 This is used for SMB clients.
1154 Changes to this property only take effect when the file system is umounted and
1158 for more information on
1160 mounts. This property is not used on Linux.
1161 .It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
1162 Allow mounting on a busy directory or a directory which already contains
1163 files or directories.
1164 This is the default mount behavior for Linux and FreeBSD file systems.
1165 On these platforms the property is
1170 to disable overlay mounts for consistency with OpenZFS on other platforms.
1171 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1172 Controls what is cached in the primary cache
1174 If this property is set to
1176 then both user data and metadata is cached.
1177 If this property is set to
1179 then neither user data nor metadata is cached.
1180 If this property is set to
1182 then only metadata is cached.
1183 The default value is
1185 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1186 Limits the amount of space a dataset and its descendents can consume.
1187 This property enforces a hard limit on the amount of space used.
1188 This includes all space consumed by descendents, including file systems and
1190 Setting a quota on a descendent of a dataset that already has a quota does not
1191 override the ancestor's quota, but rather imposes an additional limit.
1193 Quotas cannot be set on volumes, as the
1195 property acts as an implicit quota.
1196 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1197 Limits the number of snapshots that can be created on a dataset and its
1201 on a descendent of a dataset that already has a
1203 does not override the ancestor's
1204 .Sy snapshot_limit ,
1205 but rather imposes an additional limit.
1206 The limit is not enforced if the user is allowed to change the limit.
1207 For example, this means that recursive snapshots taken from the global zone are
1208 counted against each delegated dataset within a zone.
1209 This feature must be enabled to be used
1211 .Xr zpool-features 5
1213 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1214 Limits the amount of space consumed by the specified user.
1215 User space consumption is identified by the
1216 .Sy userspace@ Ns Em user
1219 Enforcement of user quotas may be delayed by several seconds.
1220 This delay means that a user might exceed their quota before the system notices
1221 that they are over quota and begins to refuse additional writes with the
1225 .Nm zfs Cm userspace
1226 subcommand for more information.
1228 Unprivileged users can only access their own groups' space usage.
1229 The root user, or a user who has been granted the
1233 can get and set everyone's quota.
1235 This property is not available on volumes, on file systems before version 4, or
1236 on pools before version 15.
1238 .Sy userquota@ Ns Em ...
1239 properties are not displayed by
1240 .Nm zfs Cm get Sy all .
1241 The user's name must be appended after the
1243 symbol, using one of the following forms:
1251 .Em POSIX numeric ID
1258 .Sy joe.smith@mydomain
1267 Files created on Linux always have POSIX owners.
1268 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1273 but it limits the number of objects a user can create. Please refer to
1275 for more information about how objects are counted.
1276 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1277 Limits the amount of space consumed by the specified group.
1278 Group space consumption is identified by the
1279 .Sy groupused@ Ns Em group
1282 Unprivileged users can access only their own groups' space usage.
1283 The root user, or a user who has been granted the
1287 can get and set all groups' quotas.
1288 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1293 but it limits number of objects a group can consume. Please refer to
1295 for more information about how objects are counted.
1296 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1297 Limits the amount of space consumed by the specified project. Project
1298 space consumption is identified by the
1299 .Sy projectused@ Ns Em project
1300 property. Please refer to
1302 for more information about how project is identified and set/changed.
1304 The root user, or a user who has been granted the
1308 can access all projects' quota.
1309 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1314 but it limits number of objects a project can consume. Please refer to
1316 for more information about how objects are counted.
1317 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1318 Controls whether this dataset can be modified.
1319 The default value is
1325 are equivalent to the
1331 This property can also be referred to by its shortened column name,
1333 .It Sy recordsize Ns = Ns Em size
1334 Specifies a suggested block size for files in the file system.
1335 This property is designed solely for use with database workloads that access
1336 files in fixed-size records.
1337 ZFS automatically tunes block sizes according to internal algorithms optimized
1338 for typical access patterns.
1340 For databases that create very large files but access them in small random
1341 chunks, these algorithms may be suboptimal.
1344 greater than or equal to the record size of the database can result in
1345 significant performance gains.
1346 Use of this property for general purpose file systems is strongly discouraged,
1347 and may adversely affect performance.
1349 The size specified must be a power of two greater than or equal to 512 and less
1350 than or equal to 128 Kbytes.
1353 feature is enabled on the pool, the size may be up to 1 Mbyte.
1355 .Xr zpool-features 5
1356 for details on ZFS feature flags.
1358 Changing the file system's
1360 affects only files created afterward; existing files are unaffected.
1362 This property can also be referred to by its shortened column name,
1364 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1365 Controls what types of metadata are stored redundantly.
1366 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1367 the amount of user data lost is limited.
1368 This extra copy is in addition to any redundancy provided at the pool level
1369 .Pq e.g. by mirroring or RAID-Z ,
1370 and is in addition to an extra copy specified by the
1373 .Pq up to a total of 3 copies .
1374 For example if the pool is mirrored,
1375 .Sy copies Ns = Ns 2 ,
1377 .Sy redundant_metadata Ns = Ns Sy most ,
1378 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1383 ZFS stores an extra copy of all metadata.
1384 If a single on-disk block is corrupt, at worst a single block of user data
1393 ZFS stores an extra copy of most types of metadata.
1394 This can improve performance of random writes, because less metadata must be
1396 In practice, at worst about 100 blocks
1401 of user data can be lost if a single on-disk block is corrupt.
1402 The exact behavior of which metadata blocks are stored redundantly may change in
1405 The default value is
1407 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1408 Limits the amount of space a dataset can consume.
1409 This property enforces a hard limit on the amount of space used.
1410 This hard limit does not include space used by descendents, including file
1411 systems and snapshots.
1412 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1413 The minimum amount of space guaranteed to a dataset, not including its
1415 When the amount of space used is below this value, the dataset is treated as if
1416 it were taking up the amount of space specified by
1417 .Sy refreservation .
1420 reservation is accounted for in the parent datasets' space used, and counts
1421 against the parent datasets' quotas and reservations.
1425 is set, a snapshot is only allowed if there is enough free pool space outside of
1426 this reservation to accommodate the current number of
1428 bytes in the dataset.
1434 a volume is thick provisioned
1438 .Sy refreservation Ns = Ns Sy auto
1439 is only supported on volumes.
1443 .Sx Native Properties
1444 section for more information about sparse volumes.
1446 This property can also be referred to by its shortened column name,
1448 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1449 Controls the manner in which the access time is updated when
1451 is set. Turning this property on causes the access time to be updated relative
1452 to the modify or change time. Access time is only updated if the previous
1453 access time was earlier than the current modify or change time or if the
1454 existing access time hasn't been updated within the past 24 hours. The default
1461 are equivalent to the
1466 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1467 The minimum amount of space guaranteed to a dataset and its descendants.
1468 When the amount of space used is below this value, the dataset is treated as if
1469 it were taking up the amount of space specified by its reservation.
1470 Reservations are accounted for in the parent datasets' space used, and count
1471 against the parent datasets' quotas and reservations.
1473 This property can also be referred to by its shortened column name,
1475 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1476 Controls what is cached in the secondary cache
1478 If this property is set to
1480 then both user data and metadata is cached.
1481 If this property is set to
1483 then neither user data nor metadata is cached.
1484 If this property is set to
1486 then only metadata is cached.
1487 The default value is
1489 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1490 Controls whether the setuid bit is respected for the file system.
1491 The default value is
1497 are equivalent to the
1502 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1503 Controls whether the file system is shared by using
1504 .Sy Samba USERSHARES
1505 and what options are to be used. Otherwise, the file system is automatically
1506 shared and unshared with the
1510 commands. If the property is set to on, the
1512 command is invoked to create a
1515 Because SMB shares requires a resource name, a unique resource name is
1516 constructed from the dataset name. The constructed name is a copy of the
1517 dataset name except that the characters in the dataset name, which would be
1518 invalid in the resource name, are replaced with underscore (_) characters.
1519 Linux does not currently support additional options which might be available
1526 the file systems are unshared.
1528 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1529 stands for "full permissions", ie. read and write permissions) and no guest
1530 access (which means Samba must be able to authenticate a real user, system
1531 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1532 additional access control (disallow specific user specific access etc) must
1533 be done on the underlying file system.
1534 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1535 Controls whether the file system is shared via NFS, and what options are to be
1537 A file system with a
1543 command and entries in the
1546 Otherwise, the file system is automatically shared and unshared with the
1551 If the property is set to
1553 the dataset is shared using the default options:
1555 .Em sec=sys,rw,crossmnt,no_subtree_check
1559 for the meaning of the default options. Otherwise, the
1561 command is invoked with options equivalent to the contents of this property.
1565 property is changed for a dataset, the dataset and any children inheriting the
1566 property are re-shared with the new options, only if the property was previously
1568 or if they were shared before the property was changed.
1569 If the new property is
1571 the file systems are unshared.
1572 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1573 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1579 ZFS will use pool log devices
1581 to handle the requests at low latency.
1586 ZFS will not use configured pool log devices.
1587 ZFS will instead optimize synchronous operations for global pool throughput and
1588 efficient use of resources.
1589 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1590 Controls whether the volume snapshot devices under
1591 .Em /dev/zvol/<pool>
1592 are hidden or visible. The default value is
1594 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1595 Controls whether the
1597 directory is hidden or visible in the root of the file system as discussed in
1602 The default value is
1604 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1605 Controls the behavior of synchronous requests
1606 .Pq e.g. fsync, O_DSYNC .
1610 specified behavior of ensuring all synchronous requests are written to stable
1611 storage and all devices are flushed to ensure data is not cached by device
1613 .Pq this is the default .
1615 causes every file system transaction to be written and flushed before its
1616 system call returns.
1617 This has a large performance penalty.
1619 disables synchronous requests.
1620 File system transactions are only committed to stable storage periodically.
1621 This option will give the highest performance.
1622 However, it is very dangerous as ZFS would be ignoring the synchronous
1623 transaction demands of applications such as databases or NFS.
1624 Administrators should only use this option when the risks are understood.
1625 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1626 The on-disk version of this file system, which is independent of the pool
1628 This property can only be set to later supported versions.
1632 .It Sy volsize Ns = Ns Em size
1633 For volumes, specifies the logical size of the volume.
1634 By default, creating a volume establishes a reservation of equal size.
1635 For storage pools with a version number of 9 or higher, a
1640 are reflected in an equivalent change to the reservation
1646 can only be set to a multiple of
1650 The reservation is kept equal to the volume's logical size to prevent unexpected
1651 behavior for consumers.
1652 Without the reservation, the volume could run out of space, resulting in
1653 undefined behavior or data corruption, depending on how the volume is used.
1654 These effects can also occur when the volume size is changed while it is in use
1655 .Pq particularly when shrinking the size .
1656 Extreme care should be used when adjusting the volume size.
1658 Though not recommended, a
1661 .Qq thin provisioned
1663 can be created by specifying the
1666 .Nm zfs Cm create Fl V
1667 command, or by changing the value of the
1672 property on pool version 8 or earlier
1674 after the volume has been created.
1677 is a volume where the value of
1679 is less than the size of the volume plus the space required to store its
1681 Consequently, writes to a sparse volume can fail with
1683 when the pool is low on space.
1684 For a sparse volume, changes to
1686 are not reflected in the
1688 A volume that is not sparse is said to be
1689 .Qq thick provisioned .
1690 A sparse volume can become thick provisioned by setting
1694 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1695 This property specifies how volumes should be exposed to the OS.
1698 exposes volumes as fully fledged block devices, providing maximal
1699 functionality. The value
1701 is just an alias for
1703 and is kept for compatibility.
1706 hides its partitions.
1707 Volumes with property set to
1709 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
1710 that can be suitable for backup purposes.
1713 means that volumes exposition is controlled by system-wide tunable
1720 are encoded as 1, 2 and 3 respectively.
1721 The default values is
1723 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1724 Controls whether regular files should be scanned for viruses when a file is
1726 In addition to enabling this property, the virus scan service must also be
1727 enabled for virus scanning to occur.
1728 The default value is
1730 This property is not used on Linux.
1731 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1732 Controls whether extended attributes are enabled for this file system. Two
1733 styles of extended attributes are supported either directory based or system
1736 The default value of
1738 enables directory based extended attributes. This style of extended attribute
1739 imposes no practical limit on either the size or number of attributes which
1740 can be set on a file. Although under Linux the
1744 system calls limit the maximum size to 64K. This is the most compatible
1745 style of extended attribute and is supported by all OpenZFS implementations.
1747 System attribute based xattrs can be enabled by setting the value to
1749 The key advantage of this type of xattr is improved performance. Storing
1750 extended attributes as system attributes significantly decreases the amount of
1751 disk IO required. Up to 64K of data may be stored per-file in the space
1752 reserved for system attributes. If there is not enough space available for
1753 an extended attribute then it will be automatically written as a directory
1754 based xattr. System attribute based extended attributes are not accessible
1755 on platforms which do not support the
1759 The use of system attribute based xattrs is strongly encouraged for users of
1760 SELinux or POSIX ACLs. Both of these features heavily rely of extended
1761 attributes and benefit significantly from the reduced access time.
1767 are equivalent to the
1772 .It Sy jailed Ns = Ns Cm off | on
1773 Controls whether the dataset is managed from a jail. See the
1777 for more information. Jails are a FreeBSD feature and are not relevant on
1778 other platforms. The default value is
1780 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1781 Controls whether the dataset is managed from a non-global zone. Zones are a
1782 Solaris feature and are not relevant on other platforms. The default value is
1786 The following three properties cannot be changed after the file system is
1787 created, and therefore, should be set when the file system is created.
1788 If the properties are not set with the
1792 commands, these properties are inherited from the parent dataset.
1793 If the parent dataset lacks these properties due to having been created prior to
1794 these features being supported, the new file system will have the default values
1795 for these properties.
1798 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1799 .Sy insensitive Ns | Ns Sy mixed
1801 Indicates whether the file name matching algorithm used by the file system
1802 should be case-sensitive, case-insensitive, or allow a combination of both
1804 The default value for the
1812 file systems have case-sensitive file names.
1818 property indicates that the file system can support requests for both
1819 case-sensitive and case-insensitive matching behavior.
1820 Currently, case-insensitive matching behavior on a file system that supports
1821 mixed behavior is limited to the SMB server product.
1822 For more information about the
1824 value behavior, see the "ZFS Administration Guide".
1826 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1827 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1829 Indicates whether the file system should perform a
1831 normalization of file names whenever two file names are compared, and which
1832 normalization algorithm should be used.
1833 File names are always stored unmodified, names are normalized as part of any
1835 If this property is set to a legal value other than
1839 property was left unspecified, the
1841 property is automatically set to
1843 The default value of the
1847 This property cannot be changed after the file system is created.
1848 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1849 Indicates whether the file system should reject file names that include
1850 characters that are not present in the
1853 If this property is explicitly set to
1855 the normalization property must either not be explicitly set or be set to
1857 The default value for the
1861 This property cannot be changed after the file system is created.
1865 .Sy casesensitivity ,
1869 properties are also new permissions that can be assigned to non-privileged users
1870 by using the ZFS delegated administration feature.
1871 .Ss "Temporary Mount Point Properties"
1872 When a file system is mounted, either through
1874 for legacy mounts or the
1876 command for normal file systems, its mount options are set according to its
1878 The correlation between properties and mount options is as follows:
1880 PROPERTY MOUNT OPTION
1882 canmount auto/noauto
1886 relatime relatime/norelatime
1891 In addition, these options can be set on a per-mount basis using the
1893 option, without affecting the property that is stored on disk.
1894 The values specified on the command line override the values stored in the
1898 option is an alias for
1899 .Sy nodevices Ns \&, Ns Sy nosetuid .
1900 These properties are reported as
1905 If the properties are changed while the dataset is mounted, the new setting
1906 overrides any temporary settings.
1907 .Ss "User Properties"
1908 In addition to the standard native properties, ZFS supports arbitrary user
1910 User properties have no effect on ZFS behavior, but applications or
1911 administrators can use them to annotate datasets
1912 .Pq file systems, volumes, and snapshots .
1914 User property names must contain a colon
1916 character to distinguish them from native properties.
1917 They may contain lowercase letters, numbers, and the following punctuation
1926 The expected convention is that the property name is divided into two portions
1928 .Em module Ns \&: Ns Em property ,
1929 but this namespace is not enforced by ZFS.
1930 User property names can be at most 256 characters, and cannot begin with a dash
1933 When making programmatic use of user properties, it is strongly suggested to use
1938 component of property names to reduce the chance that two
1939 independently-developed packages use the same property name for different
1942 The values of user properties are arbitrary strings, are always inherited, and
1943 are never validated.
1944 All of the commands that operate on properties
1945 .Po Nm zfs Cm list ,
1950 can be used to manipulate both native properties and user properties.
1953 command to clear a user property.
1954 If the property is not defined in any parent dataset, it is removed entirely.
1955 Property values are limited to 8192 bytes.
projects / mirror_zfs.git / blob