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, 2017 by Delphix. All rights reserved.
25 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
26 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
27 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
28 .\" Copyright (c) 2014 Integros [integros.com]
29 .\" Copyright 2016 Richard Laager. All rights reserved.
30 .\" Copyright 2017 Nexenta Systems, Inc.
31 .\" Copyright 2018 Joyent, Inc.
38 .Nd configures ZFS file systems
45 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
52 .Fl V Ar size Ar volume
56 .Ar filesystem Ns | Ns Ar volume
60 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
61 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
64 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
68 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
69 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
77 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
78 .Ar snapshot Ar filesystem Ns | Ns Ar volume
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
86 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
90 .Ar filesystem Ns | Ns Ar volume
91 .Ar filesystem Ns | Ns Ar volume
95 .Ar snapshot Ar snapshot
98 .Op Fl r Ns | Ns Fl d Ar depth
100 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
101 .Oo Fl s Ar property Oc Ns ...
102 .Oo Fl S Ar property Oc Ns ...
103 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
104 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
107 .Ar filesystem Ns | Ns Ar volume
110 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
111 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
114 .Op Fl r Ns | Ns Fl d Ar depth
116 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
117 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
118 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
119 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
120 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
124 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
134 .Fl a | Ar filesystem
138 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
139 .Oo Fl s Ar field Oc Ns ...
140 .Oo Fl S Ar field Oc Ns ...
141 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
142 .Ar filesystem Ns | Ns Ar snapshot
146 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
147 .Oo Fl s Ar field Oc Ns ...
148 .Oo Fl S Ar field Oc Ns ...
149 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
150 .Ar filesystem Ns | Ns Ar snapshot
154 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
155 .Oo Fl s Ar field Oc Ns ...
156 .Oo Fl S Ar field Oc Ns ...
157 .Ar filesystem Ns | Ns Ar snapshot
160 .Oo Fl d Ns | Ns Fl r Ns Oc
161 .Ar file Ns | Ns Ar directory Ns ...
166 .Ar file Ns | Ns Ar directory Ns ...
171 .Oo Fl d Ns | Ns Fl r Ns Oc
173 .Ar file Ns | Ns Ar directory Ns ...
178 .Ar file Ns | Ns Ar directory Ns ...
185 .Fl a | Ar filesystem
189 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
192 .Fl a | Ar filesystem
195 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
198 .Ar snapshot bookmark
202 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
207 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
208 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
212 .Fl t Ar receive_resume_token
216 .Op Fl o Sy origin Ns = Ns Ar snapshot
217 .Op Fl o Ar property Ns = Ns Ar value
219 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
223 .Op Fl d Ns | Ns Fl e
224 .Op Fl o Sy origin Ns = Ns Ar snapshot
225 .Op Fl o Ar property Ns = Ns Ar value
231 .Ar filesystem Ns | Ns Ar volume
234 .Ar filesystem Ns | Ns Ar volume
238 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
239 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
240 .Ar setname Oc Ns ...
241 .Ar filesystem Ns | Ns Ar volume
245 .Fl e Ns | Ns Sy everyone
246 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
247 .Ar setname Oc Ns ...
248 .Ar filesystem Ns | Ns Ar volume
252 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
253 .Ar setname Oc Ns ...
254 .Ar filesystem Ns | Ns Ar volume
257 .Fl s No @ Ns Ar setname
258 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
259 .Ar setname Oc Ns ...
260 .Ar filesystem Ns | Ns Ar volume
264 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
265 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
266 .Ar setname Oc Ns ... Oc
267 .Ar filesystem Ns | Ns Ar volume
271 .Fl e Ns | Ns Sy everyone
272 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
273 .Ar setname Oc Ns ... Oc
274 .Ar filesystem Ns | Ns Ar volume
279 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
280 .Ar setname Oc Ns ... Oc
281 .Ar filesystem Ns | Ns Ar volume
285 .Fl s @ Ns Ar setname
286 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
287 .Ar setname Oc Ns ... Oc
288 .Ar filesystem Ns | Ns Ar volume
292 .Ar tag Ar snapshot Ns ...
300 .Ar tag Ar snapshot Ns ...
304 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
309 .Op Fl m Ar memory_limit
315 .Op Fl L Ar keylocation
316 .Fl a | Ar filesystem
320 .Fl a | Ar filesystem
324 .Op Fl o Ar keylocation Ns = Ns Ar value
325 .Op Fl o Ar keyformat Ns = Ns Ar value
326 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
336 command configures ZFS datasets within a ZFS storage pool, as described in
338 A dataset is identified by a unique path within the ZFS namespace.
341 pool/{filesystem,volume,snapshot}
344 where the maximum length of a dataset name is
348 A dataset can be one of the following:
349 .Bl -tag -width "file system"
351 A ZFS dataset of type
353 can be mounted within the standard system namespace and behaves like other file
355 While ZFS file systems are designed to be POSIX compliant, known issues exist
356 that prevent compliance in some cases.
357 Applications that depend on standards conformance might fail due to non-standard
358 behavior when checking file system free space.
360 A logical volume exported as a raw or block device.
361 This type of dataset should only be used under special circumstances.
362 File systems are typically used in most environments.
364 A read-only version of a file system or volume at a given point in time.
366 .Ar filesystem Ns @ Ns Ar name
368 .Ar volume Ns @ Ns Ar name .
372 but without the hold on on-disk data. It can be used as the source of a send
373 (but not for a receive). It is specified as
374 .Ar filesystem Ns # Ns Ar name
376 .Ar volume Ns # Ns Ar name .
378 .Ss ZFS File System Hierarchy
379 A ZFS storage pool is a logical collection of devices that provide space for
381 A storage pool is also the root of the ZFS file system hierarchy.
383 The root of the pool can be accessed as a file system, such as mounting and
384 unmounting, taking snapshots, and setting properties.
385 The physical storage characteristics, however, are managed by the
391 for more information on creating and administering pools.
393 A snapshot is a read-only copy of a file system or volume.
394 Snapshots can be created extremely quickly, and initially consume no additional
395 space within the pool.
396 As data within the active dataset changes, the snapshot consumes more data than
397 would otherwise be shared with the active dataset.
399 Snapshots can have arbitrary names.
400 Snapshots of volumes can be cloned or rolled back, visibility is determined
403 property of the parent volume.
405 File system snapshots can be accessed under the
407 directory in the root of the file system.
408 Snapshots are automatically mounted on demand and may be unmounted at regular
410 The visibility of the
412 directory can be controlled by the
416 A bookmark is like a snapshot, a read-only copy of a file system or volume.
417 Bookmarks can be created extremely quickly, compared to snapshots, and they
418 consume no additional space within the pool. Bookmarks can also have arbitrary
419 names, much like snapshots.
421 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
422 way. From a storage standpoint a bookmark just provides a way to reference
423 when a snapshot was created as a distinct object. Bookmarks are initially
424 tied to a snapshot, not the filesystem or volume, and they will survive if the
425 snapshot itself is destroyed. Since they are very light weight there's little
426 incentive to destroy them.
428 A clone is a writable volume or file system whose initial contents are the same
430 As with snapshots, creating a clone is nearly instantaneous, and initially
431 consumes no additional space.
433 Clones can only be created from a snapshot.
434 When a snapshot is cloned, it creates an implicit dependency between the parent
436 Even though the clone is created somewhere else in the dataset hierarchy, the
437 original snapshot cannot be destroyed as long as a clone exists.
440 property exposes this dependency, and the
442 command lists any such dependencies, if they exist.
444 The clone parent-child dependency relationship can be reversed by using the
449 file system to become a clone of the specified file system, which makes it
450 possible to destroy the file system that the clone was created from.
452 Creating a ZFS file system is a simple operation, so the number of file systems
453 per system is likely to be numerous.
454 To cope with this, ZFS automatically manages mounting and unmounting file
455 systems without the need to edit the
458 All automatically managed file systems are mounted by ZFS at boot time.
460 By default, file systems are mounted under
464 is the name of the file system in the ZFS namespace.
465 Directories are created and destroyed as needed.
467 A file system can also have a mount point set in the
470 This directory is created as needed, and ZFS automatically mounts the file
472 .Nm zfs Cm mount Fl a
479 property can be inherited, so if
485 automatically inherits a mount point of
486 .Pa /export/stuff/user .
492 prevents the file system from being mounted.
494 If needed, ZFS file systems can also be managed with traditional tools
500 If a file system's mount point is set to
502 ZFS makes no attempt to manage the file system, and the administrator is
503 responsible for mounting and unmounting the file system. Because pools must
504 be imported before a legacy mount can succeed, administrators should ensure
505 that legacy mounts are only attempted after the zpool import process
506 finishes at boot time. For example, on machines using systemd, the mount
509 .Nm x-systemd.requires=zfs-import.target
511 will ensure that the zfs-import completes before systemd attempts mounting
512 the filesystem. See systemd.mount(5) for details.
514 Deduplication is the process for removing redundant data at the block level,
515 reducing the total amount of data stored. If a file system has the
517 property enabled, duplicate data blocks are removed synchronously. The result
518 is that only unique data is stored and common components are shared among files.
520 Deduplicating data is a very resource-intensive operation. It is generally
521 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
522 you enable deduplication. Calculating the exact requirement depends heavily
523 on the type of data stored in the pool.
525 Enabling deduplication on an improperly-designed system can result in
526 performance issues (slow IO and administrative operations). It can potentially
527 lead to problems importing a pool due to memory exhaustion. Deduplication
528 can consume significant processing power (CPU) and memory as well as generate
531 Before creating a pool with deduplication enabled, ensure that you have planned
532 your hardware requirements appropriately and implemented appropriate recovery
533 practices, such as regular backups. As an alternative to deduplication
536 as a less resource-intensive alternative.
537 .Ss Native Properties
538 Properties are divided into two types, native properties and user-defined
543 Native properties either export internal statistics or control ZFS behavior.
544 In addition, native properties are either editable or read-only.
545 User properties have no effect on ZFS behavior, but you can use them to annotate
546 datasets in a way that is meaningful in your environment.
547 For more information about user properties, see the
551 Every dataset has a set of properties that export statistics about the dataset
552 as well as control various behaviors.
553 Properties are inherited from the parent unless overridden by the child.
554 Some properties apply only to certain types of datasets
555 .Pq file systems, volumes, or snapshots .
557 The values of numeric properties can be specified using human-readable suffixes
567 The following are all valid
570 .Li 1536M, 1.5g, 1.50GB .
572 The values of non-numeric properties are case sensitive and must be lowercase,
579 The following native properties consist of read-only statistics about the
581 These properties can be neither set, nor inherited.
582 Native properties apply to all dataset types unless otherwise noted.
583 .Bl -tag -width "usedbyrefreservation"
585 The amount of space available to the dataset and all its children, assuming that
586 there is no other activity in the pool.
587 Because space is shared within a pool, availability can be limited by any number
588 of factors, including physical pool size, quotas, reservations, or other
589 datasets within the pool.
591 This property can also be referred to by its shortened column name,
594 For non-snapshots, the compression ratio achieved for the
596 space of this dataset, expressed as a multiplier.
599 property includes descendant datasets, and, for clones, does not include the
600 space shared with the origin snapshot.
606 Compression can be turned on by running:
607 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
611 The transaction group (txg) in which the dataset was created. Bookmarks have
614 as the snapshot they are initially tied to. This property is suitable for
615 ordering a list of snapshots, e.g. for incremental send and receive.
617 The time this dataset was created.
619 For snapshots, this property is a comma-separated list of filesystems or volumes
620 which are clones of this snapshot.
623 property is this snapshot.
626 property is not empty, then this snapshot can not be destroyed
633 The roles of origin and clone can be swapped by promoting the clone with the
639 if the snapshot has been marked for deferred destroy by using the
640 .Nm zfs Cm destroy Fl d
642 Otherwise, the property is
644 .It Sy encryptionroot
645 For encrypted datasets, indicates where the dataset is currently inheriting its
646 encryption key from. Loading or unloading a key for the
648 will implicitly load / unload the key for any inheriting datasets (see
651 .Nm zfs Cm unload-key
653 Clones will always share an
654 encryption key with their origin. See the
657 .It Sy filesystem_count
658 The total number of filesystems and volumes that exist under this location in
660 This value is only available when a
662 has been set somewhere in the tree under which the dataset resides.
664 Indicates if an encryption key is currently loaded into ZFS. The possible
673 .Nm zfs Cm unload-key .
675 The 64 bit GUID of this dataset or bookmark which does not change over its
676 entire lifetime. When a snapshot is sent to another pool, the received
677 snapshot has the same GUID. Thus, the
679 is suitable to identify a snapshot across pools.
680 .It Sy logicalreferenced
681 The amount of space that is
683 accessible by this dataset.
687 The logical space ignores the effect of the
691 properties, giving a quantity closer to the amount of data that applications
693 However, it does include space consumed by metadata.
695 This property can also be referred to by its shortened column name,
698 The amount of space that is
700 consumed by this dataset and all its descendents.
704 The logical space ignores the effect of the
708 properties, giving a quantity closer to the amount of data that applications
710 However, it does include space consumed by metadata.
712 This property can also be referred to by its shortened column name,
715 For file systems, indicates whether the file system is currently mounted.
716 This property can be either
721 For cloned file systems or volumes, the snapshot from which the clone was
726 .It Sy receive_resume_token
727 For filesystems or volumes which have saved partially-completed state from
729 this opaque token can be provided to
731 to resume and complete the
734 The amount of data that is accessible by this dataset, which may or may not be
735 shared with other datasets in the pool.
736 When a snapshot or clone is created, it initially references the same amount of
737 space as the file system or snapshot it was created from, since its contents are
740 This property can also be referred to by its shortened column name,
742 .It Sy refcompressratio
743 The compression ratio achieved for the
745 space of this dataset, expressed as a multiplier.
749 .It Sy snapshot_count
750 The total number of snapshots that exist under this location in the dataset
752 This value is only available when a
754 has been set somewhere in the tree under which the dataset resides.
762 The amount of space consumed by this dataset and all its descendents.
763 This is the value that is checked against this dataset's quota and reservation.
764 The space used does not include this dataset's reservation, but does take into
765 account the reservations of any descendent datasets.
766 The amount of space that a dataset consumes from its parent, as well as the
767 amount of space that is freed if this dataset is recursively destroyed, is the
768 greater of its space used and its reservation.
770 The used space of a snapshot
775 is space that is referenced exclusively by this snapshot.
776 If this snapshot is destroyed, the amount of
779 Space that is shared by multiple snapshots isn't accounted for in this metric.
780 When a snapshot is destroyed, space that was previously shared with this
781 snapshot can become unique to snapshots adjacent to it, thus changing the used
782 space of those snapshots.
783 The used space of the latest snapshot can also be affected by changes in the
787 space of a snapshot is a subset of the
789 space of the snapshot.
791 The amount of space used, available, or referenced does not take into account
793 Pending changes are generally accounted for within a few seconds.
794 Committing a change to a disk using
798 does not necessarily guarantee that the space usage information is updated
803 properties decompose the
805 properties into the various reasons that space is used.
808 .Sy usedbychildren No +
809 .Sy usedbydataset No +
810 .Sy usedbyrefreservation No +
811 .Sy usedbysnapshots .
812 These properties are only available for datasets created on
816 .It Sy usedbychildren
817 The amount of space used by children of this dataset, which would be freed if
818 all the dataset's children were destroyed.
820 The amount of space used by this dataset itself, which would be freed if the
821 dataset were destroyed
822 .Po after first removing any
824 and destroying any necessary snapshots or descendents
826 .It Sy usedbyrefreservation
827 The amount of space used by a
829 set on this dataset, which would be freed if the
832 .It Sy usedbysnapshots
833 The amount of space consumed by snapshots of this dataset.
834 In particular, it is the amount of space that would be freed if all of this
835 dataset's snapshots were destroyed.
836 Note that this is not simply the sum of the snapshots'
838 properties because space can be shared by multiple snapshots.
839 .It Sy userused Ns @ Ns Em user
840 The amount of space consumed by the specified user in this dataset.
841 Space is charged to the owner of each file, as displayed by
843 The amount of space charged is displayed by
849 subcommand for more information.
851 Unprivileged users can access only their own space usage.
852 The root user, or a user who has been granted the
856 can access everyone's usage.
859 .Sy userused Ns @ Ns Em ...
860 properties are not displayed by
861 .Nm zfs Cm get Sy all .
862 The user's name must be appended after the @ symbol, using one of the following
864 .Bl -bullet -width ""
878 .Sy joe.smith@mydomain
887 Files created on Linux always have POSIX owners.
888 .It Sy userobjused Ns @ Ns Em user
891 property is similar to
893 but instead it counts the number of objects consumed by a user. This property
894 counts all objects allocated on behalf of the user, it may differ from the
895 results of system tools such as
900 is set on a file system additional objects will be created per-file to store
901 extended attributes. These additional objects are reflected in the
903 value and are counted against the user's
905 When a file system is configured to use
907 no additional internal objects are normally required.
909 This property is set to the number of user holds on this snapshot.
910 User holds are set by using the
913 .It Sy groupused Ns @ Ns Em group
914 The amount of space consumed by the specified group in this dataset.
915 Space is charged to the group of each file, as displayed by
918 .Sy userused Ns @ Ns Em user
919 property for more information.
921 Unprivileged users can only access their own groups' space usage.
922 The root user, or a user who has been granted the
926 can access all groups' usage.
927 .It Sy groupobjused Ns @ Ns Em group
928 The number of objects consumed by the specified group in this dataset.
929 Multiple objects may be charged to the group for each file when extended
930 attributes are in use. See the
931 .Sy userobjused Ns @ Ns Em user
932 property for more information.
934 Unprivileged users can only access their own groups' space usage.
935 The root user, or a user who has been granted the
939 can access all groups' usage.
940 .It Sy projectused Ns @ Ns Em project
941 The amount of space consumed by the specified project in this dataset. Project
942 is identified via the project identifier (ID) that is object-based numeral
943 attribute. An object can inherit the project ID from its parent object (if the
944 parent has the flag of inherit project ID that can be set and changed via
947 .Nm zfs project Fl s )
948 when being created. The privileged user can set and change object's project
953 anytime. Space is charged to the project of each file, as displayed by
958 .Sy userused Ns @ Ns Em user
959 property for more information.
961 The root user, or a user who has been granted the
965 can access all projects' usage.
966 .It Sy projectobjused Ns @ Ns Em project
971 but instead it counts the number of objects consumed by project. When the
974 is set on a fileset, ZFS will create additional objects per-file to store
975 extended attributes. These additional objects are reflected in the
977 value and are counted against the project's
978 .Sy projectobjquota .
979 When a filesystem is configured to use
981 no additional internal objects are required. See the
982 .Sy userobjused Ns @ Ns Em user
983 property for more information.
985 The root user, or a user who has been granted the
989 can access all projects' objects usage.
991 For volumes, specifies the block size of the volume.
994 cannot be changed once the volume has been written, so it should be set at
995 volume creation time.
998 for volumes is 8 Kbytes.
999 Any power of 2 from 512 bytes to 128 Kbytes is valid.
1001 This property can also be referred to by its shortened column name,
1006 by this dataset, that was written since the previous snapshot
1007 .Pq i.e. that is not referenced by the previous snapshot .
1008 .It Sy written Ns @ Ns Em snapshot
1011 space written to this dataset since the specified snapshot.
1012 This is the space that is referenced by this dataset but was not referenced by
1013 the specified snapshot.
1017 may be specified as a short snapshot name
1018 .Po just the part after the
1021 in which case it will be interpreted as a snapshot in the same filesystem as
1025 may be a full snapshot name
1026 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1027 which for clones may be a snapshot in the origin's filesystem
1028 .Pq or the origin of the origin's filesystem, etc.
1031 The following native properties can be used to change the behavior of a ZFS
1035 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1036 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1038 Controls how ACEs are inherited when files and directories are created.
1039 .Bl -tag -width "passthrough-x"
1041 does not inherit any ACEs.
1043 only inherits inheritable ACEs that specify
1047 default, removes the
1051 permissions when the ACE is inherited.
1053 inherits all inheritable ACEs without any modifications.
1054 .It Sy passthrough-x
1062 ACEs inherit the execute permission only if the file creation mode also requests
1066 When the property value is set to
1068 files are created with a mode determined by the inheritable ACEs.
1069 If no inheritable ACEs exist that affect the mode, then the mode is set in
1070 accordance to the requested mode from the application.
1074 property does not apply to posix ACLs.
1075 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1076 Controls whether ACLs are enabled and if so what type of ACL to use.
1077 .Bl -tag -width "posixacl"
1079 default, when a file system has the
1081 property set to off then ACLs are disabled.
1086 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
1087 not functional on other platforms. Posix ACLs are stored as an extended
1088 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1092 To obtain the best performance when setting
1094 users are strongly encouraged to set the
1096 property. This will result in the posix ACL being stored more efficiently on
1097 disk. But as a consequence of this all new extended attributes will only be
1098 accessible from OpenZFS implementations which support the
1102 property for more details.
1103 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1104 Controls whether the access time for files is updated when they are read.
1105 Turning this property off avoids producing write traffic when reading files and
1106 can result in significant performance gains, though it might confuse mailers
1107 and other similar utilities. The values
1111 are equivalent to the
1115 mount options. The default value is
1120 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1121 If this property is set to
1123 the file system cannot be mounted, and is ignored by
1124 .Nm zfs Cm mount Fl a .
1125 Setting this property to
1127 is similar to setting the
1131 except that the dataset still has a normal
1133 property, which can be inherited.
1134 Setting this property to
1136 allows datasets to be used solely as a mechanism to inherit properties.
1137 One example of setting
1138 .Sy canmount Ns = Ns Sy off
1139 is to have two datasets with the same
1141 so that the children of both datasets appear in the same directory, but might
1142 have different inherited characteristics.
1146 a dataset can only be mounted and unmounted explicitly.
1147 The dataset is not mounted automatically when the dataset is created or
1148 imported, nor is it mounted by the
1149 .Nm zfs Cm mount Fl a
1150 command or unmounted by the
1151 .Nm zfs Cm unmount Fl a
1154 This property is not inherited.
1156 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1157 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1158 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1160 Controls the checksum used to verify data integrity.
1161 The default value is
1163 which automatically selects an appropriate algorithm
1166 but this may change in future releases
1170 disables integrity checking on user data.
1173 not only disables integrity but also disables maintaining parity for user data.
1174 This setting is used internally by a dump device residing on a RAID-Z pool and
1175 should not be used by any other dataset.
1176 Disabling checksums is
1178 a recommended practice.
1185 checksum algorithms require enabling the appropriate features on the pool.
1187 .Xr zpool-features 5
1188 for more information on these algorithms.
1190 Changing this property affects only newly-written data.
1192 Salted checksum algorithms
1193 .Pq Cm edonr , skein
1194 are currently not supported for any filesystem on the boot pools.
1196 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1197 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1199 Controls the compression algorithm used for this dataset.
1201 Setting compression to
1203 indicates that the current default compression algorithm should be used.
1204 The default balances compression and decompression speed, with compression ratio
1205 and is expected to work well on a wide variety of workloads.
1206 Unlike all other settings for this property,
1208 does not select a fixed compression type.
1209 As new compression algorithms are added to ZFS and enabled on a pool, the
1210 default compression algorithm may change.
1211 The current default compression algorithm is either
1220 compression algorithm is a high-performance replacement for the
1223 It features significantly faster compression and decompression, as well as a
1224 moderately higher compression ratio than
1226 but can only be used on pools with the
1231 .Xr zpool-features 5
1232 for details on ZFS feature flags and the
1238 compression algorithm is optimized for performance while providing decent data
1243 compression algorithm uses the same compression as the
1248 level by using the value
1252 is an integer from 1
1255 .Pq best compression ratio .
1260 .Po which is also the default for
1266 compression algorithm compresses runs of zeros.
1268 This property can also be referred to by its shortened column name
1270 Changing this property affects only newly-written data.
1272 .Sy context Ns = Ns Sy none Ns | Ns
1273 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1275 This flag sets the SELinux context for all files in the file system under
1276 a mount point for that file system. See
1278 for more information.
1280 .Sy fscontext Ns = Ns Sy none Ns | Ns
1281 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1283 This flag sets the SELinux context for the file system file system being
1286 for more information.
1288 .Sy defcontext Ns = Ns Sy none Ns | Ns
1289 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1291 This flag sets the SELinux default context for unlabeled files. See
1293 for more information.
1295 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1296 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1298 This flag sets the SELinux context for the root inode of the file system. See
1300 for more information.
1301 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1302 Controls the number of copies of data stored for this dataset.
1303 These copies are in addition to any redundancy provided by the pool, for
1304 example, mirroring or RAID-Z.
1305 The copies are stored on different disks, if possible.
1306 The space used by multiple copies is charged to the associated file and dataset,
1309 property and counting against quotas and reservations.
1311 Changing this property only affects newly-written data.
1312 Therefore, set this property at file system creation time by using the
1313 .Fl o Sy copies Ns = Ns Ar N
1316 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1318 create, for example a two-disk striped pool and set
1320 on some datasets thinking you have setup redundancy for them. When a disk
1321 fails you will not be able to import the pool and will have lost all of your
1323 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1324 Controls whether device nodes can be opened on this file system.
1325 The default value is
1331 are equivalent to the
1337 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1338 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1341 Configures deduplication for a dataset. The default value is
1343 The default deduplication checksum is
1345 (this may change in the future). When
1347 is enabled, the checksum defined here overrides the
1349 property. Setting the value to
1351 has the same effect as the setting
1356 ZFS will do a byte-to-byte comparsion in case of two blocks having the same
1357 signature to make sure the block contents are identical. Specifying
1359 is mandatory for the
1363 Unless necessary, deduplication should NOT be enabled on a system. See
1367 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1368 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1370 Specifies a compatibility mode or literal value for the size of dnodes in the
1371 file system. The default value is
1373 Setting this property to a value other than
1375 requires the large_dnode pool feature to be enabled.
1381 if the dataset uses the
1383 property setting and the workload makes heavy use of extended attributes. This
1384 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1385 servers, for example. Literal values are supported for cases where the optimal
1386 size is known in advance and for performance testing.
1392 if you need to receive a send stream of this dataset on a pool that doesn't
1393 enable the large_dnode feature, or if you need to import this pool on a system
1394 that doesn't support the large_dnode feature.
1396 This property can also be referred to by its shortened column name,
1399 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1400 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1401 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1403 Controls the encryption cipher suite (block cipher, key length, and mode) used
1404 for this dataset. Requires the
1406 feature to be enabled on the pool.
1409 to be set at dataset creation time.
1412 .Sy encryption Ns = Ns Sy on
1413 when creating a dataset indicates that the default encryption suite will be
1414 selected, which is currently
1416 In order to provide consistent data protection, encryption must be specified at
1417 dataset creation time and it cannot be changed afterwards.
1419 For more details and caveats about encryption see the
1422 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1423 Controls what format the user's encryption key will be provided as. This
1424 property is only set when the dataset is encrypted.
1426 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1427 encryption suite) and must be randomly generated. A raw key can be generated
1428 with the following command:
1430 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1433 Passphrases must be between 8 and 512 bytes long and will be processed through
1434 PBKDF2 before being used (see the
1436 property). Even though the
1437 encryption suite cannot be changed after dataset creation, the keyformat can be
1439 .Nm zfs Cm change-key .
1441 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1443 Controls where the user's encryption key will be loaded from by default for
1447 .Nm zfs Cm mount Cm -l . This property is
1448 only set for encrypted datasets which are encryption roots. If unspecified, the
1452 Even though the encryption suite cannot be changed after dataset creation, the
1453 keylocation can be with either
1456 .Nm zfs Cm change-key .
1459 is selected ZFS will ask for the key at the command prompt when it is required
1460 to access the encrypted data (see
1462 for details). This setting will also allow the key to be passed in via STDIN,
1463 but users should be careful not to place keys which should be kept secret on
1464 the command line. If a file URI is selected, the key will be loaded from the
1465 specified absolute file path.
1466 .It Sy pbkdf2iters Ns = Ns Ar iterations
1467 Controls the number of PBKDF2 iterations that a
1469 encryption key should be run through when processing it into an encryption key.
1470 This property is only defined when encryption is enabled and a keyformat of
1472 is selected. The goal of PBKDF2 is to significantly increase the
1473 computational difficulty needed to brute force a user's passphrase. This is
1474 accomplished by forcing the attacker to run each passphrase through a
1475 computationally expensive hashing function many times before they arrive at the
1476 resulting key. A user who actually knows the passphrase will only have to pay
1477 this cost once. As CPUs become better at processing, this number should be
1478 raised to ensure that a brute force attack is still not possible. The current
1483 This property may be changed with
1484 .Nm zfs Cm change-key .
1485 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1486 Controls whether processes can be executed from within this file system.
1487 The default value is
1493 are equivalent to the
1498 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1499 Limits the number of filesystems and volumes that can exist under this point in
1501 The limit is not enforced if the user is allowed to change the limit.
1503 .Sy filesystem_limit
1506 a descendent of a filesystem that already has a
1507 .Sy filesystem_limit
1508 does not override the ancestor's
1509 .Sy filesystem_limit ,
1510 but rather imposes an additional limit.
1511 This feature must be enabled to be used
1513 .Xr zpool-features 5
1515 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1516 Controls the mount point used for this file system.
1519 section for more information on how this property is used.
1523 property is changed for a file system, the file system and any children that
1524 inherit the mount point are unmounted.
1527 then they remain unmounted.
1528 Otherwise, they are automatically remounted in the new location if the property
1533 or if they were mounted before the property was changed.
1534 In addition, any shared file systems are unshared and shared in the new
1536 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1537 Controls whether the file system should be mounted with
1539 .Pq Non Blocking mandatory locks .
1540 This is used for SMB clients.
1541 Changes to this property only take effect when the file system is umounted and
1545 for more information on
1547 mounts. This property is not used on Linux.
1548 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1549 Allow mounting on a busy directory or a directory which already contains
1550 files or directories. This is the default mount behavior for Linux file systems.
1551 For consistency with OpenZFS on other platforms overlay mounts are
1555 to enable overlay mounts.
1556 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1557 Controls what is cached in the primary cache
1559 If this property is set to
1561 then both user data and metadata is cached.
1562 If this property is set to
1564 then neither user data nor metadata is cached.
1565 If this property is set to
1567 then only metadata is cached.
1568 The default value is
1570 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1571 Limits the amount of space a dataset and its descendents can consume.
1572 This property enforces a hard limit on the amount of space used.
1573 This includes all space consumed by descendents, including file systems and
1575 Setting a quota on a descendent of a dataset that already has a quota does not
1576 override the ancestor's quota, but rather imposes an additional limit.
1578 Quotas cannot be set on volumes, as the
1580 property acts as an implicit quota.
1581 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1582 Limits the number of snapshots that can be created on a dataset and its
1586 on a descendent of a dataset that already has a
1588 does not override the ancestor's
1589 .Sy snapshot_limit ,
1590 but rather imposes an additional limit.
1591 The limit is not enforced if the user is allowed to change the limit.
1592 For example, this means that recursive snapshots taken from the global zone are
1593 counted against each delegated dataset within a zone.
1594 This feature must be enabled to be used
1596 .Xr zpool-features 5
1598 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1599 Limits the amount of space consumed by the specified user.
1600 User space consumption is identified by the
1601 .Sy userspace@ Ns Em user
1604 Enforcement of user quotas may be delayed by several seconds.
1605 This delay means that a user might exceed their quota before the system notices
1606 that they are over quota and begins to refuse additional writes with the
1610 .Nm zfs Cm userspace
1611 subcommand for more information.
1613 Unprivileged users can only access their own groups' space usage.
1614 The root user, or a user who has been granted the
1618 can get and set everyone's quota.
1620 This property is not available on volumes, on file systems before version 4, or
1621 on pools before version 15.
1623 .Sy userquota@ Ns Em ...
1624 properties are not displayed by
1625 .Nm zfs Cm get Sy all .
1626 The user's name must be appended after the
1628 symbol, using one of the following forms:
1636 .Em POSIX numeric ID
1643 .Sy joe.smith@mydomain
1652 Files created on Linux always have POSIX owners.
1653 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1658 but it limits the number of objects a user can create. Please refer to
1660 for more information about how objects are counted.
1661 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1662 Limits the amount of space consumed by the specified group.
1663 Group space consumption is identified by the
1664 .Sy groupused@ Ns Em group
1667 Unprivileged users can access only their own groups' space usage.
1668 The root user, or a user who has been granted the
1672 can get and set all groups' quotas.
1673 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1678 but it limits number of objects a group can consume. Please refer to
1680 for more information about how objects are counted.
1681 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1682 Limits the amount of space consumed by the specified project. Project
1683 space consumption is identified by the
1684 .Sy projectused@ Ns Em project
1685 property. Please refer to
1687 for more information about how project is identified and set/changed.
1689 The root user, or a user who has been granted the
1693 can access all projects' quota.
1694 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1699 but it limits number of objects a project can consume. Please refer to
1701 for more information about how objects are counted.
1702 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1703 Controls whether this dataset can be modified.
1704 The default value is
1710 are equivalent to the
1716 This property can also be referred to by its shortened column name,
1718 .It Sy recordsize Ns = Ns Em size
1719 Specifies a suggested block size for files in the file system.
1720 This property is designed solely for use with database workloads that access
1721 files in fixed-size records.
1722 ZFS automatically tunes block sizes according to internal algorithms optimized
1723 for typical access patterns.
1725 For databases that create very large files but access them in small random
1726 chunks, these algorithms may be suboptimal.
1729 greater than or equal to the record size of the database can result in
1730 significant performance gains.
1731 Use of this property for general purpose file systems is strongly discouraged,
1732 and may adversely affect performance.
1734 The size specified must be a power of two greater than or equal to 512 and less
1735 than or equal to 128 Kbytes.
1738 feature is enabled on the pool, the size may be up to 1 Mbyte.
1740 .Xr zpool-features 5
1741 for details on ZFS feature flags.
1743 Changing the file system's
1745 affects only files created afterward; existing files are unaffected.
1747 This property can also be referred to by its shortened column name,
1749 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1750 Controls what types of metadata are stored redundantly.
1751 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1752 the amount of user data lost is limited.
1753 This extra copy is in addition to any redundancy provided at the pool level
1754 .Pq e.g. by mirroring or RAID-Z ,
1755 and is in addition to an extra copy specified by the
1758 .Pq up to a total of 3 copies .
1759 For example if the pool is mirrored,
1760 .Sy copies Ns = Ns 2 ,
1762 .Sy redundant_metadata Ns = Ns Sy most ,
1763 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1768 ZFS stores an extra copy of all metadata.
1769 If a single on-disk block is corrupt, at worst a single block of user data
1778 ZFS stores an extra copy of most types of metadata.
1779 This can improve performance of random writes, because less metadata must be
1781 In practice, at worst about 100 blocks
1786 of user data can be lost if a single on-disk block is corrupt.
1787 The exact behavior of which metadata blocks are stored redundantly may change in
1790 The default value is
1792 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1793 Limits the amount of space a dataset can consume.
1794 This property enforces a hard limit on the amount of space used.
1795 This hard limit does not include space used by descendents, including file
1796 systems and snapshots.
1797 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1798 The minimum amount of space guaranteed to a dataset, not including its
1800 When the amount of space used is below this value, the dataset is treated as if
1801 it were taking up the amount of space specified by
1802 .Sy refreservation .
1805 reservation is accounted for in the parent datasets' space used, and counts
1806 against the parent datasets' quotas and reservations.
1810 is set, a snapshot is only allowed if there is enough free pool space outside of
1811 this reservation to accommodate the current number of
1813 bytes in the dataset.
1819 a volume is thick provisioned
1823 .Sy refreservation Ns = Ns Sy auto
1824 is only supported on volumes.
1828 .Sx Native Properties
1829 section for more information about sparse volumes.
1831 This property can also be referred to by its shortened column name,
1833 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1834 Controls the manner in which the access time is updated when
1836 is set. Turning this property on causes the access time to be updated relative
1837 to the modify or change time. Access time is only updated if the previous
1838 access time was earlier than the current modify or change time or if the
1839 existing access time hasn't been updated within the past 24 hours. The default
1846 are equivalent to the
1851 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1852 The minimum amount of space guaranteed to a dataset and its descendants.
1853 When the amount of space used is below this value, the dataset is treated as if
1854 it were taking up the amount of space specified by its reservation.
1855 Reservations are accounted for in the parent datasets' space used, and count
1856 against the parent datasets' quotas and reservations.
1858 This property can also be referred to by its shortened column name,
1860 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1861 Controls what is cached in the secondary cache
1863 If this property is set to
1865 then both user data and metadata is cached.
1866 If this property is set to
1868 then neither user data nor metadata is cached.
1869 If this property is set to
1871 then only metadata is cached.
1872 The default value is
1874 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1875 Controls whether the setuid bit is respected for the file system.
1876 The default value is
1882 are equivalent to the
1887 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1888 Controls whether the file system is shared by using
1889 .Sy Samba USERSHARES
1890 and what options are to be used. Otherwise, the file system is automatically
1891 shared and unshared with the
1895 commands. If the property is set to on, the
1897 command is invoked to create a
1900 Because SMB shares requires a resource name, a unique resource name is
1901 constructed from the dataset name. The constructed name is a copy of the
1902 dataset name except that the characters in the dataset name, which would be
1903 invalid in the resource name, are replaced with underscore (_) characters.
1904 Linux does not currently support additional options which might be available
1911 the file systems are unshared.
1913 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1914 stands for "full permissions", ie. read and write permissions) and no guest
1915 access (which means Samba must be able to authenticate a real user, system
1916 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1917 additional access control (disallow specific user specific access etc) must
1918 be done on the underlying file system.
1919 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1920 Controls whether the file system is shared via NFS, and what options are to be
1922 A file system with a
1928 command and entries in the
1931 Otherwise, the file system is automatically shared and unshared with the
1936 If the property is set to
1938 the dataset is shared using the default options:
1940 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1944 for the meaning of the default options. Otherwise, the
1946 command is invoked with options equivalent to the contents of this property.
1950 property is changed for a dataset, the dataset and any children inheriting the
1951 property are re-shared with the new options, only if the property was previously
1953 or if they were shared before the property was changed.
1954 If the new property is
1956 the file systems are unshared.
1957 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1958 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1964 ZFS will use pool log devices
1966 to handle the requests at low latency.
1971 ZFS will not use configured pool log devices.
1972 ZFS will instead optimize synchronous operations for global pool throughput and
1973 efficient use of resources.
1974 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1975 Controls whether the volume snapshot devices under
1976 .Em /dev/zvol/<pool>
1977 are hidden or visible. The default value is
1979 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1980 Controls whether the
1982 directory is hidden or visible in the root of the file system as discussed in
1986 The default value is
1988 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1989 Controls the behavior of synchronous requests
1990 .Pq e.g. fsync, O_DSYNC .
1994 specified behavior of ensuring all synchronous requests are written to stable
1995 storage and all devices are flushed to ensure data is not cached by device
1997 .Pq this is the default .
1999 causes every file system transaction to be written and flushed before its
2000 system call returns.
2001 This has a large performance penalty.
2003 disables synchronous requests.
2004 File system transactions are only committed to stable storage periodically.
2005 This option will give the highest performance.
2006 However, it is very dangerous as ZFS would be ignoring the synchronous
2007 transaction demands of applications such as databases or NFS.
2008 Administrators should only use this option when the risks are understood.
2009 .It Sy version Ns = Ns Em N Ns | Ns Sy current
2010 The on-disk version of this file system, which is independent of the pool
2012 This property can only be set to later supported versions.
2016 .It Sy volsize Ns = Ns Em size
2017 For volumes, specifies the logical size of the volume.
2018 By default, creating a volume establishes a reservation of equal size.
2019 For storage pools with a version number of 9 or higher, a
2024 are reflected in an equivalent change to the reservation
2030 can only be set to a multiple of
2034 The reservation is kept equal to the volume's logical size to prevent unexpected
2035 behavior for consumers.
2036 Without the reservation, the volume could run out of space, resulting in
2037 undefined behavior or data corruption, depending on how the volume is used.
2038 These effects can also occur when the volume size is changed while it is in use
2039 .Pq particularly when shrinking the size .
2040 Extreme care should be used when adjusting the volume size.
2042 Though not recommended, a
2045 .Qq thin provisioned
2047 can be created by specifying the
2050 .Nm zfs Cm create Fl V
2051 command, or by changing the value of the
2056 property on pool version 8 or earlier
2058 after the volume has been created.
2061 is a volume where the value of
2063 is less than the size of the volume plus the space required to store its
2065 Consequently, writes to a sparse volume can fail with
2067 when the pool is low on space.
2068 For a sparse volume, changes to
2070 are not reflected in the
2072 A volume that is not sparse is said to be
2073 .Qq thick provisioned .
2074 A sparse volume can become thick provisioned by setting
2078 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2079 This property specifies how volumes should be exposed to the OS.
2082 exposes volumes as fully fledged block devices, providing maximal
2083 functionality. The value
2085 is just an alias for
2087 and is kept for compatibility.
2090 hides its partitions.
2091 Volumes with property set to
2093 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
2094 that can be suitable for backup purposes.
2097 means that volumes exposition is controlled by system-wide tunable
2104 are encoded as 1, 2 and 3 respectively.
2105 The default values is
2107 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2108 Controls whether regular files should be scanned for viruses when a file is
2110 In addition to enabling this property, the virus scan service must also be
2111 enabled for virus scanning to occur.
2112 The default value is
2114 This property is not used on Linux.
2115 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2116 Controls whether extended attributes are enabled for this file system. Two
2117 styles of extended attributes are supported either directory based or system
2120 The default value of
2122 enables directory based extended attributes. This style of extended attribute
2123 imposes no practical limit on either the size or number of attributes which
2124 can be set on a file. Although under Linux the
2128 system calls limit the maximum size to 64K. This is the most compatible
2129 style of extended attribute and is supported by all OpenZFS implementations.
2131 System attribute based xattrs can be enabled by setting the value to
2133 The key advantage of this type of xattr is improved performance. Storing
2134 extended attributes as system attributes significantly decreases the amount of
2135 disk IO required. Up to 64K of data may be stored per-file in the space
2136 reserved for system attributes. If there is not enough space available for
2137 an extended attribute then it will be automatically written as a directory
2138 based xattr. System attribute based extended attributes are not accessible
2139 on platforms which do not support the
2143 The use of system attribute based xattrs is strongly encouraged for users of
2144 SELinux or posix ACLs. Both of these features heavily rely of extended
2145 attributes and benefit significantly from the reduced access time.
2151 are equivalent to the
2156 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2157 Controls whether the dataset is managed from a non-global zone. Zones are a
2158 Solaris feature and are not relevant on Linux. The default value is
2162 The following three properties cannot be changed after the file system is
2163 created, and therefore, should be set when the file system is created.
2164 If the properties are not set with the
2168 commands, these properties are inherited from the parent dataset.
2169 If the parent dataset lacks these properties due to having been created prior to
2170 these features being supported, the new file system will have the default values
2171 for these properties.
2174 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2175 .Sy insensitive Ns | Ns Sy mixed
2177 Indicates whether the file name matching algorithm used by the file system
2178 should be case-sensitive, case-insensitive, or allow a combination of both
2180 The default value for the
2188 file systems have case-sensitive file names.
2194 property indicates that the file system can support requests for both
2195 case-sensitive and case-insensitive matching behavior.
2196 Currently, case-insensitive matching behavior on a file system that supports
2197 mixed behavior is limited to the SMB server product.
2198 For more information about the
2200 value behavior, see the "ZFS Administration Guide".
2202 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2203 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2205 Indicates whether the file system should perform a
2207 normalization of file names whenever two file names are compared, and which
2208 normalization algorithm should be used.
2209 File names are always stored unmodified, names are normalized as part of any
2211 If this property is set to a legal value other than
2215 property was left unspecified, the
2217 property is automatically set to
2219 The default value of the
2223 This property cannot be changed after the file system is created.
2224 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2225 Indicates whether the file system should reject file names that include
2226 characters that are not present in the
2229 If this property is explicitly set to
2231 the normalization property must either not be explicitly set or be set to
2233 The default value for the
2237 This property cannot be changed after the file system is created.
2241 .Sy casesensitivity ,
2245 properties are also new permissions that can be assigned to non-privileged users
2246 by using the ZFS delegated administration feature.
2247 .Ss "Temporary Mount Point Properties"
2248 When a file system is mounted, either through
2250 for legacy mounts or the
2252 command for normal file systems, its mount options are set according to its
2254 The correlation between properties and mount options is as follows:
2256 PROPERTY MOUNT OPTION
2258 canmount auto/noauto
2262 relatime relatime/norelatime
2267 In addition, these options can be set on a per-mount basis using the
2269 option, without affecting the property that is stored on disk.
2270 The values specified on the command line override the values stored in the
2274 option is an alias for
2275 .Sy nodevices Ns \&, Ns Sy nosetuid .
2276 These properties are reported as
2281 If the properties are changed while the dataset is mounted, the new setting
2282 overrides any temporary settings.
2283 .Ss "User Properties"
2284 In addition to the standard native properties, ZFS supports arbitrary user
2286 User properties have no effect on ZFS behavior, but applications or
2287 administrators can use them to annotate datasets
2288 .Pq file systems, volumes, and snapshots .
2290 User property names must contain a colon
2292 character to distinguish them from native properties.
2293 They may contain lowercase letters, numbers, and the following punctuation
2302 The expected convention is that the property name is divided into two portions
2304 .Em module Ns \&: Ns Em property ,
2305 but this namespace is not enforced by ZFS.
2306 User property names can be at most 256 characters, and cannot begin with a dash
2309 When making programmatic use of user properties, it is strongly suggested to use
2314 component of property names to reduce the chance that two
2315 independently-developed packages use the same property name for different
2318 The values of user properties are arbitrary strings, are always inherited, and
2319 are never validated.
2320 All of the commands that operate on properties
2321 .Po Nm zfs Cm list ,
2326 can be used to manipulate both native properties and user properties.
2329 command to clear a user property.
2330 If the property is not defined in any parent dataset, it is removed entirely.
2331 Property values are limited to 8192 bytes.
2332 .Ss ZFS Volumes as Swap
2333 ZFS volumes may be used as swap devices. After creating the volume with the
2334 .Nm zfs Cm create Fl V
2335 command set up and enable the swap area using the
2339 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2340 configuration is not supported.
2344 feature allows for the creation of encrypted filesystems and volumes.
2346 will encrypt all user data including file and zvol data, file attributes,
2347 ACLs, permission bits, directory listings, FUID mappings, and userused /
2350 will not encrypt metadata related to the pool structure, including dataset
2351 names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
2352 is managed internally by the kernel module and changing the user's key does not
2353 require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
2354 renamed, and deleted without the encryption keys being loaded (see the
2356 subcommand for more info on key loading).
2358 Creating an encrypted dataset requires specifying the
2362 properties at creation time, along with an optional
2366 After entering an encryption key, the
2367 created dataset will become an encryption root. Any descendant datasets will
2368 inherit their encryption key from the encryption root by default, meaning that
2369 loading, unloading, or changing the key for the encryption root will implicitly
2370 do the same for all inheriting datasets. If this inheritance is not desired,
2373 when creating the child dataset or use
2374 .Nm zfs Cm change-key
2375 to break an existing relationship, creating a new encryption root on the child.
2376 Note that the child's
2378 may match that of the parent while still creating a new encryption root, and
2381 property alone does not create a new encryption root; this would simply use a
2382 different cipher suite with the same key as its encryption root. The one
2383 exception is that clones will always use their origin's encryption key.
2384 As a result of this exception, some encryption-related properties (namely
2390 do not inherit like other ZFS properties and instead use the value determined
2391 by their encryption root. Encryption root inheritance can be tracked via the
2396 Encryption changes the behavior of a few
2398 operations. Encryption is applied after compression so compression ratios are
2399 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2400 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2401 the encryption suite, which provides additional protection against maliciously
2402 altered data. Deduplication is still possible with encryption enabled but for
2403 security, datasets will only dedup against themselves, their snapshots, and
2406 There are a few limitations on encrypted datasets. Encrypted data cannot be
2409 feature. Encrypted datasets may not have
2410 .Sy copies Ns = Ns Em 3
2411 since the implementation stores some encryption metadata where the third copy
2412 would normally be. Since compression is applied before encryption datasets may
2413 be vulnerable to a CRIME-like attack if applications accessing the data allow
2414 for it. Deduplication with encryption will leak information about which blocks
2415 are equivalent in a dataset and will incur an extra CPU cost per block written.
2417 All subcommands that modify state are logged persistently to the pool in their
2421 Displays a help message.
2426 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2429 Creates a new ZFS file system.
2430 The file system is automatically mounted according to the
2432 property inherited from the parent.
2433 .Bl -tag -width "-o"
2434 .It Fl o Ar property Ns = Ns Ar value
2435 Sets the specified property as if the command
2436 .Nm zfs Cm set Ar property Ns = Ns Ar value
2437 was invoked at the same time the dataset was created.
2438 Any editable ZFS property can also be set at creation time.
2441 options can be specified.
2442 An error results if the same property is specified in multiple
2446 Creates all the non-existing parent datasets.
2447 Datasets created in this manner are automatically mounted according to the
2449 property inherited from their parent.
2450 Any property specified on the command line using the
2453 If the target filesystem already exists, the operation completes successfully.
2459 .Op Fl b Ar blocksize
2460 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2461 .Fl V Ar size Ar volume
2463 Creates a volume of the given size.
2464 The volume is exported as a block device in
2465 .Pa /dev/zvol/path ,
2468 is the name of the volume in the ZFS namespace.
2469 The size represents the logical size as exported by the device.
2470 By default, a reservation of equal size is created.
2473 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2474 has an integral number of blocks regardless of
2476 .Bl -tag -width "-b"
2477 .It Fl b Ar blocksize
2479 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2480 If this option is specified in conjunction with
2481 .Fl o Sy volblocksize ,
2482 the resulting behavior is undefined.
2483 .It Fl o Ar property Ns = Ns Ar value
2484 Sets the specified property as if the
2485 .Nm zfs Cm set Ar property Ns = Ns Ar value
2486 command was invoked at the same time the dataset was created.
2487 Any editable ZFS property can also be set at creation time.
2490 options can be specified.
2491 An error results if the same property is specified in multiple
2495 Creates all the non-existing parent datasets.
2496 Datasets created in this manner are automatically mounted according to the
2498 property inherited from their parent.
2499 Any property specified on the command line using the
2502 If the target filesystem already exists, the operation completes successfully.
2504 Creates a sparse volume with no reservation.
2508 .Sx Native Properties
2509 section for more information about sparse volumes.
2515 .Ar filesystem Ns | Ns Ar volume
2517 Destroys the given dataset.
2518 By default, the command unshares any file systems that are currently shared,
2519 unmounts any file systems that are currently mounted, and refuses to destroy a
2520 dataset that has active dependents
2521 .Pq children or clones .
2522 .Bl -tag -width "-R"
2524 Recursively destroy all dependents, including cloned file systems outside the
2527 Force an unmount of any file systems using the
2530 This option has no effect on non-file systems or unmounted file systems.
2535 No data will be deleted.
2536 This is useful in conjunction with the
2540 flags to determine what data would be deleted.
2542 Print machine-parsable verbose information about the deleted data.
2544 Recursively destroy all children.
2546 Print verbose information about the deleted data.
2549 Extreme care should be taken when applying either the
2553 options, as they can destroy large portions of a pool and cause unexpected
2554 behavior for mounted file systems in use.
2559 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2560 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2562 The given snapshots are destroyed immediately if and only if the
2566 option would have destroyed it.
2567 Such immediate destruction would occur, for example, if the snapshot had no
2568 clones and the user-initiated reference count were zero.
2570 If a snapshot does not qualify for immediate destruction, it is marked for
2572 In this state, it exists as a usable, visible snapshot until both of the
2573 preconditions listed above are met, at which point it is destroyed.
2575 An inclusive range of snapshots may be specified by separating the first and
2576 last snapshots with a percent sign.
2577 The first and/or last snapshots may be left blank, in which case the
2578 filesystem's oldest or newest snapshot will be implied.
2581 .Pq or ranges of snapshots
2582 of the same filesystem or volume may be specified in a comma-separated list of
2584 Only the snapshot's short name
2585 .Po the part after the
2588 should be specified when using a range or comma-separated list to identify
2590 .Bl -tag -width "-R"
2592 Recursively destroy all clones of these snapshots, including the clones,
2593 snapshots, and children.
2594 If this flag is specified, the
2596 flag will have no effect.
2598 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2599 deferred destruction.
2604 No data will be deleted.
2605 This is useful in conjunction with the
2609 flags to determine what data would be deleted.
2611 Print machine-parsable verbose information about the deleted data.
2614 .Pq or mark for deferred deletion
2615 all snapshots with this name in descendent file systems.
2617 Print verbose information about the deleted data.
2619 Extreme care should be taken when applying either the
2623 options, as they can destroy large portions of a pool and cause unexpected
2624 behavior for mounted file systems in use.
2629 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2631 The given bookmark is destroyed.
2636 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2637 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2639 Creates snapshots with the given names.
2640 All previous modifications by successful system calls to the file system are
2641 part of the snapshots.
2642 Snapshots are taken atomically, so that all snapshots correspond to the same
2645 can be used as an alias for
2646 .Nm zfs Cm snapshot.
2649 section for details.
2650 .Bl -tag -width "-o"
2651 .It Fl o Ar property Ns = Ns Ar value
2652 Sets the specified property; see
2656 Recursively create snapshots of all descendent datasets
2664 Roll back the given dataset to a previous snapshot.
2665 When a dataset is rolled back, all data that has changed since the snapshot is
2666 discarded, and the dataset reverts to the state at the time of the snapshot.
2667 By default, the command refuses to roll back to a snapshot other than the most
2669 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2676 options do not recursively destroy the child snapshots of a recursive snapshot.
2677 Only direct snapshots of the specified filesystem are destroyed by either of
2679 To completely roll back a recursive snapshot, you must rollback the individual
2681 .Bl -tag -width "-R"
2683 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2688 option to force an unmount of any clone file systems that are to be destroyed.
2690 Destroy any snapshots and bookmarks more recent than the one specified.
2696 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2697 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2699 Creates a clone of the given snapshot.
2702 section for details.
2703 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2704 as the same type as the original.
2705 .Bl -tag -width "-o"
2706 .It Fl o Ar property Ns = Ns Ar value
2707 Sets the specified property; see
2711 Creates all the non-existing parent datasets.
2712 Datasets created in this manner are automatically mounted according to the
2714 property inherited from their parent.
2715 If the target filesystem or volume already exists, the operation completes
2721 .Ar clone-filesystem
2723 Promotes a clone file system to no longer be dependent on its
2726 This makes it possible to destroy the file system that the clone was created
2728 The clone parent-child dependency relationship is reversed, so that the origin
2729 file system becomes a clone of the specified file system.
2731 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2732 now owned by the promoted clone.
2733 The space they use moves from the origin file system to the promoted clone, so
2734 enough space must be available to accommodate these snapshots.
2735 No new space is consumed by this operation, but the space accounting is
2737 The promoted clone must not have any conflicting snapshot names of its own.
2740 subcommand can be used to rename any conflicting snapshots.
2745 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2746 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2752 .Ar filesystem Ns | Ns Ar volume
2753 .Ar filesystem Ns | Ns Ar volume
2755 Renames the given dataset.
2756 The new target can be located anywhere in the ZFS hierarchy, with the exception
2758 Snapshots can only be renamed within the parent file system or volume.
2759 When renaming a snapshot, the parent file system of the snapshot does not need
2760 to be specified as part of the second argument.
2761 Renamed file systems can inherit new mount points, in which case they are
2762 unmounted and remounted at the new mount point.
2763 .Bl -tag -width "-a"
2765 Force unmount any filesystems that need to be unmounted in the process.
2767 Creates all the nonexistent parent datasets.
2768 Datasets created in this manner are automatically mounted according to the
2770 property inherited from their parent.
2776 .Ar snapshot Ar snapshot
2778 Recursively rename the snapshots of all descendent datasets.
2779 Snapshots are the only dataset that can be renamed recursively.
2783 .Op Fl r Ns | Ns Fl d Ar depth
2785 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2786 .Oo Fl s Ar property Oc Ns ...
2787 .Oo Fl S Ar property Oc Ns ...
2788 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2789 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2791 Lists the property information for the given datasets in tabular form.
2792 If specified, you can list property information by the absolute pathname or the
2794 By default, all file systems and volumes are displayed.
2795 Snapshots are displayed if the
2802 The following fields are displayed,
2803 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2805 .Bl -tag -width "-H"
2807 Used for scripting mode.
2808 Do not print headers and separate fields by a single tab instead of arbitrary
2810 .It Fl S Ar property
2813 option, but sorts by property in descending order.
2815 Recursively display any children of the dataset, limiting the recursion to
2821 will display only the dataset and its direct children.
2822 .It Fl o Ar property
2823 A comma-separated list of properties to display.
2824 The property must be:
2827 One of the properties described in the
2828 .Sx Native Properties
2835 to display the dataset name
2839 to display space usage properties on file systems and volumes.
2840 This is a shortcut for specifying
2841 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2842 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2843 .Sy filesystem Ns \&, Ns Sy volume
2847 Display numbers in parsable
2851 Recursively display any children of the dataset on the command line.
2852 .It Fl s Ar property
2853 A property for sorting the output by column in ascending order based on the
2854 value of the property.
2855 The property must be one of the properties described in the
2857 section, or the special value
2859 to sort by the dataset name.
2860 Multiple properties can be specified at one time using multiple
2865 options are evaluated from left to right in decreasing order of importance.
2866 The following is a list of sorting criteria:
2869 Numeric types sort in numeric order.
2871 String types sort in alphabetical order.
2873 Types inappropriate for a row sort that row to the literal bottom, regardless of
2874 the specified ordering.
2877 If no sorting options are specified the existing behavior of
2881 A comma-separated list of types to display, where
2890 For example, specifying
2892 displays only snapshots.
2897 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2898 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2900 Sets the property or list of properties to the given value(s) for each dataset.
2901 Only some properties can be edited.
2904 section for more information on what properties can be set and acceptable
2906 Numeric values can be specified as exact values, or in a human-readable form
2908 .Sy B , K , M , G , T , P , E , Z
2909 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2910 or zettabytes, respectively
2912 User properties can be set on snapshots.
2913 For more information, see the
2919 .Op Fl r Ns | Ns Fl d Ar depth
2921 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2922 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2923 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2924 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2925 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2927 Displays properties for the given datasets.
2928 If no datasets are specified, then the command displays properties for all
2929 datasets on the system.
2930 For each property, the following columns are displayed:
2933 property Property name
2934 value Property value
2935 source Property source. Can either be local, default,
2936 temporary, inherited, or none (-).
2939 All columns are displayed by default, though this can be controlled by using the
2942 This command takes a comma-separated list of properties as described in the
2943 .Sx Native Properties
2950 can be used to display all properties that apply to the given dataset's type
2951 .Pq filesystem, volume, snapshot, or bookmark .
2952 .Bl -tag -width "-H"
2954 Display output in a form more easily parsed by scripts.
2955 Any headers are omitted, and fields are explicitly separated by a single tab
2956 instead of an arbitrary amount of space.
2958 Recursively display any children of the dataset, limiting the recursion to
2962 will display only the dataset and its direct children.
2964 A comma-separated list of columns to display.
2965 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2966 is the default value.
2968 Display numbers in parsable
2972 Recursively display properties for any children.
2974 A comma-separated list of sources to display.
2975 Those properties coming from a source other than those in this list are ignored.
2976 Each source must be one of the following:
2983 The default value is all sources.
2985 A comma-separated list of types to display, where
2999 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3001 Clears the specified property, causing it to be inherited from an ancestor,
3002 restored to default if no ancestor has the property set, or with the
3004 option reverted to the received value if one exists.
3007 section for a listing of default values, and details on which properties can be
3009 .Bl -tag -width "-r"
3011 Recursively inherit the given property for all children.
3013 Revert the property to the received value if one exists; otherwise operate as
3016 option was not specified.
3021 .Ar filesystem Ns | Ns Ar volume
3023 Remap the indirect blocks in the given fileystem or volume so that they no
3024 longer reference blocks on previously removed vdevs and we can eventually
3025 shrink the size of the indirect mapping objects for the previously removed
3026 vdevs. Note that remapping all blocks might not be possible and that
3027 references from snapshots will still exist and cannot be remapped.
3032 Displays a list of file systems that are not the most recent version.
3038 Displays a list of currently supported file system versions.
3044 .Fl a | Ar filesystem
3046 Upgrades file systems to a new on-disk version.
3047 Once this is done, the file systems will no longer be accessible on systems
3048 running older versions of the software.
3050 streams generated from new snapshots of these file systems cannot be accessed on
3051 systems running older versions of the software.
3053 In general, the file system version is independent of the pool version.
3056 for information on the
3057 .Nm zpool Cm upgrade
3060 In some cases, the file system version and the pool version are interrelated and
3061 the pool version must be upgraded before the file system version can be
3063 .Bl -tag -width "-V"
3065 Upgrade to the specified
3069 flag is not specified, this command upgrades to the most recent version.
3071 option can only be used to increase the version number, and only up to the most
3072 recent version supported by this software.
3074 Upgrade all file systems on all imported pools.
3076 Upgrade the specified file system.
3078 Upgrade the specified file system and all descendent file systems.
3084 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3085 .Oo Fl s Ar field Oc Ns ...
3086 .Oo Fl S Ar field Oc Ns ...
3087 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3088 .Ar filesystem Ns | Ns Ar snapshot
3090 Displays space consumed by, and quotas on, each user in the specified filesystem
3092 This corresponds to the
3093 .Sy userused@ Ns Em user ,
3094 .Sy userobjused@ Ns Em user ,
3095 .Sy userquota@ Ns Em user,
3097 .Sy userobjquota@ Ns Em user
3099 .Bl -tag -width "-H"
3101 Do not print headers, use tab-delimited output.
3103 Sort by this field in reverse order.
3107 Translate SID to POSIX ID.
3108 The POSIX ID may be ephemeral if no mapping exists.
3109 Normal POSIX interfaces
3114 perform this translation, so the
3116 option allows the output from
3117 .Nm zfs Cm userspace
3118 to be compared directly with those utilities.
3121 may lead to confusion if some files were created by an SMB user before a
3122 SMB-to-POSIX name mapping was established.
3123 In such a case, some files will be owned by the SMB entity and some by the POSIX
3127 option will report that the POSIX entity has the total usage and quota for both.
3129 Print numeric ID instead of user/group name.
3130 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3131 Display only the specified fields from the following set:
3136 The default is to display all fields.
3142 Sort output by this field.
3147 flags may be specified multiple times to sort first by one field, then by
3150 .Fl s Sy type Fl s Sy name .
3151 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3152 Print only the specified types from the following set:
3159 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3160 The default can be changed to include group types.
3166 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3167 .Oo Fl s Ar field Oc Ns ...
3168 .Oo Fl S Ar field Oc Ns ...
3169 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3170 .Ar filesystem Ns | Ns Ar snapshot
3172 Displays space consumed by, and quotas on, each group in the specified
3173 filesystem or snapshot.
3174 This subcommand is identical to
3175 .Nm zfs Cm userspace ,
3176 except that the default types to display are
3177 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3182 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3183 .Oo Fl s Ar field Oc Ns ...
3184 .Oo Fl S Ar field Oc Ns ...
3185 .Ar filesystem Ns | Ns Ar snapshot
3187 Displays space consumed by, and quotas on, each project in the specified
3188 filesystem or snapshot. This subcommand is identical to
3189 .Nm zfs Cm userspace ,
3190 except that the project identifier is numeral, not name. So need neither
3193 for SID to POSIX ID nor
3201 .Oo Fl d Ns | Ns Fl r Ns Oc
3202 .Ar file Ns | Ns Ar directory Ns ...
3204 List project identifier (ID) and inherit flag of file(s) or directories.
3205 .Bl -tag -width "-d"
3207 Show the directory project ID and inherit flag, not its childrens. It will
3208 overwrite the former specified
3212 Show on subdirectories recursively. It will overwrite the former specified
3221 .Ar file Ns | Ns Ar directory Ns ...
3223 Clear project inherit flag and/or ID on the file(s) or directories.
3224 .Bl -tag -width "-k"
3226 Keep the project ID unchanged. If not specified, the project ID will be reset
3229 Clear on subdirectories recursively.
3236 .Oo Fl d Ns | Ns Fl r Ns Oc
3238 .Ar file Ns | Ns Ar directory Ns ...
3240 Check project ID and inherit flag on the file(s) or directories, report the
3241 entries without project inherit flag or with different project IDs from the
3244 option) value or the target directory's project ID.
3245 .Bl -tag -width "-0"
3247 Print file name with a trailing NUL instead of newline (by default), like
3250 Check the directory project ID and inherit flag, not its childrens. It will
3251 overwrite the former specified
3255 Specify the referenced ID for comparing with the target file(s) or directories'
3256 project IDs. If not specified, the target (top) directory's project ID will be
3257 used as the referenced one.
3259 Check on subdirectories recursively. It will overwrite the former specified
3268 .Ar file Ns | Ns Ar directory Ns ...
3270 .Bl -tag -width "-p"
3271 Set project ID and/or inherit flag on the file(s) or directories.
3273 Set the file(s)' or directories' project ID with the given value.
3275 Set on subdirectories recursively.
3277 Set project inherit flag on the given file(s) or directories. It is usually used
3278 for setup tree quota on the directory target with
3280 option specified together. When setup tree quota, by default the directory's
3281 project ID will be set to all its descendants unless you specify the project
3290 Displays all ZFS file systems currently mounted.
3296 .Fl a | Ar filesystem
3298 Mounts ZFS file systems.
3299 .Bl -tag -width "-O"
3301 Perform an overlay mount.
3304 for more information.
3306 Mount all available ZFS file systems.
3307 Invoked automatically as part of the boot process.
3309 Mount the specified filesystem.
3311 An optional, comma-separated list of mount options to use temporarily for the
3312 duration of the mount.
3314 .Sx Temporary Mount Point Properties
3315 section for details.
3317 Load keys for encrypted filesystems as they are being mounted. This is
3318 equivalent to executing
3320 on each encryption root before mounting it. Note that if a filesystem has a
3324 this will cause the terminal to interactively block after asking for the key.
3326 Report mount progress.
3332 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3334 Unmounts currently mounted ZFS file systems.
3335 .Bl -tag -width "-a"
3337 Unmount all available ZFS file systems.
3338 Invoked automatically as part of the shutdown process.
3339 .It Ar filesystem Ns | Ns Ar mountpoint
3340 Unmount the specified filesystem.
3341 The command can also be given a path to a ZFS file system mount point on the
3344 Forcefully unmount the file system, even if it is currently in use.
3349 .Fl a | Ar filesystem
3351 Shares available ZFS file systems.
3352 .Bl -tag -width "-a"
3354 Share all available ZFS file systems.
3355 Invoked automatically as part of the boot process.
3357 Share the specified filesystem according to the
3362 File systems are shared when the
3371 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3373 Unshares currently shared ZFS file systems.
3374 .Bl -tag -width "-a"
3376 Unshare all available ZFS file systems.
3377 Invoked automatically as part of the shutdown process.
3378 .It Ar filesystem Ns | Ns Ar mountpoint
3379 Unshare the specified filesystem.
3380 The command can also be given a path to a ZFS file system shared on the system.
3385 .Ar snapshot bookmark
3387 Creates a bookmark of the given snapshot.
3388 Bookmarks mark the point in time when the snapshot was created, and can be used
3389 as the incremental source for a
3393 This feature must be enabled to be used.
3395 .Xr zpool-features 5
3396 for details on ZFS feature flags and the
3403 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3406 Creates a stream representation of the second
3408 which is written to standard output.
3409 The output can be redirected to a file or to a different system
3410 .Po for example, using
3413 By default, a full stream is generated.
3414 .Bl -tag -width "-D"
3416 Generate a deduplicated stream.
3417 Blocks which would have been sent multiple times in the send stream will only be
3419 The receiving system must also support this feature to receive a deduplicated
3421 This flag can be used regardless of the dataset's
3423 property, but performance will be much better if the filesystem uses a
3424 dedup-capable checksum
3428 .It Fl I Ar snapshot
3429 Generate a stream package that sends all intermediary snapshots from the first
3430 snapshot to the second snapshot.
3434 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3435 The incremental source may be specified as with the
3438 .It Fl L, -large-block
3439 Generate a stream which may contain blocks larger than 128KB.
3440 This flag has no effect if the
3442 pool feature is disabled, or if the
3444 property of this filesystem has never been set above 128KB.
3445 The receiving system must have the
3447 pool feature enabled as well.
3449 .Xr zpool-features 5
3450 for details on ZFS feature flags and the
3454 Print machine-parsable verbose information about the stream package generated.
3455 .It Fl R, -replicate
3456 Generate a replication stream package, which will replicate the specified
3457 file system, and all descendent file systems, up to the named snapshot.
3458 When received, all properties, snapshots, descendent file systems, and clones
3465 flags are used in conjunction with the
3467 flag, an incremental replication stream is generated.
3468 The current values of properties, and current snapshot and file system names are
3469 set when the stream is received.
3472 flag is specified when this stream is received, snapshots and file systems that
3473 do not exist on the sending side are destroyed.
3475 Generate a more compact stream by using
3477 records for blocks which are stored more compactly on disk by the
3480 This flag has no effect if the
3482 feature is disabled.
3483 The receiving system must have the
3488 feature is active on the sending system, then the receiving system must have
3489 that feature enabled as well. Datasets that are sent with this flag may not be
3490 received as an encrypted dataset, since encrypted datasets cannot use the
3494 .Xr zpool-features 5
3495 for details on ZFS feature flags and the
3499 Sends only received property values whether or not they are overridden by local
3500 settings, but only if the dataset has ever been received. Use this option when
3503 to restore received properties backed up on the sent dataset and to avoid
3504 sending local settings that may have nothing to do with the source dataset,
3505 but only with how the data is backed up.
3506 .It Fl c, -compressed
3507 Generate a more compact stream by using compressed WRITE records for blocks
3508 which are compressed on disk and in memory
3511 property for details
3515 feature is active on the sending system, then the receiving system must have
3516 that feature enabled as well.
3519 feature is enabled on the sending system but the
3521 option is not supplied in conjunction with
3523 then the data will be decompressed before sending so it can be split into
3524 smaller block sizes.
3526 For encrypted datasets, send data exactly as it exists on disk. This allows
3527 backups to be taken even if encryption keys are not currently loaded. The
3528 backup may then be received on an untrusted machine since that machine will
3529 not have the encryption keys to read the protected data or alter it without
3530 being detected. Upon being received, the dataset will have the same encryption
3531 keys as it did on the send side, although the
3533 property will be defaulted to
3535 if not otherwise provided. For unencrypted datasets, this flag will be
3538 Note that if you do not use this flag for sending encrypted datasets, data will
3539 be sent unencrypted and may be re-encrypted with a different encryption key on
3540 the receiving system, which will disable the ability to do a raw send to that
3541 system for incrementals.
3542 .It Fl i Ar snapshot
3543 Generate an incremental stream from the first
3545 .Pq the incremental source
3548 .Pq the incremental target .
3549 The incremental source can be specified as the last component of the snapshot
3553 character and following
3555 and it is assumed to be from the same file system as the incremental target.
3557 If the destination is a clone, the source may be the origin snapshot, which must
3560 .Em pool/fs@origin ,
3568 Do not generate any actual send data.
3569 This is useful in conjunction with the
3573 flags to determine what data will be sent.
3574 In this case, the verbose output will be written to standard output
3575 .Po contrast with a non-dry-run, where the stream is written to standard output
3576 and the verbose output goes to standard error
3579 Include the dataset's properties in the stream.
3580 This flag is implicit when
3583 The receiving system must also support this feature. Sends of encrypted datasets
3586 when using this flag.
3588 Print verbose information about the stream package generated.
3589 This information includes a per-second report of how much data has been sent.
3591 The format of the stream is committed.
3592 You will be able to receive your streams on future versions of ZFS.
3598 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3599 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3601 Generate a send stream, which may be of a filesystem, and may be incremental
3603 If the destination is a filesystem or volume, the pool must be read-only, or the
3604 filesystem must not be mounted.
3605 When the stream generated from a filesystem or volume is received, the default
3606 snapshot name will be
3608 .Bl -tag -width "-L"
3609 .It Fl L, -large-block
3610 Generate a stream which may contain blocks larger than 128KB.
3611 This flag has no effect if the
3613 pool feature is disabled, or if the
3615 property of this filesystem has never been set above 128KB.
3616 The receiving system must have the
3618 pool feature enabled as well.
3620 .Xr zpool-features 5
3621 for details on ZFS feature flags and the
3625 Print machine-parsable verbose information about the stream package generated.
3626 .It Fl c, -compressed
3627 Generate a more compact stream by using compressed WRITE records for blocks
3628 which are compressed on disk and in memory
3631 property for details
3635 feature is active on the sending system, then the receiving system must have
3636 that feature enabled as well.
3639 feature is enabled on the sending system but the
3641 option is not supplied in conjunction with
3643 then the data will be decompressed before sending so it can be split into
3644 smaller block sizes.
3646 For encrypted datasets, send data exactly as it exists on disk. This allows
3647 backups to be taken even if encryption keys are not currently loaded. The
3648 backup may then be received on an untrusted machine since that machine will
3649 not have the encryption keys to read the protected data or alter it without
3650 being detected. Upon being received, the dataset will have the same encryption
3651 keys as it did on the send side, although the
3653 property will be defaulted to
3655 if not otherwise provided. For unencrypted datasets, this flag will be
3658 Note that if you do not use this flag for sending encrypted datasets, data will
3659 be sent unencrypted and may be re-encrypted with a different encryption key on
3660 the receiving system, which will disable the ability to do a raw send to that
3661 system for incrementals.
3663 Generate a more compact stream by using
3665 records for blocks which are stored more compactly on disk by the
3668 This flag has no effect if the
3670 feature is disabled.
3671 The receiving system must have the
3676 feature is active on the sending system, then the receiving system must have
3677 that feature enabled as well. Datasets that are sent with this flag may not be
3678 received as an encrypted dataset, since encrypted datasets cannot use the
3682 .Xr zpool-features 5
3683 for details on ZFS feature flags and the
3686 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3687 Generate an incremental send stream.
3688 The incremental source must be an earlier snapshot in the destination's history.
3689 It will commonly be an earlier snapshot in the destination's file system, in
3690 which case it can be specified as the last component of the name
3695 character and following
3698 If the incremental target is a clone, the incremental source can be the origin
3699 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3705 Do not generate any actual send data.
3706 This is useful in conjunction with the
3710 flags to determine what data will be sent.
3711 In this case, the verbose output will be written to standard output
3712 .Po contrast with a non-dry-run, where the stream is written to standard output
3713 and the verbose output goes to standard error
3716 Print verbose information about the stream package generated.
3717 This information includes a per-second report of how much data has been sent.
3724 .Ar receive_resume_token
3726 Creates a send stream which resumes an interrupted receive.
3728 .Ar receive_resume_token
3729 is the value of this property on the filesystem or volume that was being
3731 See the documentation for
3738 .Op Fl o Sy origin Ns = Ns Ar snapshot
3739 .Op Fl o Ar property Ns = Ns Ar value
3740 .Op Fl x Ar property
3741 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3747 .Op Fl d Ns | Ns Fl e
3748 .Op Fl o Sy origin Ns = Ns Ar snapshot
3749 .Op Fl o Ar property Ns = Ns Ar value
3750 .Op Fl x Ar property
3753 Creates a snapshot whose contents are as specified in the stream provided on
3755 If a full stream is received, then a new file system is created as well.
3756 Streams are created using the
3758 subcommand, which by default creates a full stream.
3760 can be used as an alias for
3763 If an incremental stream is received, then the destination file system must
3764 already exist, and its most recent snapshot must match the incremental stream's
3768 the destination device link is destroyed and recreated, which means the
3770 cannot be accessed during the
3774 When a snapshot replication package stream that is generated by using the
3775 .Nm zfs Cm send Fl R
3776 command is received, any snapshots that do not exist on the sending location are
3777 destroyed by using the
3778 .Nm zfs Cm destroy Fl d
3782 .Fl o Em property Ns = Ns Ar value
3785 is specified, it applies to the effective value of the property throughout
3786 the entire subtree of replicated datasets. Effective property values will be
3791 ) on the topmost in the replicated subtree. In descendant datasets, if the
3792 property is set by the send stream, it will be overridden by forcing the
3793 property to be inherited from the top‐most file system. Received properties
3794 are retained in spite of being overridden and may be restored with
3795 .Nm zfs Cm inherit Fl S .
3797 .Fl o Sy origin Ns = Ns Em snapshot
3798 is a special case because, even if
3800 is a read-only property and cannot be set, it's allowed to receive the send
3801 stream as a clone of the given snapshot.
3803 Raw encrypted send streams (created with
3804 .Nm zfs Cm send Fl w
3805 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3806 recompressed by the receive process. Unencrypted streams can be received as
3807 encrypted datasets, either through inheritance or by specifying encryption
3812 The name of the snapshot
3813 .Pq and file system, if a full stream is received
3814 that this subcommand creates depends on the argument type and the use of the
3820 If the argument is a snapshot name, the specified
3823 If the argument is a file system or volume name, a snapshot with the same name
3824 as the sent snapshot is created within the specified
3832 options are specified, the provided target snapshot name is used exactly as
3839 options cause the file system name of the target snapshot to be determined by
3840 appending a portion of the sent snapshot's name to the specified target
3844 option is specified, all but the first element of the sent snapshot's file
3846 .Pq usually the pool name
3847 is used and any required intermediate file systems within the specified one are
3851 option is specified, then only the last element of the sent snapshot's file
3853 .Pq i.e. the name of the source file system itself
3854 is used as the target file system name.
3855 .Bl -tag -width "-F"
3857 Force a rollback of the file system to the most recent snapshot before
3858 performing the receive operation.
3859 If receiving an incremental replication stream
3860 .Po for example, one generated by
3861 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3863 destroy snapshots and file systems that do not exist on the sending side.
3865 Discard the first element of the sent snapshot's file system name, using the
3866 remaining elements to determine the name of the target file system for the new
3867 snapshot as described in the paragraph above.
3869 Discard all but the last element of the sent snapshot's file system name, using
3870 that element to determine the name of the target file system for the new
3871 snapshot as described in the paragraph above.
3873 Do not actually receive the stream.
3874 This can be useful in conjunction with the
3876 option to verify the name the receive operation would use.
3877 .It Fl o Sy origin Ns = Ns Ar snapshot
3878 Forces the stream to be received as a clone of the given snapshot.
3879 If the stream is a full send stream, this will create the filesystem
3880 described by the stream as a clone of the specified snapshot.
3881 Which snapshot was specified will not affect the success or failure of the
3882 receive, as long as the snapshot does exist.
3883 If the stream is an incremental send stream, all the normal verification will be
3885 .It Fl o Em property Ns = Ns Ar value
3886 Sets the specified property as if the command
3887 .Nm zfs Cm set Em property Ns = Ns Ar value
3888 was invoked immediately before the receive. When receiving a stream from
3889 .Nm zfs Cm send Fl R ,
3890 causes the property to be inherited by all descendant datasets, as through
3891 .Nm zfs Cm inherit Em property
3892 was run on any descendant datasets that have this property set on the
3895 Any editable property can be set at receive time. Set-once properties bound
3896 to the received data, such as
3899 .Sy casesensitivity ,
3900 cannot be set at receive time even when the datasets are newly created by
3901 .Nm zfs Cm receive .
3902 Additionally both settable properties
3906 cannot be set at receive time.
3910 option may be specified multiple times, for different properties. An error
3911 results if the same property is specified in multiple
3917 If the receive is interrupted, save the partially received state, rather
3919 Interruption may be due to premature termination of the stream
3920 .Po e.g. due to network failure or failure of the remote system
3921 if the stream is being read over a network connection
3923 a checksum error in the stream, termination of the
3925 process, or unclean shutdown of the system.
3927 The receive can be resumed with a stream generated by
3928 .Nm zfs Cm send Fl t Ar token ,
3932 .Sy receive_resume_token
3933 property of the filesystem or volume which is received into.
3935 To use this flag, the storage pool must have the
3936 .Sy extensible_dataset
3939 .Xr zpool-features 5
3940 for details on ZFS feature flags.
3942 File system that is associated with the received stream is not mounted.
3944 Print verbose information about the stream and the time required to perform the
3946 .It Fl x Em property
3947 Ensures that the effective value of the specified property after the
3948 receive is unaffected by the value of that property in the send stream (if any),
3949 as if the property had been excluded from the send stream.
3951 If the specified property is not present in the send stream, this option does
3954 If a received property needs to be overridden, the effective value will be
3955 set or inherited, depending on whether the property is inheritable or not.
3957 In the case of an incremental update,
3959 leaves any existing local setting or explicit inheritance unchanged.
3963 restrictions on set-once and special properties apply equally to
3970 .Ar filesystem Ns | Ns Ar volume
3972 Abort an interrupted
3973 .Nm zfs Cm receive Fl s ,
3974 deleting its saved partially received state.
3978 .Ar filesystem Ns | Ns Ar volume
3980 Displays permissions that have been delegated on the specified filesystem or
3982 See the other forms of
3984 for more information.
3986 Delegations are supported under Linux with the exception of
3994 These permissions cannot be delegated because the Linux
3996 command restricts modifications of the global namespace to the root user.
4001 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4002 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4003 .Ar setname Oc Ns ...
4004 .Ar filesystem Ns | Ns Ar volume
4009 .Fl e Ns | Ns Sy everyone
4010 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4011 .Ar setname Oc Ns ...
4012 .Ar filesystem Ns | Ns Ar volume
4014 Delegates ZFS administration permission for the file systems to non-privileged
4016 .Bl -tag -width "-d"
4018 Allow only for the descendent file systems.
4019 .It Fl e Ns | Ns Sy everyone
4020 Specifies that the permissions be delegated to everyone.
4021 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
4022 Explicitly specify that permissions are delegated to the group.
4026 only for the specified file system.
4027 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
4028 Explicitly specify that permissions are delegated to the user.
4029 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4030 Specifies to whom the permissions are delegated.
4031 Multiple entities can be specified as a comma-separated list.
4034 options are specified, then the argument is interpreted preferentially as the
4037 then as a user name, and lastly as a group name.
4038 To specify a user or group named
4045 To specify a group with the same name as a user, use the
4049 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4050 .Ar setname Oc Ns ...
4052 The permissions to delegate.
4053 Multiple permissions may be specified as a comma-separated list.
4054 Permission names are the same as ZFS subcommand and property names.
4055 See the property list below.
4056 Property set names, which begin with
4061 form below for details.
4066 options are specified, or both are, then the permissions are allowed for the
4067 file system or volume, and all of its descendents.
4069 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4071 The following permissions are available:
4074 allow subcommand Must also have the permission that is
4076 clone subcommand Must also have the 'create' ability and
4077 'mount' ability in the origin file system
4078 create subcommand Must also have the 'mount' ability
4079 destroy subcommand Must also have the 'mount' ability
4080 diff subcommand Allows lookup of paths within a dataset
4081 given an object number, and the ability
4082 to create snapshots necessary to
4084 load-key subcommand Allows loading and unloading of encryption key
4085 (see 'zfs load-key' and 'zfs unload-key').
4086 change-key subcommand Allows changing an encryption key via
4088 mount subcommand Allows mount/umount of ZFS datasets
4089 promote subcommand Must also have the 'mount' and 'promote'
4090 ability in the origin file system
4091 receive subcommand Must also have the 'mount' and 'create'
4093 rename subcommand Must also have the 'mount' and 'create'
4094 ability in the new parent
4095 rollback subcommand Must also have the 'mount' ability
4097 share subcommand Allows sharing file systems over NFS
4099 snapshot subcommand Must also have the 'mount' ability
4101 groupquota other Allows accessing any groupquota@...
4103 groupused other Allows reading any groupused@... property
4104 userprop other Allows changing any user property
4105 userquota other Allows accessing any userquota@...
4107 userused other Allows reading any userused@... property
4108 projectobjquota other Allows accessing any projectobjquota@...
4110 projectquota other Allows accessing any projectquota@... property
4111 projectobjused other Allows reading any projectobjused@... property
4112 projectused other Allows reading any projectused@... property
4118 casesensitivity property
4120 compression property
4124 filesystem_limit property
4127 normalization property
4128 primarycache property
4133 refreservation property
4134 reservation property
4135 secondarycache property
4140 snapshot_limit property
4143 volblocksize property
4153 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4154 .Ar setname Oc Ns ...
4155 .Ar filesystem Ns | Ns Ar volume
4160 These permissions are granted
4162 to the creator of any newly-created descendent file system.
4166 .Fl s No @ Ns Ar setname
4167 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4168 .Ar setname Oc Ns ...
4169 .Ar filesystem Ns | Ns Ar volume
4171 Defines or adds permissions to a permission set.
4172 The set can be used by other
4174 commands for the specified file system and its descendents.
4175 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4176 Permission sets follow the same naming restrictions as ZFS file systems, but the
4177 name must begin with
4179 and can be no more than 64 characters long.
4184 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4185 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4186 .Ar setname Oc Ns ... Oc
4187 .Ar filesystem Ns | Ns Ar volume
4192 .Fl e Ns | Ns Sy everyone
4193 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4194 .Ar setname Oc Ns ... Oc
4195 .Ar filesystem Ns | Ns Ar volume
4201 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4202 .Ar setname Oc Ns ... Oc
4203 .Ar filesystem Ns | Ns Ar volume
4205 Removes permissions that were granted with the
4208 No permissions are explicitly denied, so other permissions granted are still in
4210 For example, if the permission is granted by an ancestor.
4211 If no permissions are specified, then all permissions for the specified
4223 only removes the permissions that were granted to everyone, not all permissions
4224 for every user and group.
4227 command for a description of the
4230 .Bl -tag -width "-r"
4232 Recursively remove the permissions from this file system and all descendents.
4238 .Fl s No @ Ns Ar setname
4239 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4240 .Ar setname Oc Ns ... Oc
4241 .Ar filesystem Ns | Ns Ar volume
4243 Removes permissions from a permission set.
4244 If no permissions are specified, then all permissions are removed, thus removing
4250 .Ar tag Ar snapshot Ns ...
4252 Adds a single reference, named with the
4254 argument, to the specified snapshot or snapshots.
4255 Each snapshot has its own tag namespace, and tags must be unique within that
4258 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4262 .Bl -tag -width "-r"
4264 Specifies that a hold with the given tag is applied recursively to the snapshots
4265 of all descendent file systems.
4273 Lists all existing user references for the given snapshot or snapshots.
4274 .Bl -tag -width "-r"
4276 Lists the holds that are set on the named descendent snapshots, in addition to
4277 listing the holds on the named snapshot.
4283 .Ar tag Ar snapshot Ns ...
4285 Removes a single reference, named with the
4287 argument, from the specified snapshot or snapshots.
4288 The tag must already exist for each snapshot.
4289 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4293 .Bl -tag -width "-r"
4295 Recursively releases a hold with the given tag on the snapshots of all
4296 descendent file systems.
4302 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4304 Display the difference between a snapshot of a given filesystem and another
4305 snapshot of that filesystem from a later time or the current contents of the
4307 The first column is a character indicating the type of change, the other columns
4308 indicate pathname, new pathname
4309 .Pq in case of rename ,
4310 change in link count, and optionally file type and/or change time.
4311 The types of change are:
4313 - The path has been removed
4314 + The path has been created
4315 M The path has been modified
4316 R The path has been renamed
4318 .Bl -tag -width "-F"
4320 Display an indication of the type of file, in a manner similar to the
4336 Give more parsable tab-separated output, without header lines and without
4339 Display the path's inode change time as the first column of output.
4346 .Op Fl m Ar memory_limit
4352 as a ZFS channel program on
4355 program interface allows ZFS administrative operations to be run
4356 programmatically via a Lua script.
4357 The entire script is executed atomically, with no other administrative
4358 operations taking effect concurrently.
4359 A library of ZFS calls is made available to channel program scripts.
4360 Channel programs may only be run with root privileges.
4362 For full documentation of the ZFS channel program interface, see the manual
4367 Display channel program output in JSON format. When this flag is specified and
4368 standard output is empty - channel program encountered an error. The details of
4369 such an error will be printed to standard error in plain text.
4371 Executes a read-only channel program, which runs faster.
4372 The program cannot change on-disk state by calling functions from
4373 the zfs.sync submodule.
4374 The program can be used to gather information such as properties and
4375 determining if changes would succeed (zfs.check.*).
4376 Without this flag, all pending changes must be synced to disk before
4377 a channel program can complete.
4379 Execution time limit, in milliseconds.
4380 If a channel program executes for longer than the provided timeout, it will
4381 be stopped and an error will be returned.
4382 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
4383 .It Fl m Ar memory-limit
4384 Memory limit, in bytes.
4385 If a channel program attempts to allocate more memory than the given limit,
4386 it will be stopped and an error returned.
4387 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4389 All remaining argument strings are passed directly to the channel program as
4393 for more information.
4399 .Op Fl L Ar keylocation
4400 .Fl a | Ar filesystem
4404 allowing it and all children that inherit the
4406 property to be accessed. The key will be expected in the format specified by the
4408 and location specified by the
4410 property. Note that if the
4414 the terminal will interactively wait for the key to be entered. Loading a key
4415 will not automatically mount the dataset. If that functionality is desired,
4416 .Nm zfs Cm mount Sy -l
4417 will ask for the key and mount the dataset. Once the key is loaded the
4419 property will become
4421 .Bl -tag -width "-r"
4423 Recursively loads the keys for the specified filesystem and all descendent
4426 Loads the keys for all encryption roots in all imported pools.
4430 load-key. This will cause zfs to simply check that the
4431 provided key is correct. This command may be run even if the key is already
4433 .It Fl L Ar keylocation
4438 property. This will not change the value of the property on the dataset. Note
4439 that if used with either
4444 may only be given as
4451 .Fl a | Ar filesystem
4453 Unloads a key from ZFS, removing the ability to access the dataset and all of
4454 its children that inherit the
4456 property. This requires that the dataset is not currently open or mounted. Once
4457 the key is unloaded the
4459 property will become
4461 .Bl -tag -width "-r"
4463 Recursively unloads the keys for the specified filesystem and all descendent
4466 Unloads the keys for all encryption roots in all imported pools.
4472 .Op Fl o Ar keylocation Ns = Ns Ar value
4473 .Op Fl o Ar keyformat Ns = Ns Ar value
4474 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4484 Allows a user to change the encryption key used to access a dataset. This
4485 command requires that the existing key for the dataset is already loaded into
4486 ZFS. This command may also be used to change the
4491 properties as needed. If the dataset was not previously an encryption root it
4492 will become one. Alternatively, the
4494 flag may be provided to cause an encryption root to inherit the parent's key
4496 .Bl -tag -width "-r"
4498 Ensures the key is loaded before attempting to change the key. This is
4499 effectively equivalent to
4500 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4501 .It Fl o Ar property Ns = Ns Ar value
4502 Allows the user to set encryption key properties (
4507 ) while changing the key. This is the only way to alter
4511 after the dataset has been created.
4513 Indicates that zfs should make
4515 inherit the key of its parent. Note that this command can only be run on an
4516 encryption root that has an encrypted parent.
4522 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4523 options were specified.
4526 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4527 The following commands create a file system named
4529 and a file system named
4533 is set for the parent file system, and is automatically inherited by the child
4536 # zfs create pool/home
4537 # zfs set mountpoint=/export/home pool/home
4538 # zfs create pool/home/bob
4540 .It Sy Example 2 No Creating a ZFS Snapshot
4541 The following command creates a snapshot named
4543 This snapshot is mounted on demand in the
4545 directory at the root of the
4549 # zfs snapshot pool/home/bob@yesterday
4551 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4552 The following command creates snapshots named
4556 and all of its descendent file systems.
4557 Each snapshot is mounted on demand in the
4559 directory at the root of its file system.
4560 The second command destroys the newly created snapshots.
4562 # zfs snapshot -r pool/home@yesterday
4563 # zfs destroy -r pool/home@yesterday
4565 .It Sy Example 4 No Disabling and Enabling File System Compression
4566 The following command disables the
4568 property for all file systems under
4570 The next command explicitly enables
4573 .Em pool/home/anne .
4575 # zfs set compression=off pool/home
4576 # zfs set compression=on pool/home/anne
4578 .It Sy Example 5 No Listing ZFS Datasets
4579 The following command lists all active file systems and volumes in the system.
4580 Snapshots are displayed if the
4588 for more information on pool properties.
4591 NAME USED AVAIL REFER MOUNTPOINT
4592 pool 450K 457G 18K /pool
4593 pool/home 315K 457G 21K /export/home
4594 pool/home/anne 18K 457G 18K /export/home/anne
4595 pool/home/bob 276K 457G 276K /export/home/bob
4597 .It Sy Example 6 No Setting a Quota on a ZFS File System
4598 The following command sets a quota of 50 Gbytes for
4601 # zfs set quota=50G pool/home/bob
4603 .It Sy Example 7 No Listing ZFS Properties
4604 The following command lists all properties for
4607 # zfs get all pool/home/bob
4608 NAME PROPERTY VALUE SOURCE
4609 pool/home/bob type filesystem -
4610 pool/home/bob creation Tue Jul 21 15:53 2009 -
4611 pool/home/bob used 21K -
4612 pool/home/bob available 20.0G -
4613 pool/home/bob referenced 21K -
4614 pool/home/bob compressratio 1.00x -
4615 pool/home/bob mounted yes -
4616 pool/home/bob quota 20G local
4617 pool/home/bob reservation none default
4618 pool/home/bob recordsize 128K default
4619 pool/home/bob mountpoint /pool/home/bob default
4620 pool/home/bob sharenfs off default
4621 pool/home/bob checksum on default
4622 pool/home/bob compression on local
4623 pool/home/bob atime on default
4624 pool/home/bob devices on default
4625 pool/home/bob exec on default
4626 pool/home/bob setuid on default
4627 pool/home/bob readonly off default
4628 pool/home/bob zoned off default
4629 pool/home/bob snapdir hidden default
4630 pool/home/bob acltype off default
4631 pool/home/bob aclinherit restricted default
4632 pool/home/bob canmount on default
4633 pool/home/bob xattr on default
4634 pool/home/bob copies 1 default
4635 pool/home/bob version 4 -
4636 pool/home/bob utf8only off -
4637 pool/home/bob normalization none -
4638 pool/home/bob casesensitivity sensitive -
4639 pool/home/bob vscan off default
4640 pool/home/bob nbmand off default
4641 pool/home/bob sharesmb off default
4642 pool/home/bob refquota none default
4643 pool/home/bob refreservation none default
4644 pool/home/bob primarycache all default
4645 pool/home/bob secondarycache all default
4646 pool/home/bob usedbysnapshots 0 -
4647 pool/home/bob usedbydataset 21K -
4648 pool/home/bob usedbychildren 0 -
4649 pool/home/bob usedbyrefreservation 0 -
4652 The following command gets a single property value.
4654 # zfs get -H -o value compression pool/home/bob
4657 The following command lists all properties with local settings for
4660 # zfs get -r -s local -o name,property,value all pool/home/bob
4662 pool/home/bob quota 20G
4663 pool/home/bob compression on
4665 .It Sy Example 8 No Rolling Back a ZFS File System
4666 The following command reverts the contents of
4668 to the snapshot named
4670 deleting all intermediate snapshots.
4672 # zfs rollback -r pool/home/anne@yesterday
4674 .It Sy Example 9 No Creating a ZFS Clone
4675 The following command creates a writable file system whose initial contents are
4677 .Em pool/home/bob@yesterday .
4679 # zfs clone pool/home/bob@yesterday pool/clone
4681 .It Sy Example 10 No Promoting a ZFS Clone
4682 The following commands illustrate how to test out changes to a file system, and
4683 then replace the original file system with the changed one, using clones, clone
4684 promotion, and renaming:
4686 # zfs create pool/project/production
4687 populate /pool/project/production with data
4688 # zfs snapshot pool/project/production@today
4689 # zfs clone pool/project/production@today pool/project/beta
4690 make changes to /pool/project/beta and test them
4691 # zfs promote pool/project/beta
4692 # zfs rename pool/project/production pool/project/legacy
4693 # zfs rename pool/project/beta pool/project/production
4694 once the legacy version is no longer needed, it can be destroyed
4695 # zfs destroy pool/project/legacy
4697 .It Sy Example 11 No Inheriting ZFS Properties
4698 The following command causes
4704 property from their parent.
4706 # zfs inherit checksum pool/home/bob pool/home/anne
4708 .It Sy Example 12 No Remotely Replicating ZFS Data
4709 The following commands send a full stream and then an incremental stream to a
4710 remote machine, restoring them into
4711 .Em poolB/received/fs@a
4713 .Em poolB/received/fs@b ,
4716 must contain the file system
4717 .Em poolB/received ,
4718 and must not initially contain
4719 .Em poolB/received/fs .
4721 # zfs send pool/fs@a | \e
4722 ssh host zfs receive poolB/received/fs@a
4723 # zfs send -i a pool/fs@b | \e
4724 ssh host zfs receive poolB/received/fs
4726 .It Sy Example 13 No Using the zfs receive -d Option
4727 The following command sends a full stream of
4728 .Em poolA/fsA/fsB@snap
4729 to a remote machine, receiving it into
4730 .Em poolB/received/fsA/fsB@snap .
4733 portion of the received snapshot's name is determined from the name of the sent
4736 must contain the file system
4737 .Em poolB/received .
4739 .Em poolB/received/fsA
4740 does not exist, it is created as an empty file system.
4742 # zfs send poolA/fsA/fsB@snap | \e
4743 ssh host zfs receive -d poolB/received
4745 .It Sy Example 14 No Setting User Properties
4746 The following example sets the user-defined
4747 .Sy com.example:department
4748 property for a dataset.
4750 # zfs set com.example:department=12345 tank/accounting
4752 .It Sy Example 15 No Performing a Rolling Snapshot
4753 The following example shows how to maintain a history of snapshots with a
4754 consistent naming scheme.
4755 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4756 renames the remaining snapshots, and then creates a new snapshot, as follows:
4758 # zfs destroy -r pool/users@7daysago
4759 # zfs rename -r pool/users@6daysago @7daysago
4760 # zfs rename -r pool/users@5daysago @6daysago
4761 # zfs rename -r pool/users@yesterday @5daysago
4762 # zfs rename -r pool/users@yesterday @4daysago
4763 # zfs rename -r pool/users@yesterday @3daysago
4764 # zfs rename -r pool/users@yesterday @2daysago
4765 # zfs rename -r pool/users@today @yesterday
4766 # zfs snapshot -r pool/users@today
4768 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4769 The following commands show how to set
4771 property options to enable
4775 addresses and to enable root access for system
4781 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4786 for host name resolution, specify the fully qualified hostname.
4787 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4788 The following example shows how to set permissions so that user
4790 can create, destroy, mount, and take snapshots on
4796 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4797 # zfs allow tank/cindys
4798 ---- Permissions on tank/cindys --------------------------------------
4799 Local+Descendent permissions:
4800 user cindys create,destroy,mount,snapshot
4805 mount point permission is set to 755 by default, user
4807 will be unable to mount file systems under
4809 Add an ACE similar to the following syntax to provide mount point access:
4811 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4813 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4814 The following example shows how to grant anyone in the group
4816 to create file systems in
4818 This syntax also allows staff members to destroy their own file systems, but not
4819 destroy anyone else's file system.
4824 # zfs allow staff create,mount tank/users
4825 # zfs allow -c destroy tank/users
4826 # zfs allow tank/users
4827 ---- Permissions on tank/users ---------------------------------------
4830 Local+Descendent permissions:
4831 group staff create,mount
4833 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4834 The following example shows how to define and grant a permission set on the
4841 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4842 # zfs allow staff @pset tank/users
4843 # zfs allow tank/users
4844 ---- Permissions on tank/users ---------------------------------------
4846 @pset create,destroy,mount,snapshot
4847 Local+Descendent permissions:
4850 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4851 The following example shows to grant the ability to set quotas and reservations
4859 # zfs allow cindys quota,reservation users/home
4860 # zfs allow users/home
4861 ---- Permissions on users/home ---------------------------------------
4862 Local+Descendent permissions:
4863 user cindys quota,reservation
4864 cindys% zfs set quota=10G users/home/marks
4865 cindys% zfs get quota users/home/marks
4866 NAME PROPERTY VALUE SOURCE
4867 users/home/marks quota 10G local
4869 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4870 The following example shows how to remove the snapshot permission from the
4879 # zfs unallow staff snapshot tank/users
4880 # zfs allow tank/users
4881 ---- Permissions on tank/users ---------------------------------------
4883 @pset create,destroy,mount,snapshot
4884 Local+Descendent permissions:
4887 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4888 The following example shows how to see what has changed between a prior
4889 snapshot of a ZFS dataset and its current state.
4892 option is used to indicate type information for the files affected.
4894 # zfs diff -F tank/test@before tank/test
4896 M F /tank/test/linked (+1)
4897 R F /tank/test/oldname -> /tank/test/newname
4898 - F /tank/test/deleted
4899 + F /tank/test/created
4900 M F /tank/test/modified
4902 .It Sy Example 23 No Creating a bookmark
4903 The following example create a bookmark to a snapshot. This bookmark
4904 can then be used instead of snapshot in send streams.
4906 # zfs bookmark rpool@snapshot rpool#bookmark
4908 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4909 The following example show how to share SMB filesystem through ZFS. Note that
4910 that a user and his/her password must be given.
4912 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4913 -o user=workgroup/turbo,password=obrut,uid=1000
4917 .Em /etc/samba/smb.conf
4918 configuration required:
4920 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4921 communicate with Samba. This is the default behavior for most Linux
4924 Samba must be able to authenticate a user. This can be done in a number of
4925 ways, depending on if using the system password file, LDAP or the Samba
4926 specific smbpasswd file. How to do this is outside the scope of this manual.
4929 man page for more information.
4932 .Sy USERSHARE section
4935 man page for all configuration options in case you need to modify any options
4936 to the share afterwards. Do note that any changes done with the
4938 command will be undone if the share is ever unshared (such as at a reboot etc).
4940 .Sh INTERFACE STABILITY
projects / mirror_zfs.git / blob