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 2016 Richard Laager. All rights reserved.
30 .\" Copyright 2017 Nexenta Systems, 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 Ar 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 property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
107 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
110 .Op Fl r Ns | Ns Fl d Ar depth
112 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
113 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
114 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
115 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
116 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
120 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
130 .Fl a | Ar filesystem
134 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
135 .Oo Fl s Ar field Oc Ns ...
136 .Oo Fl S Ar field Oc Ns ...
137 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
138 .Ar filesystem Ns | Ns Ar snapshot
142 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
143 .Oo Fl s Ar field Oc Ns ...
144 .Oo Fl S Ar field Oc Ns ...
145 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
146 .Ar filesystem Ns | Ns Ar snapshot
153 .Fl a | Ar filesystem
157 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
160 .Fl a | Ar filesystem
163 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
166 .Ar snapshot bookmark
170 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
175 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
176 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
180 .Fl t Ar receive_resume_token
184 .Op Fl o Sy origin Ns = Ns Ar snapshot
185 .Op Fl o Ar property Ns = Ns Ar value
187 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
191 .Op Fl d Ns | Ns Fl e
192 .Op Fl o Sy origin Ns = Ns Ar snapshot
193 .Op Fl o Ar property Ns = Ns Ar value
199 .Ar filesystem Ns | Ns Ar volume
202 .Ar filesystem Ns | Ns Ar volume
206 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
207 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
208 .Ar setname Oc Ns ...
209 .Ar filesystem Ns | Ns Ar volume
213 .Fl e Ns | Ns Sy everyone
214 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
215 .Ar setname Oc Ns ...
216 .Ar filesystem Ns | Ns Ar volume
220 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
221 .Ar setname Oc Ns ...
222 .Ar filesystem Ns | Ns Ar volume
225 .Fl s No @ Ns Ar setname
226 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
227 .Ar setname Oc Ns ...
228 .Ar filesystem Ns | Ns Ar volume
232 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
233 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
234 .Ar setname Oc Ns ... Oc
235 .Ar filesystem Ns | Ns Ar volume
239 .Fl e Ns | Ns Sy everyone
240 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
241 .Ar setname Oc Ns ... Oc
242 .Ar filesystem Ns | Ns Ar volume
247 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
248 .Ar setname Oc Ns ... Oc
249 .Ar filesystem Ns | Ns Ar volume
253 .Fl s @ Ns Ar setname
254 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
255 .Ar setname Oc Ns ... Oc
256 .Ar filesystem Ns | Ns Ar volume
260 .Ar tag Ar snapshot Ns ...
268 .Ar tag Ar snapshot Ns ...
272 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
276 .Op Fl L Ar keylocation
277 .Fl a | Ar filesystem
281 .Fl a | Ar filesystem
285 .Op Fl o Ar keylocation Ns = Ns Ar value
286 .Op Fl o Ar keyformat Ns = Ns Ar value
287 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
297 command configures ZFS datasets within a ZFS storage pool, as described in
299 A dataset is identified by a unique path within the ZFS namespace.
302 pool/{filesystem,volume,snapshot}
305 where the maximum length of a dataset name is
309 A dataset can be one of the following:
310 .Bl -tag -width "file system"
312 A ZFS dataset of type
314 can be mounted within the standard system namespace and behaves like other file
316 While ZFS file systems are designed to be POSIX compliant, known issues exist
317 that prevent compliance in some cases.
318 Applications that depend on standards conformance might fail due to non-standard
319 behavior when checking file system free space.
321 A logical volume exported as a raw or block device.
322 This type of dataset should only be used under special circumstances.
323 File systems are typically used in most environments.
325 A read-only version of a file system or volume at a given point in time.
327 .Ar filesystem Ns @ Ns Ar name
329 .Ar volume Ns @ Ns Ar name .
333 but without the hold on on-disk data. It can be used as the source of a send
334 (but not for a receive). It is specified as
335 .Ar filesystem Ns # Ns Ar name
337 .Ar volume Ns # Ns Ar name .
339 .Ss ZFS File System Hierarchy
340 A ZFS storage pool is a logical collection of devices that provide space for
342 A storage pool is also the root of the ZFS file system hierarchy.
344 The root of the pool can be accessed as a file system, such as mounting and
345 unmounting, taking snapshots, and setting properties.
346 The physical storage characteristics, however, are managed by the
352 for more information on creating and administering pools.
354 A snapshot is a read-only copy of a file system or volume.
355 Snapshots can be created extremely quickly, and initially consume no additional
356 space within the pool.
357 As data within the active dataset changes, the snapshot consumes more data than
358 would otherwise be shared with the active dataset.
360 Snapshots can have arbitrary names.
361 Snapshots of volumes can be cloned or rolled back, visibility is determined
364 property of the parent volume.
366 File system snapshots can be accessed under the
368 directory in the root of the file system.
369 Snapshots are automatically mounted on demand and may be unmounted at regular
371 The visibility of the
373 directory can be controlled by the
377 A bookmark is like a snapshot, a read-only copy of a file system or volume.
378 Bookmarks can be created extremely quickly, compared to snapshots, and they
379 consume no additional space within the pool. Bookmarks can also have arbitrary
380 names, much like snapshots.
382 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
383 way. From a storage standpoint a bookmark just provides a way to reference
384 when a snapshot was created as a distinct object. Bookmarks are initially
385 tied to a snapshot, not the filesystem or volume, and they will survive if the
386 snapshot itself is destroyed. Since they are very light weight there's little
387 incentive to destroy them.
389 A clone is a writable volume or file system whose initial contents are the same
391 As with snapshots, creating a clone is nearly instantaneous, and initially
392 consumes no additional space.
394 Clones can only be created from a snapshot.
395 When a snapshot is cloned, it creates an implicit dependency between the parent
397 Even though the clone is created somewhere else in the dataset hierarchy, the
398 original snapshot cannot be destroyed as long as a clone exists.
401 property exposes this dependency, and the
403 command lists any such dependencies, if they exist.
405 The clone parent-child dependency relationship can be reversed by using the
410 file system to become a clone of the specified file system, which makes it
411 possible to destroy the file system that the clone was created from.
413 Creating a ZFS file system is a simple operation, so the number of file systems
414 per system is likely to be numerous.
415 To cope with this, ZFS automatically manages mounting and unmounting file
416 systems without the need to edit the
419 All automatically managed file systems are mounted by ZFS at boot time.
421 By default, file systems are mounted under
425 is the name of the file system in the ZFS namespace.
426 Directories are created and destroyed as needed.
428 A file system can also have a mount point set in the
431 This directory is created as needed, and ZFS automatically mounts the file
433 .Nm zfs Cm mount Fl a
440 property can be inherited, so if
446 automatically inherits a mount point of
447 .Pa /export/stuff/user .
453 prevents the file system from being mounted.
455 If needed, ZFS file systems can also be managed with traditional tools
461 If a file system's mount point is set to
463 ZFS makes no attempt to manage the file system, and the administrator is
464 responsible for mounting and unmounting the file system. Because pools must
465 be imported before a legacy mount can succeed, administrators should ensure
466 that legacy mounts are only attempted after the zpool import process
467 finishes at boot time. For example, on machines using systemd, the mount
470 .Nm x-systemd.requires=zfs-import.target
472 will ensure that the zfs-import completes before systemd attempts mounting
473 the filesystem. See systemd.mount(5) for details.
475 Deduplication is the process for removing redundant data at the block level,
476 reducing the total amount of data stored. If a file system has the
478 property enabled, duplicate data blocks are removed synchronously. The result
479 is that only unique data is stored and common components are shared among files.
481 Deduplicating data is a very resource-intensive operation. It is generally
482 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
483 you enable deduplication. Calculating the exact requirement depends heavily
484 on the type of data stored in the pool.
486 Enabling deduplication on an improperly-designed system can result in
487 performance issues (slow IO and administrative operations). It can potentially
488 lead to problems importing a pool due to memory exhaustion. Deduplication
489 can consume significant processing power (CPU) and memory as well as generate
492 Before creating a pool with deduplication enabled, ensure that you have planned
493 your hardware requirements appropriately and implemented appropriate recovery
494 practices, such as regular backups. As an alternative to deduplication
497 as a less resource-intensive alternative.
498 .Ss Native Properties
499 Properties are divided into two types, native properties and user-defined
504 Native properties either export internal statistics or control ZFS behavior.
505 In addition, native properties are either editable or read-only.
506 User properties have no effect on ZFS behavior, but you can use them to annotate
507 datasets in a way that is meaningful in your environment.
508 For more information about user properties, see the
512 Every dataset has a set of properties that export statistics about the dataset
513 as well as control various behaviors.
514 Properties are inherited from the parent unless overridden by the child.
515 Some properties apply only to certain types of datasets
516 .Pq file systems, volumes, or snapshots .
518 The values of numeric properties can be specified using human-readable suffixes
528 The following are all valid
531 .Li 1536M, 1.5g, 1.50GB .
533 The values of non-numeric properties are case sensitive and must be lowercase,
540 The following native properties consist of read-only statistics about the
542 These properties can be neither set, nor inherited.
543 Native properties apply to all dataset types unless otherwise noted.
544 .Bl -tag -width "usedbyrefreservation"
546 The amount of space available to the dataset and all its children, assuming that
547 there is no other activity in the pool.
548 Because space is shared within a pool, availability can be limited by any number
549 of factors, including physical pool size, quotas, reservations, or other
550 datasets within the pool.
552 This property can also be referred to by its shortened column name,
555 For non-snapshots, the compression ratio achieved for the
557 space of this dataset, expressed as a multiplier.
560 property includes descendant datasets, and, for clones, does not include the
561 space shared with the origin snapshot.
567 Compression can be turned on by running:
568 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
572 The transaction group (txg) in which the dataset was created. Bookmarks have
575 as the snapshot they are initially tied to. This property is suitable for
576 ordering a list of snapshots, e.g. for incremental send and receive.
578 The time this dataset was created.
580 For snapshots, this property is a comma-separated list of filesystems or volumes
581 which are clones of this snapshot.
584 property is this snapshot.
587 property is not empty, then this snapshot can not be destroyed
594 The roles of origin and clone can be swapped by promoting the clone with the
600 if the snapshot has been marked for deferred destroy by using the
601 .Nm zfs Cm destroy Fl d
603 Otherwise, the property is
605 .It Sy encryptionroot
606 For encrypted datasets, indicates where the dataset is currently inheriting its
607 encryption key from. Loading or unloading a key for the
609 will implicitly load / unload the key for any inheriting datasets (see
612 .Nm zfs Cm unload-key
614 Clones will always share an
615 encryption key with their origin. See the
618 .It Sy filesystem_count
619 The total number of filesystems and volumes that exist under this location in
621 This value is only available when a
623 has been set somewhere in the tree under which the dataset resides.
625 Indicates if an encryption key is currently loaded into ZFS. The possible
634 .Nm zfs Cm unload-key .
636 The 64 bit GUID of this dataset or bookmark which does not change over its
637 entire lifetime. When a snapshot is sent to another pool, the received
638 snapshot has the same GUID. Thus, the
640 is suitable to identify a snapshot across pools.
641 .It Sy logicalreferenced
642 The amount of space that is
644 accessible by this dataset.
648 The logical space ignores the effect of the
652 properties, giving a quantity closer to the amount of data that applications
654 However, it does include space consumed by metadata.
656 This property can also be referred to by its shortened column name,
659 The amount of space that is
661 consumed by this dataset and all its descendents.
665 The logical space ignores the effect of the
669 properties, giving a quantity closer to the amount of data that applications
671 However, it does include space consumed by metadata.
673 This property can also be referred to by its shortened column name,
676 For file systems, indicates whether the file system is currently mounted.
677 This property can be either
682 For cloned file systems or volumes, the snapshot from which the clone was
687 .It Sy receive_resume_token
688 For filesystems or volumes which have saved partially-completed state from
690 this opaque token can be provided to
692 to resume and complete the
695 The amount of data that is accessible by this dataset, which may or may not be
696 shared with other datasets in the pool.
697 When a snapshot or clone is created, it initially references the same amount of
698 space as the file system or snapshot it was created from, since its contents are
701 This property can also be referred to by its shortened column name,
703 .It Sy refcompressratio
704 The compression ratio achieved for the
706 space of this dataset, expressed as a multiplier.
710 .It Sy snapshot_count
711 The total number of snapshots that exist under this location in the dataset
713 This value is only available when a
715 has been set somewhere in the tree under which the dataset resides.
723 The amount of space consumed by this dataset and all its descendents.
724 This is the value that is checked against this dataset's quota and reservation.
725 The space used does not include this dataset's reservation, but does take into
726 account the reservations of any descendent datasets.
727 The amount of space that a dataset consumes from its parent, as well as the
728 amount of space that is freed if this dataset is recursively destroyed, is the
729 greater of its space used and its reservation.
731 The used space of a snapshot
736 is space that is referenced exclusively by this snapshot.
737 If this snapshot is destroyed, the amount of
740 Space that is shared by multiple snapshots isn't accounted for in this metric.
741 When a snapshot is destroyed, space that was previously shared with this
742 snapshot can become unique to snapshots adjacent to it, thus changing the used
743 space of those snapshots.
744 The used space of the latest snapshot can also be affected by changes in the
748 space of a snapshot is a subset of the
750 space of the snapshot.
752 The amount of space used, available, or referenced does not take into account
754 Pending changes are generally accounted for within a few seconds.
755 Committing a change to a disk using
759 does not necessarily guarantee that the space usage information is updated
764 properties decompose the
766 properties into the various reasons that space is used.
769 .Sy usedbychildren No +
770 .Sy usedbydataset No +
771 .Sy usedbyrefreservation No +
772 .Sy usedbysnapshots .
773 These properties are only available for datasets created on
777 .It Sy usedbychildren
778 The amount of space used by children of this dataset, which would be freed if
779 all the dataset's children were destroyed.
781 The amount of space used by this dataset itself, which would be freed if the
782 dataset were destroyed
783 .Po after first removing any
785 and destroying any necessary snapshots or descendents
787 .It Sy usedbyrefreservation
788 The amount of space used by a
790 set on this dataset, which would be freed if the
793 .It Sy usedbysnapshots
794 The amount of space consumed by snapshots of this dataset.
795 In particular, it is the amount of space that would be freed if all of this
796 dataset's snapshots were destroyed.
797 Note that this is not simply the sum of the snapshots'
799 properties because space can be shared by multiple snapshots.
800 .It Sy userused Ns @ Ns Em user
801 The amount of space consumed by the specified user in this dataset.
802 Space is charged to the owner of each file, as displayed by
804 The amount of space charged is displayed by
810 subcommand for more information.
812 Unprivileged users can access only their own space usage.
813 The root user, or a user who has been granted the
817 can access everyone's usage.
820 .Sy userused Ns @ Ns Em ...
821 properties are not displayed by
822 .Nm zfs Cm get Sy all .
823 The user's name must be appended after the @ symbol, using one of the following
825 .Bl -bullet -width ""
839 .Sy joe.smith@mydomain
848 Files created on Linux always have POSIX owners.
849 .It Sy userobjused Ns @ Ns Em user
852 property is similar to
854 but instead it counts the number of objects consumed by a user. This property
855 counts all objects allocated on behalf of the user, it may differ from the
856 results of system tools such as
861 is set on a file system additional objects will be created per-file to store
862 extended attributes. These additional objects are reflected in the
864 value and are counted against the user's
866 When a file system is configured to use
868 no additional internal objects are normally required.
870 This property is set to the number of user holds on this snapshot.
871 User holds are set by using the
874 .It Sy groupused Ns @ Ns Em group
875 The amount of space consumed by the specified group in this dataset.
876 Space is charged to the group of each file, as displayed by
879 .Sy userused Ns @ Ns Em user
880 property for more information.
882 Unprivileged users can only access their own groups' space usage.
883 The root user, or a user who has been granted the
887 can access all groups' usage.
888 .It Sy groupobjused Ns @ Ns Em group
889 The number of objects consumed by the specified group in this dataset.
890 Multiple objects may be charged to the group for each file when extended
891 attributes are in use. See the
892 .Sy userobjused Ns @ Ns Em user
893 property for more information.
895 Unprivileged users can only access their own groups' space usage.
896 The root user, or a user who has been granted the
900 can access all groups' usage.
902 For volumes, specifies the block size of the volume.
905 cannot be changed once the volume has been written, so it should be set at
906 volume creation time.
909 for volumes is 8 Kbytes.
910 Any power of 2 from 512 bytes to 128 Kbytes is valid.
912 This property can also be referred to by its shortened column name,
917 by this dataset, that was written since the previous snapshot
918 .Pq i.e. that is not referenced by the previous snapshot .
919 .It Sy written Ns @ Ns Em snapshot
922 space written to this dataset since the specified snapshot.
923 This is the space that is referenced by this dataset but was not referenced by
924 the specified snapshot.
928 may be specified as a short snapshot name
929 .Po just the part after the
932 in which case it will be interpreted as a snapshot in the same filesystem as
936 may be a full snapshot name
937 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
938 which for clones may be a snapshot in the origin's filesystem
939 .Pq or the origin of the origin's filesystem, etc.
942 The following native properties can be used to change the behavior of a ZFS
946 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
947 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
949 Controls how ACEs are inherited when files and directories are created.
950 .Bl -tag -width "passthrough-x"
952 does not inherit any ACEs.
954 only inherits inheritable ACEs that specify
962 permissions when the ACE is inherited.
964 inherits all inheritable ACEs without any modifications.
973 ACEs inherit the execute permission only if the file creation mode also requests
977 When the property value is set to
979 files are created with a mode determined by the inheritable ACEs.
980 If no inheritable ACEs exist that affect the mode, then the mode is set in
981 accordance to the requested mode from the application.
985 property does not apply to posix ACLs.
986 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
987 Controls whether ACLs are enabled and if so what type of ACL to use.
988 .Bl -tag -width "posixacl"
990 default, when a file system has the
992 property set to off then ACLs are disabled.
997 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
998 not functional on other platforms. Posix ACLs are stored as an extended
999 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1003 To obtain the best performance when setting
1005 users are strongly encouraged to set the
1007 property. This will result in the posix ACL being stored more efficiently on
1008 disk. But as a consequence of this all new extended attributes will only be
1009 accessible from OpenZFS implementations which support the
1013 property for more details.
1014 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1015 Controls whether the access time for files is updated when they are read.
1016 Turning this property off avoids producing write traffic when reading files and
1017 can result in significant performance gains, though it might confuse mailers
1018 and other similar utilities. The values
1022 are equivalent to the
1026 mount options. The default value is
1031 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1032 If this property is set to
1034 the file system cannot be mounted, and is ignored by
1035 .Nm zfs Cm mount Fl a .
1036 Setting this property to
1038 is similar to setting the
1042 except that the dataset still has a normal
1044 property, which can be inherited.
1045 Setting this property to
1047 allows datasets to be used solely as a mechanism to inherit properties.
1048 One example of setting
1049 .Sy canmount Ns = Ns Sy off
1050 is to have two datasets with the same
1052 so that the children of both datasets appear in the same directory, but might
1053 have different inherited characteristics.
1057 a dataset can only be mounted and unmounted explicitly.
1058 The dataset is not mounted automatically when the dataset is created or
1059 imported, nor is it mounted by the
1060 .Nm zfs Cm mount Fl a
1061 command or unmounted by the
1062 .Nm zfs Cm unmount Fl a
1065 This property is not inherited.
1067 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1068 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1069 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1071 Controls the checksum used to verify data integrity.
1072 The default value is
1074 which automatically selects an appropriate algorithm
1077 but this may change in future releases
1081 disables integrity checking on user data.
1084 not only disables integrity but also disables maintaining parity for user data.
1085 This setting is used internally by a dump device residing on a RAID-Z pool and
1086 should not be used by any other dataset.
1087 Disabling checksums is
1089 a recommended practice.
1096 checksum algorithms require enabling the appropriate features on the pool.
1098 .Xr zpool-features 5
1099 for more information on these algorithms.
1101 Changing this property affects only newly-written data.
1103 Salted checksum algorithms
1104 .Pq Cm edonr , skein
1105 are currently not supported for any filesystem on the boot pools.
1107 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1108 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1110 Controls the compression algorithm used for this dataset.
1112 Setting compression to
1114 indicates that the current default compression algorithm should be used.
1115 The default balances compression and decompression speed, with compression ratio
1116 and is expected to work well on a wide variety of workloads.
1117 Unlike all other settings for this property,
1119 does not select a fixed compression type.
1120 As new compression algorithms are added to ZFS and enabled on a pool, the
1121 default compression algorithm may change.
1122 The current default compression algorithm is either
1131 compression algorithm is a high-performance replacement for the
1134 It features significantly faster compression and decompression, as well as a
1135 moderately higher compression ratio than
1137 but can only be used on pools with the
1142 .Xr zpool-features 5
1143 for details on ZFS feature flags and the
1149 compression algorithm is optimized for performance while providing decent data
1154 compression algorithm uses the same compression as the
1159 level by using the value
1163 is an integer from 1
1166 .Pq best compression ratio .
1171 .Po which is also the default for
1177 compression algorithm compresses runs of zeros.
1179 This property can also be referred to by its shortened column name
1181 Changing this property affects only newly-written data.
1183 .Sy context Ns = Ns Sy none Ns | Ns
1184 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1186 This flag sets the SELinux context for all files in the file system under
1187 a mount point for that file system. See
1189 for more information.
1191 .Sy fscontext Ns = Ns Sy none Ns | Ns
1192 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1194 This flag sets the SELinux context for the file system file system being
1197 for more information.
1199 .Sy defcontext Ns = Ns Sy none Ns | Ns
1200 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1202 This flag sets the SELinux default context for unlabeled files. See
1204 for more information.
1206 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1207 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1209 This flag sets the SELinux context for the root inode of the file system. See
1211 for more information.
1212 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1213 Controls the number of copies of data stored for this dataset.
1214 These copies are in addition to any redundancy provided by the pool, for
1215 example, mirroring or RAID-Z.
1216 The copies are stored on different disks, if possible.
1217 The space used by multiple copies is charged to the associated file and dataset,
1220 property and counting against quotas and reservations.
1222 Changing this property only affects newly-written data.
1223 Therefore, set this property at file system creation time by using the
1224 .Fl o Sy copies Ns = Ns Ar N
1227 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1229 create, for example a two-disk striped pool and set
1231 on some datasets thinking you have setup redundancy for them. When a disk
1232 fails you will not be able to import the pool and will have lost all of your
1234 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1235 Controls whether device nodes can be opened on this file system.
1236 The default value is
1242 are equivalent to the
1248 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1249 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1251 Specifies a compatibility mode or literal value for the size of dnodes in the
1252 file system. The default value is
1254 Setting this property to a value other than
1256 requires the large_dnode pool feature to be enabled.
1262 if the dataset uses the
1264 property setting and the workload makes heavy use of extended attributes. This
1265 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1266 servers, for example. Literal values are supported for cases where the optimal
1267 size is known in advance and for performance testing.
1273 if you need to receive a send stream of this dataset on a pool that doesn't
1274 enable the large_dnode feature, or if you need to import this pool on a system
1275 that doesn't support the large_dnode feature.
1277 This property can also be referred to by its shortened column name,
1280 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1281 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1282 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1284 Controls the encryption cipher suite (block cipher, key length, and mode) used
1285 for this dataset. Requires the
1287 feature to be enabled on the pool.
1290 to be set at dataset creation time.
1293 .Sy encryption Ns = Ns Sy on
1294 when creating a dataset indicates that the default encryption suite will be
1295 selected, which is currently
1297 In order to provide consistent data protection, encryption must be specified at
1298 dataset creation time and it cannot be changed afterwards.
1300 For more details and caveats about encryption see the
1303 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1304 Controls what format the user's encryption key will be provided as. This
1305 property is only set when the dataset is encrypted.
1307 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1308 encryption suite) and must be randomly generated. A raw key can be generated
1309 with the following command:
1311 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1314 Passphrases must be between 8 and 512 bytes long and will be processed through
1315 PBKDF2 before being used (see the
1317 property). Even though the
1318 encryption suite cannot be changed after dataset creation, the keyformat can be
1320 .Nm zfs Cm change-key .
1322 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1324 Controls where the user's encryption key will be loaded from by default for
1328 .Nm zfs Cm mount Cm -l . This property is
1329 only set for encrypted datasets which are encryption roots. If unspecified, the
1333 Even though the encryption suite cannot be changed after dataset creation, the
1334 keylocation can be with either
1337 .Nm zfs Cm change-key .
1340 is selected ZFS will ask for the key at the command prompt when it is required
1341 to access the encrypted data (see
1343 for details). This setting will also allow the key to be passed in via STDIN,
1344 but users should be careful not to place keys which should be kept secret on
1345 the command line. If a file URI is selected, the key will be loaded from the
1346 specified absolute file path.
1347 .It Sy pbkdf2iters Ns = Ns Ar iterations
1348 Controls the number of PBKDF2 iterations that a
1350 encryption key should be run through when processing it into an encryption key.
1351 This property is only defined when encryption is enabled and a keyformat of
1353 is selected. The goal of PBKDF2 is to significantly increase the
1354 computational difficulty needed to brute force a user's passphrase. This is
1355 accomplished by forcing the attacker to run each passphrase through a
1356 computationally expensive hashing function many times before they arrive at the
1357 resulting key. A user who actually knows the passphrase will only have to pay
1358 this cost once. As CPUs become better at processing, this number should be
1359 raised to ensure that a brute force attack is still not possible. The current
1364 This property may be changed with
1365 .Nm zfs Cm change-key .
1366 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1367 Controls whether processes can be executed from within this file system.
1368 The default value is
1374 are equivalent to the
1379 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1380 Limits the number of filesystems and volumes that can exist under this point in
1382 The limit is not enforced if the user is allowed to change the limit.
1384 .Sy filesystem_limit
1387 a descendent of a filesystem that already has a
1388 .Sy filesystem_limit
1389 does not override the ancestor's
1390 .Sy filesystem_limit ,
1391 but rather imposes an additional limit.
1392 This feature must be enabled to be used
1394 .Xr zpool-features 5
1396 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1397 Controls the mount point used for this file system.
1400 section for more information on how this property is used.
1404 property is changed for a file system, the file system and any children that
1405 inherit the mount point are unmounted.
1408 then they remain unmounted.
1409 Otherwise, they are automatically remounted in the new location if the property
1414 or if they were mounted before the property was changed.
1415 In addition, any shared file systems are unshared and shared in the new
1417 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1418 Controls whether the file system should be mounted with
1420 .Pq Non Blocking mandatory locks .
1421 This is used for SMB clients.
1422 Changes to this property only take effect when the file system is umounted and
1426 for more information on
1428 mounts. This property is not used on Linux.
1429 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1430 Allow mounting on a busy directory or a directory which already contains
1431 files or directories. This is the default mount behavior for Linux file systems.
1432 For consistency with OpenZFS on other platforms overlay mounts are
1436 to enable overlay mounts.
1437 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1438 Controls what is cached in the primary cache
1440 If this property is set to
1442 then both user data and metadata is cached.
1443 If this property is set to
1445 then neither user data nor metadata is cached.
1446 If this property is set to
1448 then only metadata is cached.
1449 The default value is
1451 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1452 Limits the amount of space a dataset and its descendents can consume.
1453 This property enforces a hard limit on the amount of space used.
1454 This includes all space consumed by descendents, including file systems and
1456 Setting a quota on a descendent of a dataset that already has a quota does not
1457 override the ancestor's quota, but rather imposes an additional limit.
1459 Quotas cannot be set on volumes, as the
1461 property acts as an implicit quota.
1462 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1463 Limits the number of snapshots that can be created on a dataset and its
1467 on a descendent of a dataset that already has a
1469 does not override the ancestor's
1470 .Sy snapshot_limit ,
1471 but rather imposes an additional limit.
1472 The limit is not enforced if the user is allowed to change the limit.
1473 For example, this means that recursive snapshots taken from the global zone are
1474 counted against each delegated dataset within a zone.
1475 This feature must be enabled to be used
1477 .Xr zpool-features 5
1479 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1480 Limits the amount of space consumed by the specified user.
1481 User space consumption is identified by the
1482 .Sy userspace@ Ns Em user
1485 Enforcement of user quotas may be delayed by several seconds.
1486 This delay means that a user might exceed their quota before the system notices
1487 that they are over quota and begins to refuse additional writes with the
1491 .Nm zfs Cm userspace
1492 subcommand for more information.
1494 Unprivileged users can only access their own groups' space usage.
1495 The root user, or a user who has been granted the
1499 can get and set everyone's quota.
1501 This property is not available on volumes, on file systems before version 4, or
1502 on pools before version 15.
1504 .Sy userquota@ Ns Em ...
1505 properties are not displayed by
1506 .Nm zfs Cm get Sy all .
1507 The user's name must be appended after the
1509 symbol, using one of the following forms:
1517 .Em POSIX numeric ID
1524 .Sy joe.smith@mydomain
1533 Files created on Linux always have POSIX owners.
1534 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1539 but it limits the number of objects a user can create. Please refer to
1541 for more information about how objects are counted.
1542 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1543 Limits the amount of space consumed by the specified group.
1544 Group space consumption is identified by the
1545 .Sy groupused@ Ns Em group
1548 Unprivileged users can access only their own groups' space usage.
1549 The root user, or a user who has been granted the
1553 can get and set all groups' quotas.
1554 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1559 but it limits number of objects a group can consume. Please refer to
1561 for more information about how objects are counted.
1562 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1563 Controls whether this dataset can be modified.
1564 The default value is
1570 are equivalent to the
1576 This property can also be referred to by its shortened column name,
1578 .It Sy recordsize Ns = Ns Em size
1579 Specifies a suggested block size for files in the file system.
1580 This property is designed solely for use with database workloads that access
1581 files in fixed-size records.
1582 ZFS automatically tunes block sizes according to internal algorithms optimized
1583 for typical access patterns.
1585 For databases that create very large files but access them in small random
1586 chunks, these algorithms may be suboptimal.
1589 greater than or equal to the record size of the database can result in
1590 significant performance gains.
1591 Use of this property for general purpose file systems is strongly discouraged,
1592 and may adversely affect performance.
1594 The size specified must be a power of two greater than or equal to 512 and less
1595 than or equal to 128 Kbytes.
1598 feature is enabled on the pool, the size may be up to 1 Mbyte.
1600 .Xr zpool-features 5
1601 for details on ZFS feature flags.
1603 Changing the file system's
1605 affects only files created afterward; existing files are unaffected.
1607 This property can also be referred to by its shortened column name,
1609 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1610 Controls what types of metadata are stored redundantly.
1611 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1612 the amount of user data lost is limited.
1613 This extra copy is in addition to any redundancy provided at the pool level
1614 .Pq e.g. by mirroring or RAID-Z ,
1615 and is in addition to an extra copy specified by the
1618 .Pq up to a total of 3 copies .
1619 For example if the pool is mirrored,
1620 .Sy copies Ns = Ns 2 ,
1622 .Sy redundant_metadata Ns = Ns Sy most ,
1623 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1628 ZFS stores an extra copy of all metadata.
1629 If a single on-disk block is corrupt, at worst a single block of user data
1638 ZFS stores an extra copy of most types of metadata.
1639 This can improve performance of random writes, because less metadata must be
1641 In practice, at worst about 100 blocks
1646 of user data can be lost if a single on-disk block is corrupt.
1647 The exact behavior of which metadata blocks are stored redundantly may change in
1650 The default value is
1652 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1653 Limits the amount of space a dataset can consume.
1654 This property enforces a hard limit on the amount of space used.
1655 This hard limit does not include space used by descendents, including file
1656 systems and snapshots.
1657 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1658 The minimum amount of space guaranteed to a dataset, not including its
1660 When the amount of space used is below this value, the dataset is treated as if
1661 it were taking up the amount of space specified by
1662 .Sy refreservation .
1665 reservation is accounted for in the parent datasets' space used, and counts
1666 against the parent datasets' quotas and reservations.
1670 is set, a snapshot is only allowed if there is enough free pool space outside of
1671 this reservation to accommodate the current number of
1673 bytes in the dataset.
1675 This property can also be referred to by its shortened column name,
1677 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1678 Controls the manner in which the access time is updated when
1680 is set. Turning this property on causes the access time to be updated relative
1681 to the modify or change time. Access time is only updated if the previous
1682 access time was earlier than the current modify or change time or if the
1683 existing access time hasn't been updated within the past 24 hours. The default
1690 are equivalent to the
1695 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1696 The minimum amount of space guaranteed to a dataset and its descendants.
1697 When the amount of space used is below this value, the dataset is treated as if
1698 it were taking up the amount of space specified by its reservation.
1699 Reservations are accounted for in the parent datasets' space used, and count
1700 against the parent datasets' quotas and reservations.
1702 This property can also be referred to by its shortened column name,
1704 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1705 Controls what is cached in the secondary cache
1707 If this property is set to
1709 then both user data and metadata is cached.
1710 If this property is set to
1712 then neither user data nor metadata is cached.
1713 If this property is set to
1715 then only metadata is cached.
1716 The default value is
1718 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1719 Controls whether the setuid bit is respected for the file system.
1720 The default value is
1726 are equivalent to the
1731 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1732 Controls whether the file system is shared by using
1733 .Sy Samba USERSHARES
1734 and what options are to be used. Otherwise, the file system is automatically
1735 shared and unshared with the
1739 commands. If the property is set to on, the
1741 command is invoked to create a
1744 Because SMB shares requires a resource name, a unique resource name is
1745 constructed from the dataset name. The constructed name is a copy of the
1746 dataset name except that the characters in the dataset name, which would be
1747 invalid in the resource name, are replaced with underscore (_) characters.
1748 Linux does not currently support additional options which might be available
1755 the file systems are unshared.
1757 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1758 stands for "full permissions", ie. read and write permissions) and no guest
1759 access (which means Samba must be able to authenticate a real user, system
1760 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1761 additional access control (disallow specific user specific access etc) must
1762 be done on the underlying file system.
1763 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1764 Controls whether the file system is shared via NFS, and what options are to be
1766 A file system with a
1772 command and entries in the
1775 Otherwise, the file system is automatically shared and unshared with the
1780 If the property is set to
1782 the dataset is shared using the default options:
1784 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1788 for the meaning of the default options. Otherwise, the
1790 command is invoked with options equivalent to the contents of this property.
1794 property is changed for a dataset, the dataset and any children inheriting the
1795 property are re-shared with the new options, only if the property was previously
1797 or if they were shared before the property was changed.
1798 If the new property is
1800 the file systems are unshared.
1801 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1802 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1808 ZFS will use pool log devices
1810 to handle the requests at low latency.
1815 ZFS will not use configured pool log devices.
1816 ZFS will instead optimize synchronous operations for global pool throughput and
1817 efficient use of resources.
1818 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1819 Controls whether the volume snapshot devices under
1820 .Em /dev/zvol/<pool>
1821 are hidden or visible. The default value is
1823 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1824 Controls whether the
1826 directory is hidden or visible in the root of the file system as discussed in
1830 The default value is
1832 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1833 Controls the behavior of synchronous requests
1834 .Pq e.g. fsync, O_DSYNC .
1838 specified behavior of ensuring all synchronous requests are written to stable
1839 storage and all devices are flushed to ensure data is not cached by device
1841 .Pq this is the default .
1843 causes every file system transaction to be written and flushed before its
1844 system call returns.
1845 This has a large performance penalty.
1847 disables synchronous requests.
1848 File system transactions are only committed to stable storage periodically.
1849 This option will give the highest performance.
1850 However, it is very dangerous as ZFS would be ignoring the synchronous
1851 transaction demands of applications such as databases or NFS.
1852 Administrators should only use this option when the risks are understood.
1853 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1854 The on-disk version of this file system, which is independent of the pool
1856 This property can only be set to later supported versions.
1860 .It Sy volsize Ns = Ns Em size
1861 For volumes, specifies the logical size of the volume.
1862 By default, creating a volume establishes a reservation of equal size.
1863 For storage pools with a version number of 9 or higher, a
1868 are reflected in an equivalent change to the reservation
1874 can only be set to a multiple of
1878 The reservation is kept equal to the volume's logical size to prevent unexpected
1879 behavior for consumers.
1880 Without the reservation, the volume could run out of space, resulting in
1881 undefined behavior or data corruption, depending on how the volume is used.
1882 These effects can also occur when the volume size is changed while it is in use
1883 .Pq particularly when shrinking the size .
1884 Extreme care should be used when adjusting the volume size.
1886 Though not recommended, a
1889 .Qq thin provisioning
1891 can be created by specifying the
1894 .Nm zfs Cm create Fl V
1895 command, or by changing the reservation after the volume has been created.
1898 is a volume where the reservation is less then the volume size.
1899 Consequently, writes to a sparse volume can fail with
1901 when the pool is low on space.
1902 For a sparse volume, changes to
1904 are not reflected in the reservation.
1905 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1906 This property specifies how volumes should be exposed to the OS.
1909 exposes volumes as fully fledged block devices, providing maximal
1910 functionality. The value
1912 is just an alias for
1914 and is kept for compatibility.
1917 hides its partitions.
1918 Volumes with property set to
1920 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
1921 that can be suitable for backup purposes.
1924 means that volumes exposition is controlled by system-wide tunable
1931 are encoded as 1, 2 and 3 respectively.
1932 The default values is
1934 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1935 Controls whether regular files should be scanned for viruses when a file is
1937 In addition to enabling this property, the virus scan service must also be
1938 enabled for virus scanning to occur.
1939 The default value is
1941 This property is not used on Linux.
1942 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1943 Controls whether extended attributes are enabled for this file system. Two
1944 styles of extended attributes are supported either directory based or system
1947 The default value of
1949 enables directory based extended attributes. This style of extended attribute
1950 imposes no practical limit on either the size or number of attributes which
1951 can be set on a file. Although under Linux the
1955 system calls limit the maximum size to 64K. This is the most compatible
1956 style of extended attribute and is supported by all OpenZFS implementations.
1958 System attribute based xattrs can be enabled by setting the value to
1960 The key advantage of this type of xattr is improved performance. Storing
1961 extended attributes as system attributes significantly decreases the amount of
1962 disk IO required. Up to 64K of data may be stored per-file in the space
1963 reserved for system attributes. If there is not enough space available for
1964 an extended attribute then it will be automatically written as a directory
1965 based xattr. System attribute based extended attributes are not accessible
1966 on platforms which do not support the
1970 The use of system attribute based xattrs is strongly encouraged for users of
1971 SELinux or posix ACLs. Both of these features heavily rely of extended
1972 attributes and benefit significantly from the reduced access time.
1978 are equivalent to the
1983 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1984 Controls whether the dataset is managed from a non-global zone. Zones are a
1985 Solaris feature and are not relevant on Linux. The default value is
1989 The following three properties cannot be changed after the file system is
1990 created, and therefore, should be set when the file system is created.
1991 If the properties are not set with the
1995 commands, these properties are inherited from the parent dataset.
1996 If the parent dataset lacks these properties due to having been created prior to
1997 these features being supported, the new file system will have the default values
1998 for these properties.
2001 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2002 .Sy insensitive Ns | Ns Sy mixed
2004 Indicates whether the file name matching algorithm used by the file system
2005 should be case-sensitive, case-insensitive, or allow a combination of both
2007 The default value for the
2015 file systems have case-sensitive file names.
2021 property indicates that the file system can support requests for both
2022 case-sensitive and case-insensitive matching behavior.
2023 Currently, case-insensitive matching behavior on a file system that supports
2024 mixed behavior is limited to the SMB server product.
2025 For more information about the
2027 value behavior, see the "ZFS Administration Guide".
2029 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2030 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2032 Indicates whether the file system should perform a
2034 normalization of file names whenever two file names are compared, and which
2035 normalization algorithm should be used.
2036 File names are always stored unmodified, names are normalized as part of any
2038 If this property is set to a legal value other than
2042 property was left unspecified, the
2044 property is automatically set to
2046 The default value of the
2050 This property cannot be changed after the file system is created.
2051 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2052 Indicates whether the file system should reject file names that include
2053 characters that are not present in the
2056 If this property is explicitly set to
2058 the normalization property must either not be explicitly set or be set to
2060 The default value for the
2064 This property cannot be changed after the file system is created.
2068 .Sy casesensitivity ,
2072 properties are also new permissions that can be assigned to non-privileged users
2073 by using the ZFS delegated administration feature.
2074 .Ss "Temporary Mount Point Properties"
2075 When a file system is mounted, either through
2077 for legacy mounts or the
2079 command for normal file systems, its mount options are set according to its
2081 The correlation between properties and mount options is as follows:
2083 PROPERTY MOUNT OPTION
2085 canmount auto/noauto
2089 relatime relatime/norelatime
2094 In addition, these options can be set on a per-mount basis using the
2096 option, without affecting the property that is stored on disk.
2097 The values specified on the command line override the values stored in the
2101 option is an alias for
2102 .Sy nodevices Ns \&, Ns Sy nosetuid .
2103 These properties are reported as
2108 If the properties are changed while the dataset is mounted, the new setting
2109 overrides any temporary settings.
2110 .Ss "User Properties"
2111 In addition to the standard native properties, ZFS supports arbitrary user
2113 User properties have no effect on ZFS behavior, but applications or
2114 administrators can use them to annotate datasets
2115 .Pq file systems, volumes, and snapshots .
2117 User property names must contain a colon
2119 character to distinguish them from native properties.
2120 They may contain lowercase letters, numbers, and the following punctuation
2129 The expected convention is that the property name is divided into two portions
2131 .Em module Ns \&: Ns Em property ,
2132 but this namespace is not enforced by ZFS.
2133 User property names can be at most 256 characters, and cannot begin with a dash
2136 When making programmatic use of user properties, it is strongly suggested to use
2141 component of property names to reduce the chance that two
2142 independently-developed packages use the same property name for different
2145 The values of user properties are arbitrary strings, are always inherited, and
2146 are never validated.
2147 All of the commands that operate on properties
2148 .Po Nm zfs Cm list ,
2153 can be used to manipulate both native properties and user properties.
2156 command to clear a user property.
2157 If the property is not defined in any parent dataset, it is removed entirely.
2158 Property values are limited to 8192 bytes.
2159 .Ss ZFS Volumes as Swap
2160 ZFS volumes may be used as swap devices. After creating the volume with the
2161 .Nm zfs Cm create Fl V
2162 command set up and enable the swap area using the
2166 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2167 configuration is not supported.
2171 feature allows for the creation of encrypted filesystems and volumes.
2173 will encrypt all user data including file and zvol data, file attributes,
2174 ACLs, permission bits, directory listings, FUID mappings, and userused /
2177 will not encrypt metadata related to the pool structure, including dataset
2178 names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
2179 is managed internally by the kernel module and changing the user's key does not
2180 require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
2181 renamed, and deleted without the encryption keys being loaded (see the
2183 subcommand for more info on key loading).
2185 Creating an encrypted dataset requires specifying the
2189 properties at creation time, along with an optional
2193 After entering an encryption key, the
2194 created dataset will become an encryption root. Any descendant datasets will
2195 inherit their encryption key from the encryption root by default, meaning that
2196 loading, unloading, or changing the key for the encryption root will implicitly
2197 do the same for all inheriting datasets. If this inheritance is not desired,
2200 when creating the child dataset or use
2201 .Nm zfs Cm change-key
2202 to break an existing relationship, creating a new encryption root on the child.
2203 Note that the child's
2205 may match that of the parent while still creating a new encryption root, and
2208 property alone does not create a new encryption root; this would simply use a
2209 different cipher suite with the same key as its encryption root. The one
2210 exception is that clones will always use their origin's encryption key.
2211 As a result of this exception, some encryption-related properties (namely
2217 do not inherit like other ZFS properties and instead use the value determined
2218 by their encryption root. Encryption root inheritance can be tracked via the
2223 Encryption changes the behavior of a few
2225 operations. Encryption is applied after compression so compression ratios are
2226 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2227 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2228 the encryption suite, which provides additional protection against maliciously
2229 altered data. Deduplication is still possible with encryption enabled but for
2230 security, datasets will only dedup against themselves, their snapshots, and
2233 There are a few limitations on encrypted datasets. Encrypted data cannot be
2236 feature. Encrypted datasets may not have
2237 .Sy copies Ns = Ns Em 3
2238 since the implementation stores some encryption metadata where the third copy
2239 would normally be. Since compression is applied before encryption datasets may
2240 be vulnerable to a CRIME-like attack if applications accessing the data allow
2241 for it. Deduplication with encryption will leak information about which blocks
2242 are equivalent in a dataset and will incur an extra CPU cost per block written.
2244 All subcommands that modify state are logged persistently to the pool in their
2248 Displays a help message.
2253 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2256 Creates a new ZFS file system.
2257 The file system is automatically mounted according to the
2259 property inherited from the parent.
2260 .Bl -tag -width "-o"
2261 .It Fl o Ar property Ns = Ns Ar value
2262 Sets the specified property as if the command
2263 .Nm zfs Cm set Ar property Ns = Ns Ar value
2264 was invoked at the same time the dataset was created.
2265 Any editable ZFS property can also be set at creation time.
2268 options can be specified.
2269 An error results if the same property is specified in multiple
2273 Creates all the non-existing parent datasets.
2274 Datasets created in this manner are automatically mounted according to the
2276 property inherited from their parent.
2277 Any property specified on the command line using the
2280 If the target filesystem already exists, the operation completes successfully.
2286 .Op Fl b Ar blocksize
2287 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2288 .Fl V Ar size Ar volume
2290 Creates a volume of the given size.
2291 The volume is exported as a block device in
2292 .Pa /dev/zvol/path ,
2295 is the name of the volume in the ZFS namespace.
2296 The size represents the logical size as exported by the device.
2297 By default, a reservation of equal size is created.
2300 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2301 has an integral number of blocks regardless of
2303 .Bl -tag -width "-b"
2304 .It Fl b Ar blocksize
2306 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2307 If this option is specified in conjunction with
2308 .Fl o Sy volblocksize ,
2309 the resulting behavior is undefined.
2310 .It Fl o Ar property Ns = Ns Ar value
2311 Sets the specified property as if the
2312 .Nm zfs Cm set Ar property Ns = Ns Ar value
2313 command was invoked at the same time the dataset was created.
2314 Any editable ZFS property can also be set at creation time.
2317 options can be specified.
2318 An error results if the same property is specified in multiple
2322 Creates all the non-existing parent datasets.
2323 Datasets created in this manner are automatically mounted according to the
2325 property inherited from their parent.
2326 Any property specified on the command line using the
2329 If the target filesystem already exists, the operation completes successfully.
2331 Creates a sparse volume with no reservation.
2335 .Sx Native Properties
2336 section for more information about sparse volumes.
2342 .Ar filesystem Ns | Ns Ar volume
2344 Destroys the given dataset.
2345 By default, the command unshares any file systems that are currently shared,
2346 unmounts any file systems that are currently mounted, and refuses to destroy a
2347 dataset that has active dependents
2348 .Pq children or clones .
2349 .Bl -tag -width "-R"
2351 Recursively destroy all dependents, including cloned file systems outside the
2354 Force an unmount of any file systems using the
2357 This option has no effect on non-file systems or unmounted file systems.
2362 No data will be deleted.
2363 This is useful in conjunction with the
2367 flags to determine what data would be deleted.
2369 Print machine-parsable verbose information about the deleted data.
2371 Recursively destroy all children.
2373 Print verbose information about the deleted data.
2376 Extreme care should be taken when applying either the
2380 options, as they can destroy large portions of a pool and cause unexpected
2381 behavior for mounted file systems in use.
2386 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2387 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2389 The given snapshots are destroyed immediately if and only if the
2393 option would have destroyed it.
2394 Such immediate destruction would occur, for example, if the snapshot had no
2395 clones and the user-initiated reference count were zero.
2397 If a snapshot does not qualify for immediate destruction, it is marked for
2399 In this state, it exists as a usable, visible snapshot until both of the
2400 preconditions listed above are met, at which point it is destroyed.
2402 An inclusive range of snapshots may be specified by separating the first and
2403 last snapshots with a percent sign.
2404 The first and/or last snapshots may be left blank, in which case the
2405 filesystem's oldest or newest snapshot will be implied.
2408 .Pq or ranges of snapshots
2409 of the same filesystem or volume may be specified in a comma-separated list of
2411 Only the snapshot's short name
2412 .Po the part after the
2415 should be specified when using a range or comma-separated list to identify
2417 .Bl -tag -width "-R"
2419 Recursively destroy all clones of these snapshots, including the clones,
2420 snapshots, and children.
2421 If this flag is specified, the
2423 flag will have no effect.
2425 Defer snapshot deletion.
2430 No data will be deleted.
2431 This is useful in conjunction with the
2435 flags to determine what data would be deleted.
2437 Print machine-parsable verbose information about the deleted data.
2440 .Pq or mark for deferred deletion
2441 all snapshots with this name in descendent file systems.
2443 Print verbose information about the deleted data.
2445 Extreme care should be taken when applying either the
2449 options, as they can destroy large portions of a pool and cause unexpected
2450 behavior for mounted file systems in use.
2455 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2457 The given bookmark is destroyed.
2462 .Oo Fl o Ar property Ns = Ns value Oc Ns ...
2463 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2465 Creates snapshots with the given names.
2466 All previous modifications by successful system calls to the file system are
2467 part of the snapshots.
2468 Snapshots are taken atomically, so that all snapshots correspond to the same
2472 section for details.
2473 .Bl -tag -width "-o"
2474 .It Fl o Ar property Ns = Ns Ar value
2475 Sets the specified property; see
2479 Recursively create snapshots of all descendent datasets
2487 Roll back the given dataset to a previous snapshot.
2488 When a dataset is rolled back, all data that has changed since the snapshot is
2489 discarded, and the dataset reverts to the state at the time of the snapshot.
2490 By default, the command refuses to roll back to a snapshot other than the most
2492 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2499 options do not recursively destroy the child snapshots of a recursive snapshot.
2500 Only direct snapshots of the specified filesystem are destroyed by either of
2502 To completely roll back a recursive snapshot, you must rollback the individual
2504 .Bl -tag -width "-R"
2506 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2511 option to force an unmount of any clone file systems that are to be destroyed.
2513 Destroy any snapshots and bookmarks more recent than the one specified.
2519 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2520 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2522 Creates a clone of the given snapshot.
2525 section for details.
2526 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2527 as the same type as the original.
2528 .Bl -tag -width "-o"
2529 .It Fl o Ar property Ns = Ns Ar value
2530 Sets the specified property; see
2534 Creates all the non-existing parent datasets.
2535 Datasets created in this manner are automatically mounted according to the
2537 property inherited from their parent.
2538 If the target filesystem or volume already exists, the operation completes
2544 .Ar clone-filesystem
2546 Promotes a clone file system to no longer be dependent on its
2549 This makes it possible to destroy the file system that the clone was created
2551 The clone parent-child dependency relationship is reversed, so that the origin
2552 file system becomes a clone of the specified file system.
2554 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2555 now owned by the promoted clone.
2556 The space they use moves from the origin file system to the promoted clone, so
2557 enough space must be available to accommodate these snapshots.
2558 No new space is consumed by this operation, but the space accounting is
2560 The promoted clone must not have any conflicting snapshot names of its own.
2563 subcommand can be used to rename any conflicting snapshots.
2568 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2569 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2575 .Ar filesystem Ns | Ns Ar volume
2576 .Ar filesystem Ns | Ns Ar volume
2578 Renames the given dataset.
2579 The new target can be located anywhere in the ZFS hierarchy, with the exception
2581 Snapshots can only be renamed within the parent file system or volume.
2582 When renaming a snapshot, the parent file system of the snapshot does not need
2583 to be specified as part of the second argument.
2584 Renamed file systems can inherit new mount points, in which case they are
2585 unmounted and remounted at the new mount point.
2586 .Bl -tag -width "-a"
2588 Force unmount any filesystems that need to be unmounted in the process.
2590 Creates all the nonexistent parent datasets.
2591 Datasets created in this manner are automatically mounted according to the
2593 property inherited from their parent.
2599 .Ar snapshot Ar snapshot
2601 Recursively rename the snapshots of all descendent datasets.
2602 Snapshots are the only dataset that can be renamed recursively.
2606 .Op Fl r Ns | Ns Fl d Ar depth
2608 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2609 .Oo Fl s Ar property Oc Ns ...
2610 .Oo Fl S Ar property Oc Ns ...
2611 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2612 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2614 Lists the property information for the given datasets in tabular form.
2615 If specified, you can list property information by the absolute pathname or the
2617 By default, all file systems and volumes are displayed.
2618 Snapshots are displayed if the
2625 The following fields are displayed,
2626 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2628 .Bl -tag -width "-H"
2630 Used for scripting mode.
2631 Do not print headers and separate fields by a single tab instead of arbitrary
2633 .It Fl S Ar property
2636 option, but sorts by property in descending order.
2638 Recursively display any children of the dataset, limiting the recursion to
2644 will display only the dataset and its direct children.
2645 .It Fl o Ar property
2646 A comma-separated list of properties to display.
2647 The property must be:
2650 One of the properties described in the
2651 .Sx Native Properties
2658 to display the dataset name
2662 to display space usage properties on file systems and volumes.
2663 This is a shortcut for specifying
2664 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2665 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2666 .Sy filesystem Ns \&, Ns Sy volume
2670 Display numbers in parsable
2674 Recursively display any children of the dataset on the command line.
2675 .It Fl s Ar property
2676 A property for sorting the output by column in ascending order based on the
2677 value of the property.
2678 The property must be one of the properties described in the
2680 section, or the special value
2682 to sort by the dataset name.
2683 Multiple properties can be specified at one time using multiple
2688 options are evaluated from left to right in decreasing order of importance.
2689 The following is a list of sorting criteria:
2692 Numeric types sort in numeric order.
2694 String types sort in alphabetical order.
2696 Types inappropriate for a row sort that row to the literal bottom, regardless of
2697 the specified ordering.
2700 If no sorting options are specified the existing behavior of
2704 A comma-separated list of types to display, where
2713 For example, specifying
2715 displays only snapshots.
2720 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2721 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2723 Sets the property or list of properties to the given value(s) for each dataset.
2724 Only some properties can be edited.
2727 section for more information on what properties can be set and acceptable
2729 Numeric values can be specified as exact values, or in a human-readable form
2731 .Sy B , K , M , G , T , P , E , Z
2732 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2733 or zettabytes, respectively
2735 User properties can be set on snapshots.
2736 For more information, see the
2742 .Op Fl r Ns | Ns Fl d Ar depth
2744 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2745 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2746 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2747 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2748 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2750 Displays properties for the given datasets.
2751 If no datasets are specified, then the command displays properties for all
2752 datasets on the system.
2753 For each property, the following columns are displayed:
2756 property Property name
2757 value Property value
2758 source Property source. Can either be local, default,
2759 temporary, inherited, or none (-).
2762 All columns are displayed by default, though this can be controlled by using the
2765 This command takes a comma-separated list of properties as described in the
2766 .Sx Native Properties
2773 can be used to display all properties that apply to the given dataset's type
2774 .Pq filesystem, volume, snapshot, or bookmark .
2775 .Bl -tag -width "-H"
2777 Display output in a form more easily parsed by scripts.
2778 Any headers are omitted, and fields are explicitly separated by a single tab
2779 instead of an arbitrary amount of space.
2781 Recursively display any children of the dataset, limiting the recursion to
2785 will display only the dataset and its direct children.
2787 A comma-separated list of columns to display.
2788 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2789 is the default value.
2791 Display numbers in parsable
2795 Recursively display properties for any children.
2797 A comma-separated list of sources to display.
2798 Those properties coming from a source other than those in this list are ignored.
2799 Each source must be one of the following:
2806 The default value is all sources.
2808 A comma-separated list of types to display, where
2822 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2824 Clears the specified property, causing it to be inherited from an ancestor,
2825 restored to default if no ancestor has the property set, or with the
2827 option reverted to the received value if one exists.
2830 section for a listing of default values, and details on which properties can be
2832 .Bl -tag -width "-r"
2834 Recursively inherit the given property for all children.
2836 Revert the property to the received value if one exists; otherwise operate as
2839 option was not specified.
2845 Displays a list of file systems that are not the most recent version.
2851 Displays a list of currently supported file system versions.
2857 .Fl a | Ar filesystem
2859 Upgrades file systems to a new on-disk version.
2860 Once this is done, the file systems will no longer be accessible on systems
2861 running older versions of the software.
2863 streams generated from new snapshots of these file systems cannot be accessed on
2864 systems running older versions of the software.
2866 In general, the file system version is independent of the pool version.
2869 for information on the
2870 .Nm zpool Cm upgrade
2873 In some cases, the file system version and the pool version are interrelated and
2874 the pool version must be upgraded before the file system version can be
2876 .Bl -tag -width "-V"
2878 Upgrade to the specified
2882 flag is not specified, this command upgrades to the most recent version.
2884 option can only be used to increase the version number, and only up to the most
2885 recent version supported by this software.
2887 Upgrade all file systems on all imported pools.
2889 Upgrade the specified file system.
2891 Upgrade the specified file system and all descendent file systems.
2897 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2898 .Oo Fl s Ar field Oc Ns ...
2899 .Oo Fl S Ar field Oc Ns ...
2900 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2901 .Ar filesystem Ns | Ns Ar snapshot
2903 Displays space consumed by, and quotas on, each user in the specified filesystem
2905 This corresponds to the
2906 .Sy userused@ Ns Em user ,
2907 .Sy userobjused@ Ns Em user ,
2908 .Sy userquota@ Ns Em user,
2910 .Sy userobjquota@ Ns Em user
2912 .Bl -tag -width "-H"
2914 Do not print headers, use tab-delimited output.
2916 Sort by this field in reverse order.
2920 Translate SID to POSIX ID.
2921 The POSIX ID may be ephemeral if no mapping exists.
2922 Normal POSIX interfaces
2927 perform this translation, so the
2929 option allows the output from
2930 .Nm zfs Cm userspace
2931 to be compared directly with those utilities.
2934 may lead to confusion if some files were created by an SMB user before a
2935 SMB-to-POSIX name mapping was established.
2936 In such a case, some files will be owned by the SMB entity and some by the POSIX
2940 option will report that the POSIX entity has the total usage and quota for both.
2942 Print numeric ID instead of user/group name.
2943 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2944 Display only the specified fields from the following set:
2949 The default is to display all fields.
2955 Sort output by this field.
2960 flags may be specified multiple times to sort first by one field, then by
2963 .Fl s Sy type Fl s Sy name .
2964 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2965 Print only the specified types from the following set:
2972 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
2973 The default can be changed to include group types.
2979 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2980 .Oo Fl s Ar field Oc Ns ...
2981 .Oo Fl S Ar field Oc Ns ...
2982 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2983 .Ar filesystem Ns | Ns Ar snapshot
2985 Displays space consumed by, and quotas on, each group in the specified
2986 filesystem or snapshot.
2987 This subcommand is identical to
2988 .Nm zfs Cm userspace ,
2989 except that the default types to display are
2990 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
2995 Displays all ZFS file systems currently mounted.
3001 .Fl a | Ar filesystem
3003 Mounts ZFS file systems.
3004 .Bl -tag -width "-O"
3006 Perform an overlay mount.
3009 for more information.
3011 Mount all available ZFS file systems.
3012 Invoked automatically as part of the boot process.
3014 Mount the specified filesystem.
3016 An optional, comma-separated list of mount options to use temporarily for the
3017 duration of the mount.
3019 .Sx Temporary Mount Point Properties
3020 section for details.
3022 Load keys for encrypted filesystems as they are being mounted. This is
3023 equivalent to executing
3025 on each encryption root before mounting it. Note that if a filesystem has a
3029 this will cause the terminal to interactively block after asking for the key.
3031 Report mount progress.
3037 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3039 Unmounts currently mounted ZFS file systems.
3040 .Bl -tag -width "-a"
3042 Unmount all available ZFS file systems.
3043 Invoked automatically as part of the shutdown process.
3044 .It Ar filesystem Ns | Ns Ar mountpoint
3045 Unmount the specified filesystem.
3046 The command can also be given a path to a ZFS file system mount point on the
3049 Forcefully unmount the file system, even if it is currently in use.
3054 .Fl a | Ar filesystem
3056 Shares available ZFS file systems.
3057 .Bl -tag -width "-a"
3059 Share all available ZFS file systems.
3060 Invoked automatically as part of the boot process.
3062 Share the specified filesystem according to the
3067 File systems are shared when the
3076 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3078 Unshares currently shared ZFS file systems.
3079 .Bl -tag -width "-a"
3081 Unshare all available ZFS file systems.
3082 Invoked automatically as part of the shutdown process.
3083 .It Ar filesystem Ns | Ns Ar mountpoint
3084 Unshare the specified filesystem.
3085 The command can also be given a path to a ZFS file system shared on the system.
3090 .Ar snapshot bookmark
3092 Creates a bookmark of the given snapshot.
3093 Bookmarks mark the point in time when the snapshot was created, and can be used
3094 as the incremental source for a
3098 This feature must be enabled to be used.
3100 .Xr zpool-features 5
3101 for details on ZFS feature flags and the
3108 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3111 Creates a stream representation of the second
3113 which is written to standard output.
3114 The output can be redirected to a file or to a different system
3115 .Po for example, using
3118 By default, a full stream is generated.
3119 .Bl -tag -width "-D"
3121 Generate a deduplicated stream.
3122 Blocks which would have been sent multiple times in the send stream will only be
3124 The receiving system must also support this feature to receive a deduplicated
3126 This flag can be used regardless of the dataset's
3128 property, but performance will be much better if the filesystem uses a
3129 dedup-capable checksum
3133 .It Fl I Ar snapshot
3134 Generate a stream package that sends all intermediary snapshots from the first
3135 snapshot to the second snapshot.
3139 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3140 The incremental source may be specified as with the
3143 .It Fl L, -large-block
3144 Generate a stream which may contain blocks larger than 128KB.
3145 This flag has no effect if the
3147 pool feature is disabled, or if the
3149 property of this filesystem has never been set above 128KB.
3150 The receiving system must have the
3152 pool feature enabled as well.
3154 .Xr zpool-features 5
3155 for details on ZFS feature flags and the
3159 Print machine-parsable verbose information about the stream package generated.
3160 .It Fl R, -replicate
3161 Generate a replication stream package, which will replicate the specified
3162 file system, and all descendent file systems, up to the named snapshot.
3163 When received, all properties, snapshots, descendent file systems, and clones
3170 flags are used in conjunction with the
3172 flag, an incremental replication stream is generated.
3173 The current values of properties, and current snapshot and file system names are
3174 set when the stream is received.
3177 flag is specified when this stream is received, snapshots and file systems that
3178 do not exist on the sending side are destroyed.
3180 Generate a more compact stream by using
3182 records for blocks which are stored more compactly on disk by the
3185 This flag has no effect if the
3187 feature is disabled.
3188 The receiving system must have the
3193 feature is active on the sending system, then the receiving system must have
3194 that feature enabled as well. Datasets that are sent with this flag may not be
3195 received as an encrypted dataset, since encrypted datasets cannot use the
3199 .Xr zpool-features 5
3200 for details on ZFS feature flags and the
3203 .It Fl c, -compressed
3204 Generate a more compact stream by using compressed WRITE records for blocks
3205 which are compressed on disk and in memory
3208 property for details
3212 feature is active on the sending system, then the receiving system must have
3213 that feature enabled as well.
3216 feature is enabled on the sending system but the
3218 option is not supplied in conjunction with
3220 then the data will be decompressed before sending so it can be split into
3221 smaller block sizes.
3223 For encrypted datasets, send data exactly as it exists on disk. This allows
3224 backups to be taken even if encryption keys are not currently loaded. The
3225 backup may then be received on an untrusted machine since that machine will
3226 not have the encryption keys to read the protected data or alter it without
3227 being detected. Upon being received, the dataset will have the same encryption
3228 keys as it did on the send side, although the
3230 property will be defaulted to
3232 if not otherwise provided. For unencrypted datasets, this flag will be
3235 Note that if you do not use this flag for sending encrypted datasets, data will
3236 be sent unencrypted and may be re-encrypted with a different encryption key on
3237 the receiving system, which will disable the ability to do a raw send to that
3238 system for incrementals.
3239 .It Fl i Ar snapshot
3240 Generate an incremental stream from the first
3242 .Pq the incremental source
3245 .Pq the incremental target .
3246 The incremental source can be specified as the last component of the snapshot
3250 character and following
3252 and it is assumed to be from the same file system as the incremental target.
3254 If the destination is a clone, the source may be the origin snapshot, which must
3257 .Em pool/fs@origin ,
3265 Do not generate any actual send data.
3266 This is useful in conjunction with the
3270 flags to determine what data will be sent.
3271 In this case, the verbose output will be written to standard output
3272 .Po contrast with a non-dry-run, where the stream is written to standard output
3273 and the verbose output goes to standard error
3276 Include the dataset's properties in the stream.
3277 This flag is implicit when
3280 The receiving system must also support this feature. Sends of encrypted datasets
3283 when using this flag.
3285 Print verbose information about the stream package generated.
3286 This information includes a per-second report of how much data has been sent.
3288 The format of the stream is committed.
3289 You will be able to receive your streams on future versions of ZFS.
3295 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3296 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3298 Generate a send stream, which may be of a filesystem, and may be incremental
3300 If the destination is a filesystem or volume, the pool must be read-only, or the
3301 filesystem must not be mounted.
3302 When the stream generated from a filesystem or volume is received, the default
3303 snapshot name will be
3305 .Bl -tag -width "-L"
3306 .It Fl L, -large-block
3307 Generate a stream which may contain blocks larger than 128KB.
3308 This flag has no effect if the
3310 pool feature is disabled, or if the
3312 property of this filesystem has never been set above 128KB.
3313 The receiving system must have the
3315 pool feature enabled as well.
3317 .Xr zpool-features 5
3318 for details on ZFS feature flags and the
3322 Print machine-parsable verbose information about the stream package generated.
3323 .It Fl c, -compressed
3324 Generate a more compact stream by using compressed WRITE records for blocks
3325 which are compressed on disk and in memory
3328 property for details
3332 feature is active on the sending system, then the receiving system must have
3333 that feature enabled as well.
3336 feature is enabled on the sending system but the
3338 option is not supplied in conjunction with
3340 then the data will be decompressed before sending so it can be split into
3341 smaller block sizes.
3343 For encrypted datasets, send data exactly as it exists on disk. This allows
3344 backups to be taken even if encryption keys are not currently loaded. The
3345 backup may then be received on an untrusted machine since that machine will
3346 not have the encryption keys to read the protected data or alter it without
3347 being detected. Upon being received, the dataset will have the same encryption
3348 keys as it did on the send side, although the
3350 property will be defaulted to
3352 if not otherwise provided. For unencrypted datasets, this flag will be
3355 Note that if you do not use this flag for sending encrypted datasets, data will
3356 be sent unencrypted and may be re-encrypted with a different encryption key on
3357 the receiving system, which will disable the ability to do a raw send to that
3358 system for incrementals.
3360 Generate a more compact stream by using
3362 records for blocks which are stored more compactly on disk by the
3365 This flag has no effect if the
3367 feature is disabled.
3368 The receiving system must have the
3373 feature is active on the sending system, then the receiving system must have
3374 that feature enabled as well. Datasets that are sent with this flag may not be
3375 received as an encrypted dataset, since encrypted datasets cannot use the
3379 .Xr zpool-features 5
3380 for details on ZFS feature flags and the
3383 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3384 Generate an incremental send stream.
3385 The incremental source must be an earlier snapshot in the destination's history.
3386 It will commonly be an earlier snapshot in the destination's file system, in
3387 which case it can be specified as the last component of the name
3392 character and following
3395 If the incremental target is a clone, the incremental source can be the origin
3396 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3402 Do not generate any actual send data.
3403 This is useful in conjunction with the
3407 flags to determine what data will be sent.
3408 In this case, the verbose output will be written to standard output
3409 .Po contrast with a non-dry-run, where the stream is written to standard output
3410 and the verbose output goes to standard error
3413 Print verbose information about the stream package generated.
3414 This information includes a per-second report of how much data has been sent.
3421 .Ar receive_resume_token
3423 Creates a send stream which resumes an interrupted receive.
3425 .Ar receive_resume_token
3426 is the value of this property on the filesystem or volume that was being
3428 See the documentation for
3435 .Op Fl o Sy origin Ns = Ns Ar snapshot
3436 .Op Fl o Ar property Ns = Ns Ar value
3437 .Op Fl x Ar property
3438 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3444 .Op Fl d Ns | Ns Fl e
3445 .Op Fl o Sy origin Ns = Ns Ar snapshot
3446 .Op Fl o Ar property Ns = Ns Ar value
3447 .Op Fl x Ar property
3450 Creates a snapshot whose contents are as specified in the stream provided on
3452 If a full stream is received, then a new file system is created as well.
3453 Streams are created using the
3455 subcommand, which by default creates a full stream.
3457 can be used as an alias for
3460 If an incremental stream is received, then the destination file system must
3461 already exist, and its most recent snapshot must match the incremental stream's
3465 the destination device link is destroyed and recreated, which means the
3467 cannot be accessed during the
3471 When a snapshot replication package stream that is generated by using the
3472 .Nm zfs Cm send Fl R
3473 command is received, any snapshots that do not exist on the sending location are
3474 destroyed by using the
3475 .Nm zfs Cm destroy Fl d
3479 .Fl o Em property Ns = Ns Ar value
3482 is specified, it applies to the effective value of the property throughout
3483 the entire subtree of replicated datasets. Effective property values will be
3488 ) on the topmost in the replicated subtree. In descendant datasets, if the
3489 property is set by the send stream, it will be overridden by forcing the
3490 property to be inherited from the top‐most file system. Received properties
3491 are retained in spite of being overridden and may be restored with
3492 .Nm zfs Cm inherit Fl S .
3494 .Fl o Sy origin Ns = Ns Em snapshot
3495 is a special case because, even if
3497 is a read-only property and cannot be set, it's allowed to receive the send
3498 stream as a clone of the given snapshot.
3500 Raw encrypted send streams (created with
3501 .Nm zfs Cm send Fl w
3502 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3503 recompressed by the receive process. Unencrypted streams can be received as
3504 encrypted datasets, either through inheritance or by specifying encryption
3509 The name of the snapshot
3510 .Pq and file system, if a full stream is received
3511 that this subcommand creates depends on the argument type and the use of the
3517 If the argument is a snapshot name, the specified
3520 If the argument is a file system or volume name, a snapshot with the same name
3521 as the sent snapshot is created within the specified
3529 options are specified, the provided target snapshot name is used exactly as
3536 options cause the file system name of the target snapshot to be determined by
3537 appending a portion of the sent snapshot's name to the specified target
3541 option is specified, all but the first element of the sent snapshot's file
3543 .Pq usually the pool name
3544 is used and any required intermediate file systems within the specified one are
3548 option is specified, then only the last element of the sent snapshot's file
3550 .Pq i.e. the name of the source file system itself
3551 is used as the target file system name.
3552 .Bl -tag -width "-F"
3554 Force a rollback of the file system to the most recent snapshot before
3555 performing the receive operation.
3556 If receiving an incremental replication stream
3557 .Po for example, one generated by
3558 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3560 destroy snapshots and file systems that do not exist on the sending side.
3562 Discard the first element of the sent snapshot's file system name, using the
3563 remaining elements to determine the name of the target file system for the new
3564 snapshot as described in the paragraph above.
3566 Discard all but the last element of the sent snapshot's file system name, using
3567 that element to determine the name of the target file system for the new
3568 snapshot as described in the paragraph above.
3570 Do not actually receive the stream.
3571 This can be useful in conjunction with the
3573 option to verify the name the receive operation would use.
3574 .It Fl o Sy origin Ns = Ns Ar snapshot
3575 Forces the stream to be received as a clone of the given snapshot.
3576 If the stream is a full send stream, this will create the filesystem
3577 described by the stream as a clone of the specified snapshot.
3578 Which snapshot was specified will not affect the success or failure of the
3579 receive, as long as the snapshot does exist.
3580 If the stream is an incremental send stream, all the normal verification will be
3582 .It Fl o Em property Ns = Ns Ar value
3583 Sets the specified property as if the command
3584 .Nm zfs Cm set Em property Ns = Ns Ar value
3585 was invoked immediately before the receive. When receiving a stream from
3586 .Nm zfs Cm send Fl R ,
3587 causes the property to be inherited by all descendant datasets, as through
3588 .Nm zfs Cm inherit Em property
3589 was run on any descendant datasets that have this property set on the
3592 Any editable property can be set at receive time. Set-once properties bound
3593 to the received data, such as
3596 .Sy casesensitivity ,
3597 cannot be set at receive time even when the datasets are newly created by
3598 .Nm zfs Cm receive .
3599 Additionally both settable properties
3603 cannot be set at receive time.
3607 option may be specified multiple times, for different properties. An error
3608 results if the same property is specified in multiple
3614 If the receive is interrupted, save the partially received state, rather
3616 Interruption may be due to premature termination of the stream
3617 .Po e.g. due to network failure or failure of the remote system
3618 if the stream is being read over a network connection
3620 a checksum error in the stream, termination of the
3622 process, or unclean shutdown of the system.
3624 The receive can be resumed with a stream generated by
3625 .Nm zfs Cm send Fl t Ar token ,
3629 .Sy receive_resume_token
3630 property of the filesystem or volume which is received into.
3632 To use this flag, the storage pool must have the
3633 .Sy extensible_dataset
3636 .Xr zpool-features 5
3637 for details on ZFS feature flags.
3639 File system that is associated with the received stream is not mounted.
3641 Print verbose information about the stream and the time required to perform the
3643 .It Fl x Em property
3644 Ensures that the effective value of the specified property after the
3645 receive is unaffected by the value of that property in the send stream (if any),
3646 as if the property had been excluded from the send stream.
3648 If the specified property is not present in the send stream, this option does
3651 If a received property needs to be overridden, the effective value will be
3652 set or inherited, depending on whether the property is inheritable or not.
3654 In the case of an incremental update,
3656 leaves any existing local setting or explicit inheritance unchanged.
3660 restrictions on set-once and special properties apply equally to
3667 .Ar filesystem Ns | Ns Ar volume
3669 Abort an interrupted
3670 .Nm zfs Cm receive Fl s ,
3671 deleting its saved partially received state.
3675 .Ar filesystem Ns | Ns Ar volume
3677 Displays permissions that have been delegated on the specified filesystem or
3679 See the other forms of
3681 for more information.
3683 Delegations are supported under Linux with the exception of
3691 These permissions cannot be delegated because the Linux
3693 command restricts modifications of the global namespace to the root user.
3698 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3699 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3700 .Ar setname Oc Ns ...
3701 .Ar filesystem Ns | Ns Ar volume
3706 .Fl e Ns | Ns Sy everyone
3707 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3708 .Ar setname Oc Ns ...
3709 .Ar filesystem Ns | Ns Ar volume
3711 Delegates ZFS administration permission for the file systems to non-privileged
3713 .Bl -tag -width "-d"
3715 Allow only for the descendent file systems.
3716 .It Fl e Ns | Ns Sy everyone
3717 Specifies that the permissions be delegated to everyone.
3718 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3719 Explicitly specify that permissions are delegated to the group.
3723 only for the specified file system.
3724 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3725 Explicitly specify that permissions are delegated to the user.
3726 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3727 Specifies to whom the permissions are delegated.
3728 Multiple entities can be specified as a comma-separated list.
3731 options are specified, then the argument is interpreted preferentially as the
3734 then as a user name, and lastly as a group name.
3735 To specify a user or group named
3742 To specify a group with the same name as a user, use the
3746 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3747 .Ar setname Oc Ns ...
3749 The permissions to delegate.
3750 Multiple permissions may be specified as a comma-separated list.
3751 Permission names are the same as ZFS subcommand and property names.
3752 See the property list below.
3753 Property set names, which begin with
3758 form below for details.
3763 options are specified, or both are, then the permissions are allowed for the
3764 file system or volume, and all of its descendents.
3766 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3768 The following permissions are available:
3771 allow subcommand Must also have the permission that is
3773 clone subcommand Must also have the 'create' ability and
3774 'mount' ability in the origin file system
3775 create subcommand Must also have the 'mount' ability
3776 destroy subcommand Must also have the 'mount' ability
3777 diff subcommand Allows lookup of paths within a dataset
3778 given an object number, and the ability
3779 to create snapshots necessary to
3781 load-key subcommand Allows loading and unloading of encryption key
3782 (see 'zfs load-key' and 'zfs unload-key').
3783 change-key subcommand Allows changing an encryption key via
3785 mount subcommand Allows mount/umount of ZFS datasets
3786 promote subcommand Must also have the 'mount' and 'promote'
3787 ability in the origin file system
3788 receive subcommand Must also have the 'mount' and 'create'
3790 rename subcommand Must also have the 'mount' and 'create'
3791 ability in the new parent
3792 rollback subcommand Must also have the 'mount' ability
3794 share subcommand Allows sharing file systems over NFS
3796 snapshot subcommand Must also have the 'mount' ability
3798 groupquota other Allows accessing any groupquota@...
3800 groupused other Allows reading any groupused@... property
3801 userprop other Allows changing any user property
3802 userquota other Allows accessing any userquota@...
3804 userused other Allows reading any userused@... property
3810 casesensitivity property
3812 compression property
3816 filesystem_limit property
3819 normalization property
3820 primarycache property
3825 refreservation property
3826 reservation property
3827 secondarycache property
3832 snapshot_limit property
3835 volblocksize property
3845 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3846 .Ar setname Oc Ns ...
3847 .Ar filesystem Ns | Ns Ar volume
3852 These permissions are granted
3854 to the creator of any newly-created descendent file system.
3858 .Fl s No @ Ns Ar setname
3859 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3860 .Ar setname Oc Ns ...
3861 .Ar filesystem Ns | Ns Ar volume
3863 Defines or adds permissions to a permission set.
3864 The set can be used by other
3866 commands for the specified file system and its descendents.
3867 Sets are evaluated dynamically, so changes to a set are immediately reflected.
3868 Permission sets follow the same naming restrictions as ZFS file systems, but the
3869 name must begin with
3871 and can be no more than 64 characters long.
3876 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3877 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3878 .Ar setname Oc Ns ... Oc
3879 .Ar filesystem Ns | Ns Ar volume
3884 .Fl e Ns | Ns Sy everyone
3885 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3886 .Ar setname Oc Ns ... Oc
3887 .Ar filesystem Ns | Ns Ar volume
3893 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3894 .Ar setname Oc Ns ... Oc
3895 .Ar filesystem Ns | Ns Ar volume
3897 Removes permissions that were granted with the
3900 No permissions are explicitly denied, so other permissions granted are still in
3902 For example, if the permission is granted by an ancestor.
3903 If no permissions are specified, then all permissions for the specified
3915 only removes the permissions that were granted to everyone, not all permissions
3916 for every user and group.
3919 command for a description of the
3922 .Bl -tag -width "-r"
3924 Recursively remove the permissions from this file system and all descendents.
3930 .Fl s No @ Ns Ar setname
3931 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3932 .Ar setname Oc Ns ... Oc
3933 .Ar filesystem Ns | Ns Ar volume
3935 Removes permissions from a permission set.
3936 If no permissions are specified, then all permissions are removed, thus removing
3942 .Ar tag Ar snapshot Ns ...
3944 Adds a single reference, named with the
3946 argument, to the specified snapshot or snapshots.
3947 Each snapshot has its own tag namespace, and tags must be unique within that
3950 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3954 .Bl -tag -width "-r"
3956 Specifies that a hold with the given tag is applied recursively to the snapshots
3957 of all descendent file systems.
3965 Lists all existing user references for the given snapshot or snapshots.
3966 .Bl -tag -width "-r"
3968 Lists the holds that are set on the named descendent snapshots, in addition to
3969 listing the holds on the named snapshot.
3975 .Ar tag Ar snapshot Ns ...
3977 Removes a single reference, named with the
3979 argument, from the specified snapshot or snapshots.
3980 The tag must already exist for each snapshot.
3981 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3985 .Bl -tag -width "-r"
3987 Recursively releases a hold with the given tag on the snapshots of all
3988 descendent file systems.
3994 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3996 Display the difference between a snapshot of a given filesystem and another
3997 snapshot of that filesystem from a later time or the current contents of the
3999 The first column is a character indicating the type of change, the other columns
4000 indicate pathname, new pathname
4001 .Pq in case of rename ,
4002 change in link count, and optionally file type and/or change time.
4003 The types of change are:
4005 - The path has been removed
4006 + The path has been created
4007 M The path has been modified
4008 R The path has been renamed
4010 .Bl -tag -width "-F"
4012 Display an indication of the type of file, in a manner similar to the
4028 Give more parsable tab-separated output, without header lines and without
4031 Display the path's inode change time as the first column of output.
4037 .Op Fl L Ar keylocation
4038 .Fl a | Ar filesystem
4042 allowing it and all children that inherit the
4044 property to be accessed. The key will be expected in the format specified by the
4046 and location specified by the
4048 property. Note that if the
4052 the terminal will interactively wait for the key to be entered. Loading a key
4053 will not automatically mount the dataset. If that functionality is desired,
4054 .Nm zfs Cm mount Sy -l
4055 will ask for the key and mount the dataset. Once the key is loaded the
4057 property will become
4059 .Bl -tag -width "-r"
4061 Recursively loads the keys for the specified filesystem and all descendent
4064 Loads the keys for all encryption roots in all imported pools.
4068 load-key. This will cause zfs to simply check that the
4069 provided key is correct. This command may be run even if the key is already
4071 .It Fl L Ar keylocation
4076 property. This will not change the value of the property on the dataset. Note
4077 that if used with either
4082 may only be given as
4089 .Fl a | Ar filesystem
4091 Unloads a key from ZFS, removing the ability to access the dataset and all of
4092 its children that inherit the
4094 property. This requires that the dataset is not currently open or mounted. Once
4095 the key is unloaded the
4097 property will become
4099 .Bl -tag -width "-r"
4101 Recursively unloads the keys for the specified filesystem and all descendent
4104 Unloads the keys for all encryption roots in all imported pools.
4110 .Op Fl o Ar keylocation Ns = Ns Ar value
4111 .Op Fl o Ar keyformat Ns = Ns Ar value
4112 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4122 Allows a user to change the encryption key used to access a dataset. This
4123 command requires that the existing key for the dataset is already loaded into
4124 ZFS. This command may also be used to change the
4129 properties as needed. If the dataset was not previously an encryption root it
4130 will become one. Alternatively, the
4132 flag may be provided to cause an encryption root to inherit the parent's key
4134 .Bl -tag -width "-r"
4136 Ensures the key is loaded before attempting to change the key. This is
4137 effectively equivalent to
4138 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4139 .It Fl o Ar property Ns = Ns Ar value
4140 Allows the user to set encryption key properties (
4145 ) while changing the key. This is the only way to alter
4149 after the dataset has been created.
4151 Indicates that zfs should make
4153 inherit the key of its parent. Note that this command can only be run on an
4154 encryption root that has an encrypted parent.
4160 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4161 options were specified.
4164 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4165 The following commands create a file system named
4167 and a file system named
4171 is set for the parent file system, and is automatically inherited by the child
4174 # zfs create pool/home
4175 # zfs set mountpoint=/export/home pool/home
4176 # zfs create pool/home/bob
4178 .It Sy Example 2 No Creating a ZFS Snapshot
4179 The following command creates a snapshot named
4181 This snapshot is mounted on demand in the
4183 directory at the root of the
4187 # zfs snapshot pool/home/bob@yesterday
4189 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4190 The following command creates snapshots named
4194 and all of its descendent file systems.
4195 Each snapshot is mounted on demand in the
4197 directory at the root of its file system.
4198 The second command destroys the newly created snapshots.
4200 # zfs snapshot -r pool/home@yesterday
4201 # zfs destroy -r pool/home@yesterday
4203 .It Sy Example 4 No Disabling and Enabling File System Compression
4204 The following command disables the
4206 property for all file systems under
4208 The next command explicitly enables
4211 .Em pool/home/anne .
4213 # zfs set compression=off pool/home
4214 # zfs set compression=on pool/home/anne
4216 .It Sy Example 5 No Listing ZFS Datasets
4217 The following command lists all active file systems and volumes in the system.
4218 Snapshots are displayed if the
4226 for more information on pool properties.
4229 NAME USED AVAIL REFER MOUNTPOINT
4230 pool 450K 457G 18K /pool
4231 pool/home 315K 457G 21K /export/home
4232 pool/home/anne 18K 457G 18K /export/home/anne
4233 pool/home/bob 276K 457G 276K /export/home/bob
4235 .It Sy Example 6 No Setting a Quota on a ZFS File System
4236 The following command sets a quota of 50 Gbytes for
4239 # zfs set quota=50G pool/home/bob
4241 .It Sy Example 7 No Listing ZFS Properties
4242 The following command lists all properties for
4245 # zfs get all pool/home/bob
4246 NAME PROPERTY VALUE SOURCE
4247 pool/home/bob type filesystem -
4248 pool/home/bob creation Tue Jul 21 15:53 2009 -
4249 pool/home/bob used 21K -
4250 pool/home/bob available 20.0G -
4251 pool/home/bob referenced 21K -
4252 pool/home/bob compressratio 1.00x -
4253 pool/home/bob mounted yes -
4254 pool/home/bob quota 20G local
4255 pool/home/bob reservation none default
4256 pool/home/bob recordsize 128K default
4257 pool/home/bob mountpoint /pool/home/bob default
4258 pool/home/bob sharenfs off default
4259 pool/home/bob checksum on default
4260 pool/home/bob compression on local
4261 pool/home/bob atime on default
4262 pool/home/bob devices on default
4263 pool/home/bob exec on default
4264 pool/home/bob setuid on default
4265 pool/home/bob readonly off default
4266 pool/home/bob zoned off default
4267 pool/home/bob snapdir hidden default
4268 pool/home/bob acltype off default
4269 pool/home/bob aclinherit restricted default
4270 pool/home/bob canmount on default
4271 pool/home/bob xattr on default
4272 pool/home/bob copies 1 default
4273 pool/home/bob version 4 -
4274 pool/home/bob utf8only off -
4275 pool/home/bob normalization none -
4276 pool/home/bob casesensitivity sensitive -
4277 pool/home/bob vscan off default
4278 pool/home/bob nbmand off default
4279 pool/home/bob sharesmb off default
4280 pool/home/bob refquota none default
4281 pool/home/bob refreservation none default
4282 pool/home/bob primarycache all default
4283 pool/home/bob secondarycache all default
4284 pool/home/bob usedbysnapshots 0 -
4285 pool/home/bob usedbydataset 21K -
4286 pool/home/bob usedbychildren 0 -
4287 pool/home/bob usedbyrefreservation 0 -
4290 The following command gets a single property value.
4292 # zfs get -H -o value compression pool/home/bob
4295 The following command lists all properties with local settings for
4298 # zfs get -r -s local -o name,property,value all pool/home/bob
4300 pool/home/bob quota 20G
4301 pool/home/bob compression on
4303 .It Sy Example 8 No Rolling Back a ZFS File System
4304 The following command reverts the contents of
4306 to the snapshot named
4308 deleting all intermediate snapshots.
4310 # zfs rollback -r pool/home/anne@yesterday
4312 .It Sy Example 9 No Creating a ZFS Clone
4313 The following command creates a writable file system whose initial contents are
4315 .Em pool/home/bob@yesterday .
4317 # zfs clone pool/home/bob@yesterday pool/clone
4319 .It Sy Example 10 No Promoting a ZFS Clone
4320 The following commands illustrate how to test out changes to a file system, and
4321 then replace the original file system with the changed one, using clones, clone
4322 promotion, and renaming:
4324 # zfs create pool/project/production
4325 populate /pool/project/production with data
4326 # zfs snapshot pool/project/production@today
4327 # zfs clone pool/project/production@today pool/project/beta
4328 make changes to /pool/project/beta and test them
4329 # zfs promote pool/project/beta
4330 # zfs rename pool/project/production pool/project/legacy
4331 # zfs rename pool/project/beta pool/project/production
4332 once the legacy version is no longer needed, it can be destroyed
4333 # zfs destroy pool/project/legacy
4335 .It Sy Example 11 No Inheriting ZFS Properties
4336 The following command causes
4342 property from their parent.
4344 # zfs inherit checksum pool/home/bob pool/home/anne
4346 .It Sy Example 12 No Remotely Replicating ZFS Data
4347 The following commands send a full stream and then an incremental stream to a
4348 remote machine, restoring them into
4349 .Em poolB/received/fs@a
4351 .Em poolB/received/fs@b ,
4354 must contain the file system
4355 .Em poolB/received ,
4356 and must not initially contain
4357 .Em poolB/received/fs .
4359 # zfs send pool/fs@a | \e
4360 ssh host zfs receive poolB/received/fs@a
4361 # zfs send -i a pool/fs@b | \e
4362 ssh host zfs receive poolB/received/fs
4364 .It Sy Example 13 No Using the zfs receive -d Option
4365 The following command sends a full stream of
4366 .Em poolA/fsA/fsB@snap
4367 to a remote machine, receiving it into
4368 .Em poolB/received/fsA/fsB@snap .
4371 portion of the received snapshot's name is determined from the name of the sent
4374 must contain the file system
4375 .Em poolB/received .
4377 .Em poolB/received/fsA
4378 does not exist, it is created as an empty file system.
4380 # zfs send poolA/fsA/fsB@snap | \e
4381 ssh host zfs receive -d poolB/received
4383 .It Sy Example 14 No Setting User Properties
4384 The following example sets the user-defined
4385 .Sy com.example:department
4386 property for a dataset.
4388 # zfs set com.example:department=12345 tank/accounting
4390 .It Sy Example 15 No Performing a Rolling Snapshot
4391 The following example shows how to maintain a history of snapshots with a
4392 consistent naming scheme.
4393 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4394 renames the remaining snapshots, and then creates a new snapshot, as follows:
4396 # zfs destroy -r pool/users@7daysago
4397 # zfs rename -r pool/users@6daysago @7daysago
4398 # zfs rename -r pool/users@5daysago @6daysago
4399 # zfs rename -r pool/users@yesterday @5daysago
4400 # zfs rename -r pool/users@yesterday @4daysago
4401 # zfs rename -r pool/users@yesterday @3daysago
4402 # zfs rename -r pool/users@yesterday @2daysago
4403 # zfs rename -r pool/users@today @yesterday
4404 # zfs snapshot -r pool/users@today
4406 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4407 The following commands show how to set
4409 property options to enable
4413 addresses and to enable root access for system
4419 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4424 for host name resolution, specify the fully qualified hostname.
4425 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4426 The following example shows how to set permissions so that user
4428 can create, destroy, mount, and take snapshots on
4434 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4435 # zfs allow tank/cindys
4436 ---- Permissions on tank/cindys --------------------------------------
4437 Local+Descendent permissions:
4438 user cindys create,destroy,mount,snapshot
4443 mount point permission is set to 755 by default, user
4445 will be unable to mount file systems under
4447 Add an ACE similar to the following syntax to provide mount point access:
4449 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4451 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4452 The following example shows how to grant anyone in the group
4454 to create file systems in
4456 This syntax also allows staff members to destroy their own file systems, but not
4457 destroy anyone else's file system.
4462 # zfs allow staff create,mount tank/users
4463 # zfs allow -c destroy tank/users
4464 # zfs allow tank/users
4465 ---- Permissions on tank/users ---------------------------------------
4468 Local+Descendent permissions:
4469 group staff create,mount
4471 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4472 The following example shows how to define and grant a permission set on the
4479 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4480 # zfs allow staff @pset tank/users
4481 # zfs allow tank/users
4482 ---- Permissions on tank/users ---------------------------------------
4484 @pset create,destroy,mount,snapshot
4485 Local+Descendent permissions:
4488 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4489 The following example shows to grant the ability to set quotas and reservations
4497 # zfs allow cindys quota,reservation users/home
4498 # zfs allow users/home
4499 ---- Permissions on users/home ---------------------------------------
4500 Local+Descendent permissions:
4501 user cindys quota,reservation
4502 cindys% zfs set quota=10G users/home/marks
4503 cindys% zfs get quota users/home/marks
4504 NAME PROPERTY VALUE SOURCE
4505 users/home/marks quota 10G local
4507 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4508 The following example shows how to remove the snapshot permission from the
4517 # zfs unallow staff snapshot tank/users
4518 # zfs allow tank/users
4519 ---- Permissions on tank/users ---------------------------------------
4521 @pset create,destroy,mount,snapshot
4522 Local+Descendent permissions:
4525 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4526 The following example shows how to see what has changed between a prior
4527 snapshot of a ZFS dataset and its current state.
4530 option is used to indicate type information for the files affected.
4532 # zfs diff -F tank/test@before tank/test
4534 M F /tank/test/linked (+1)
4535 R F /tank/test/oldname -> /tank/test/newname
4536 - F /tank/test/deleted
4537 + F /tank/test/created
4538 M F /tank/test/modified
4540 .It Sy Example 23 No Creating a bookmark
4541 The following example create a bookmark to a snapshot. This bookmark
4542 can then be used instead of snapshot in send streams.
4544 # zfs bookmark rpool@snapshot rpool#bookmark
4546 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4547 The following example show how to share SMB filesystem through ZFS. Note that
4548 that a user and his/her password must be given.
4550 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4551 -o user=workgroup/turbo,password=obrut,uid=1000
4555 .Em /etc/samba/smb.conf
4556 configuration required:
4558 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4559 communicate with Samba. This is the default behavior for most Linux
4562 Samba must be able to authenticate a user. This can be done in a number of
4563 ways, depending on if using the system password file, LDAP or the Samba
4564 specific smbpasswd file. How to do this is outside the scope of this manual.
4567 man page for more information.
4570 .Sy USERSHARE section
4573 man page for all configuration options in case you need to modify any options
4574 to the share afterwards. Do note that any changes done with the
4576 command will be undone if the share is ever unshared (such as at a reboot etc).
4578 .Sh INTERFACE STABILITY
projects / mirror_zfs.git / blob