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, 2016 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 2017 Nexenta Systems, Inc.
30 .\" Copyright 2018 Joyent, Inc.
37 .Nd configures ZFS file systems
44 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
50 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Fl V Ar size Ar volume
55 .Ar filesystem Ns | Ns Ar volume
59 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
60 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
63 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
67 .Oo Fl o Ar property Ns = Ns value Oc Ns ...
68 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
76 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
77 .Ar snapshot Ar filesystem Ns | Ns Ar volume
84 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
89 .Ar filesystem Ns | Ns Ar volume
90 .Ar filesystem Ns | Ns Ar volume
94 .Ar snapshot Ar snapshot
97 .Op Fl r Ns | Ns Fl d Ar depth
99 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
100 .Oo Fl s Ar property Oc Ns ...
101 .Oo Fl S Ar property Oc Ns ...
102 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
103 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
106 .Ar filesystem Ns | Ns Ar volume
109 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
110 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
113 .Op Fl r Ns | Ns Fl d Ar depth
115 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
116 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
117 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
118 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
119 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
123 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
133 .Fl a | Ar filesystem
137 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
138 .Oo Fl s Ar field Oc Ns ...
139 .Oo Fl S Ar field Oc Ns ...
140 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
141 .Ar filesystem Ns | Ns Ar snapshot
145 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
146 .Oo Fl s Ar field Oc Ns ...
147 .Oo Fl S Ar field Oc Ns ...
148 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
149 .Ar filesystem Ns | Ns Ar snapshot
156 .Fl a | Ar filesystem
160 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
163 .Fl a | Ar filesystem
166 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
169 .Ar snapshot bookmark
173 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
178 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
179 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
183 .Fl t Ar receive_resume_token
187 .Op Fl o Sy origin Ns = Ns Ar snapshot
188 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
192 .Op Fl d Ns | Ns Fl e
193 .Op Fl o Sy origin Ns = Ns Ar snapshot
198 .Ar filesystem Ns | Ns Ar volume
201 .Ar filesystem Ns | Ns Ar volume
205 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
206 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
207 .Ar setname Oc Ns ...
208 .Ar filesystem Ns | Ns Ar volume
212 .Fl e Ns | Ns Sy everyone
213 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
214 .Ar setname Oc Ns ...
215 .Ar filesystem Ns | Ns Ar volume
219 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
220 .Ar setname Oc Ns ...
221 .Ar filesystem Ns | Ns Ar volume
224 .Fl s No @ Ns Ar setname
225 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
226 .Ar setname Oc Ns ...
227 .Ar filesystem Ns | Ns Ar volume
231 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
232 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
233 .Ar setname Oc Ns ... Oc
234 .Ar filesystem Ns | Ns Ar volume
238 .Fl e Ns | Ns Sy everyone
239 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
240 .Ar setname Oc Ns ... Oc
241 .Ar filesystem Ns | Ns Ar volume
246 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
247 .Ar setname Oc Ns ... Oc
248 .Ar filesystem Ns | Ns Ar volume
252 .Fl s @ Ns Ar setname
253 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
254 .Ar setname Oc Ns ... Oc
255 .Ar filesystem Ns | Ns Ar volume
259 .Ar tag Ar snapshot Ns ...
267 .Ar tag Ar snapshot Ns ...
271 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
276 .Op Fl m Ar memory_limit
282 command configures ZFS datasets within a ZFS storage pool, as described in
284 A dataset is identified by a unique path within the ZFS namespace.
287 pool/{filesystem,volume,snapshot}
290 where the maximum length of a dataset name is
293 and the maximum amount of nesting allowed in a path is 50 levels deep.
295 A dataset can be one of the following:
296 .Bl -tag -width "file system"
298 A ZFS dataset of type
300 can be mounted within the standard system namespace and behaves like other file
302 While ZFS file systems are designed to be POSIX compliant, known issues exist
303 that prevent compliance in some cases.
304 Applications that depend on standards conformance might fail due to non-standard
305 behavior when checking file system free space.
307 A logical volume exported as a raw or block device.
308 This type of dataset should only be used under special circumstances.
309 File systems are typically used in most environments.
311 A read-only version of a file system or volume at a given point in time.
313 .Ar filesystem Ns @ Ns Ar name
315 .Ar volume Ns @ Ns Ar name .
317 .Ss ZFS File System Hierarchy
318 A ZFS storage pool is a logical collection of devices that provide space for
320 A storage pool is also the root of the ZFS file system hierarchy.
322 The root of the pool can be accessed as a file system, such as mounting and
323 unmounting, taking snapshots, and setting properties.
324 The physical storage characteristics, however, are managed by the
330 for more information on creating and administering pools.
332 A snapshot is a read-only copy of a file system or volume.
333 Snapshots can be created extremely quickly, and initially consume no additional
334 space within the pool.
335 As data within the active dataset changes, the snapshot consumes more data than
336 would otherwise be shared with the active dataset.
338 Snapshots can have arbitrary names.
339 Snapshots of volumes can be cloned or rolled back, but cannot be accessed
342 File system snapshots can be accessed under the
344 directory in the root of the file system.
345 Snapshots are automatically mounted on demand and may be unmounted at regular
347 The visibility of the
349 directory can be controlled by the
353 A clone is a writable volume or file system whose initial contents are the same
355 As with snapshots, creating a clone is nearly instantaneous, and initially
356 consumes no additional space.
358 Clones can only be created from a snapshot.
359 When a snapshot is cloned, it creates an implicit dependency between the parent
361 Even though the clone is created somewhere else in the dataset hierarchy, the
362 original snapshot cannot be destroyed as long as a clone exists.
365 property exposes this dependency, and the
367 command lists any such dependencies, if they exist.
369 The clone parent-child dependency relationship can be reversed by using the
374 file system to become a clone of the specified file system, which makes it
375 possible to destroy the file system that the clone was created from.
377 Creating a ZFS file system is a simple operation, so the number of file systems
378 per system is likely to be numerous.
379 To cope with this, ZFS automatically manages mounting and unmounting file
380 systems without the need to edit the
383 All automatically managed file systems are mounted by ZFS at boot time.
385 By default, file systems are mounted under
389 is the name of the file system in the ZFS namespace.
390 Directories are created and destroyed as needed.
392 A file system can also have a mount point set in the
395 This directory is created as needed, and ZFS automatically mounts the file
397 .Nm zfs Cm mount Fl a
404 property can be inherited, so if
410 automatically inherits a mount point of
411 .Pa /export/stuff/user .
417 prevents the file system from being mounted.
419 If needed, ZFS file systems can also be managed with traditional tools
425 If a file system's mount point is set to
427 ZFS makes no attempt to manage the file system, and the administrator is
428 responsible for mounting and unmounting the file system.
430 A ZFS file system can be added to a non-global zone by using the
431 .Nm zonecfg Cm add Sy fs
433 A ZFS file system that is added to a non-global zone must have its
438 The physical properties of an added file system are controlled by the global
440 However, the zone administrator can create, modify, or destroy files within the
441 added file system, depending on how the file system is mounted.
443 A dataset can also be delegated to a non-global zone by using the
444 .Nm zonecfg Cm add Sy dataset
446 You cannot delegate a dataset to one zone and the children of the same dataset
448 The zone administrator can change properties of the dataset or any of its
455 properties of the delegated dataset can be modified only by the global
458 A ZFS volume can be added as a device to a non-global zone by using the
459 .Nm zonecfg Cm add Sy device
461 However, its physical properties can be modified only by the global
464 For more information about
469 After a dataset is delegated to a non-global zone, the
471 property is automatically set.
472 A zoned file system cannot be mounted in the global zone, since the zone
473 administrator might have to set the mount point to an unacceptable value.
475 The global administrator can forcibly clear the
477 property, though this should be done with extreme care.
478 The global administrator should verify that all the mount points are acceptable
479 before clearing the property.
480 .Ss Native Properties
481 Properties are divided into two types, native properties and user-defined
486 Native properties either export internal statistics or control ZFS behavior.
487 In addition, native properties are either editable or read-only.
488 User properties have no effect on ZFS behavior, but you can use them to annotate
489 datasets in a way that is meaningful in your environment.
490 For more information about user properties, see the
494 Every dataset has a set of properties that export statistics about the dataset
495 as well as control various behaviors.
496 Properties are inherited from the parent unless overridden by the child.
497 Some properties apply only to certain types of datasets
498 .Pq file systems, volumes, or snapshots .
500 The values of numeric properties can be specified using human-readable suffixes
510 The following are all valid
513 .Li 1536M, 1.5g, 1.50GB .
515 The values of non-numeric properties are case sensitive and must be lowercase,
522 The following native properties consist of read-only statistics about the
524 These properties can be neither set, nor inherited.
525 Native properties apply to all dataset types unless otherwise noted.
526 .Bl -tag -width "usedbyrefreservation"
528 The amount of space available to the dataset and all its children, assuming that
529 there is no other activity in the pool.
530 Because space is shared within a pool, availability can be limited by any number
531 of factors, including physical pool size, quotas, reservations, or other
532 datasets within the pool.
534 This property can also be referred to by its shortened column name,
537 For non-snapshots, the compression ratio achieved for the
539 space of this dataset, expressed as a multiplier.
542 property includes descendant datasets, and, for clones, does not include the
543 space shared with the origin snapshot.
549 Compression can be turned on by running:
550 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
554 The time this dataset was created.
556 For snapshots, this property is a comma-separated list of filesystems or volumes
557 which are clones of this snapshot.
560 property is this snapshot.
563 property is not empty, then this snapshot can not be destroyed
573 if the snapshot has been marked for deferred destroy by using the
574 .Nm zfs Cm destroy Fl d
576 Otherwise, the property is
578 .It Sy filesystem_count
579 The total number of filesystems and volumes that exist under this location in
581 This value is only available when a
583 has been set somewhere in the tree under which the dataset resides.
584 .It Sy logicalreferenced
585 The amount of space that is
587 accessible by this dataset.
591 The logical space ignores the effect of the
595 properties, giving a quantity closer to the amount of data that applications
597 However, it does include space consumed by metadata.
599 This property can also be referred to by its shortened column name,
602 The amount of space that is
604 consumed by this dataset and all its descendents.
608 The logical space ignores the effect of the
612 properties, giving a quantity closer to the amount of data that applications
614 However, it does include space consumed by metadata.
616 This property can also be referred to by its shortened column name,
619 For file systems, indicates whether the file system is currently mounted.
620 This property can be either
625 For cloned file systems or volumes, the snapshot from which the clone was
630 .It Sy receive_resume_token
631 For filesystems or volumes which have saved partially-completed state from
633 this opaque token can be provided to
635 to resume and complete the
638 The amount of data that is accessible by this dataset, which may or may not be
639 shared with other datasets in the pool.
640 When a snapshot or clone is created, it initially references the same amount of
641 space as the file system or snapshot it was created from, since its contents are
644 This property can also be referred to by its shortened column name,
646 .It Sy refcompressratio
647 The compression ratio achieved for the
649 space of this dataset, expressed as a multiplier.
653 .It Sy snapshot_count
654 The total number of snapshots that exist under this location in the dataset
656 This value is only available when a
658 has been set somewhere in the tree under which the dataset resides.
666 The amount of space consumed by this dataset and all its descendents.
667 This is the value that is checked against this dataset's quota and reservation.
668 The space used does not include this dataset's reservation, but does take into
669 account the reservations of any descendent datasets.
670 The amount of space that a dataset consumes from its parent, as well as the
671 amount of space that is freed if this dataset is recursively destroyed, is the
672 greater of its space used and its reservation.
674 The used space of a snapshot
679 is space that is referenced exclusively by this snapshot.
680 If this snapshot is destroyed, the amount of
683 Space that is shared by multiple snapshots isn't accounted for in this metric.
684 When a snapshot is destroyed, space that was previously shared with this
685 snapshot can become unique to snapshots adjacent to it, thus changing the used
686 space of those snapshots.
687 The used space of the latest snapshot can also be affected by changes in the
691 space of a snapshot is a subset of the
693 space of the snapshot.
695 The amount of space used, available, or referenced does not take into account
697 Pending changes are generally accounted for within a few seconds.
698 Committing a change to a disk using
702 does not necessarily guarantee that the space usage information is updated
707 properties decompose the
709 properties into the various reasons that space is used.
712 .Sy usedbychildren No +
713 .Sy usedbydataset No +
714 .Sy usedbyrefreservation No +
715 .Sy usedbysnapshots .
716 These properties are only available for datasets created on
720 .It Sy usedbychildren
721 The amount of space used by children of this dataset, which would be freed if
722 all the dataset's children were destroyed.
724 The amount of space used by this dataset itself, which would be freed if the
725 dataset were destroyed
726 .Po after first removing any
728 and destroying any necessary snapshots or descendents
730 .It Sy usedbyrefreservation
731 The amount of space used by a
733 set on this dataset, which would be freed if the
736 .It Sy usedbysnapshots
737 The amount of space consumed by snapshots of this dataset.
738 In particular, it is the amount of space that would be freed if all of this
739 dataset's snapshots were destroyed.
740 Note that this is not simply the sum of the snapshots'
742 properties because space can be shared by multiple snapshots.
743 .It Sy userused Ns @ Ns Em user
744 The amount of space consumed by the specified user in this dataset.
745 Space is charged to the owner of each file, as displayed by
747 The amount of space charged is displayed by
753 subcommand for more information.
755 Unprivileged users can access only their own space usage.
756 The root user, or a user who has been granted the
760 can access everyone's usage.
763 .Sy userused Ns @ Ns Em ...
764 properties are not displayed by
765 .Nm zfs Cm get Sy all .
766 The user's name must be appended after the @ symbol, using one of the following
768 .Bl -bullet -width ""
782 .Sy joe.smith@mydomain
791 This property is set to the number of user holds on this snapshot.
792 User holds are set by using the
795 .It Sy groupused Ns @ Ns Em group
796 The amount of space consumed by the specified group in this dataset.
797 Space is charged to the group of each file, as displayed by
800 .Sy userused Ns @ Ns Em user
801 property for more information.
803 Unprivileged users can only access their own groups' space usage.
804 The root user, or a user who has been granted the
808 can access all groups' usage.
810 For volumes, specifies the block size of the volume.
813 cannot be changed once the volume has been written, so it should be set at
814 volume creation time.
817 for volumes is 8 Kbytes.
818 Any power of 2 from 512 bytes to 128 Kbytes is valid.
820 This property can also be referred to by its shortened column name,
825 by this dataset, that was written since the previous snapshot
826 .Pq i.e. that is not referenced by the previous snapshot .
827 .It Sy written Ns @ Ns Em snapshot
830 space written to this dataset since the specified snapshot.
831 This is the space that is referenced by this dataset but was not referenced by
832 the specified snapshot.
836 may be specified as a short snapshot name
837 .Po just the part after the
840 in which case it will be interpreted as a snapshot in the same filesystem as
844 may be a full snapshot name
845 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
846 which for clones may be a snapshot in the origin's filesystem
847 .Pq or the origin of the origin's filesystem, etc.
850 The following native properties can be used to change the behavior of a ZFS
854 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
855 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
857 Controls how ACEs are inherited when files and directories are created.
858 .Bl -tag -width "passthrough-x"
860 does not inherit any ACEs.
862 only inherits inheritable ACEs that specify
870 permissions when the ACE is inherited.
872 inherits all inheritable ACEs without any modifications.
881 ACEs inherit the execute permission only if the file creation mode also requests
885 When the property value is set to
887 files are created with a mode determined by the inheritable ACEs.
888 If no inheritable ACEs exist that affect the mode, then the mode is set in
889 accordance to the requested mode from the application.
891 .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
892 .Sy passthrough Ns | Ns Sy restricted
894 Controls how an ACL is modified during
896 and how inherited ACEs are modified by the file creation mode.
897 .Bl -tag -width "passthrough"
899 default, deletes all ACEs except for those representing the mode of the file or
900 directory requested by
903 reduces permissions granted by all
905 entries found in the ACL such that they are no greater than the group
906 permissions specified by the mode.
908 indicates that no changes are made to the ACL other than creating or updating
909 the necessary ACEs to represent the new mode of the file or directory.
913 operation to return an error when used on any file or directory which has a
914 non-trivial ACL, with entries in addition to those that represent the mode.
918 is required to change the set user ID, set group ID, or sticky bit on a file or
919 directory, as they do not have equivalent ACEs.
922 on a file or directory with a non-trivial ACL when
926 you must first remove all ACEs except for those that represent the current mode.
927 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
928 Controls whether the access time for files is updated when they are read.
929 Turning this property off avoids producing write traffic when reading files and
930 can result in significant performance gains, though it might confuse mailers
931 and other similar utilities.
934 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
935 If this property is set to
937 the file system cannot be mounted, and is ignored by
938 .Nm zfs Cm mount Fl a .
939 Setting this property to
941 is similar to setting the
945 except that the dataset still has a normal
947 property, which can be inherited.
948 Setting this property to
950 allows datasets to be used solely as a mechanism to inherit properties.
951 One example of setting
952 .Sy canmount Ns = Ns Sy off
953 is to have two datasets with the same
955 so that the children of both datasets appear in the same directory, but might
956 have different inherited characteristics.
960 a dataset can only be mounted and unmounted explicitly.
961 The dataset is not mounted automatically when the dataset is created or
962 imported, nor is it mounted by the
963 .Nm zfs Cm mount Fl a
964 command or unmounted by the
965 .Nm zfs Cm unmount Fl a
968 This property is not inherited.
970 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
971 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
972 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
974 Controls the checksum used to verify data integrity.
977 which automatically selects an appropriate algorithm
980 but this may change in future releases
984 disables integrity checking on user data.
987 not only disables integrity but also disables maintaining parity for user data.
988 This setting is used internally by a dump device residing on a RAID-Z pool and
989 should not be used by any other dataset.
990 Disabling checksums is
992 a recommended practice.
999 checksum algorithms require enabling the appropriate features on the pool.
1001 .Xr zpool-features 5
1002 for more information on these algorithms.
1004 Changing this property affects only newly-written data.
1006 Salted checksum algorithms
1007 .Pq Cm edonr , skein
1008 are currently not supported for any filesystem on the boot pools.
1010 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1011 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1013 Controls the compression algorithm used for this dataset.
1015 Setting compression to
1017 indicates that the current default compression algorithm should be used.
1018 The default balances compression and decompression speed, with compression ratio
1019 and is expected to work well on a wide variety of workloads.
1020 Unlike all other settings for this property,
1022 does not select a fixed compression type.
1023 As new compression algorithms are added to ZFS and enabled on a pool, the
1024 default compression algorithm may change.
1025 The current default compression algorithm is either
1034 compression algorithm is a high-performance replacement for the
1037 It features significantly faster compression and decompression, as well as a
1038 moderately higher compression ratio than
1040 but can only be used on pools with the
1045 .Xr zpool-features 5
1046 for details on ZFS feature flags and the
1052 compression algorithm is optimized for performance while providing decent data
1057 compression algorithm uses the same compression as the
1062 level by using the value
1066 is an integer from 1
1069 .Pq best compression ratio .
1074 .Po which is also the default for
1080 compression algorithm compresses runs of zeros.
1082 This property can also be referred to by its shortened column name
1084 Changing this property affects only newly-written data.
1085 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1086 Controls the number of copies of data stored for this dataset.
1087 These copies are in addition to any redundancy provided by the pool, for
1088 example, mirroring or RAID-Z.
1089 The copies are stored on different disks, if possible.
1090 The space used by multiple copies is charged to the associated file and dataset,
1093 property and counting against quotas and reservations.
1095 Changing this property only affects newly-written data.
1096 Therefore, set this property at file system creation time by using the
1097 .Fl o Sy copies Ns = Ns Ar N
1099 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1100 Controls whether device nodes can be opened on this file system.
1101 The default value is
1103 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1104 Controls whether processes can be executed from within this file system.
1105 The default value is
1107 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1108 Limits the number of filesystems and volumes that can exist under this point in
1110 The limit is not enforced if the user is allowed to change the limit.
1112 .Sy filesystem_limit
1115 a descendent of a filesystem that already has a
1116 .Sy filesystem_limit
1117 does not override the ancestor's
1118 .Sy filesystem_limit ,
1119 but rather imposes an additional limit.
1120 This feature must be enabled to be used
1122 .Xr zpool-features 5
1124 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1125 Controls the mount point used for this file system.
1128 section for more information on how this property is used.
1132 property is changed for a file system, the file system and any children that
1133 inherit the mount point are unmounted.
1136 then they remain unmounted.
1137 Otherwise, they are automatically remounted in the new location if the property
1142 or if they were mounted before the property was changed.
1143 In addition, any shared file systems are unshared and shared in the new
1145 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1146 Controls whether the file system should be mounted with
1148 .Pq Non Blocking mandatory locks .
1149 This is used for SMB clients.
1150 Changes to this property only take effect when the file system is umounted and
1154 for more information on
1157 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1158 Controls what is cached in the primary cache
1160 If this property is set to
1162 then both user data and metadata is cached.
1163 If this property is set to
1165 then neither user data nor metadata is cached.
1166 If this property is set to
1168 then only metadata is cached.
1169 The default value is
1171 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1172 Limits the amount of space a dataset and its descendents can consume.
1173 This property enforces a hard limit on the amount of space used.
1174 This includes all space consumed by descendents, including file systems and
1176 Setting a quota on a descendent of a dataset that already has a quota does not
1177 override the ancestor's quota, but rather imposes an additional limit.
1179 Quotas cannot be set on volumes, as the
1181 property acts as an implicit quota.
1182 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1183 Limits the number of snapshots that can be created on a dataset and its
1187 on a descendent of a dataset that already has a
1189 does not override the ancestor's
1190 .Sy snapshot_limit ,
1191 but rather imposes an additional limit.
1192 The limit is not enforced if the user is allowed to change the limit.
1193 For example, this means that recursive snapshots taken from the global zone are
1194 counted against each delegated dataset within a zone.
1195 This feature must be enabled to be used
1197 .Xr zpool-features 5
1199 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1200 Limits the amount of space consumed by the specified user.
1201 User space consumption is identified by the
1202 .Sy userspace@ Ns Em user
1205 Enforcement of user quotas may be delayed by several seconds.
1206 This delay means that a user might exceed their quota before the system notices
1207 that they are over quota and begins to refuse additional writes with the
1211 .Nm zfs Cm userspace
1212 subcommand for more information.
1214 Unprivileged users can only access their own groups' space usage.
1215 The root user, or a user who has been granted the
1219 can get and set everyone's quota.
1221 This property is not available on volumes, on file systems before version 4, or
1222 on pools before version 15.
1224 .Sy userquota@ Ns Em ...
1225 properties are not displayed by
1226 .Nm zfs Cm get Sy all .
1227 The user's name must be appended after the
1229 symbol, using one of the following forms:
1237 .Em POSIX numeric ID
1244 .Sy joe.smith@mydomain
1252 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1253 Limits the amount of space consumed by the specified group.
1254 Group space consumption is identified by the
1255 .Sy groupused@ Ns Em group
1258 Unprivileged users can access only their own groups' space usage.
1259 The root user, or a user who has been granted the
1263 can get and set all groups' quotas.
1264 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1265 Controls whether this dataset can be modified.
1266 The default value is
1269 This property can also be referred to by its shortened column name,
1271 .It Sy recordsize Ns = Ns Em size
1272 Specifies a suggested block size for files in the file system.
1273 This property is designed solely for use with database workloads that access
1274 files in fixed-size records.
1275 ZFS automatically tunes block sizes according to internal algorithms optimized
1276 for typical access patterns.
1278 For databases that create very large files but access them in small random
1279 chunks, these algorithms may be suboptimal.
1282 greater than or equal to the record size of the database can result in
1283 significant performance gains.
1284 Use of this property for general purpose file systems is strongly discouraged,
1285 and may adversely affect performance.
1287 The size specified must be a power of two greater than or equal to 512 and less
1288 than or equal to 128 Kbytes.
1291 feature is enabled on the pool, the size may be up to 1 Mbyte.
1293 .Xr zpool-features 5
1294 for details on ZFS feature flags.
1296 Changing the file system's
1298 affects only files created afterward; existing files are unaffected.
1300 This property can also be referred to by its shortened column name,
1302 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1303 Controls what types of metadata are stored redundantly.
1304 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1305 the amount of user data lost is limited.
1306 This extra copy is in addition to any redundancy provided at the pool level
1307 .Pq e.g. by mirroring or RAID-Z ,
1308 and is in addition to an extra copy specified by the
1311 .Pq up to a total of 3 copies .
1312 For example if the pool is mirrored,
1313 .Sy copies Ns = Ns 2 ,
1315 .Sy redundant_metadata Ns = Ns Sy most ,
1316 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1321 ZFS stores an extra copy of all metadata.
1322 If a single on-disk block is corrupt, at worst a single block of user data
1331 ZFS stores an extra copy of most types of metadata.
1332 This can improve performance of random writes, because less metadata must be
1334 In practice, at worst about 100 blocks
1339 of user data can be lost if a single on-disk block is corrupt.
1340 The exact behavior of which metadata blocks are stored redundantly may change in
1343 The default value is
1345 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1346 Limits the amount of space a dataset can consume.
1347 This property enforces a hard limit on the amount of space used.
1348 This hard limit does not include space used by descendents, including file
1349 systems and snapshots.
1350 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1351 The minimum amount of space guaranteed to a dataset, not including its
1353 When the amount of space used is below this value, the dataset is treated as if
1354 it were taking up the amount of space specified by
1355 .Sy refreservation .
1358 reservation is accounted for in the parent datasets' space used, and counts
1359 against the parent datasets' quotas and reservations.
1363 is set, a snapshot is only allowed if there is enough free pool space outside of
1364 this reservation to accommodate the current number of
1366 bytes in the dataset.
1372 a volume is thick provisioned
1376 .Sy refreservation Ns = Ns Sy auto
1377 is only supported on volumes.
1381 .Sx Native Properties
1382 section for more information about sparse volumes.
1384 This property can also be referred to by its shortened column name,
1386 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1387 The minimum amount of space guaranteed to a dataset and its descendants.
1388 When the amount of space used is below this value, the dataset is treated as if
1389 it were taking up the amount of space specified by its reservation.
1390 Reservations are accounted for in the parent datasets' space used, and count
1391 against the parent datasets' quotas and reservations.
1393 This property can also be referred to by its shortened column name,
1395 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1396 Controls what is cached in the secondary cache
1398 If this property is set to
1400 then both user data and metadata is cached.
1401 If this property is set to
1403 then neither user data nor metadata is cached.
1404 If this property is set to
1406 then only metadata is cached.
1407 The default value is
1409 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1410 Controls whether the setuid bit is respected for the file system.
1411 The default value is
1413 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1414 Controls whether the file system is shared via SMB, and what options are to be
1416 A file system with the
1420 is managed through traditional tools such as
1422 Otherwise, the file system is automatically shared and unshared with the
1427 If the property is set to
1431 command is invoked with no options.
1434 command is invoked with options equivalent to the contents of this property.
1436 Because SMB shares requires a resource name, a unique resource name is
1437 constructed from the dataset name.
1438 The constructed name is a copy of the dataset name except that the characters in
1439 the dataset name, which would be invalid in the resource name, are replaced with
1445 is also supported that allows you to replace the data set name with a specified
1447 The specified name is then used to replace the prefix dataset in the case of
1449 For example, if the dataset
1452 .Sy name Ns = Ns Sy john ,
1455 has a resource name of
1458 .Em data/home/john/backups
1459 is shared, it has a resource name of
1462 When SMB shares are created, the SMB share name appears as an entry in the
1469 command to display the share-level ACLs on the entries in this directory.
1473 property is changed for a dataset, the dataset and any children inheriting the
1474 property are re-shared with the new options, only if the property was previously
1477 or if they were shared before the property was changed.
1478 If the new property is set to
1480 the file systems are unshared.
1481 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1482 Controls whether the file system is shared via NFS, and what options are to be
1484 A file system with a
1488 is managed through traditional tools such as
1493 Otherwise, the file system is automatically shared and unshared with the
1498 If the property is set to
1501 command is invoked with no options.
1504 command is invoked with options equivalent to the contents of this property.
1508 property is changed for a dataset, the dataset and any children inheriting the
1509 property are re-shared with the new options, only if the property was previously
1511 or if they were shared before the property was changed.
1512 If the new property is
1514 the file systems are unshared.
1515 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1516 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1522 ZFS will use pool log devices
1524 to handle the requests at low latency.
1529 ZFS will not use configured pool log devices.
1530 ZFS will instead optimize synchronous operations for global pool throughput and
1531 efficient use of resources.
1532 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1533 Controls whether the
1535 directory is hidden or visible in the root of the file system as discussed in
1539 The default value is
1541 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1542 Controls the behavior of synchronous requests
1543 .Pq e.g. fsync, O_DSYNC .
1547 specified behavior of ensuring all synchronous requests are written to stable
1548 storage and all devices are flushed to ensure data is not cached by device
1550 .Pq this is the default .
1552 causes every file system transaction to be written and flushed before its
1553 system call returns.
1554 This has a large performance penalty.
1556 disables synchronous requests.
1557 File system transactions are only committed to stable storage periodically.
1558 This option will give the highest performance.
1559 However, it is very dangerous as ZFS would be ignoring the synchronous
1560 transaction demands of applications such as databases or NFS.
1561 Administrators should only use this option when the risks are understood.
1562 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1563 The on-disk version of this file system, which is independent of the pool
1565 This property can only be set to later supported versions.
1569 .It Sy volsize Ns = Ns Em size
1570 For volumes, specifies the logical size of the volume.
1571 By default, creating a volume establishes a reservation of equal size.
1572 For storage pools with a version number of 9 or higher, a
1577 are reflected in an equivalent change to the reservation
1583 can only be set to a multiple of
1587 The reservation is kept equal to the volume's logical size to prevent unexpected
1588 behavior for consumers.
1589 Without the reservation, the volume could run out of space, resulting in
1590 undefined behavior or data corruption, depending on how the volume is used.
1591 These effects can also occur when the volume size is changed while it is in use
1592 .Pq particularly when shrinking the size .
1593 Extreme care should be used when adjusting the volume size.
1595 Though not recommended, a
1598 .Qq thin provisioned
1600 can be created by specifying the
1603 .Nm zfs Cm create Fl V
1604 command, or by changing the value of the
1609 property on pool version 8 or earlier
1611 after the volume has been created.
1614 is a volume where the value of
1616 is less than the size of the volume plus the space required to store its
1618 Consequently, writes to a sparse volume can fail with
1620 when the pool is low on space.
1621 For a sparse volume, changes to
1623 are not reflected in the
1625 A volume that is not sparse is said to be
1626 .Qq thick provisioned .
1627 A sparse volume can become thick provisioned by setting
1631 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1632 Controls whether regular files should be scanned for viruses when a file is
1634 In addition to enabling this property, the virus scan service must also be
1635 enabled for virus scanning to occur.
1636 The default value is
1638 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off
1639 Controls whether extended attributes are enabled for this file system.
1640 The default value is
1642 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1643 Controls whether the dataset is managed from a non-global zone.
1646 section for more information.
1647 The default value is
1651 The following three properties cannot be changed after the file system is
1652 created, and therefore, should be set when the file system is created.
1653 If the properties are not set with the
1657 commands, these properties are inherited from the parent dataset.
1658 If the parent dataset lacks these properties due to having been created prior to
1659 these features being supported, the new file system will have the default values
1660 for these properties.
1663 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1664 .Sy insensitive Ns | Ns Sy mixed
1666 Indicates whether the file name matching algorithm used by the file system
1667 should be case-sensitive, case-insensitive, or allow a combination of both
1669 The default value for the
1677 file systems have case-sensitive file names.
1683 property indicates that the file system can support requests for both
1684 case-sensitive and case-insensitive matching behavior.
1685 Currently, case-insensitive matching behavior on a file system that supports
1686 mixed behavior is limited to the SMB server product.
1687 For more information about the
1689 value behavior, see the "ZFS Administration Guide".
1691 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1692 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1694 Indicates whether the file system should perform a
1696 normalization of file names whenever two file names are compared, and which
1697 normalization algorithm should be used.
1698 File names are always stored unmodified, names are normalized as part of any
1700 If this property is set to a legal value other than
1704 property was left unspecified, the
1706 property is automatically set to
1708 The default value of the
1712 This property cannot be changed after the file system is created.
1713 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1714 Indicates whether the file system should reject file names that include
1715 characters that are not present in the
1718 If this property is explicitly set to
1720 the normalization property must either not be explicitly set or be set to
1722 The default value for the
1726 This property cannot be changed after the file system is created.
1730 .Sy casesensitivity ,
1734 properties are also new permissions that can be assigned to non-privileged users
1735 by using the ZFS delegated administration feature.
1736 .Ss "Temporary Mount Point Properties"
1737 When a file system is mounted, either through
1739 for legacy mounts or the
1741 command for normal file systems, its mount options are set according to its
1743 The correlation between properties and mount options is as follows:
1745 PROPERTY MOUNT OPTION
1746 devices devices/nodevices
1749 setuid setuid/nosetuid
1753 In addition, these options can be set on a per-mount basis using the
1755 option, without affecting the property that is stored on disk.
1756 The values specified on the command line override the values stored in the
1760 option is an alias for
1761 .Sy nodevices Ns \&, Ns Sy nosetuid .
1762 These properties are reported as
1767 If the properties are changed while the dataset is mounted, the new setting
1768 overrides any temporary settings.
1769 .Ss "User Properties"
1770 In addition to the standard native properties, ZFS supports arbitrary user
1772 User properties have no effect on ZFS behavior, but applications or
1773 administrators can use them to annotate datasets
1774 .Pq file systems, volumes, and snapshots .
1776 User property names must contain a colon
1778 character to distinguish them from native properties.
1779 They may contain lowercase letters, numbers, and the following punctuation
1788 The expected convention is that the property name is divided into two portions
1790 .Em module Ns \&: Ns Em property ,
1791 but this namespace is not enforced by ZFS.
1792 User property names can be at most 256 characters, and cannot begin with a dash
1795 When making programmatic use of user properties, it is strongly suggested to use
1800 component of property names to reduce the chance that two
1801 independently-developed packages use the same property name for different
1804 The values of user properties are arbitrary strings, are always inherited, and
1805 are never validated.
1806 All of the commands that operate on properties
1807 .Po Nm zfs Cm list ,
1812 can be used to manipulate both native properties and user properties.
1815 command to clear a user property.
1816 If the property is not defined in any parent dataset, it is removed entirely.
1817 Property values are limited to 8192 bytes.
1818 .Ss ZFS Volumes as Swap or Dump Devices
1819 During an initial installation a swap device and dump device are created on ZFS
1820 volumes in the ZFS root pool.
1821 By default, the swap area size is based on 1/2 the size of physical memory up to
1823 The size of the dump device depends on the kernel's requirements at installation
1825 Separate ZFS volumes must be used for the swap area and dump devices.
1826 Do not swap to a file on a ZFS file system.
1827 A ZFS swap file configuration is not supported.
1829 If you need to change your swap area or dump device after the system is
1830 installed or upgraded, use the
1836 All subcommands that modify state are logged persistently to the pool in their
1840 Displays a help message.
1845 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1848 Creates a new ZFS file system.
1849 The file system is automatically mounted according to the
1851 property inherited from the parent.
1852 .Bl -tag -width "-o"
1853 .It Fl o Ar property Ns = Ns Ar value
1854 Sets the specified property as if the command
1855 .Nm zfs Cm set Ar property Ns = Ns Ar value
1856 was invoked at the same time the dataset was created.
1857 Any editable ZFS property can also be set at creation time.
1860 options can be specified.
1861 An error results if the same property is specified in multiple
1865 Creates all the non-existing parent datasets.
1866 Datasets created in this manner are automatically mounted according to the
1868 property inherited from their parent.
1869 Any property specified on the command line using the
1872 If the target filesystem already exists, the operation completes successfully.
1878 .Op Fl b Ar blocksize
1879 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1880 .Fl V Ar size Ar volume
1882 Creates a volume of the given size.
1883 The volume is exported as a block device in
1884 .Pa /dev/zvol/{dsk,rdsk}/path ,
1887 is the name of the volume in the ZFS namespace.
1888 The size represents the logical size as exported by the device.
1889 By default, a reservation of equal size is created.
1892 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
1893 has an integral number of blocks regardless of
1895 .Bl -tag -width "-b"
1896 .It Fl b Ar blocksize
1898 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
1899 If this option is specified in conjunction with
1900 .Fl o Sy volblocksize ,
1901 the resulting behavior is undefined.
1902 .It Fl o Ar property Ns = Ns Ar value
1903 Sets the specified property as if the
1904 .Nm zfs Cm set Ar property Ns = Ns Ar value
1905 command was invoked at the same time the dataset was created.
1906 Any editable ZFS property can also be set at creation time.
1909 options can be specified.
1910 An error results if the same property is specified in multiple
1914 Creates all the non-existing parent datasets.
1915 Datasets created in this manner are automatically mounted according to the
1917 property inherited from their parent.
1918 Any property specified on the command line using the
1921 If the target filesystem already exists, the operation completes successfully.
1923 Creates a sparse volume with no reservation.
1927 .Sx Native Properties
1928 section for more information about sparse volumes.
1934 .Ar filesystem Ns | Ns Ar volume
1936 Destroys the given dataset.
1937 By default, the command unshares any file systems that are currently shared,
1938 unmounts any file systems that are currently mounted, and refuses to destroy a
1939 dataset that has active dependents
1940 .Pq children or clones .
1941 .Bl -tag -width "-R"
1943 Recursively destroy all dependents, including cloned file systems outside the
1946 Force an unmount of any file systems using the
1949 This option has no effect on non-file systems or unmounted file systems.
1954 No data will be deleted.
1955 This is useful in conjunction with the
1959 flags to determine what data would be deleted.
1961 Print machine-parsable verbose information about the deleted data.
1963 Recursively destroy all children.
1965 Print verbose information about the deleted data.
1968 Extreme care should be taken when applying either the
1972 options, as they can destroy large portions of a pool and cause unexpected
1973 behavior for mounted file systems in use.
1978 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
1979 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
1981 The given snapshots are destroyed immediately if and only if the
1985 option would have destroyed it.
1986 Such immediate destruction would occur, for example, if the snapshot had no
1987 clones and the user-initiated reference count were zero.
1989 If a snapshot does not qualify for immediate destruction, it is marked for
1991 In this state, it exists as a usable, visible snapshot until both of the
1992 preconditions listed above are met, at which point it is destroyed.
1994 An inclusive range of snapshots may be specified by separating the first and
1995 last snapshots with a percent sign.
1996 The first and/or last snapshots may be left blank, in which case the
1997 filesystem's oldest or newest snapshot will be implied.
2000 .Pq or ranges of snapshots
2001 of the same filesystem or volume may be specified in a comma-separated list of
2003 Only the snapshot's short name
2004 .Po the part after the
2007 should be specified when using a range or comma-separated list to identify
2009 .Bl -tag -width "-R"
2011 Recursively destroy all clones of these snapshots, including the clones,
2012 snapshots, and children.
2013 If this flag is specified, the
2015 flag will have no effect.
2017 Defer snapshot deletion.
2022 No data will be deleted.
2023 This is useful in conjunction with the
2027 flags to determine what data would be deleted.
2029 Print machine-parsable verbose information about the deleted data.
2032 .Pq or mark for deferred deletion
2033 all snapshots with this name in descendent file systems.
2035 Print verbose information about the deleted data.
2037 Extreme care should be taken when applying either the
2041 options, as they can destroy large portions of a pool and cause unexpected
2042 behavior for mounted file systems in use.
2047 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2049 The given bookmark is destroyed.
2054 .Oo Fl o Ar property Ns = Ns value Oc Ns ...
2055 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2057 Creates snapshots with the given names.
2058 All previous modifications by successful system calls to the file system are
2059 part of the snapshots.
2060 Snapshots are taken atomically, so that all snapshots correspond to the same
2064 section for details.
2065 .Bl -tag -width "-o"
2066 .It Fl o Ar property Ns = Ns Ar value
2067 Sets the specified property; see
2071 Recursively create snapshots of all descendent datasets
2079 Roll back the given dataset to a previous snapshot.
2080 When a dataset is rolled back, all data that has changed since the snapshot is
2081 discarded, and the dataset reverts to the state at the time of the snapshot.
2082 By default, the command refuses to roll back to a snapshot other than the most
2084 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2091 options do not recursively destroy the child snapshots of a recursive snapshot.
2092 Only direct snapshots of the specified filesystem are destroyed by either of
2094 To completely roll back a recursive snapshot, you must rollback the individual
2096 .Bl -tag -width "-R"
2098 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2103 option to force an unmount of any clone file systems that are to be destroyed.
2105 Destroy any snapshots and bookmarks more recent than the one specified.
2111 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2112 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2114 Creates a clone of the given snapshot.
2117 section for details.
2118 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2119 as the same type as the original.
2120 .Bl -tag -width "-o"
2121 .It Fl o Ar property Ns = Ns Ar value
2122 Sets the specified property; see
2126 Creates all the non-existing parent datasets.
2127 Datasets created in this manner are automatically mounted according to the
2129 property inherited from their parent.
2130 If the target filesystem or volume already exists, the operation completes
2136 .Ar clone-filesystem
2138 Promotes a clone file system to no longer be dependent on its
2141 This makes it possible to destroy the file system that the clone was created
2143 The clone parent-child dependency relationship is reversed, so that the origin
2144 file system becomes a clone of the specified file system.
2146 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2147 now owned by the promoted clone.
2148 The space they use moves from the origin file system to the promoted clone, so
2149 enough space must be available to accommodate these snapshots.
2150 No new space is consumed by this operation, but the space accounting is
2152 The promoted clone must not have any conflicting snapshot names of its own.
2155 subcommand can be used to rename any conflicting snapshots.
2160 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2161 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2167 .Ar filesystem Ns | Ns Ar volume
2168 .Ar filesystem Ns | Ns Ar volume
2170 Renames the given dataset.
2171 The new target can be located anywhere in the ZFS hierarchy, with the exception
2173 Snapshots can only be renamed within the parent file system or volume.
2174 When renaming a snapshot, the parent file system of the snapshot does not need
2175 to be specified as part of the second argument.
2176 Renamed file systems can inherit new mount points, in which case they are
2177 unmounted and remounted at the new mount point.
2178 .Bl -tag -width "-a"
2180 Force unmount any filesystems that need to be unmounted in the process.
2182 Creates all the nonexistent parent datasets.
2183 Datasets created in this manner are automatically mounted according to the
2185 property inherited from their parent.
2191 .Ar snapshot Ar snapshot
2193 Recursively rename the snapshots of all descendent datasets.
2194 Snapshots are the only dataset that can be renamed recursively.
2198 .Op Fl r Ns | Ns Fl d Ar depth
2200 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2201 .Oo Fl s Ar property Oc Ns ...
2202 .Oo Fl S Ar property Oc Ns ...
2203 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2204 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2206 Lists the property information for the given datasets in tabular form.
2207 If specified, you can list property information by the absolute pathname or the
2209 By default, all file systems and volumes are displayed.
2210 Snapshots are displayed if the
2217 The following fields are displayed,
2218 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2220 .Bl -tag -width "-H"
2222 Used for scripting mode.
2223 Do not print headers and separate fields by a single tab instead of arbitrary
2225 .It Fl S Ar property
2228 option, but sorts by property in descending order.
2230 Recursively display any children of the dataset, limiting the recursion to
2236 will display only the dataset and its direct children.
2237 .It Fl o Ar property
2238 A comma-separated list of properties to display.
2239 The property must be:
2242 One of the properties described in the
2243 .Sx Native Properties
2250 to display the dataset name
2254 to display space usage properties on file systems and volumes.
2255 This is a shortcut for specifying
2256 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2257 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2258 .Sy filesystem Ns \&, Ns Sy volume
2262 Display numbers in parsable
2266 Recursively display any children of the dataset on the command line.
2267 .It Fl s Ar property
2268 A property for sorting the output by column in ascending order based on the
2269 value of the property.
2270 The property must be one of the properties described in the
2272 section, or the special value
2274 to sort by the dataset name.
2275 Multiple properties can be specified at one time using multiple
2280 options are evaluated from left to right in decreasing order of importance.
2281 The following is a list of sorting criteria:
2284 Numeric types sort in numeric order.
2286 String types sort in alphabetical order.
2288 Types inappropriate for a row sort that row to the literal bottom, regardless of
2289 the specified ordering.
2292 If no sorting options are specified the existing behavior of
2296 A comma-separated list of types to display, where
2305 For example, specifying
2307 displays only snapshots.
2312 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2313 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2315 Sets the property or list of properties to the given value(s) for each dataset.
2316 Only some properties can be edited.
2319 section for more information on what properties can be set and acceptable
2321 Numeric values can be specified as exact values, or in a human-readable form
2323 .Sy B , K , M , G , T , P , E , Z
2324 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2325 or zettabytes, respectively
2327 User properties can be set on snapshots.
2328 For more information, see the
2334 .Op Fl r Ns | Ns Fl d Ar depth
2336 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2337 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2338 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2339 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2340 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2342 Displays properties for the given datasets.
2343 If no datasets are specified, then the command displays properties for all
2344 datasets on the system.
2345 For each property, the following columns are displayed:
2348 property Property name
2349 value Property value
2350 source Property source. Can either be local, default,
2351 temporary, inherited, or none (-).
2354 All columns are displayed by default, though this can be controlled by using the
2357 This command takes a comma-separated list of properties as described in the
2358 .Sx Native Properties
2365 can be used to display all properties that apply to the given dataset's type
2366 .Pq filesystem, volume, snapshot, or bookmark .
2367 .Bl -tag -width "-H"
2369 Display output in a form more easily parsed by scripts.
2370 Any headers are omitted, and fields are explicitly separated by a single tab
2371 instead of an arbitrary amount of space.
2373 Recursively display any children of the dataset, limiting the recursion to
2377 will display only the dataset and its direct children.
2379 A comma-separated list of columns to display.
2380 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2381 is the default value.
2383 Display numbers in parsable
2387 Recursively display properties for any children.
2389 A comma-separated list of sources to display.
2390 Those properties coming from a source other than those in this list are ignored.
2391 Each source must be one of the following:
2398 The default value is all sources.
2400 A comma-separated list of types to display, where
2414 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2416 Clears the specified property, causing it to be inherited from an ancestor,
2417 restored to default if no ancestor has the property set, or with the
2419 option reverted to the received value if one exists.
2422 section for a listing of default values, and details on which properties can be
2424 .Bl -tag -width "-r"
2426 Recursively inherit the given property for all children.
2428 Revert the property to the received value if one exists; otherwise operate as
2431 option was not specified.
2436 .Ar filesystem Ns | Ns Ar volume
2438 Remap the indirect blocks in the given fileystem or volume so that they no
2439 longer reference blocks on previously removed vdevs and we can eventually
2440 shrink the size of the indirect mapping objects for the previously removed
2441 vdevs. Note that remapping all blocks might not be possible and that
2442 references from snapshots will still exist and cannot be remapped.
2447 Displays a list of file systems that are not the most recent version.
2453 Displays a list of currently supported file system versions.
2459 .Fl a | Ar filesystem
2461 Upgrades file systems to a new on-disk version.
2462 Once this is done, the file systems will no longer be accessible on systems
2463 running older versions of the software.
2465 streams generated from new snapshots of these file systems cannot be accessed on
2466 systems running older versions of the software.
2468 In general, the file system version is independent of the pool version.
2471 for information on the
2472 .Nm zpool Cm upgrade
2475 In some cases, the file system version and the pool version are interrelated and
2476 the pool version must be upgraded before the file system version can be
2478 .Bl -tag -width "-V"
2480 Upgrade to the specified
2484 flag is not specified, this command upgrades to the most recent version.
2486 option can only be used to increase the version number, and only up to the most
2487 recent version supported by this software.
2489 Upgrade all file systems on all imported pools.
2491 Upgrade the specified file system.
2493 Upgrade the specified file system and all descendent file systems.
2499 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2500 .Oo Fl s Ar field Oc Ns ...
2501 .Oo Fl S Ar field Oc Ns ...
2502 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2503 .Ar filesystem Ns | Ns Ar snapshot
2505 Displays space consumed by, and quotas on, each user in the specified filesystem
2507 This corresponds to the
2508 .Sy userused@ Ns Em user
2510 .Sy userquota@ Ns Em user
2512 .Bl -tag -width "-H"
2514 Do not print headers, use tab-delimited output.
2516 Sort by this field in reverse order.
2520 Translate SID to POSIX ID.
2521 The POSIX ID may be ephemeral if no mapping exists.
2522 Normal POSIX interfaces
2527 perform this translation, so the
2529 option allows the output from
2530 .Nm zfs Cm userspace
2531 to be compared directly with those utilities.
2534 may lead to confusion if some files were created by an SMB user before a
2535 SMB-to-POSIX name mapping was established.
2536 In such a case, some files will be owned by the SMB entity and some by the POSIX
2540 option will report that the POSIX entity has the total usage and quota for both.
2542 Print numeric ID instead of user/group name.
2543 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2544 Display only the specified fields from the following set:
2549 The default is to display all fields.
2555 Sort output by this field.
2560 flags may be specified multiple times to sort first by one field, then by
2563 .Fl s Sy type Fl s Sy name .
2564 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2565 Print only the specified types from the following set:
2572 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
2573 The default can be changed to include group types.
2579 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2580 .Oo Fl s Ar field Oc Ns ...
2581 .Oo Fl S Ar field Oc Ns ...
2582 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2583 .Ar filesystem Ns | Ns Ar snapshot
2585 Displays space consumed by, and quotas on, each group in the specified
2586 filesystem or snapshot.
2587 This subcommand is identical to
2588 .Nm zfs Cm userspace ,
2589 except that the default types to display are
2590 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
2595 Displays all ZFS file systems currently mounted.
2601 .Fl a | Ar filesystem
2603 Mounts ZFS file systems.
2604 .Bl -tag -width "-O"
2606 Perform an overlay mount.
2609 for more information.
2611 Mount all available ZFS file systems.
2612 Invoked automatically as part of the boot process.
2614 Mount the specified filesystem.
2616 An optional, comma-separated list of mount options to use temporarily for the
2617 duration of the mount.
2619 .Sx Temporary Mount Point Properties
2620 section for details.
2622 Report mount progress.
2628 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2630 Unmounts currently mounted ZFS file systems.
2631 .Bl -tag -width "-a"
2633 Unmount all available ZFS file systems.
2634 Invoked automatically as part of the shutdown process.
2635 .It Ar filesystem Ns | Ns Ar mountpoint
2636 Unmount the specified filesystem.
2637 The command can also be given a path to a ZFS file system mount point on the
2640 Forcefully unmount the file system, even if it is currently in use.
2645 .Fl a | Ar filesystem
2647 Shares available ZFS file systems.
2648 .Bl -tag -width "-a"
2650 Share all available ZFS file systems.
2651 Invoked automatically as part of the boot process.
2653 Share the specified filesystem according to the
2658 File systems are shared when the
2667 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2669 Unshares currently shared ZFS file systems.
2670 .Bl -tag -width "-a"
2672 Unshare all available ZFS file systems.
2673 Invoked automatically as part of the shutdown process.
2674 .It Ar filesystem Ns | Ns Ar mountpoint
2675 Unshare the specified filesystem.
2676 The command can also be given a path to a ZFS file system shared on the system.
2681 .Ar snapshot bookmark
2683 Creates a bookmark of the given snapshot.
2684 Bookmarks mark the point in time when the snapshot was created, and can be used
2685 as the incremental source for a
2689 This feature must be enabled to be used.
2691 .Xr zpool-features 5
2692 for details on ZFS feature flags and the
2699 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2702 Creates a stream representation of the second
2704 which is written to standard output.
2705 The output can be redirected to a file or to a different system
2706 .Po for example, using
2709 By default, a full stream is generated.
2710 .Bl -tag -width "-D"
2712 Generate a deduplicated stream.
2713 Blocks which would have been sent multiple times in the send stream will only be
2715 The receiving system must also support this feature to receive a deduplicated
2717 This flag can be used regardless of the dataset's
2719 property, but performance will be much better if the filesystem uses a
2720 dedup-capable checksum
2724 .It Fl I Ar snapshot
2725 Generate a stream package that sends all intermediary snapshots from the first
2726 snapshot to the second snapshot.
2730 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
2731 The incremental source may be specified as with the
2734 .It Fl L, -large-block
2735 Generate a stream which may contain blocks larger than 128KB.
2736 This flag has no effect if the
2738 pool feature is disabled, or if the
2740 property of this filesystem has never been set above 128KB.
2741 The receiving system must have the
2743 pool feature enabled as well.
2745 .Xr zpool-features 5
2746 for details on ZFS feature flags and the
2750 Print machine-parsable verbose information about the stream package generated.
2751 .It Fl R, -replicate
2752 Generate a replication stream package, which will replicate the specified
2753 file system, and all descendent file systems, up to the named snapshot.
2754 When received, all properties, snapshots, descendent file systems, and clones
2761 flags are used in conjunction with the
2763 flag, an incremental replication stream is generated.
2764 The current values of properties, and current snapshot and file system names are
2765 set when the stream is received.
2768 flag is specified when this stream is received, snapshots and file systems that
2769 do not exist on the sending side are destroyed.
2771 Generate a more compact stream by using
2773 records for blocks which are stored more compactly on disk by the
2776 This flag has no effect if the
2778 feature is disabled.
2779 The receiving system must have the
2784 feature is active on the sending system, then the receiving system must have
2785 that feature enabled as well.
2787 .Xr zpool-features 5
2788 for details on ZFS feature flags and the
2791 .It Fl c, -compressed
2792 Generate a more compact stream by using compressed WRITE records for blocks
2793 which are compressed on disk and in memory
2796 property for details
2800 feature is active on the sending system, then the receiving system must have
2801 that feature enabled as well.
2804 feature is enabled on the sending system but the
2806 option is not supplied in conjunction with
2808 then the data will be decompressed before sending so it can be split into
2809 smaller block sizes.
2810 .It Fl i Ar snapshot
2811 Generate an incremental stream from the first
2813 .Pq the incremental source
2816 .Pq the incremental target .
2817 The incremental source can be specified as the last component of the snapshot
2821 character and following
2823 and it is assumed to be from the same file system as the incremental target.
2825 If the destination is a clone, the source may be the origin snapshot, which must
2828 .Em pool/fs@origin ,
2836 Do not generate any actual send data.
2837 This is useful in conjunction with the
2841 flags to determine what data will be sent.
2842 In this case, the verbose output will be written to standard output
2843 .Po contrast with a non-dry-run, where the stream is written to standard output
2844 and the verbose output goes to standard error
2847 Include the dataset's properties in the stream.
2848 This flag is implicit when
2851 The receiving system must also support this feature.
2853 Print verbose information about the stream package generated.
2854 This information includes a per-second report of how much data has been sent.
2856 The format of the stream is committed.
2857 You will be able to receive your streams on future versions of ZFS .
2863 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
2864 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2866 Generate a send stream, which may be of a filesystem, and may be incremental
2868 If the destination is a filesystem or volume, the pool must be read-only, or the
2869 filesystem must not be mounted.
2870 When the stream generated from a filesystem or volume is received, the default
2871 snapshot name will be
2873 .Bl -tag -width "-L"
2874 .It Fl L, -large-block
2875 Generate a stream which may contain blocks larger than 128KB.
2876 This flag has no effect if the
2878 pool feature is disabled, or if the
2880 property of this filesystem has never been set above 128KB.
2881 The receiving system must have the
2883 pool feature enabled as well.
2885 .Xr zpool-features 5
2886 for details on ZFS feature flags and the
2889 .It Fl c, -compressed
2890 Generate a more compact stream by using compressed WRITE records for blocks
2891 which are compressed on disk and in memory
2894 property for details
2898 feature is active on the sending system, then the receiving system must have
2899 that feature enabled as well.
2902 feature is enabled on the sending system but the
2904 option is not supplied in conjunction with
2906 then the data will be decompressed before sending so it can be split into
2907 smaller block sizes.
2909 Generate a more compact stream by using
2911 records for blocks which are stored more compactly on disk by the
2914 This flag has no effect if the
2916 feature is disabled.
2917 The receiving system must have the
2922 feature is active on the sending system, then the receiving system must have
2923 that feature enabled as well.
2925 .Xr zpool-features 5
2926 for details on ZFS feature flags and the
2929 .It Fl i Ar snapshot Ns | Ns Ar bookmark
2930 Generate an incremental send stream.
2931 The incremental source must be an earlier snapshot in the destination's history.
2932 It will commonly be an earlier snapshot in the destination's file system, in
2933 which case it can be specified as the last component of the name
2938 character and following
2941 If the incremental target is a clone, the incremental source can be the origin
2942 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
2950 .Ar receive_resume_token
2952 Creates a send stream which resumes an interrupted receive.
2954 .Ar receive_resume_token
2955 is the value of this property on the filesystem or volume that was being
2957 See the documentation for
2964 .Op Fl o Sy origin Ns = Ns Ar snapshot
2965 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2971 .Op Fl d Ns | Ns Fl e
2972 .Op Fl o Sy origin Ns = Ns Ar snapshot
2975 Creates a snapshot whose contents are as specified in the stream provided on
2977 If a full stream is received, then a new file system is created as well.
2978 Streams are created using the
2980 subcommand, which by default creates a full stream.
2982 can be used as an alias for
2985 If an incremental stream is received, then the destination file system must
2986 already exist, and its most recent snapshot must match the incremental stream's
2990 the destination device link is destroyed and recreated, which means the
2992 cannot be accessed during the
2996 When a snapshot replication package stream that is generated by using the
2997 .Nm zfs Cm send Fl R
2998 command is received, any snapshots that do not exist on the sending location are
2999 destroyed by using the
3000 .Nm zfs Cm destroy Fl d
3003 The name of the snapshot
3004 .Pq and file system, if a full stream is received
3005 that this subcommand creates depends on the argument type and the use of the
3011 If the argument is a snapshot name, the specified
3014 If the argument is a file system or volume name, a snapshot with the same name
3015 as the sent snapshot is created within the specified
3023 options are specified, the provided target snapshot name is used exactly as
3030 options cause the file system name of the target snapshot to be determined by
3031 appending a portion of the sent snapshot's name to the specified target
3035 option is specified, all but the first element of the sent snapshot's file
3037 .Pq usually the pool name
3038 is used and any required intermediate file systems within the specified one are
3042 option is specified, then only the last element of the sent snapshot's file
3044 .Pq i.e. the name of the source file system itself
3045 is used as the target file system name.
3046 .Bl -tag -width "-F"
3048 Force a rollback of the file system to the most recent snapshot before
3049 performing the receive operation.
3050 If receiving an incremental replication stream
3051 .Po for example, one generated by
3052 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3054 destroy snapshots and file systems that do not exist on the sending side.
3056 Discard the first element of the sent snapshot's file system name, using the
3057 remaining elements to determine the name of the target file system for the new
3058 snapshot as described in the paragraph above.
3060 Discard all but the last element of the sent snapshot's file system name, using
3061 that element to determine the name of the target file system for the new
3062 snapshot as described in the paragraph above.
3064 Do not actually receive the stream.
3065 This can be useful in conjunction with the
3067 option to verify the name the receive operation would use.
3068 .It Fl o Sy origin Ns = Ns Ar snapshot
3069 Forces the stream to be received as a clone of the given snapshot.
3070 If the stream is a full send stream, this will create the filesystem
3071 described by the stream as a clone of the specified snapshot.
3072 Which snapshot was specified will not affect the success or failure of the
3073 receive, as long as the snapshot does exist.
3074 If the stream is an incremental send stream, all the normal verification will be
3077 File system that is associated with the received stream is not mounted.
3079 Print verbose information about the stream and the time required to perform the
3082 If the receive is interrupted, save the partially received state, rather
3084 Interruption may be due to premature termination of the stream
3085 .Po e.g. due to network failure or failure of the remote system
3086 if the stream is being read over a network connection
3088 a checksum error in the stream, termination of the
3090 process, or unclean shutdown of the system.
3092 The receive can be resumed with a stream generated by
3093 .Nm zfs Cm send Fl t Ar token ,
3097 .Sy receive_resume_token
3098 property of the filesystem or volume which is received into.
3100 To use this flag, the storage pool must have the
3101 .Sy extensible_dataset
3104 .Xr zpool-features 5
3105 for details on ZFS feature flags.
3111 .Ar filesystem Ns | Ns Ar volume
3113 Abort an interrupted
3114 .Nm zfs Cm receive Fl s ,
3115 deleting its saved partially received state.
3119 .Ar filesystem Ns | Ns Ar volume
3121 Displays permissions that have been delegated on the specified filesystem or
3123 See the other forms of
3125 for more information.
3130 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3131 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3132 .Ar setname Oc Ns ...
3133 .Ar filesystem Ns | Ns Ar volume
3138 .Fl e Ns | Ns Sy everyone
3139 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3140 .Ar setname Oc Ns ...
3141 .Ar filesystem Ns | Ns Ar volume
3143 Delegates ZFS administration permission for the file systems to non-privileged
3145 .Bl -tag -width "-d"
3147 Allow only for the descendent file systems.
3148 .It Fl e Ns | Ns Sy everyone
3149 Specifies that the permissions be delegated to everyone.
3150 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3151 Explicitly specify that permissions are delegated to the group.
3155 only for the specified file system.
3156 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3157 Explicitly specify that permissions are delegated to the user.
3158 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3159 Specifies to whom the permissions are delegated.
3160 Multiple entities can be specified as a comma-separated list.
3163 options are specified, then the argument is interpreted preferentially as the
3166 then as a user name, and lastly as a group name.
3167 To specify a user or group named
3174 To specify a group with the same name as a user, use the
3178 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3179 .Ar setname Oc Ns ...
3181 The permissions to delegate.
3182 Multiple permissions may be specified as a comma-separated list.
3183 Permission names are the same as ZFS subcommand and property names.
3184 See the property list below.
3185 Property set names, which begin with
3190 form below for details.
3195 options are specified, or both are, then the permissions are allowed for the
3196 file system or volume, and all of its descendents.
3198 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3200 The following permissions are available:
3203 allow subcommand Must also have the permission that is
3205 clone subcommand Must also have the 'create' ability and
3206 'mount' ability in the origin file system
3207 create subcommand Must also have the 'mount' ability
3208 destroy subcommand Must also have the 'mount' ability
3209 diff subcommand Allows lookup of paths within a dataset
3210 given an object number, and the ability
3211 to create snapshots necessary to
3213 mount subcommand Allows mount/umount of ZFS datasets
3214 promote subcommand Must also have the 'mount' and 'promote'
3215 ability in the origin file system
3216 receive subcommand Must also have the 'mount' and 'create'
3218 rename subcommand Must also have the 'mount' and 'create'
3219 ability in the new parent
3220 rollback subcommand Must also have the 'mount' ability
3222 share subcommand Allows sharing file systems over NFS
3224 snapshot subcommand Must also have the 'mount' ability
3226 groupquota other Allows accessing any groupquota@...
3228 groupused other Allows reading any groupused@... property
3229 userprop other Allows changing any user property
3230 userquota other Allows accessing any userquota@...
3232 userused other Allows reading any userused@... property
3238 casesensitivity property
3240 compression property
3244 filesystem_limit property
3247 normalization property
3248 primarycache property
3253 refreservation property
3254 reservation property
3255 secondarycache property
3260 snapshot_limit property
3263 volblocksize property
3273 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3274 .Ar setname Oc Ns ...
3275 .Ar filesystem Ns | Ns Ar volume
3280 These permissions are granted
3282 to the creator of any newly-created descendent file system.
3286 .Fl s No @ Ns Ar setname
3287 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3288 .Ar setname Oc Ns ...
3289 .Ar filesystem Ns | Ns Ar volume
3291 Defines or adds permissions to a permission set.
3292 The set can be used by other
3294 commands for the specified file system and its descendents.
3295 Sets are evaluated dynamically, so changes to a set are immediately reflected.
3296 Permission sets follow the same naming restrictions as ZFS file systems, but the
3297 name must begin with
3299 and can be no more than 64 characters long.
3304 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3305 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3306 .Ar setname Oc Ns ... Oc
3307 .Ar filesystem Ns | Ns Ar volume
3312 .Fl e Ns | Ns Sy everyone
3313 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3314 .Ar setname Oc Ns ... Oc
3315 .Ar filesystem Ns | Ns Ar volume
3321 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3322 .Ar setname Oc Ns ... Oc
3323 .Ar filesystem Ns | Ns Ar volume
3325 Removes permissions that were granted with the
3328 No permissions are explicitly denied, so other permissions granted are still in
3330 For example, if the permission is granted by an ancestor.
3331 If no permissions are specified, then all permissions for the specified
3343 only removes the permissions that were granted to everyone, not all permissions
3344 for every user and group.
3347 command for a description of the
3350 .Bl -tag -width "-r"
3352 Recursively remove the permissions from this file system and all descendents.
3358 .Fl s No @ Ns Ar setname
3359 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3360 .Ar setname Oc Ns ... Oc
3361 .Ar filesystem Ns | Ns Ar volume
3363 Removes permissions from a permission set.
3364 If no permissions are specified, then all permissions are removed, thus removing
3370 .Ar tag Ar snapshot Ns ...
3372 Adds a single reference, named with the
3374 argument, to the specified snapshot or snapshots.
3375 Each snapshot has its own tag namespace, and tags must be unique within that
3378 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3382 .Bl -tag -width "-r"
3384 Specifies that a hold with the given tag is applied recursively to the snapshots
3385 of all descendent file systems.
3393 Lists all existing user references for the given snapshot or snapshots.
3394 .Bl -tag -width "-r"
3396 Lists the holds that are set on the named descendent snapshots, in addition to
3397 listing the holds on the named snapshot.
3403 .Ar tag Ar snapshot Ns ...
3405 Removes a single reference, named with the
3407 argument, from the specified snapshot or snapshots.
3408 The tag must already exist for each snapshot.
3409 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3413 .Bl -tag -width "-r"
3415 Recursively releases a hold with the given tag on the snapshots of all
3416 descendent file systems.
3422 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3424 Display the difference between a snapshot of a given filesystem and another
3425 snapshot of that filesystem from a later time or the current contents of the
3427 The first column is a character indicating the type of change, the other columns
3428 indicate pathname, new pathname
3429 .Pq in case of rename ,
3430 change in link count, and optionally file type and/or change time.
3431 The types of change are:
3433 - The path has been removed
3434 + The path has been created
3435 M The path has been modified
3436 R The path has been renamed
3438 .Bl -tag -width "-F"
3440 Display an indication of the type of file, in a manner similar to the
3456 Give more parsable tab-separated output, without header lines and without
3459 Display the path's inode change time as the first column of output.
3466 .Op Fl m Ar memory_limit
3472 as a ZFS channel program on
3475 program interface allows ZFS administrative operations to be run
3476 programmatically via a Lua script.
3477 The entire script is executed atomically, with no other administrative
3478 operations taking effect concurrently.
3479 A library of ZFS calls is made available to channel program scripts.
3480 Channel programs may only be run with root privileges.
3482 For full documentation of the ZFS channel program interface, see the manual
3486 Executes a read-only channel program, which runs faster.
3487 The program cannot change on-disk state by calling functions from
3488 the zfs.sync submodule.
3489 The program can be used to gather information such as properties and
3490 determining if changes would succeed (zfs.check.*).
3491 Without this flag, all pending changes must be synced to disk before
3492 a channel program can complete.
3494 Execution time limit, in milliseconds.
3495 If a channel program executes for longer than the provided timeout, it will
3496 be stopped and an error will be returned.
3497 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
3498 .It Fl m Ar memory-limit
3499 Memory limit, in bytes.
3500 If a channel program attempts to allocate more memory than the given limit,
3501 it will be stopped and an error returned.
3502 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
3504 All remaining argument strings are passed directly to the channel program as
3508 for more information.
3514 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3515 options were specified.
3518 .It Sy Example 1 No Creating a ZFS File System Hierarchy
3519 The following commands create a file system named
3521 and a file system named
3525 is set for the parent file system, and is automatically inherited by the child
3528 # zfs create pool/home
3529 # zfs set mountpoint=/export/home pool/home
3530 # zfs create pool/home/bob
3532 .It Sy Example 2 No Creating a ZFS Snapshot
3533 The following command creates a snapshot named
3535 This snapshot is mounted on demand in the
3537 directory at the root of the
3541 # zfs snapshot pool/home/bob@yesterday
3543 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3544 The following command creates snapshots named
3548 and all of its descendent file systems.
3549 Each snapshot is mounted on demand in the
3551 directory at the root of its file system.
3552 The second command destroys the newly created snapshots.
3554 # zfs snapshot -r pool/home@yesterday
3555 # zfs destroy -r pool/home@yesterday
3557 .It Sy Example 4 No Disabling and Enabling File System Compression
3558 The following command disables the
3560 property for all file systems under
3562 The next command explicitly enables
3565 .Em pool/home/anne .
3567 # zfs set compression=off pool/home
3568 # zfs set compression=on pool/home/anne
3570 .It Sy Example 5 No Listing ZFS Datasets
3571 The following command lists all active file systems and volumes in the system.
3572 Snapshots are displayed if the
3580 for more information on pool properties.
3583 NAME USED AVAIL REFER MOUNTPOINT
3584 pool 450K 457G 18K /pool
3585 pool/home 315K 457G 21K /export/home
3586 pool/home/anne 18K 457G 18K /export/home/anne
3587 pool/home/bob 276K 457G 276K /export/home/bob
3589 .It Sy Example 6 No Setting a Quota on a ZFS File System
3590 The following command sets a quota of 50 Gbytes for
3593 # zfs set quota=50G pool/home/bob
3595 .It Sy Example 7 No Listing ZFS Properties
3596 The following command lists all properties for
3599 # zfs get all pool/home/bob
3600 NAME PROPERTY VALUE SOURCE
3601 pool/home/bob type filesystem -
3602 pool/home/bob creation Tue Jul 21 15:53 2009 -
3603 pool/home/bob used 21K -
3604 pool/home/bob available 20.0G -
3605 pool/home/bob referenced 21K -
3606 pool/home/bob compressratio 1.00x -
3607 pool/home/bob mounted yes -
3608 pool/home/bob quota 20G local
3609 pool/home/bob reservation none default
3610 pool/home/bob recordsize 128K default
3611 pool/home/bob mountpoint /pool/home/bob default
3612 pool/home/bob sharenfs off default
3613 pool/home/bob checksum on default
3614 pool/home/bob compression on local
3615 pool/home/bob atime on default
3616 pool/home/bob devices on default
3617 pool/home/bob exec on default
3618 pool/home/bob setuid on default
3619 pool/home/bob readonly off default
3620 pool/home/bob zoned off default
3621 pool/home/bob snapdir hidden default
3622 pool/home/bob aclmode discard default
3623 pool/home/bob aclinherit restricted default
3624 pool/home/bob canmount on default
3625 pool/home/bob xattr on default
3626 pool/home/bob copies 1 default
3627 pool/home/bob version 4 -
3628 pool/home/bob utf8only off -
3629 pool/home/bob normalization none -
3630 pool/home/bob casesensitivity sensitive -
3631 pool/home/bob vscan off default
3632 pool/home/bob nbmand off default
3633 pool/home/bob sharesmb off default
3634 pool/home/bob refquota none default
3635 pool/home/bob refreservation none default
3636 pool/home/bob primarycache all default
3637 pool/home/bob secondarycache all default
3638 pool/home/bob usedbysnapshots 0 -
3639 pool/home/bob usedbydataset 21K -
3640 pool/home/bob usedbychildren 0 -
3641 pool/home/bob usedbyrefreservation 0 -
3644 The following command gets a single property value.
3646 # zfs get -H -o value compression pool/home/bob
3649 The following command lists all properties with local settings for
3652 # zfs get -r -s local -o name,property,value all pool/home/bob
3654 pool/home/bob quota 20G
3655 pool/home/bob compression on
3657 .It Sy Example 8 No Rolling Back a ZFS File System
3658 The following command reverts the contents of
3660 to the snapshot named
3662 deleting all intermediate snapshots.
3664 # zfs rollback -r pool/home/anne@yesterday
3666 .It Sy Example 9 No Creating a ZFS Clone
3667 The following command creates a writable file system whose initial contents are
3669 .Em pool/home/bob@yesterday .
3671 # zfs clone pool/home/bob@yesterday pool/clone
3673 .It Sy Example 10 No Promoting a ZFS Clone
3674 The following commands illustrate how to test out changes to a file system, and
3675 then replace the original file system with the changed one, using clones, clone
3676 promotion, and renaming:
3678 # zfs create pool/project/production
3679 populate /pool/project/production with data
3680 # zfs snapshot pool/project/production@today
3681 # zfs clone pool/project/production@today pool/project/beta
3682 make changes to /pool/project/beta and test them
3683 # zfs promote pool/project/beta
3684 # zfs rename pool/project/production pool/project/legacy
3685 # zfs rename pool/project/beta pool/project/production
3686 once the legacy version is no longer needed, it can be destroyed
3687 # zfs destroy pool/project/legacy
3689 .It Sy Example 11 No Inheriting ZFS Properties
3690 The following command causes
3696 property from their parent.
3698 # zfs inherit checksum pool/home/bob pool/home/anne
3700 .It Sy Example 12 No Remotely Replicating ZFS Data
3701 The following commands send a full stream and then an incremental stream to a
3702 remote machine, restoring them into
3703 .Em poolB/received/fs@a
3705 .Em poolB/received/fs@b ,
3708 must contain the file system
3709 .Em poolB/received ,
3710 and must not initially contain
3711 .Em poolB/received/fs .
3713 # zfs send pool/fs@a | \e
3714 ssh host zfs receive poolB/received/fs@a
3715 # zfs send -i a pool/fs@b | \e
3716 ssh host zfs receive poolB/received/fs
3718 .It Sy Example 13 No Using the zfs receive -d Option
3719 The following command sends a full stream of
3720 .Em poolA/fsA/fsB@snap
3721 to a remote machine, receiving it into
3722 .Em poolB/received/fsA/fsB@snap .
3725 portion of the received snapshot's name is determined from the name of the sent
3728 must contain the file system
3729 .Em poolB/received .
3731 .Em poolB/received/fsA
3732 does not exist, it is created as an empty file system.
3734 # zfs send poolA/fsA/fsB@snap | \e
3735 ssh host zfs receive -d poolB/received
3737 .It Sy Example 14 No Setting User Properties
3738 The following example sets the user-defined
3739 .Sy com.example:department
3740 property for a dataset.
3742 # zfs set com.example:department=12345 tank/accounting
3744 .It Sy Example 15 No Performing a Rolling Snapshot
3745 The following example shows how to maintain a history of snapshots with a
3746 consistent naming scheme.
3747 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
3748 renames the remaining snapshots, and then creates a new snapshot, as follows:
3750 # zfs destroy -r pool/users@7daysago
3751 # zfs rename -r pool/users@6daysago @7daysago
3752 # zfs rename -r pool/users@5daysago @6daysago
3753 # zfs rename -r pool/users@yesterday @5daysago
3754 # zfs rename -r pool/users@yesterday @4daysago
3755 # zfs rename -r pool/users@yesterday @3daysago
3756 # zfs rename -r pool/users@yesterday @2daysago
3757 # zfs rename -r pool/users@today @yesterday
3758 # zfs snapshot -r pool/users@today
3760 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3761 The following commands show how to set
3763 property options to enable
3767 addresses and to enable root access for system
3773 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
3778 for host name resolution, specify the fully qualified hostname.
3779 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
3780 The following example shows how to set permissions so that user
3782 can create, destroy, mount, and take snapshots on
3788 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
3789 # zfs allow tank/cindys
3790 ---- Permissions on tank/cindys --------------------------------------
3791 Local+Descendent permissions:
3792 user cindys create,destroy,mount,snapshot
3797 mount point permission is set to 755 by default, user
3799 will be unable to mount file systems under
3801 Add an ACE similar to the following syntax to provide mount point access:
3803 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
3805 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
3806 The following example shows how to grant anyone in the group
3808 to create file systems in
3810 This syntax also allows staff members to destroy their own file systems, but not
3811 destroy anyone else's file system.
3816 # zfs allow staff create,mount tank/users
3817 # zfs allow -c destroy tank/users
3818 # zfs allow tank/users
3819 ---- Permissions on tank/users ---------------------------------------
3822 Local+Descendent permissions:
3823 group staff create,mount
3825 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
3826 The following example shows how to define and grant a permission set on the
3833 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
3834 # zfs allow staff @pset tank/users
3835 # zfs allow tank/users
3836 ---- Permissions on tank/users ---------------------------------------
3838 @pset create,destroy,mount,snapshot
3839 Local+Descendent permissions:
3842 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
3843 The following example shows to grant the ability to set quotas and reservations
3851 # zfs allow cindys quota,reservation users/home
3852 # zfs allow users/home
3853 ---- Permissions on users/home ---------------------------------------
3854 Local+Descendent permissions:
3855 user cindys quota,reservation
3856 cindys% zfs set quota=10G users/home/marks
3857 cindys% zfs get quota users/home/marks
3858 NAME PROPERTY VALUE SOURCE
3859 users/home/marks quota 10G local
3861 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
3862 The following example shows how to remove the snapshot permission from the
3871 # zfs unallow staff snapshot tank/users
3872 # zfs allow tank/users
3873 ---- Permissions on tank/users ---------------------------------------
3875 @pset create,destroy,mount,snapshot
3876 Local+Descendent permissions:
3879 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
3880 The following example shows how to see what has changed between a prior
3881 snapshot of a ZFS dataset and its current state.
3884 option is used to indicate type information for the files affected.
3886 # zfs diff -F tank/test@before tank/test
3888 M F /tank/test/linked (+1)
3889 R F /tank/test/oldname -> /tank/test/newname
3890 - F /tank/test/deleted
3891 + F /tank/test/created
3892 M F /tank/test/modified
3895 .Sh INTERFACE STABILITY