4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
22 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
23 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
24 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
25 .\" Copyright (c) 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 2019 Richard Laager. All rights reserved.
30 .\" Copyright 2018 Nexenta Systems, Inc.
31 .\" Copyright 2018 Joyent, Inc.
38 .Nd configures ZFS file systems
45 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
52 .Fl V Ar size Ar volume
56 .Ar filesystem Ns | Ns Ar volume
60 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
61 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
64 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
68 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
69 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
77 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
78 .Ar snapshot Ar filesystem Ns | Ns Ar volume
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
86 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
90 .Ar filesystem Ns | Ns Ar volume
91 .Ar filesystem Ns | Ns Ar volume
95 .Ar snapshot Ar snapshot
98 .Op Fl r Ns | Ns Fl d Ar depth
100 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
101 .Oo Fl s Ar property Oc Ns ...
102 .Oo Fl S Ar property Oc Ns ...
103 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
104 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
107 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
108 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
111 .Op Fl r Ns | Ns Fl d Ar depth
113 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
114 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
115 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
116 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
117 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ...
121 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
131 .Fl a | Ar filesystem
135 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
136 .Oo Fl s Ar field Oc Ns ...
137 .Oo Fl S Ar field Oc Ns ...
138 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
139 .Ar filesystem Ns | Ns Ar snapshot
143 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
144 .Oo Fl s Ar field Oc Ns ...
145 .Oo Fl S Ar field Oc Ns ...
146 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
147 .Ar filesystem Ns | Ns Ar snapshot
151 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
152 .Oo Fl s Ar field Oc Ns ...
153 .Oo Fl S Ar field Oc Ns ...
154 .Ar filesystem Ns | Ns Ar snapshot
157 .Oo Fl d Ns | Ns Fl r Ns Oc
158 .Ar file Ns | Ns Ar directory Ns ...
163 .Ar file Ns | Ns Ar directory Ns ...
168 .Oo Fl d Ns | Ns Fl r Ns Oc
170 .Ar file Ns | Ns Ar directory Ns ...
175 .Ar file Ns | Ns Ar directory Ns ...
182 .Fl a | Ar filesystem
186 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
189 .Fl a | Ar filesystem
192 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
195 .Ar snapshot bookmark
199 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
204 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
205 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
209 .Fl t Ar receive_resume_token
213 .Op Fl o Sy origin Ns = Ns Ar snapshot
214 .Op Fl o Ar property Ns = Ns Ar value
216 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
220 .Op Fl d Ns | Ns Fl e
221 .Op Fl o Sy origin Ns = Ns Ar snapshot
222 .Op Fl o Ar property Ns = Ns Ar value
228 .Ar filesystem Ns | Ns Ar volume
231 .Ar filesystem Ns | Ns Ar volume
235 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
236 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
237 .Ar setname Oc Ns ...
238 .Ar filesystem Ns | Ns Ar volume
242 .Fl e Ns | Ns Sy everyone
243 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
244 .Ar setname Oc Ns ...
245 .Ar filesystem Ns | Ns Ar volume
249 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
250 .Ar setname Oc Ns ...
251 .Ar filesystem Ns | Ns Ar volume
254 .Fl s No @ Ns Ar setname
255 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
256 .Ar setname Oc Ns ...
257 .Ar filesystem Ns | Ns Ar volume
261 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
262 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
263 .Ar setname Oc Ns ... Oc
264 .Ar filesystem Ns | Ns Ar volume
268 .Fl e Ns | Ns Sy everyone
269 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
270 .Ar setname Oc Ns ... Oc
271 .Ar filesystem Ns | Ns Ar volume
276 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
277 .Ar setname Oc Ns ... Oc
278 .Ar filesystem Ns | Ns Ar volume
282 .Fl s @ Ns Ar setname
283 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
284 .Ar setname Oc Ns ... Oc
285 .Ar filesystem Ns | Ns Ar volume
289 .Ar tag Ar snapshot Ns ...
297 .Ar tag Ar snapshot Ns ...
301 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
305 .Op Fl t Ar instruction-limit
306 .Op Fl m Ar memory-limit
312 .Op Fl L Ar keylocation
313 .Fl a | Ar filesystem
317 .Fl a | Ar filesystem
321 .Op Fl o Ar keylocation Ns = Ns Ar value
322 .Op Fl o Ar keyformat Ns = Ns Ar value
323 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
335 command configures ZFS datasets within a ZFS storage pool, as described in
337 A dataset is identified by a unique path within the ZFS namespace.
340 pool/{filesystem,volume,snapshot}
343 where the maximum length of a dataset name is
346 and the maximum amount of nesting allowed in a path is 50 levels deep.
348 A dataset can be one of the following:
349 .Bl -tag -width "file system"
351 A ZFS dataset of type
353 can be mounted within the standard system namespace and behaves like other file
355 While ZFS file systems are designed to be POSIX compliant, known issues exist
356 that prevent compliance in some cases.
357 Applications that depend on standards conformance might fail due to non-standard
358 behavior when checking file system free space.
360 A logical volume exported as a raw or block device.
361 This type of dataset should only be used when a block device is required.
362 File systems are typically used in most environments.
364 A read-only version of a file system or volume at a given point in time.
366 .Ar filesystem Ns @ Ns Ar name
368 .Ar volume Ns @ Ns Ar name .
372 but without the hold on on-disk data. It can be used as the source of a send
373 (but not for a receive). It is specified as
374 .Ar filesystem Ns # Ns Ar name
376 .Ar volume Ns # Ns Ar name .
378 .Ss ZFS File System Hierarchy
379 A ZFS storage pool is a logical collection of devices that provide space for
381 A storage pool is also the root of the ZFS file system hierarchy.
383 The root of the pool can be accessed as a file system, such as mounting and
384 unmounting, taking snapshots, and setting properties.
385 The physical storage characteristics, however, are managed by the
391 for more information on creating and administering pools.
393 A snapshot is a read-only copy of a file system or volume.
394 Snapshots can be created extremely quickly, and initially consume no additional
395 space within the pool.
396 As data within the active dataset changes, the snapshot consumes more data than
397 would otherwise be shared with the active dataset.
399 Snapshots can have arbitrary names.
400 Snapshots of volumes can be cloned or rolled back, visibility is determined
403 property of the parent volume.
405 File system snapshots can be accessed under the
407 directory in the root of the file system.
408 Snapshots are automatically mounted on demand and may be unmounted at regular
410 The visibility of the
412 directory can be controlled by the
416 A bookmark is like a snapshot, a read-only copy of a file system or volume.
417 Bookmarks can be created extremely quickly, compared to snapshots, and they
418 consume no additional space within the pool. Bookmarks can also have arbitrary
419 names, much like snapshots.
421 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
422 way. From a storage standpoint a bookmark just provides a way to reference
423 when a snapshot was created as a distinct object. Bookmarks are initially
424 tied to a snapshot, not the filesystem or volume, and they will survive if the
425 snapshot itself is destroyed. Since they are very light weight there's little
426 incentive to destroy them.
428 A clone is a writable volume or file system whose initial contents are the same
430 As with snapshots, creating a clone is nearly instantaneous, and initially
431 consumes no additional space.
433 Clones can only be created from a snapshot.
434 When a snapshot is cloned, it creates an implicit dependency between the parent
436 Even though the clone is created somewhere else in the dataset hierarchy, the
437 original snapshot cannot be destroyed as long as a clone exists.
440 property exposes this dependency, and the
442 command lists any such dependencies, if they exist.
444 The clone parent-child dependency relationship can be reversed by using the
449 file system to become a clone of the specified file system, which makes it
450 possible to destroy the file system that the clone was created from.
452 Creating a ZFS file system is a simple operation, so the number of file systems
453 per system is likely to be numerous.
454 To cope with this, ZFS automatically manages mounting and unmounting file
455 systems without the need to edit the
458 All automatically managed file systems are mounted by ZFS at boot time.
460 By default, file systems are mounted under
464 is the name of the file system in the ZFS namespace.
465 Directories are created and destroyed as needed.
467 A file system can also have a mount point set in the
470 This directory is created as needed, and ZFS automatically mounts the file
472 .Nm zfs Cm mount Fl a
479 property can be inherited, so if
485 automatically inherits a mount point of
486 .Pa /export/stuff/user .
492 prevents the file system from being mounted.
494 If needed, ZFS file systems can also be managed with traditional tools
500 If a file system's mount point is set to
502 ZFS makes no attempt to manage the file system, and the administrator is
503 responsible for mounting and unmounting the file system. Because pools must
504 be imported before a legacy mount can succeed, administrators should ensure
505 that legacy mounts are only attempted after the zpool import process
506 finishes at boot time. For example, on machines using systemd, the mount
509 .Nm x-systemd.requires=zfs-import.target
511 will ensure that the zfs-import completes before systemd attempts mounting
512 the filesystem. See systemd.mount(5) for details.
514 Deduplication is the process for removing redundant data at the block level,
515 reducing the total amount of data stored. If a file system has the
517 property enabled, duplicate data blocks are removed synchronously. The result
518 is that only unique data is stored and common components are shared among files.
520 Deduplicating data is a very resource-intensive operation. It is generally
521 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
522 you enable deduplication. Calculating the exact requirement depends heavily
523 on the type of data stored in the pool.
525 Enabling deduplication on an improperly-designed system can result in
526 performance issues (slow IO and administrative operations). It can potentially
527 lead to problems importing a pool due to memory exhaustion. Deduplication
528 can consume significant processing power (CPU) and memory as well as generate
531 Before creating a pool with deduplication enabled, ensure that you have planned
532 your hardware requirements appropriately and implemented appropriate recovery
533 practices, such as regular backups. As an alternative to deduplication
536 as a less resource-intensive alternative.
537 .Ss Native Properties
538 Properties are divided into two types, native properties and user-defined
543 Native properties either export internal statistics or control ZFS behavior.
544 In addition, native properties are either editable or read-only.
545 User properties have no effect on ZFS behavior, but you can use them to annotate
546 datasets in a way that is meaningful in your environment.
547 For more information about user properties, see the
551 Every dataset has a set of properties that export statistics about the dataset
552 as well as control various behaviors.
553 Properties are inherited from the parent unless overridden by the child.
554 Some properties apply only to certain types of datasets
555 .Pq file systems, volumes, or snapshots .
557 The values of numeric properties can be specified using human-readable suffixes
567 The following are all valid
570 .Li 1536M, 1.5g, 1.50GB .
572 The values of non-numeric properties are case sensitive and must be lowercase,
579 The following native properties consist of read-only statistics about the
581 These properties can be neither set, nor inherited.
582 Native properties apply to all dataset types unless otherwise noted.
583 .Bl -tag -width "usedbyrefreservation"
585 The amount of space available to the dataset and all its children, assuming that
586 there is no other activity in the pool.
587 Because space is shared within a pool, availability can be limited by any number
588 of factors, including physical pool size, quotas, reservations, or other
589 datasets within the pool.
591 This property can also be referred to by its shortened column name,
594 For non-snapshots, the compression ratio achieved for the
596 space of this dataset, expressed as a multiplier.
599 property includes descendant datasets, and, for clones, does not include the
600 space shared with the origin snapshot.
606 Compression can be turned on by running:
607 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
611 The transaction group (txg) in which the dataset was created. Bookmarks have
614 as the snapshot they are initially tied to. This property is suitable for
615 ordering a list of snapshots, e.g. for incremental send and receive.
617 The time this dataset was created.
619 For snapshots, this property is a comma-separated list of filesystems or volumes
620 which are clones of this snapshot.
623 property is this snapshot.
626 property is not empty, then this snapshot can not be destroyed
633 The roles of origin and clone can be swapped by promoting the clone with the
639 if the snapshot has been marked for deferred destroy by using the
640 .Nm zfs Cm destroy Fl d
642 Otherwise, the property is
644 .It Sy encryptionroot
645 For encrypted datasets, indicates where the dataset is currently inheriting its
646 encryption key from. Loading or unloading a key for the
648 will implicitly load / unload the key for any inheriting datasets (see
651 .Nm zfs Cm unload-key
653 Clones will always share an
654 encryption key with their origin. See the
657 .It Sy filesystem_count
658 The total number of filesystems and volumes that exist under this location in
660 This value is only available when a
662 has been set somewhere in the tree under which the dataset resides.
664 Indicates if an encryption key is currently loaded into ZFS. The possible
673 .Nm zfs Cm unload-key .
675 The 64 bit GUID of this dataset or bookmark which does not change over its
676 entire lifetime. When a snapshot is sent to another pool, the received
677 snapshot has the same GUID. Thus, the
679 is suitable to identify a snapshot across pools.
680 .It Sy logicalreferenced
681 The amount of space that is
683 accessible by this dataset.
687 The logical space ignores the effect of the
691 properties, giving a quantity closer to the amount of data that applications
693 However, it does include space consumed by metadata.
695 This property can also be referred to by its shortened column name,
698 The amount of space that is
700 consumed by this dataset and all its descendents.
704 The logical space ignores the effect of the
708 properties, giving a quantity closer to the amount of data that applications
710 However, it does include space consumed by metadata.
712 This property can also be referred to by its shortened column name,
715 For file systems, indicates whether the file system is currently mounted.
716 This property can be either
721 A unique identifier for this dataset within the pool. Unlike the dataset's
725 of a dataset is not transferred to other pools when the snapshot is copied
726 with a send/receive operation.
729 can be reused (for a new datatset) after the dataset is deleted.
731 For cloned file systems or volumes, the snapshot from which the clone was
736 .It Sy receive_resume_token
737 For filesystems or volumes which have saved partially-completed state from
739 this opaque token can be provided to
741 to resume and complete the
744 The amount of data that is accessible by this dataset, which may or may not be
745 shared with other datasets in the pool.
746 When a snapshot or clone is created, it initially references the same amount of
747 space as the file system or snapshot it was created from, since its contents are
750 This property can also be referred to by its shortened column name,
752 .It Sy refcompressratio
753 The compression ratio achieved for the
755 space of this dataset, expressed as a multiplier.
759 .It Sy snapshot_count
760 The total number of snapshots that exist under this location in the dataset
762 This value is only available when a
764 has been set somewhere in the tree under which the dataset resides.
772 The amount of space consumed by this dataset and all its descendents.
773 This is the value that is checked against this dataset's quota and reservation.
774 The space used does not include this dataset's reservation, but does take into
775 account the reservations of any descendent datasets.
776 The amount of space that a dataset consumes from its parent, as well as the
777 amount of space that is freed if this dataset is recursively destroyed, is the
778 greater of its space used and its reservation.
780 The used space of a snapshot
785 is space that is referenced exclusively by this snapshot.
786 If this snapshot is destroyed, the amount of
789 Space that is shared by multiple snapshots isn't accounted for in this metric.
790 When a snapshot is destroyed, space that was previously shared with this
791 snapshot can become unique to snapshots adjacent to it, thus changing the used
792 space of those snapshots.
793 The used space of the latest snapshot can also be affected by changes in the
797 space of a snapshot is a subset of the
799 space of the snapshot.
801 The amount of space used, available, or referenced does not take into account
803 Pending changes are generally accounted for within a few seconds.
804 Committing a change to a disk using
808 does not necessarily guarantee that the space usage information is updated
813 properties decompose the
815 properties into the various reasons that space is used.
818 .Sy usedbychildren No +
819 .Sy usedbydataset No +
820 .Sy usedbyrefreservation No +
821 .Sy usedbysnapshots .
822 These properties are only available for datasets created on
826 .It Sy usedbychildren
827 The amount of space used by children of this dataset, which would be freed if
828 all the dataset's children were destroyed.
830 The amount of space used by this dataset itself, which would be freed if the
831 dataset were destroyed
832 .Po after first removing any
834 and destroying any necessary snapshots or descendents
836 .It Sy usedbyrefreservation
837 The amount of space used by a
839 set on this dataset, which would be freed if the
842 .It Sy usedbysnapshots
843 The amount of space consumed by snapshots of this dataset.
844 In particular, it is the amount of space that would be freed if all of this
845 dataset's snapshots were destroyed.
846 Note that this is not simply the sum of the snapshots'
848 properties because space can be shared by multiple snapshots.
849 .It Sy userused Ns @ Ns Em user
850 The amount of space consumed by the specified user in this dataset.
851 Space is charged to the owner of each file, as displayed by
853 The amount of space charged is displayed by
859 subcommand for more information.
861 Unprivileged users can access only their own space usage.
862 The root user, or a user who has been granted the
866 can access everyone's usage.
869 .Sy userused Ns @ Ns Em ...
870 properties are not displayed by
871 .Nm zfs Cm get Sy all .
872 The user's name must be appended after the @ symbol, using one of the following
874 .Bl -bullet -width ""
888 .Sy joe.smith@mydomain
897 Files created on Linux always have POSIX owners.
898 .It Sy userobjused Ns @ Ns Em user
901 property is similar to
903 but instead it counts the number of objects consumed by a user. This property
904 counts all objects allocated on behalf of the user, it may differ from the
905 results of system tools such as
910 is set on a file system additional objects will be created per-file to store
911 extended attributes. These additional objects are reflected in the
913 value and are counted against the user's
915 When a file system is configured to use
917 no additional internal objects are normally required.
919 This property is set to the number of user holds on this snapshot.
920 User holds are set by using the
923 .It Sy groupused Ns @ Ns Em group
924 The amount of space consumed by the specified group in this dataset.
925 Space is charged to the group of each file, as displayed by
928 .Sy userused Ns @ Ns Em user
929 property for more information.
931 Unprivileged users can only access their own groups' space usage.
932 The root user, or a user who has been granted the
936 can access all groups' usage.
937 .It Sy groupobjused Ns @ Ns Em group
938 The number of objects consumed by the specified group in this dataset.
939 Multiple objects may be charged to the group for each file when extended
940 attributes are in use. See the
941 .Sy userobjused Ns @ Ns Em user
942 property for more information.
944 Unprivileged users can only access their own groups' space usage.
945 The root user, or a user who has been granted the
949 can access all groups' usage.
950 .It Sy projectused Ns @ Ns Em project
951 The amount of space consumed by the specified project in this dataset. Project
952 is identified via the project identifier (ID) that is object-based numeral
953 attribute. An object can inherit the project ID from its parent object (if the
954 parent has the flag of inherit project ID that can be set and changed via
957 .Nm zfs project Fl s )
958 when being created. The privileged user can set and change object's project
963 anytime. Space is charged to the project of each file, as displayed by
968 .Sy userused Ns @ Ns Em user
969 property for more information.
971 The root user, or a user who has been granted the
975 can access all projects' usage.
976 .It Sy projectobjused Ns @ Ns Em project
981 but instead it counts the number of objects consumed by project. When the
984 is set on a fileset, ZFS will create additional objects per-file to store
985 extended attributes. These additional objects are reflected in the
987 value and are counted against the project's
988 .Sy projectobjquota .
989 When a filesystem is configured to use
991 no additional internal objects are required. See the
992 .Sy userobjused Ns @ Ns Em user
993 property for more information.
995 The root user, or a user who has been granted the
999 can access all projects' objects usage.
1001 For volumes, specifies the block size of the volume.
1004 cannot be changed once the volume has been written, so it should be set at
1005 volume creation time.
1008 for volumes is 8 Kbytes.
1009 Any power of 2 from 512 bytes to 128 Kbytes is valid.
1011 This property can also be referred to by its shortened column name,
1016 by this dataset, that was written since the previous snapshot
1017 .Pq i.e. that is not referenced by the previous snapshot .
1018 .It Sy written Ns @ Ns Em snapshot
1021 space written to this dataset since the specified snapshot.
1022 This is the space that is referenced by this dataset but was not referenced by
1023 the specified snapshot.
1027 may be specified as a short snapshot name
1028 .Po just the part after the
1031 in which case it will be interpreted as a snapshot in the same filesystem as
1035 may be a full snapshot name
1036 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1037 which for clones may be a snapshot in the origin's filesystem
1038 .Pq or the origin of the origin's filesystem, etc.
1041 The following native properties can be used to change the behavior of a ZFS
1045 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1046 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1048 Controls how ACEs are inherited when files and directories are created.
1049 .Bl -tag -width "passthrough-x"
1051 does not inherit any ACEs.
1053 only inherits inheritable ACEs that specify
1057 default, removes the
1061 permissions when the ACE is inherited.
1063 inherits all inheritable ACEs without any modifications.
1064 .It Sy passthrough-x
1072 ACEs inherit the execute permission only if the file creation mode also requests
1076 When the property value is set to
1078 files are created with a mode determined by the inheritable ACEs.
1079 If no inheritable ACEs exist that affect the mode, then the mode is set in
1080 accordance to the requested mode from the application.
1084 property does not apply to POSIX ACLs.
1085 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1086 Controls whether ACLs are enabled and if so what type of ACL to use.
1087 .Bl -tag -width "posixacl"
1089 default, when a file system has the
1091 property set to off then ACLs are disabled.
1096 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
1097 not functional on other platforms. POSIX ACLs are stored as an extended
1098 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1102 To obtain the best performance when setting
1104 users are strongly encouraged to set the
1106 property. This will result in the POSIX ACL being stored more efficiently on
1107 disk. But as a consequence, all new extended attributes will only be
1108 accessible from OpenZFS implementations which support the
1112 property for more details.
1113 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1114 Controls whether the access time for files is updated when they are read.
1115 Turning this property off avoids producing write traffic when reading files and
1116 can result in significant performance gains, though it might confuse mailers
1117 and other similar utilities. The values
1121 are equivalent to the
1125 mount options. The default value is
1130 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1131 If this property is set to
1133 the file system cannot be mounted, and is ignored by
1134 .Nm zfs Cm mount Fl a .
1135 Setting this property to
1137 is similar to setting the
1141 except that the dataset still has a normal
1143 property, which can be inherited.
1144 Setting this property to
1146 allows datasets to be used solely as a mechanism to inherit properties.
1147 One example of setting
1148 .Sy canmount Ns = Ns Sy off
1149 is to have two datasets with the same
1151 so that the children of both datasets appear in the same directory, but might
1152 have different inherited characteristics.
1156 a dataset can only be mounted and unmounted explicitly.
1157 The dataset is not mounted automatically when the dataset is created or
1158 imported, nor is it mounted by the
1159 .Nm zfs Cm mount Fl a
1160 command or unmounted by the
1161 .Nm zfs Cm unmount Fl a
1164 This property is not inherited.
1166 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1167 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1168 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1170 Controls the checksum used to verify data integrity.
1171 The default value is
1173 which automatically selects an appropriate algorithm
1176 but this may change in future releases
1180 disables integrity checking on user data.
1183 not only disables integrity but also disables maintaining parity for user data.
1184 This setting is used internally by a dump device residing on a RAID-Z pool and
1185 should not be used by any other dataset.
1186 Disabling checksums is
1188 a recommended practice.
1195 checksum algorithms require enabling the appropriate features on the pool.
1196 These pool features are not supported by GRUB and must not be used on the
1197 pool if GRUB needs to access the pool (e.g. for /boot).
1200 .Xr zpool-features 5
1201 for more information on these algorithms.
1203 Changing this property affects only newly-written data.
1205 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1206 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1208 Controls the compression algorithm used for this dataset.
1210 Setting compression to
1212 indicates that the current default compression algorithm should be used.
1213 The default balances compression and decompression speed, with compression ratio
1214 and is expected to work well on a wide variety of workloads.
1215 Unlike all other settings for this property,
1217 does not select a fixed compression type.
1218 As new compression algorithms are added to ZFS and enabled on a pool, the
1219 default compression algorithm may change.
1220 The current default compression algorithm is either
1229 compression algorithm is a high-performance replacement for the
1232 It features significantly faster compression and decompression, as well as a
1233 moderately higher compression ratio than
1235 but can only be used on pools with the
1240 .Xr zpool-features 5
1241 for details on ZFS feature flags and the
1247 compression algorithm is optimized for performance while providing decent data
1252 compression algorithm uses the same compression as the
1257 level by using the value
1261 is an integer from 1
1264 .Pq best compression ratio .
1269 .Po which is also the default for
1275 compression algorithm compresses runs of zeros.
1277 This property can also be referred to by its shortened column name
1279 Changing this property affects only newly-written data.
1281 When any setting except
1283 is selected, compression will explicitly check for blocks consisting of only
1284 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
1285 a hole and not compressed using the indicated compression algorithm.
1287 Any block being compressed must be no larger than 7/8 of its original size
1288 after compression, otherwise the compression will not be considered worthwhile
1289 and the block saved uncompressed. Note that when the logical block is less than
1290 8 times the disk sector size this effectively reduces the necessary compression
1291 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
1292 or less of their original size.
1294 .Sy context Ns = Ns Sy none Ns | Ns
1295 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1297 This flag sets the SELinux context for all files in the file system under
1298 a mount point for that file system. See
1300 for more information.
1302 .Sy fscontext Ns = Ns Sy none Ns | Ns
1303 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1305 This flag sets the SELinux context for the file system file system being
1308 for more information.
1310 .Sy defcontext Ns = Ns Sy none Ns | Ns
1311 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1313 This flag sets the SELinux default context for unlabeled files. See
1315 for more information.
1317 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1318 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1320 This flag sets the SELinux context for the root inode of the file system. See
1322 for more information.
1323 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1324 Controls the number of copies of data stored for this dataset.
1325 These copies are in addition to any redundancy provided by the pool, for
1326 example, mirroring or RAID-Z.
1327 The copies are stored on different disks, if possible.
1328 The space used by multiple copies is charged to the associated file and dataset,
1331 property and counting against quotas and reservations.
1333 Changing this property only affects newly-written data.
1334 Therefore, set this property at file system creation time by using the
1335 .Fl o Sy copies Ns = Ns Ar N
1338 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1340 create, for example a two-disk striped pool and set
1342 on some datasets thinking you have setup redundancy for them. When a disk
1343 fails you will not be able to import the pool and will have lost all of your
1346 Encrypted datasets may not have
1347 .Sy copies Ns = Ns Em 3
1348 since the implementation stores some encryption metadata where the third copy
1350 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1351 Controls whether device nodes can be opened on this file system.
1352 The default value is
1358 are equivalent to the
1364 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1365 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1368 Configures deduplication for a dataset. The default value is
1370 The default deduplication checksum is
1372 (this may change in the future). When
1374 is enabled, the checksum defined here overrides the
1376 property. Setting the value to
1378 has the same effect as the setting
1383 ZFS will do a byte-to-byte comparsion in case of two blocks having the same
1384 signature to make sure the block contents are identical. Specifying
1386 is mandatory for the
1390 Unless necessary, deduplication should NOT be enabled on a system. See
1394 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1395 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1397 Specifies a compatibility mode or literal value for the size of dnodes in the
1398 file system. The default value is
1400 Setting this property to a value other than
1402 requires the large_dnode pool feature to be enabled.
1408 if the dataset uses the
1410 property setting and the workload makes heavy use of extended attributes. This
1411 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1412 servers, for example. Literal values are supported for cases where the optimal
1413 size is known in advance and for performance testing.
1419 if you need to receive a send stream of this dataset on a pool that doesn't
1420 enable the large_dnode feature, or if you need to import this pool on a system
1421 that doesn't support the large_dnode feature.
1423 This property can also be referred to by its shortened column name,
1426 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1427 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1428 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1430 Controls the encryption cipher suite (block cipher, key length, and mode) used
1431 for this dataset. Requires the
1433 feature to be enabled on the pool.
1436 to be set at dataset creation time.
1439 .Sy encryption Ns = Ns Sy on
1440 when creating a dataset indicates that the default encryption suite will be
1441 selected, which is currently
1443 In order to provide consistent data protection, encryption must be specified at
1444 dataset creation time and it cannot be changed afterwards.
1446 For more details and caveats about encryption see the
1449 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1450 Controls what format the user's encryption key will be provided as. This
1451 property is only set when the dataset is encrypted.
1453 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1454 encryption suite) and must be randomly generated. A raw key can be generated
1455 with the following command:
1457 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1460 Passphrases must be between 8 and 512 bytes long and will be processed through
1461 PBKDF2 before being used (see the
1463 property). Even though the
1464 encryption suite cannot be changed after dataset creation, the keyformat can be
1466 .Nm zfs Cm change-key .
1468 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1470 Controls where the user's encryption key will be loaded from by default for
1474 .Nm zfs Cm mount Cm -l .
1475 This property is only set for encrypted datasets which are encryption roots. If
1476 unspecified, the default is
1479 Even though the encryption suite cannot be changed after dataset creation, the
1480 keylocation can be with either
1483 .Nm zfs Cm change-key .
1486 is selected ZFS will ask for the key at the command prompt when it is required
1487 to access the encrypted data (see
1489 for details). This setting will also allow the key to be passed in via STDIN,
1490 but users should be careful not to place keys which should be kept secret on
1491 the command line. If a file URI is selected, the key will be loaded from the
1492 specified absolute file path.
1493 .It Sy pbkdf2iters Ns = Ns Ar iterations
1494 Controls the number of PBKDF2 iterations that a
1496 encryption key should be run through when processing it into an encryption key.
1497 This property is only defined when encryption is enabled and a keyformat of
1499 is selected. The goal of PBKDF2 is to significantly increase the
1500 computational difficulty needed to brute force a user's passphrase. This is
1501 accomplished by forcing the attacker to run each passphrase through a
1502 computationally expensive hashing function many times before they arrive at the
1503 resulting key. A user who actually knows the passphrase will only have to pay
1504 this cost once. As CPUs become better at processing, this number should be
1505 raised to ensure that a brute force attack is still not possible. The current
1510 This property may be changed with
1511 .Nm zfs Cm change-key .
1512 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1513 Controls whether processes can be executed from within this file system.
1514 The default value is
1520 are equivalent to the
1525 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1526 Limits the number of filesystems and volumes that can exist under this point in
1528 The limit is not enforced if the user is allowed to change the limit.
1530 .Sy filesystem_limit
1533 a descendent of a filesystem that already has a
1534 .Sy filesystem_limit
1535 does not override the ancestor's
1536 .Sy filesystem_limit ,
1537 but rather imposes an additional limit.
1538 This feature must be enabled to be used
1540 .Xr zpool-features 5
1542 .It Sy special_small_blocks Ns = Ns Em size
1543 This value represents the threshold block size for including small file
1544 blocks into the special allocation class. Blocks smaller than or equal to this
1545 value will be assigned to the special allocation class while greater blocks
1546 will be assigned to the regular class. Valid values are zero or a power of two
1547 from 512B up to 128K. The default size is 0 which means no small file blocks
1548 will be allocated in the special class.
1550 Before setting this property, a special class vdev must be added to the
1553 for more details on the special allocation class.
1554 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1555 Controls the mount point used for this file system.
1558 section for more information on how this property is used.
1562 property is changed for a file system, the file system and any children that
1563 inherit the mount point are unmounted.
1566 then they remain unmounted.
1567 Otherwise, they are automatically remounted in the new location if the property
1572 or if they were mounted before the property was changed.
1573 In addition, any shared file systems are unshared and shared in the new
1575 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1576 Controls whether the file system should be mounted with
1578 .Pq Non Blocking mandatory locks .
1579 This is used for SMB clients.
1580 Changes to this property only take effect when the file system is umounted and
1584 for more information on
1586 mounts. This property is not used on Linux.
1587 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1588 Allow mounting on a busy directory or a directory which already contains
1589 files or directories. This is the default mount behavior for Linux file systems.
1590 For consistency with OpenZFS on other platforms overlay mounts are
1594 to enable overlay mounts.
1595 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1596 Controls what is cached in the primary cache
1598 If this property is set to
1600 then both user data and metadata is cached.
1601 If this property is set to
1603 then neither user data nor metadata is cached.
1604 If this property is set to
1606 then only metadata is cached.
1607 The default value is
1609 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1610 Limits the amount of space a dataset and its descendents can consume.
1611 This property enforces a hard limit on the amount of space used.
1612 This includes all space consumed by descendents, including file systems and
1614 Setting a quota on a descendent of a dataset that already has a quota does not
1615 override the ancestor's quota, but rather imposes an additional limit.
1617 Quotas cannot be set on volumes, as the
1619 property acts as an implicit quota.
1620 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1621 Limits the number of snapshots that can be created on a dataset and its
1625 on a descendent of a dataset that already has a
1627 does not override the ancestor's
1628 .Sy snapshot_limit ,
1629 but rather imposes an additional limit.
1630 The limit is not enforced if the user is allowed to change the limit.
1631 For example, this means that recursive snapshots taken from the global zone are
1632 counted against each delegated dataset within a zone.
1633 This feature must be enabled to be used
1635 .Xr zpool-features 5
1637 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1638 Limits the amount of space consumed by the specified user.
1639 User space consumption is identified by the
1640 .Sy userspace@ Ns Em user
1643 Enforcement of user quotas may be delayed by several seconds.
1644 This delay means that a user might exceed their quota before the system notices
1645 that they are over quota and begins to refuse additional writes with the
1649 .Nm zfs Cm userspace
1650 subcommand for more information.
1652 Unprivileged users can only access their own groups' space usage.
1653 The root user, or a user who has been granted the
1657 can get and set everyone's quota.
1659 This property is not available on volumes, on file systems before version 4, or
1660 on pools before version 15.
1662 .Sy userquota@ Ns Em ...
1663 properties are not displayed by
1664 .Nm zfs Cm get Sy all .
1665 The user's name must be appended after the
1667 symbol, using one of the following forms:
1675 .Em POSIX numeric ID
1682 .Sy joe.smith@mydomain
1691 Files created on Linux always have POSIX owners.
1692 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1697 but it limits the number of objects a user can create. Please refer to
1699 for more information about how objects are counted.
1700 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1701 Limits the amount of space consumed by the specified group.
1702 Group space consumption is identified by the
1703 .Sy groupused@ Ns Em group
1706 Unprivileged users can access only their own groups' space usage.
1707 The root user, or a user who has been granted the
1711 can get and set all groups' quotas.
1712 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1717 but it limits number of objects a group can consume. Please refer to
1719 for more information about how objects are counted.
1720 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1721 Limits the amount of space consumed by the specified project. Project
1722 space consumption is identified by the
1723 .Sy projectused@ Ns Em project
1724 property. Please refer to
1726 for more information about how project is identified and set/changed.
1728 The root user, or a user who has been granted the
1732 can access all projects' quota.
1733 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1738 but it limits number of objects a project can consume. Please refer to
1740 for more information about how objects are counted.
1741 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1742 Controls whether this dataset can be modified.
1743 The default value is
1749 are equivalent to the
1755 This property can also be referred to by its shortened column name,
1757 .It Sy recordsize Ns = Ns Em size
1758 Specifies a suggested block size for files in the file system.
1759 This property is designed solely for use with database workloads that access
1760 files in fixed-size records.
1761 ZFS automatically tunes block sizes according to internal algorithms optimized
1762 for typical access patterns.
1764 For databases that create very large files but access them in small random
1765 chunks, these algorithms may be suboptimal.
1768 greater than or equal to the record size of the database can result in
1769 significant performance gains.
1770 Use of this property for general purpose file systems is strongly discouraged,
1771 and may adversely affect performance.
1773 The size specified must be a power of two greater than or equal to 512 and less
1774 than or equal to 128 Kbytes.
1777 feature is enabled on the pool, the size may be up to 1 Mbyte.
1779 .Xr zpool-features 5
1780 for details on ZFS feature flags.
1782 Changing the file system's
1784 affects only files created afterward; existing files are unaffected.
1786 This property can also be referred to by its shortened column name,
1788 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1789 Controls what types of metadata are stored redundantly.
1790 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1791 the amount of user data lost is limited.
1792 This extra copy is in addition to any redundancy provided at the pool level
1793 .Pq e.g. by mirroring or RAID-Z ,
1794 and is in addition to an extra copy specified by the
1797 .Pq up to a total of 3 copies .
1798 For example if the pool is mirrored,
1799 .Sy copies Ns = Ns 2 ,
1801 .Sy redundant_metadata Ns = Ns Sy most ,
1802 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1807 ZFS stores an extra copy of all metadata.
1808 If a single on-disk block is corrupt, at worst a single block of user data
1817 ZFS stores an extra copy of most types of metadata.
1818 This can improve performance of random writes, because less metadata must be
1820 In practice, at worst about 100 blocks
1825 of user data can be lost if a single on-disk block is corrupt.
1826 The exact behavior of which metadata blocks are stored redundantly may change in
1829 The default value is
1831 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1832 Limits the amount of space a dataset can consume.
1833 This property enforces a hard limit on the amount of space used.
1834 This hard limit does not include space used by descendents, including file
1835 systems and snapshots.
1836 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1837 The minimum amount of space guaranteed to a dataset, not including its
1839 When the amount of space used is below this value, the dataset is treated as if
1840 it were taking up the amount of space specified by
1841 .Sy refreservation .
1844 reservation is accounted for in the parent datasets' space used, and counts
1845 against the parent datasets' quotas and reservations.
1849 is set, a snapshot is only allowed if there is enough free pool space outside of
1850 this reservation to accommodate the current number of
1852 bytes in the dataset.
1858 a volume is thick provisioned
1862 .Sy refreservation Ns = Ns Sy auto
1863 is only supported on volumes.
1867 .Sx Native Properties
1868 section for more information about sparse volumes.
1870 This property can also be referred to by its shortened column name,
1872 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1873 Controls the manner in which the access time is updated when
1875 is set. Turning this property on causes the access time to be updated relative
1876 to the modify or change time. Access time is only updated if the previous
1877 access time was earlier than the current modify or change time or if the
1878 existing access time hasn't been updated within the past 24 hours. The default
1885 are equivalent to the
1890 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1891 The minimum amount of space guaranteed to a dataset and its descendants.
1892 When the amount of space used is below this value, the dataset is treated as if
1893 it were taking up the amount of space specified by its reservation.
1894 Reservations are accounted for in the parent datasets' space used, and count
1895 against the parent datasets' quotas and reservations.
1897 This property can also be referred to by its shortened column name,
1899 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1900 Controls what is cached in the secondary cache
1902 If this property is set to
1904 then both user data and metadata is cached.
1905 If this property is set to
1907 then neither user data nor metadata is cached.
1908 If this property is set to
1910 then only metadata is cached.
1911 The default value is
1913 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1914 Controls whether the setuid bit is respected for the file system.
1915 The default value is
1921 are equivalent to the
1926 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1927 Controls whether the file system is shared by using
1928 .Sy Samba USERSHARES
1929 and what options are to be used. Otherwise, the file system is automatically
1930 shared and unshared with the
1934 commands. If the property is set to on, the
1936 command is invoked to create a
1939 Because SMB shares requires a resource name, a unique resource name is
1940 constructed from the dataset name. The constructed name is a copy of the
1941 dataset name except that the characters in the dataset name, which would be
1942 invalid in the resource name, are replaced with underscore (_) characters.
1943 Linux does not currently support additional options which might be available
1950 the file systems are unshared.
1952 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1953 stands for "full permissions", ie. read and write permissions) and no guest
1954 access (which means Samba must be able to authenticate a real user, system
1955 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1956 additional access control (disallow specific user specific access etc) must
1957 be done on the underlying file system.
1958 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1959 Controls whether the file system is shared via NFS, and what options are to be
1961 A file system with a
1967 command and entries in the
1970 Otherwise, the file system is automatically shared and unshared with the
1975 If the property is set to
1977 the dataset is shared using the default options:
1979 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1983 for the meaning of the default options. Otherwise, the
1985 command is invoked with options equivalent to the contents of this property.
1989 property is changed for a dataset, the dataset and any children inheriting the
1990 property are re-shared with the new options, only if the property was previously
1992 or if they were shared before the property was changed.
1993 If the new property is
1995 the file systems are unshared.
1996 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1997 Provide a hint to ZFS about handling of synchronous requests in this dataset.
2003 ZFS will use pool log devices
2005 to handle the requests at low latency.
2010 ZFS will not use configured pool log devices.
2011 ZFS will instead optimize synchronous operations for global pool throughput and
2012 efficient use of resources.
2013 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
2014 Controls whether the volume snapshot devices under
2015 .Em /dev/zvol/<pool>
2016 are hidden or visible. The default value is
2018 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
2019 Controls whether the
2021 directory is hidden or visible in the root of the file system as discussed in
2025 The default value is
2027 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
2028 Controls the behavior of synchronous requests
2029 .Pq e.g. fsync, O_DSYNC .
2033 specified behavior of ensuring all synchronous requests are written to stable
2034 storage and all devices are flushed to ensure data is not cached by device
2036 .Pq this is the default .
2038 causes every file system transaction to be written and flushed before its
2039 system call returns.
2040 This has a large performance penalty.
2042 disables synchronous requests.
2043 File system transactions are only committed to stable storage periodically.
2044 This option will give the highest performance.
2045 However, it is very dangerous as ZFS would be ignoring the synchronous
2046 transaction demands of applications such as databases or NFS.
2047 Administrators should only use this option when the risks are understood.
2048 .It Sy version Ns = Ns Em N Ns | Ns Sy current
2049 The on-disk version of this file system, which is independent of the pool
2051 This property can only be set to later supported versions.
2055 .It Sy volsize Ns = Ns Em size
2056 For volumes, specifies the logical size of the volume.
2057 By default, creating a volume establishes a reservation of equal size.
2058 For storage pools with a version number of 9 or higher, a
2063 are reflected in an equivalent change to the reservation
2069 can only be set to a multiple of
2073 The reservation is kept equal to the volume's logical size to prevent unexpected
2074 behavior for consumers.
2075 Without the reservation, the volume could run out of space, resulting in
2076 undefined behavior or data corruption, depending on how the volume is used.
2077 These effects can also occur when the volume size is changed while it is in use
2078 .Pq particularly when shrinking the size .
2079 Extreme care should be used when adjusting the volume size.
2081 Though not recommended, a
2084 .Qq thin provisioned
2086 can be created by specifying the
2089 .Nm zfs Cm create Fl V
2090 command, or by changing the value of the
2095 property on pool version 8 or earlier
2097 after the volume has been created.
2100 is a volume where the value of
2102 is less than the size of the volume plus the space required to store its
2104 Consequently, writes to a sparse volume can fail with
2106 when the pool is low on space.
2107 For a sparse volume, changes to
2109 are not reflected in the
2111 A volume that is not sparse is said to be
2112 .Qq thick provisioned .
2113 A sparse volume can become thick provisioned by setting
2117 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2118 This property specifies how volumes should be exposed to the OS.
2121 exposes volumes as fully fledged block devices, providing maximal
2122 functionality. The value
2124 is just an alias for
2126 and is kept for compatibility.
2129 hides its partitions.
2130 Volumes with property set to
2132 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
2133 that can be suitable for backup purposes.
2136 means that volumes exposition is controlled by system-wide tunable
2143 are encoded as 1, 2 and 3 respectively.
2144 The default values is
2146 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2147 Controls whether regular files should be scanned for viruses when a file is
2149 In addition to enabling this property, the virus scan service must also be
2150 enabled for virus scanning to occur.
2151 The default value is
2153 This property is not used on Linux.
2154 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2155 Controls whether extended attributes are enabled for this file system. Two
2156 styles of extended attributes are supported either directory based or system
2159 The default value of
2161 enables directory based extended attributes. This style of extended attribute
2162 imposes no practical limit on either the size or number of attributes which
2163 can be set on a file. Although under Linux the
2167 system calls limit the maximum size to 64K. This is the most compatible
2168 style of extended attribute and is supported by all OpenZFS implementations.
2170 System attribute based xattrs can be enabled by setting the value to
2172 The key advantage of this type of xattr is improved performance. Storing
2173 extended attributes as system attributes significantly decreases the amount of
2174 disk IO required. Up to 64K of data may be stored per-file in the space
2175 reserved for system attributes. If there is not enough space available for
2176 an extended attribute then it will be automatically written as a directory
2177 based xattr. System attribute based extended attributes are not accessible
2178 on platforms which do not support the
2182 The use of system attribute based xattrs is strongly encouraged for users of
2183 SELinux or POSIX ACLs. Both of these features heavily rely of extended
2184 attributes and benefit significantly from the reduced access time.
2190 are equivalent to the
2195 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2196 Controls whether the dataset is managed from a non-global zone. Zones are a
2197 Solaris feature and are not relevant on Linux. The default value is
2201 The following three properties cannot be changed after the file system is
2202 created, and therefore, should be set when the file system is created.
2203 If the properties are not set with the
2207 commands, these properties are inherited from the parent dataset.
2208 If the parent dataset lacks these properties due to having been created prior to
2209 these features being supported, the new file system will have the default values
2210 for these properties.
2213 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2214 .Sy insensitive Ns | Ns Sy mixed
2216 Indicates whether the file name matching algorithm used by the file system
2217 should be case-sensitive, case-insensitive, or allow a combination of both
2219 The default value for the
2227 file systems have case-sensitive file names.
2233 property indicates that the file system can support requests for both
2234 case-sensitive and case-insensitive matching behavior.
2235 Currently, case-insensitive matching behavior on a file system that supports
2236 mixed behavior is limited to the SMB server product.
2237 For more information about the
2239 value behavior, see the "ZFS Administration Guide".
2241 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2242 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2244 Indicates whether the file system should perform a
2246 normalization of file names whenever two file names are compared, and which
2247 normalization algorithm should be used.
2248 File names are always stored unmodified, names are normalized as part of any
2250 If this property is set to a legal value other than
2254 property was left unspecified, the
2256 property is automatically set to
2258 The default value of the
2262 This property cannot be changed after the file system is created.
2263 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2264 Indicates whether the file system should reject file names that include
2265 characters that are not present in the
2268 If this property is explicitly set to
2270 the normalization property must either not be explicitly set or be set to
2272 The default value for the
2276 This property cannot be changed after the file system is created.
2280 .Sy casesensitivity ,
2284 properties are also new permissions that can be assigned to non-privileged users
2285 by using the ZFS delegated administration feature.
2286 .Ss "Temporary Mount Point Properties"
2287 When a file system is mounted, either through
2289 for legacy mounts or the
2291 command for normal file systems, its mount options are set according to its
2293 The correlation between properties and mount options is as follows:
2295 PROPERTY MOUNT OPTION
2297 canmount auto/noauto
2301 relatime relatime/norelatime
2306 In addition, these options can be set on a per-mount basis using the
2308 option, without affecting the property that is stored on disk.
2309 The values specified on the command line override the values stored in the
2313 option is an alias for
2314 .Sy nodevices Ns \&, Ns Sy nosetuid .
2315 These properties are reported as
2320 If the properties are changed while the dataset is mounted, the new setting
2321 overrides any temporary settings.
2322 .Ss "User Properties"
2323 In addition to the standard native properties, ZFS supports arbitrary user
2325 User properties have no effect on ZFS behavior, but applications or
2326 administrators can use them to annotate datasets
2327 .Pq file systems, volumes, and snapshots .
2329 User property names must contain a colon
2331 character to distinguish them from native properties.
2332 They may contain lowercase letters, numbers, and the following punctuation
2341 The expected convention is that the property name is divided into two portions
2343 .Em module Ns \&: Ns Em property ,
2344 but this namespace is not enforced by ZFS.
2345 User property names can be at most 256 characters, and cannot begin with a dash
2348 When making programmatic use of user properties, it is strongly suggested to use
2353 component of property names to reduce the chance that two
2354 independently-developed packages use the same property name for different
2357 The values of user properties are arbitrary strings, are always inherited, and
2358 are never validated.
2359 All of the commands that operate on properties
2360 .Po Nm zfs Cm list ,
2365 can be used to manipulate both native properties and user properties.
2368 command to clear a user property.
2369 If the property is not defined in any parent dataset, it is removed entirely.
2370 Property values are limited to 8192 bytes.
2371 .Ss ZFS Volumes as Swap
2372 ZFS volumes may be used as swap devices. After creating the volume with the
2373 .Nm zfs Cm create Fl V
2374 command set up and enable the swap area using the
2378 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2379 configuration is not supported.
2383 feature allows for the creation of encrypted filesystems and volumes. ZFS
2384 will encrypt file and zvol data, file attributes, ACLs, permission bits,
2385 directory listings, FUID mappings, and
2389 data. ZFS will not encrypt metadata related to the pool structure, including
2390 dataset and snapshot names, dataset hierarchy, properties, file size, file
2391 holes, and deduplication tables (though the deduplicated data itself is
2394 Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase)
2395 does not require re-encrypting the entire dataset. Datasets can be scrubbed,
2396 resilvered, renamed, and deleted without the encryption keys being loaded (see the
2398 subcommand for more info on key loading).
2400 Creating an encrypted dataset requires specifying the
2404 properties at creation time, along with an optional
2408 After entering an encryption key, the
2409 created dataset will become an encryption root. Any descendant datasets will
2410 inherit their encryption key from the encryption root by default, meaning that
2411 loading, unloading, or changing the key for the encryption root will implicitly
2412 do the same for all inheriting datasets. If this inheritance is not desired,
2415 when creating the child dataset or use
2416 .Nm zfs Cm change-key
2417 to break an existing relationship, creating a new encryption root on the child.
2418 Note that the child's
2420 may match that of the parent while still creating a new encryption root, and
2423 property alone does not create a new encryption root; this would simply use a
2424 different cipher suite with the same key as its encryption root. The one
2425 exception is that clones will always use their origin's encryption key.
2426 As a result of this exception, some encryption-related properties (namely
2432 do not inherit like other ZFS properties and instead use the value determined
2433 by their encryption root. Encryption root inheritance can be tracked via the
2438 Encryption changes the behavior of a few ZFS
2439 operations. Encryption is applied after compression so compression ratios are
2440 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2441 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2442 the encryption suite, which provides additional protection against maliciously
2443 altered data. Deduplication is still possible with encryption enabled but for
2444 security, datasets will only dedup against themselves, their snapshots, and
2447 There are a few limitations on encrypted datasets. Encrypted data cannot be
2450 feature. Encrypted datasets may not have
2451 .Sy copies Ns = Ns Em 3
2452 since the implementation stores some encryption metadata where the third copy
2453 would normally be. Since compression is applied before encryption datasets may
2454 be vulnerable to a CRIME-like attack if applications accessing the data allow
2455 for it. Deduplication with encryption will leak information about which blocks
2456 are equivalent in a dataset and will incur an extra CPU cost per block written.
2458 All subcommands that modify state are logged persistently to the pool in their
2462 Displays a help message.
2474 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2477 Creates a new ZFS file system.
2478 The file system is automatically mounted according to the
2480 property inherited from the parent.
2481 .Bl -tag -width "-o"
2482 .It Fl o Ar property Ns = Ns Ar value
2483 Sets the specified property as if the command
2484 .Nm zfs Cm set Ar property Ns = Ns Ar value
2485 was invoked at the same time the dataset was created.
2486 Any editable ZFS property can also be set at creation time.
2489 options can be specified.
2490 An error results if the same property is specified in multiple
2494 Creates all the non-existing parent datasets.
2495 Datasets created in this manner are automatically mounted according to the
2497 property inherited from their parent.
2498 Any property specified on the command line using the
2501 If the target filesystem already exists, the operation completes successfully.
2507 .Op Fl b Ar blocksize
2508 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2509 .Fl V Ar size Ar volume
2511 Creates a volume of the given size.
2512 The volume is exported as a block device in
2513 .Pa /dev/zvol/path ,
2516 is the name of the volume in the ZFS namespace.
2517 The size represents the logical size as exported by the device.
2518 By default, a reservation of equal size is created.
2521 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2522 has an integral number of blocks regardless of
2524 .Bl -tag -width "-b"
2525 .It Fl b Ar blocksize
2527 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2528 If this option is specified in conjunction with
2529 .Fl o Sy volblocksize ,
2530 the resulting behavior is undefined.
2531 .It Fl o Ar property Ns = Ns Ar value
2532 Sets the specified property as if the
2533 .Nm zfs Cm set Ar property Ns = Ns Ar value
2534 command was invoked at the same time the dataset was created.
2535 Any editable ZFS property can also be set at creation time.
2538 options can be specified.
2539 An error results if the same property is specified in multiple
2543 Creates all the non-existing parent datasets.
2544 Datasets created in this manner are automatically mounted according to the
2546 property inherited from their parent.
2547 Any property specified on the command line using the
2550 If the target filesystem already exists, the operation completes successfully.
2552 Creates a sparse volume with no reservation.
2556 .Sx Native Properties
2557 section for more information about sparse volumes.
2563 .Ar filesystem Ns | Ns Ar volume
2565 Destroys the given dataset.
2566 By default, the command unshares any file systems that are currently shared,
2567 unmounts any file systems that are currently mounted, and refuses to destroy a
2568 dataset that has active dependents
2569 .Pq children or clones .
2570 .Bl -tag -width "-R"
2572 Recursively destroy all dependents, including cloned file systems outside the
2575 Force an unmount of any file systems using the
2578 This option has no effect on non-file systems or unmounted file systems.
2583 No data will be deleted.
2584 This is useful in conjunction with the
2588 flags to determine what data would be deleted.
2590 Print machine-parsable verbose information about the deleted data.
2592 Recursively destroy all children.
2594 Print verbose information about the deleted data.
2597 Extreme care should be taken when applying either the
2601 options, as they can destroy large portions of a pool and cause unexpected
2602 behavior for mounted file systems in use.
2607 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2608 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2610 The given snapshots are destroyed immediately if and only if the
2614 option would have destroyed it.
2615 Such immediate destruction would occur, for example, if the snapshot had no
2616 clones and the user-initiated reference count were zero.
2618 If a snapshot does not qualify for immediate destruction, it is marked for
2620 In this state, it exists as a usable, visible snapshot until both of the
2621 preconditions listed above are met, at which point it is destroyed.
2623 An inclusive range of snapshots may be specified by separating the first and
2624 last snapshots with a percent sign.
2625 The first and/or last snapshots may be left blank, in which case the
2626 filesystem's oldest or newest snapshot will be implied.
2629 .Pq or ranges of snapshots
2630 of the same filesystem or volume may be specified in a comma-separated list of
2632 Only the snapshot's short name
2633 .Po the part after the
2636 should be specified when using a range or comma-separated list to identify
2638 .Bl -tag -width "-R"
2640 Recursively destroy all clones of these snapshots, including the clones,
2641 snapshots, and children.
2642 If this flag is specified, the
2644 flag will have no effect.
2646 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2647 deferred destruction.
2652 No data will be deleted.
2653 This is useful in conjunction with the
2657 flags to determine what data would be deleted.
2659 Print machine-parsable verbose information about the deleted data.
2662 .Pq or mark for deferred deletion
2663 all snapshots with this name in descendent file systems.
2665 Print verbose information about the deleted data.
2667 Extreme care should be taken when applying either the
2671 options, as they can destroy large portions of a pool and cause unexpected
2672 behavior for mounted file systems in use.
2677 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2679 The given bookmark is destroyed.
2684 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2685 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2687 Creates snapshots with the given names.
2688 All previous modifications by successful system calls to the file system are
2689 part of the snapshots.
2690 Snapshots are taken atomically, so that all snapshots correspond to the same
2693 can be used as an alias for
2694 .Nm zfs Cm snapshot.
2697 section for details.
2698 .Bl -tag -width "-o"
2699 .It Fl o Ar property Ns = Ns Ar value
2700 Sets the specified property; see
2704 Recursively create snapshots of all descendent datasets
2712 Roll back the given dataset to a previous snapshot.
2713 When a dataset is rolled back, all data that has changed since the snapshot is
2714 discarded, and the dataset reverts to the state at the time of the snapshot.
2715 By default, the command refuses to roll back to a snapshot other than the most
2717 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2724 options do not recursively destroy the child snapshots of a recursive snapshot.
2725 Only direct snapshots of the specified filesystem are destroyed by either of
2727 To completely roll back a recursive snapshot, you must rollback the individual
2729 .Bl -tag -width "-R"
2731 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2736 option to force an unmount of any clone file systems that are to be destroyed.
2738 Destroy any snapshots and bookmarks more recent than the one specified.
2744 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2745 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2747 Creates a clone of the given snapshot.
2750 section for details.
2751 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2752 as the same type as the original.
2753 .Bl -tag -width "-o"
2754 .It Fl o Ar property Ns = Ns Ar value
2755 Sets the specified property; see
2759 Creates all the non-existing parent datasets.
2760 Datasets created in this manner are automatically mounted according to the
2762 property inherited from their parent.
2763 If the target filesystem or volume already exists, the operation completes
2769 .Ar clone-filesystem
2771 Promotes a clone file system to no longer be dependent on its
2774 This makes it possible to destroy the file system that the clone was created
2776 The clone parent-child dependency relationship is reversed, so that the origin
2777 file system becomes a clone of the specified file system.
2779 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2780 now owned by the promoted clone.
2781 The space they use moves from the origin file system to the promoted clone, so
2782 enough space must be available to accommodate these snapshots.
2783 No new space is consumed by this operation, but the space accounting is
2785 The promoted clone must not have any conflicting snapshot names of its own.
2788 subcommand can be used to rename any conflicting snapshots.
2793 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2794 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2800 .Ar filesystem Ns | Ns Ar volume
2801 .Ar filesystem Ns | Ns Ar volume
2803 Renames the given dataset.
2804 The new target can be located anywhere in the ZFS hierarchy, with the exception
2806 Snapshots can only be renamed within the parent file system or volume.
2807 When renaming a snapshot, the parent file system of the snapshot does not need
2808 to be specified as part of the second argument.
2809 Renamed file systems can inherit new mount points, in which case they are
2810 unmounted and remounted at the new mount point.
2811 .Bl -tag -width "-a"
2813 Force unmount any filesystems that need to be unmounted in the process.
2815 Creates all the nonexistent parent datasets.
2816 Datasets created in this manner are automatically mounted according to the
2818 property inherited from their parent.
2824 .Ar snapshot Ar snapshot
2826 Recursively rename the snapshots of all descendent datasets.
2827 Snapshots are the only dataset that can be renamed recursively.
2831 .Op Fl r Ns | Ns Fl d Ar depth
2833 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2834 .Oo Fl s Ar property Oc Ns ...
2835 .Oo Fl S Ar property Oc Ns ...
2836 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2837 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2839 Lists the property information for the given datasets in tabular form.
2840 If specified, you can list property information by the absolute pathname or the
2842 By default, all file systems and volumes are displayed.
2843 Snapshots are displayed if the
2850 The following fields are displayed:
2851 .Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns .
2852 .Bl -tag -width "-H"
2854 Used for scripting mode.
2855 Do not print headers and separate fields by a single tab instead of arbitrary
2857 .It Fl S Ar property
2860 option, but sorts by property in descending order.
2862 Recursively display any children of the dataset, limiting the recursion to
2868 will display only the dataset and its direct children.
2869 .It Fl o Ar property
2870 A comma-separated list of properties to display.
2871 The property must be:
2874 One of the properties described in the
2875 .Sx Native Properties
2882 to display the dataset name
2886 to display space usage properties on file systems and volumes.
2887 This is a shortcut for specifying
2888 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2889 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2890 .Sy filesystem Ns \&, Ns Sy volume
2894 Display numbers in parsable
2898 Recursively display any children of the dataset on the command line.
2899 .It Fl s Ar property
2900 A property for sorting the output by column in ascending order based on the
2901 value of the property.
2902 The property must be one of the properties described in the
2904 section or the value
2906 to sort by the dataset name.
2907 Multiple properties can be specified at one time using multiple
2912 options are evaluated from left to right in decreasing order of importance.
2913 The following is a list of sorting criteria:
2916 Numeric types sort in numeric order.
2918 String types sort in alphabetical order.
2920 Types inappropriate for a row sort that row to the literal bottom, regardless of
2921 the specified ordering.
2924 If no sorting options are specified the existing behavior of
2928 A comma-separated list of types to display, where
2937 For example, specifying
2939 displays only snapshots.
2944 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2945 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2947 Sets the property or list of properties to the given value(s) for each dataset.
2948 Only some properties can be edited.
2951 section for more information on what properties can be set and acceptable
2953 Numeric values can be specified as exact values, or in a human-readable form
2955 .Sy B , K , M , G , T , P , E , Z
2956 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2957 or zettabytes, respectively
2959 User properties can be set on snapshots.
2960 For more information, see the
2966 .Op Fl r Ns | Ns Fl d Ar depth
2968 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2969 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2970 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2971 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2972 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ...
2974 Displays properties for the given datasets.
2975 If no datasets are specified, then the command displays properties for all
2976 datasets on the system.
2977 For each property, the following columns are displayed:
2980 property Property name
2981 value Property value
2982 source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP,
2983 \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP).
2986 All columns are displayed by default, though this can be controlled by using the
2989 This command takes a comma-separated list of properties as described in the
2990 .Sx Native Properties
2997 can be used to display all properties that apply to the given dataset's type
2998 .Pq filesystem, volume, snapshot, or bookmark .
2999 .Bl -tag -width "-H"
3001 Display output in a form more easily parsed by scripts.
3002 Any headers are omitted, and fields are explicitly separated by a single tab
3003 instead of an arbitrary amount of space.
3005 Recursively display any children of the dataset, limiting the recursion to
3009 will display only the dataset and its direct children.
3011 A comma-separated list of columns to display.
3012 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
3013 is the default value.
3015 Display numbers in parsable
3019 Recursively display properties for any children.
3021 A comma-separated list of sources to display.
3022 Those properties coming from a source other than those in this list are ignored.
3023 Each source must be one of the following:
3031 The default value is all sources.
3033 A comma-separated list of types to display, where
3047 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3049 Clears the specified property, causing it to be inherited from an ancestor,
3050 restored to default if no ancestor has the property set, or with the
3052 option reverted to the received value if one exists.
3055 section for a listing of default values, and details on which properties can be
3057 .Bl -tag -width "-r"
3059 Recursively inherit the given property for all children.
3061 Revert the property to the received value if one exists; otherwise operate as
3064 option was not specified.
3070 Displays a list of file systems that are not the most recent version.
3076 Displays a list of currently supported file system versions.
3082 .Fl a | Ar filesystem
3084 Upgrades file systems to a new on-disk version.
3085 Once this is done, the file systems will no longer be accessible on systems
3086 running older versions of the software.
3088 streams generated from new snapshots of these file systems cannot be accessed on
3089 systems running older versions of the software.
3091 In general, the file system version is independent of the pool version.
3094 for information on the
3095 .Nm zpool Cm upgrade
3098 In some cases, the file system version and the pool version are interrelated and
3099 the pool version must be upgraded before the file system version can be
3101 .Bl -tag -width "-V"
3103 Upgrade to the specified
3107 flag is not specified, this command upgrades to the most recent version.
3109 option can only be used to increase the version number, and only up to the most
3110 recent version supported by this software.
3112 Upgrade all file systems on all imported pools.
3114 Upgrade the specified file system.
3116 Upgrade the specified file system and all descendent file systems.
3122 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3123 .Oo Fl s Ar field Oc Ns ...
3124 .Oo Fl S Ar field Oc Ns ...
3125 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3126 .Ar filesystem Ns | Ns Ar snapshot
3128 Displays space consumed by, and quotas on, each user in the specified filesystem
3130 This corresponds to the
3131 .Sy userused@ Ns Em user ,
3132 .Sy userobjused@ Ns Em user ,
3133 .Sy userquota@ Ns Em user,
3135 .Sy userobjquota@ Ns Em user
3137 .Bl -tag -width "-H"
3139 Do not print headers, use tab-delimited output.
3141 Sort by this field in reverse order.
3145 Translate SID to POSIX ID.
3146 The POSIX ID may be ephemeral if no mapping exists.
3147 Normal POSIX interfaces
3152 perform this translation, so the
3154 option allows the output from
3155 .Nm zfs Cm userspace
3156 to be compared directly with those utilities.
3159 may lead to confusion if some files were created by an SMB user before a
3160 SMB-to-POSIX name mapping was established.
3161 In such a case, some files will be owned by the SMB entity and some by the POSIX
3165 option will report that the POSIX entity has the total usage and quota for both.
3167 Print numeric ID instead of user/group name.
3168 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3169 Display only the specified fields from the following set:
3174 The default is to display all fields.
3180 Sort output by this field.
3185 flags may be specified multiple times to sort first by one field, then by
3188 .Fl s Sy type Fl s Sy name .
3189 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3190 Print only the specified types from the following set:
3197 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3198 The default can be changed to include group types.
3204 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3205 .Oo Fl s Ar field Oc Ns ...
3206 .Oo Fl S Ar field Oc Ns ...
3207 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3208 .Ar filesystem Ns | Ns Ar snapshot
3210 Displays space consumed by, and quotas on, each group in the specified
3211 filesystem or snapshot.
3212 This subcommand is identical to
3213 .Nm zfs Cm userspace ,
3214 except that the default types to display are
3215 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3220 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3221 .Oo Fl s Ar field Oc Ns ...
3222 .Oo Fl S Ar field Oc Ns ...
3223 .Ar filesystem Ns | Ns Ar snapshot
3225 Displays space consumed by, and quotas on, each project in the specified
3226 filesystem or snapshot. This subcommand is identical to
3227 .Nm zfs Cm userspace ,
3228 except that the project identifier is numeral, not name. So need neither
3231 for SID to POSIX ID nor
3239 .Oo Fl d Ns | Ns Fl r Ns Oc
3240 .Ar file Ns | Ns Ar directory Ns ...
3242 List project identifier (ID) and inherit flag of file(s) or directories.
3243 .Bl -tag -width "-d"
3245 Show the directory project ID and inherit flag, not its childrens. It will
3246 overwrite the former specified
3250 Show on subdirectories recursively. It will overwrite the former specified
3259 .Ar file Ns | Ns Ar directory Ns ...
3261 Clear project inherit flag and/or ID on the file(s) or directories.
3262 .Bl -tag -width "-k"
3264 Keep the project ID unchanged. If not specified, the project ID will be reset
3267 Clear on subdirectories recursively.
3274 .Oo Fl d Ns | Ns Fl r Ns Oc
3276 .Ar file Ns | Ns Ar directory Ns ...
3278 Check project ID and inherit flag on the file(s) or directories, report the
3279 entries without project inherit flag or with different project IDs from the
3282 option) value or the target directory's project ID.
3283 .Bl -tag -width "-0"
3285 Print file name with a trailing NUL instead of newline (by default), like
3288 Check the directory project ID and inherit flag, not its childrens. It will
3289 overwrite the former specified
3293 Specify the referenced ID for comparing with the target file(s) or directories'
3294 project IDs. If not specified, the target (top) directory's project ID will be
3295 used as the referenced one.
3297 Check on subdirectories recursively. It will overwrite the former specified
3306 .Ar file Ns | Ns Ar directory Ns ...
3308 .Bl -tag -width "-p"
3309 Set project ID and/or inherit flag on the file(s) or directories.
3311 Set the file(s)' or directories' project ID with the given value.
3313 Set on subdirectories recursively.
3315 Set project inherit flag on the given file(s) or directories. It is usually used
3316 for setup tree quota on the directory target with
3318 option specified together. When setup tree quota, by default the directory's
3319 project ID will be set to all its descendants unless you specify the project
3328 Displays all ZFS file systems currently mounted.
3334 .Fl a | Ar filesystem
3336 Mount ZFS filesystem on a path described by its
3338 property, if the path exists and is empty. If
3342 the filesystem should be instead mounted using
3344 .Bl -tag -width "-O"
3346 Perform an overlay mount. Allows mounting in non-empty
3350 for more information.
3352 Mount all available ZFS file systems.
3353 Invoked automatically as part of the boot process if configured.
3355 Mount the specified filesystem.
3357 An optional, comma-separated list of mount options to use temporarily for the
3358 duration of the mount.
3360 .Sx Temporary Mount Point Properties
3361 section for details.
3363 Load keys for encrypted filesystems as they are being mounted. This is
3364 equivalent to executing
3366 on each encryption root before mounting it. Note that if a filesystem has a
3370 this will cause the terminal to interactively block after asking for the key.
3372 Report mount progress.
3378 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3380 Unmounts currently mounted ZFS file systems.
3381 .Bl -tag -width "-a"
3383 Unmount all available ZFS file systems.
3384 Invoked automatically as part of the shutdown process.
3385 .It Ar filesystem Ns | Ns Ar mountpoint
3386 Unmount the specified filesystem.
3387 The command can also be given a path to a ZFS file system mount point on the
3390 Forcefully unmount the file system, even if it is currently in use.
3395 .Fl a | Ar filesystem
3397 Shares available ZFS file systems.
3398 .Bl -tag -width "-a"
3400 Share all available ZFS file systems.
3401 Invoked automatically as part of the boot process.
3403 Share the specified filesystem according to the
3408 File systems are shared when the
3417 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3419 Unshares currently shared ZFS file systems.
3420 .Bl -tag -width "-a"
3422 Unshare all available ZFS file systems.
3423 Invoked automatically as part of the shutdown process.
3424 .It Ar filesystem Ns | Ns Ar mountpoint
3425 Unshare the specified filesystem.
3426 The command can also be given a path to a ZFS file system shared on the system.
3431 .Ar snapshot bookmark
3433 Creates a bookmark of the given snapshot.
3434 Bookmarks mark the point in time when the snapshot was created, and can be used
3435 as the incremental source for a
3439 This feature must be enabled to be used.
3441 .Xr zpool-features 5
3442 for details on ZFS feature flags and the
3449 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3452 Creates a stream representation of the second
3454 which is written to standard output.
3455 The output can be redirected to a file or to a different system
3456 .Po for example, using
3459 By default, a full stream is generated.
3460 .Bl -tag -width "-D"
3462 Generate a deduplicated stream.
3463 Blocks which would have been sent multiple times in the send stream will only be
3465 The receiving system must also support this feature to receive a deduplicated
3467 This flag can be used regardless of the dataset's
3469 property, but performance will be much better if the filesystem uses a
3470 dedup-capable checksum
3474 .It Fl I Ar snapshot
3475 Generate a stream package that sends all intermediary snapshots from the first
3476 snapshot to the second snapshot.
3480 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3481 The incremental source may be specified as with the
3484 .It Fl L, -large-block
3485 Generate a stream which may contain blocks larger than 128KB.
3486 This flag has no effect if the
3488 pool feature is disabled, or if the
3490 property of this filesystem has never been set above 128KB.
3491 The receiving system must have the
3493 pool feature enabled as well.
3495 .Xr zpool-features 5
3496 for details on ZFS feature flags and the
3500 Print machine-parsable verbose information about the stream package generated.
3501 .It Fl R, -replicate
3502 Generate a replication stream package, which will replicate the specified
3503 file system, and all descendent file systems, up to the named snapshot.
3504 When received, all properties, snapshots, descendent file systems, and clones
3511 flags are used in conjunction with the
3513 flag, an incremental replication stream is generated.
3514 The current values of properties, and current snapshot and file system names are
3515 set when the stream is received.
3518 flag is specified when this stream is received, snapshots and file systems that
3519 do not exist on the sending side are destroyed. If the
3521 flag is used to send encrypted datasets, then
3523 must also be specified.
3525 Generate a more compact stream by using
3527 records for blocks which are stored more compactly on disk by the
3530 This flag has no effect if the
3532 feature is disabled.
3533 The receiving system must have the
3538 feature is active on the sending system, then the receiving system must have
3539 that feature enabled as well. Datasets that are sent with this flag may not be
3540 received as an encrypted dataset, since encrypted datasets cannot use the
3544 .Xr zpool-features 5
3545 for details on ZFS feature flags and the
3549 Sends only received property values whether or not they are overridden by local
3550 settings, but only if the dataset has ever been received. Use this option when
3553 to restore received properties backed up on the sent dataset and to avoid
3554 sending local settings that may have nothing to do with the source dataset,
3555 but only with how the data is backed up.
3556 .It Fl c, -compressed
3557 Generate a more compact stream by using compressed WRITE records for blocks
3558 which are compressed on disk and in memory
3561 property for details
3565 feature is active on the sending system, then the receiving system must have
3566 that feature enabled as well.
3569 feature is enabled on the sending system but the
3571 option is not supplied in conjunction with
3573 then the data will be decompressed before sending so it can be split into
3574 smaller block sizes.
3576 For encrypted datasets, send data exactly as it exists on disk. This allows
3577 backups to be taken even if encryption keys are not currently loaded. The
3578 backup may then be received on an untrusted machine since that machine will
3579 not have the encryption keys to read the protected data or alter it without
3580 being detected. Upon being received, the dataset will have the same encryption
3581 keys as it did on the send side, although the
3583 property will be defaulted to
3585 if not otherwise provided. For unencrypted datasets, this flag will be
3588 Note that if you do not use this flag for sending encrypted datasets, data will
3589 be sent unencrypted and may be re-encrypted with a different encryption key on
3590 the receiving system, which will disable the ability to do a raw send to that
3591 system for incrementals.
3593 Generate a stream package that includes any snapshot holds (created with the
3595 command), and indicating to
3597 that the holds be applied to the dataset on the receiving system.
3598 .It Fl i Ar snapshot
3599 Generate an incremental stream from the first
3601 .Pq the incremental source
3604 .Pq the incremental target .
3605 The incremental source can be specified as the last component of the snapshot
3609 character and following
3611 and it is assumed to be from the same file system as the incremental target.
3613 If the destination is a clone, the source may be the origin snapshot, which must
3616 .Em pool/fs@origin ,
3624 Do not generate any actual send data.
3625 This is useful in conjunction with the
3629 flags to determine what data will be sent.
3630 In this case, the verbose output will be written to standard output
3631 .Po contrast with a non-dry-run, where the stream is written to standard output
3632 and the verbose output goes to standard error
3635 Include the dataset's properties in the stream.
3636 This flag is implicit when
3639 The receiving system must also support this feature. Sends of encrypted datasets
3642 when using this flag.
3644 Print verbose information about the stream package generated.
3645 This information includes a per-second report of how much data has been sent.
3647 The format of the stream is committed.
3648 You will be able to receive your streams on future versions of ZFS.
3654 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3655 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3657 Generate a send stream, which may be of a filesystem, and may be incremental
3659 If the destination is a filesystem or volume, the pool must be read-only, or the
3660 filesystem must not be mounted.
3661 When the stream generated from a filesystem or volume is received, the default
3662 snapshot name will be
3664 .Bl -tag -width "-L"
3665 .It Fl L, -large-block
3666 Generate a stream which may contain blocks larger than 128KB.
3667 This flag has no effect if the
3669 pool feature is disabled, or if the
3671 property of this filesystem has never been set above 128KB.
3672 The receiving system must have the
3674 pool feature enabled as well.
3676 .Xr zpool-features 5
3677 for details on ZFS feature flags and the
3681 Print machine-parsable verbose information about the stream package generated.
3682 .It Fl c, -compressed
3683 Generate a more compact stream by using compressed WRITE records for blocks
3684 which are compressed on disk and in memory
3687 property for details
3691 feature is active on the sending system, then the receiving system must have
3692 that feature enabled as well.
3695 feature is enabled on the sending system but the
3697 option is not supplied in conjunction with
3699 then the data will be decompressed before sending so it can be split into
3700 smaller block sizes.
3702 For encrypted datasets, send data exactly as it exists on disk. This allows
3703 backups to be taken even if encryption keys are not currently loaded. The
3704 backup may then be received on an untrusted machine since that machine will
3705 not have the encryption keys to read the protected data or alter it without
3706 being detected. Upon being received, the dataset will have the same encryption
3707 keys as it did on the send side, although the
3709 property will be defaulted to
3711 if not otherwise provided. For unencrypted datasets, this flag will be
3714 Note that if you do not use this flag for sending encrypted datasets, data will
3715 be sent unencrypted and may be re-encrypted with a different encryption key on
3716 the receiving system, which will disable the ability to do a raw send to that
3717 system for incrementals.
3719 Generate a more compact stream by using
3721 records for blocks which are stored more compactly on disk by the
3724 This flag has no effect if the
3726 feature is disabled.
3727 The receiving system must have the
3732 feature is active on the sending system, then the receiving system must have
3733 that feature enabled as well. Datasets that are sent with this flag may not be
3734 received as an encrypted dataset, since encrypted datasets cannot use the
3738 .Xr zpool-features 5
3739 for details on ZFS feature flags and the
3742 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3743 Generate an incremental send stream.
3744 The incremental source must be an earlier snapshot in the destination's history.
3745 It will commonly be an earlier snapshot in the destination's file system, in
3746 which case it can be specified as the last component of the name
3751 character and following
3754 If the incremental target is a clone, the incremental source can be the origin
3755 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3761 Do not generate any actual send data.
3762 This is useful in conjunction with the
3766 flags to determine what data will be sent.
3767 In this case, the verbose output will be written to standard output
3768 .Po contrast with a non-dry-run, where the stream is written to standard output
3769 and the verbose output goes to standard error
3772 Print verbose information about the stream package generated.
3773 This information includes a per-second report of how much data has been sent.
3780 .Ar receive_resume_token
3782 Creates a send stream which resumes an interrupted receive.
3784 .Ar receive_resume_token
3785 is the value of this property on the filesystem or volume that was being
3787 See the documentation for
3794 .Op Fl o Sy origin Ns = Ns Ar snapshot
3795 .Op Fl o Ar property Ns = Ns Ar value
3796 .Op Fl x Ar property
3797 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3803 .Op Fl d Ns | Ns Fl e
3804 .Op Fl o Sy origin Ns = Ns Ar snapshot
3805 .Op Fl o Ar property Ns = Ns Ar value
3806 .Op Fl x Ar property
3809 Creates a snapshot whose contents are as specified in the stream provided on
3811 If a full stream is received, then a new file system is created as well.
3812 Streams are created using the
3814 subcommand, which by default creates a full stream.
3816 can be used as an alias for
3819 If an incremental stream is received, then the destination file system must
3820 already exist, and its most recent snapshot must match the incremental stream's
3824 the destination device link is destroyed and recreated, which means the
3826 cannot be accessed during the
3830 When a snapshot replication package stream that is generated by using the
3831 .Nm zfs Cm send Fl R
3832 command is received, any snapshots that do not exist on the sending location are
3833 destroyed by using the
3834 .Nm zfs Cm destroy Fl d
3838 .Fl o Em property Ns = Ns Ar value
3841 is specified, it applies to the effective value of the property throughout
3842 the entire subtree of replicated datasets. Effective property values will be
3847 ) on the topmost in the replicated subtree. In descendant datasets, if the
3848 property is set by the send stream, it will be overridden by forcing the
3849 property to be inherited from the top‐most file system. Received properties
3850 are retained in spite of being overridden and may be restored with
3851 .Nm zfs Cm inherit Fl S .
3853 .Fl o Sy origin Ns = Ns Em snapshot
3854 is a special case because, even if
3856 is a read-only property and cannot be set, it's allowed to receive the send
3857 stream as a clone of the given snapshot.
3859 Raw encrypted send streams (created with
3860 .Nm zfs Cm send Fl w
3861 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3862 recompressed by the receive process. Unencrypted streams can be received as
3863 encrypted datasets, either through inheritance or by specifying encryption
3866 options. Note that the
3868 property cannot be overridden to
3870 during a receive. This is because the receive process itself is already using
3871 stdin for the send stream. Instead, the property can be overridden after the
3874 The added security provided by raw sends adds some restrictions to the send
3875 and receive process. ZFS will not allow a mix of raw receives and non-raw
3876 receives. Specifically, any raw incremental receives that are attempted after
3877 a non-raw receive will fail. Non-raw receives do not have this restriction and,
3878 therefore, are always possible. Because of this, it is best practice to always
3879 use either raw sends for their security benefits or non-raw sends for their
3880 flexibility when working with encrypted datasets, but not a combination.
3882 The reason for this restriction stems from the inherent restrictions of the
3883 AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption,
3884 each block of data is encrypted against a randomly generated number known as
3885 the "initialization vector" (IV), which is stored in the filesystem metadata.
3886 This number is required by the encryption algorithms whenever the data is to
3887 be decrypted. Together, all of the IVs provided for all of the blocks in a
3888 given snapshot are collectively called an "IV set". When ZFS performs a raw
3889 send, the IV set is transferred from the source to the destination in the send
3890 stream. When ZFS performs a non-raw send, the data is decrypted by the source
3891 system and re-encrypted by the destination system, creating a snapshot with
3892 effectively the same data, but a different IV set. In order for decryption to
3893 work after a raw send, ZFS must ensure that the IV set used on both the source
3894 and destination side match. When an incremental raw receive is performed on
3895 top of an existing snapshot, ZFS will check to confirm that the "from"
3896 snapshot on both the source and destination were using the same IV set,
3897 ensuring the new IV set is consistent.
3899 The name of the snapshot
3900 .Pq and file system, if a full stream is received
3901 that this subcommand creates depends on the argument type and the use of the
3907 If the argument is a snapshot name, the specified
3910 If the argument is a file system or volume name, a snapshot with the same name
3911 as the sent snapshot is created within the specified
3919 options are specified, the provided target snapshot name is used exactly as
3926 options cause the file system name of the target snapshot to be determined by
3927 appending a portion of the sent snapshot's name to the specified target
3931 option is specified, all but the first element of the sent snapshot's file
3933 .Pq usually the pool name
3934 is used and any required intermediate file systems within the specified one are
3938 option is specified, then only the last element of the sent snapshot's file
3940 .Pq i.e. the name of the source file system itself
3941 is used as the target file system name.
3942 .Bl -tag -width "-F"
3944 Force a rollback of the file system to the most recent snapshot before
3945 performing the receive operation.
3946 If receiving an incremental replication stream
3947 .Po for example, one generated by
3948 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3950 destroy snapshots and file systems that do not exist on the sending side.
3952 Discard the first element of the sent snapshot's file system name, using the
3953 remaining elements to determine the name of the target file system for the new
3954 snapshot as described in the paragraph above.
3956 Discard all but the last element of the sent snapshot's file system name, using
3957 that element to determine the name of the target file system for the new
3958 snapshot as described in the paragraph above.
3960 Skip the receive of holds. There is no effect if holds are not sent.
3962 Do not actually receive the stream.
3963 This can be useful in conjunction with the
3965 option to verify the name the receive operation would use.
3966 .It Fl o Sy origin Ns = Ns Ar snapshot
3967 Forces the stream to be received as a clone of the given snapshot.
3968 If the stream is a full send stream, this will create the filesystem
3969 described by the stream as a clone of the specified snapshot.
3970 Which snapshot was specified will not affect the success or failure of the
3971 receive, as long as the snapshot does exist.
3972 If the stream is an incremental send stream, all the normal verification will be
3974 .It Fl o Em property Ns = Ns Ar value
3975 Sets the specified property as if the command
3976 .Nm zfs Cm set Em property Ns = Ns Ar value
3977 was invoked immediately before the receive. When receiving a stream from
3978 .Nm zfs Cm send Fl R ,
3979 causes the property to be inherited by all descendant datasets, as through
3980 .Nm zfs Cm inherit Em property
3981 was run on any descendant datasets that have this property set on the
3984 Any editable property can be set at receive time. Set-once properties bound
3985 to the received data, such as
3988 .Sy casesensitivity ,
3989 cannot be set at receive time even when the datasets are newly created by
3990 .Nm zfs Cm receive .
3991 Additionally both settable properties
3995 cannot be set at receive time.
3999 option may be specified multiple times, for different properties. An error
4000 results if the same property is specified in multiple
4008 option may also be used to override encryption properties upon initial
4009 receive. This allows unencrypted streams to be received as encrypted datasets.
4010 To cause the received dataset (or root dataset of a recursive stream) to be
4011 received as an encryption root, specify encryption properties in the same
4012 manner as is required for
4017 # zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile
4021 .Op Fl o Ar keylocation Ns = Ns Ar prompt
4022 may not be specified here, since stdin is already being utilized for the send
4023 stream. Once the receive has completed, you can use
4026 to change this setting after the fact. Similarly, you can receive a dataset as
4027 an encrypted child by specifying
4028 .Op Fl x Ar encryption
4029 to force the property to be inherited. Overriding encryption properties (except
4031 .Sy keylocation Ns )
4032 is not possible with raw send streams.
4034 If the receive is interrupted, save the partially received state, rather
4036 Interruption may be due to premature termination of the stream
4037 .Po e.g. due to network failure or failure of the remote system
4038 if the stream is being read over a network connection
4040 a checksum error in the stream, termination of the
4042 process, or unclean shutdown of the system.
4044 The receive can be resumed with a stream generated by
4045 .Nm zfs Cm send Fl t Ar token ,
4049 .Sy receive_resume_token
4050 property of the filesystem or volume which is received into.
4052 To use this flag, the storage pool must have the
4053 .Sy extensible_dataset
4056 .Xr zpool-features 5
4057 for details on ZFS feature flags.
4059 File system that is associated with the received stream is not mounted.
4061 Print verbose information about the stream and the time required to perform the
4063 .It Fl x Em property
4064 Ensures that the effective value of the specified property after the
4065 receive is unaffected by the value of that property in the send stream (if any),
4066 as if the property had been excluded from the send stream.
4068 If the specified property is not present in the send stream, this option does
4071 If a received property needs to be overridden, the effective value will be
4072 set or inherited, depending on whether the property is inheritable or not.
4074 In the case of an incremental update,
4076 leaves any existing local setting or explicit inheritance unchanged.
4080 restrictions (e.g. set-once) apply equally to
4087 .Ar filesystem Ns | Ns Ar volume
4089 Abort an interrupted
4090 .Nm zfs Cm receive Fl s ,
4091 deleting its saved partially received state.
4095 .Ar filesystem Ns | Ns Ar volume
4097 Displays permissions that have been delegated on the specified filesystem or
4099 See the other forms of
4101 for more information.
4103 Delegations are supported under Linux with the exception of
4111 These permissions cannot be delegated because the Linux
4113 command restricts modifications of the global namespace to the root user.
4118 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4119 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4120 .Ar setname Oc Ns ...
4121 .Ar filesystem Ns | Ns Ar volume
4127 .Fl e Ns | Ns Sy everyone
4128 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4129 .Ar setname Oc Ns ...
4130 .Ar filesystem Ns | Ns Ar volume
4132 Delegates ZFS administration permission for the file systems to non-privileged
4134 .Bl -tag -width "-d"
4136 Allow only for the descendent file systems.
4137 .It Fl e Ns | Ns Sy everyone
4138 Specifies that the permissions be delegated to everyone.
4139 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
4140 Explicitly specify that permissions are delegated to the group.
4144 only for the specified file system.
4145 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
4146 Explicitly specify that permissions are delegated to the user.
4147 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4148 Specifies to whom the permissions are delegated.
4149 Multiple entities can be specified as a comma-separated list.
4152 options are specified, then the argument is interpreted preferentially as the
4155 then as a user name, and lastly as a group name.
4156 To specify a user or group named
4163 To specify a group with the same name as a user, use the
4167 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4168 .Ar setname Oc Ns ...
4170 The permissions to delegate.
4171 Multiple permissions may be specified as a comma-separated list.
4172 Permission names are the same as ZFS subcommand and property names.
4173 See the property list below.
4174 Property set names, which begin with
4179 form below for details.
4184 options are specified, or both are, then the permissions are allowed for the
4185 file system or volume, and all of its descendents.
4187 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4189 The following permissions are available:
4192 allow subcommand Must also have the permission that is
4194 clone subcommand Must also have the 'create' ability and
4195 'mount' ability in the origin file system
4196 create subcommand Must also have the 'mount' ability.
4197 Must also have the 'refreservation' ability to
4198 create a non-sparse volume.
4199 destroy subcommand Must also have the 'mount' ability
4200 diff subcommand Allows lookup of paths within a dataset
4201 given an object number, and the ability
4202 to create snapshots necessary to
4204 load-key subcommand Allows loading and unloading of encryption key
4205 (see 'zfs load-key' and 'zfs unload-key').
4206 change-key subcommand Allows changing an encryption key via
4208 mount subcommand Allows mount/umount of ZFS datasets
4209 promote subcommand Must also have the 'mount' and 'promote'
4210 ability in the origin file system
4211 receive subcommand Must also have the 'mount' and 'create'
4213 rename subcommand Must also have the 'mount' and 'create'
4214 ability in the new parent
4215 rollback subcommand Must also have the 'mount' ability
4217 share subcommand Allows sharing file systems over NFS
4219 snapshot subcommand Must also have the 'mount' ability
4221 groupquota other Allows accessing any groupquota@...
4223 groupused other Allows reading any groupused@... property
4224 userprop other Allows changing any user property
4225 userquota other Allows accessing any userquota@...
4227 userused other Allows reading any userused@... property
4228 projectobjquota other Allows accessing any projectobjquota@...
4230 projectquota other Allows accessing any projectquota@... property
4231 projectobjused other Allows reading any projectobjused@... property
4232 projectused other Allows reading any projectused@... property
4238 casesensitivity property
4240 compression property
4244 filesystem_limit property
4247 normalization property
4248 primarycache property
4253 refreservation property
4254 reservation property
4255 secondarycache property
4260 snapshot_limit property
4263 volblocksize property
4273 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4274 .Ar setname Oc Ns ...
4275 .Ar filesystem Ns | Ns Ar volume
4280 These permissions are granted
4282 to the creator of any newly-created descendent file system.
4286 .Fl s No @ Ns Ar setname
4287 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4288 .Ar setname Oc Ns ...
4289 .Ar filesystem Ns | Ns Ar volume
4291 Defines or adds permissions to a permission set.
4292 The set can be used by other
4294 commands for the specified file system and its descendents.
4295 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4296 Permission sets follow the same naming restrictions as ZFS file systems, but the
4297 name must begin with
4299 and can be no more than 64 characters long.
4304 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4305 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4306 .Ar setname Oc Ns ... Oc
4307 .Ar filesystem Ns | Ns Ar volume
4313 .Fl e Ns | Ns Sy everyone
4314 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4315 .Ar setname Oc Ns ... Oc
4316 .Ar filesystem Ns | Ns Ar volume
4323 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4324 .Ar setname Oc Ns ... Oc
4325 .Ar filesystem Ns | Ns Ar volume
4327 Removes permissions that were granted with the
4330 No permissions are explicitly denied, so other permissions granted are still in
4332 For example, if the permission is granted by an ancestor.
4333 If no permissions are specified, then all permissions for the specified
4345 only removes the permissions that were granted to everyone, not all permissions
4346 for every user and group.
4349 command for a description of the
4352 .Bl -tag -width "-r"
4354 Recursively remove the permissions from this file system and all descendents.
4360 .Fl s No @ Ns Ar setname
4361 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4362 .Ar setname Oc Ns ... Oc
4363 .Ar filesystem Ns | Ns Ar volume
4365 Removes permissions from a permission set.
4366 If no permissions are specified, then all permissions are removed, thus removing
4372 .Ar tag Ar snapshot Ns ...
4374 Adds a single reference, named with the
4376 argument, to the specified snapshot or snapshots.
4377 Each snapshot has its own tag namespace, and tags must be unique within that
4380 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4384 .Bl -tag -width "-r"
4386 Specifies that a hold with the given tag is applied recursively to the snapshots
4387 of all descendent file systems.
4395 Lists all existing user references for the given snapshot or snapshots.
4396 .Bl -tag -width "-r"
4398 Lists the holds that are set on the named descendent snapshots, in addition to
4399 listing the holds on the named snapshot.
4401 Do not print headers, use tab-delimited output.
4407 .Ar tag Ar snapshot Ns ...
4409 Removes a single reference, named with the
4411 argument, from the specified snapshot or snapshots.
4412 The tag must already exist for each snapshot.
4413 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4417 .Bl -tag -width "-r"
4419 Recursively releases a hold with the given tag on the snapshots of all
4420 descendent file systems.
4426 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4428 Display the difference between a snapshot of a given filesystem and another
4429 snapshot of that filesystem from a later time or the current contents of the
4431 The first column is a character indicating the type of change, the other columns
4432 indicate pathname, new pathname
4433 .Pq in case of rename ,
4434 change in link count, and optionally file type and/or change time.
4435 The types of change are:
4437 - The path has been removed
4438 + The path has been created
4439 M The path has been modified
4440 R The path has been renamed
4442 .Bl -tag -width "-F"
4444 Display an indication of the type of file, in a manner similar to the
4460 Give more parsable tab-separated output, without header lines and without
4463 Display the path's inode change time as the first column of output.
4469 .Op Fl t Ar instruction-limit
4470 .Op Fl m Ar memory-limit
4476 as a ZFS channel program on
4479 program interface allows ZFS administrative operations to be run
4480 programmatically via a Lua script.
4481 The entire script is executed atomically, with no other administrative
4482 operations taking effect concurrently.
4483 A library of ZFS calls is made available to channel program scripts.
4484 Channel programs may only be run with root privileges.
4486 For full documentation of the ZFS channel program interface, see the manual
4491 Display channel program output in JSON format. When this flag is specified and
4492 standard output is empty - channel program encountered an error. The details of
4493 such an error will be printed to standard error in plain text.
4495 Executes a read-only channel program, which runs faster.
4496 The program cannot change on-disk state by calling functions from
4497 the zfs.sync submodule.
4498 The program can be used to gather information such as properties and
4499 determining if changes would succeed (zfs.check.*).
4500 Without this flag, all pending changes must be synced to disk before
4501 a channel program can complete.
4502 .It Fl t Ar instruction-limit
4503 Limit the number of Lua instructions to execute.
4504 If a channel program executes more than the specified number of instructions,
4505 it will be stopped and an error will be returned.
4506 The default limit is 10 million instructions, and it can be set to a maximum of
4507 100 million instructions.
4508 .It Fl m Ar memory-limit
4509 Memory limit, in bytes.
4510 If a channel program attempts to allocate more memory than the given limit,
4511 it will be stopped and an error returned.
4512 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4514 All remaining argument strings are passed directly to the channel program as
4518 for more information.
4524 .Op Fl L Ar keylocation
4525 .Fl a | Ar filesystem
4529 allowing it and all children that inherit the
4531 property to be accessed. The key will be expected in the format specified by the
4533 and location specified by the
4535 property. Note that if the
4539 the terminal will interactively wait for the key to be entered. Loading a key
4540 will not automatically mount the dataset. If that functionality is desired,
4541 .Nm zfs Cm mount Sy -l
4542 will ask for the key and mount the dataset. Once the key is loaded the
4544 property will become
4546 .Bl -tag -width "-r"
4548 Recursively loads the keys for the specified filesystem and all descendent
4551 Loads the keys for all encryption roots in all imported pools.
4555 load-key. This will cause zfs to simply check that the
4556 provided key is correct. This command may be run even if the key is already
4558 .It Fl L Ar keylocation
4563 property. This will not change the value of the property on the dataset. Note
4564 that if used with either
4569 may only be given as
4576 .Fl a | Ar filesystem
4578 Unloads a key from ZFS, removing the ability to access the dataset and all of
4579 its children that inherit the
4581 property. This requires that the dataset is not currently open or mounted. Once
4582 the key is unloaded the
4584 property will become
4586 .Bl -tag -width "-r"
4588 Recursively unloads the keys for the specified filesystem and all descendent
4591 Unloads the keys for all encryption roots in all imported pools.
4597 .Op Fl o Ar keylocation Ns = Ns Ar value
4598 .Op Fl o Ar keyformat Ns = Ns Ar value
4599 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4609 Allows a user to change the encryption key used to access a dataset. This
4610 command requires that the existing key for the dataset is already loaded into
4611 ZFS. This command may also be used to change the
4616 properties as needed. If the dataset was not previously an encryption root it
4617 will become one. Alternatively, the
4619 flag may be provided to cause an encryption root to inherit the parent's key
4621 .Bl -tag -width "-r"
4623 Ensures the key is loaded before attempting to change the key. This is
4624 effectively equivalent to
4625 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4626 .It Fl o Ar property Ns = Ns Ar value
4627 Allows the user to set encryption key properties (
4632 ) while changing the key. This is the only way to alter
4636 after the dataset has been created.
4638 Indicates that zfs should make
4640 inherit the key of its parent. Note that this command can only be run on an
4641 encryption root that has an encrypted parent.
4647 Displays the software version of the
4649 userland utility and the zfs kernel module.
4654 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4655 options were specified.
4658 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4659 The following commands create a file system named
4661 and a file system named
4665 is set for the parent file system, and is automatically inherited by the child
4668 # zfs create pool/home
4669 # zfs set mountpoint=/export/home pool/home
4670 # zfs create pool/home/bob
4672 .It Sy Example 2 No Creating a ZFS Snapshot
4673 The following command creates a snapshot named
4675 This snapshot is mounted on demand in the
4677 directory at the root of the
4681 # zfs snapshot pool/home/bob@yesterday
4683 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4684 The following command creates snapshots named
4688 and all of its descendent file systems.
4689 Each snapshot is mounted on demand in the
4691 directory at the root of its file system.
4692 The second command destroys the newly created snapshots.
4694 # zfs snapshot -r pool/home@yesterday
4695 # zfs destroy -r pool/home@yesterday
4697 .It Sy Example 4 No Disabling and Enabling File System Compression
4698 The following command disables the
4700 property for all file systems under
4702 The next command explicitly enables
4705 .Em pool/home/anne .
4707 # zfs set compression=off pool/home
4708 # zfs set compression=on pool/home/anne
4710 .It Sy Example 5 No Listing ZFS Datasets
4711 The following command lists all active file systems and volumes in the system.
4712 Snapshots are displayed if the
4720 for more information on pool properties.
4723 NAME USED AVAIL REFER MOUNTPOINT
4724 pool 450K 457G 18K /pool
4725 pool/home 315K 457G 21K /export/home
4726 pool/home/anne 18K 457G 18K /export/home/anne
4727 pool/home/bob 276K 457G 276K /export/home/bob
4729 .It Sy Example 6 No Setting a Quota on a ZFS File System
4730 The following command sets a quota of 50 Gbytes for
4733 # zfs set quota=50G pool/home/bob
4735 .It Sy Example 7 No Listing ZFS Properties
4736 The following command lists all properties for
4739 # zfs get all pool/home/bob
4740 NAME PROPERTY VALUE SOURCE
4741 pool/home/bob type filesystem -
4742 pool/home/bob creation Tue Jul 21 15:53 2009 -
4743 pool/home/bob used 21K -
4744 pool/home/bob available 20.0G -
4745 pool/home/bob referenced 21K -
4746 pool/home/bob compressratio 1.00x -
4747 pool/home/bob mounted yes -
4748 pool/home/bob quota 20G local
4749 pool/home/bob reservation none default
4750 pool/home/bob recordsize 128K default
4751 pool/home/bob mountpoint /pool/home/bob default
4752 pool/home/bob sharenfs off default
4753 pool/home/bob checksum on default
4754 pool/home/bob compression on local
4755 pool/home/bob atime on default
4756 pool/home/bob devices on default
4757 pool/home/bob exec on default
4758 pool/home/bob setuid on default
4759 pool/home/bob readonly off default
4760 pool/home/bob zoned off default
4761 pool/home/bob snapdir hidden default
4762 pool/home/bob acltype off default
4763 pool/home/bob aclinherit restricted default
4764 pool/home/bob canmount on default
4765 pool/home/bob xattr on default
4766 pool/home/bob copies 1 default
4767 pool/home/bob version 4 -
4768 pool/home/bob utf8only off -
4769 pool/home/bob normalization none -
4770 pool/home/bob casesensitivity sensitive -
4771 pool/home/bob vscan off default
4772 pool/home/bob nbmand off default
4773 pool/home/bob sharesmb off default
4774 pool/home/bob refquota none default
4775 pool/home/bob refreservation none default
4776 pool/home/bob primarycache all default
4777 pool/home/bob secondarycache all default
4778 pool/home/bob usedbysnapshots 0 -
4779 pool/home/bob usedbydataset 21K -
4780 pool/home/bob usedbychildren 0 -
4781 pool/home/bob usedbyrefreservation 0 -
4784 The following command gets a single property value.
4786 # zfs get -H -o value compression pool/home/bob
4789 The following command lists all properties with local settings for
4792 # zfs get -r -s local -o name,property,value all pool/home/bob
4794 pool/home/bob quota 20G
4795 pool/home/bob compression on
4797 .It Sy Example 8 No Rolling Back a ZFS File System
4798 The following command reverts the contents of
4800 to the snapshot named
4802 deleting all intermediate snapshots.
4804 # zfs rollback -r pool/home/anne@yesterday
4806 .It Sy Example 9 No Creating a ZFS Clone
4807 The following command creates a writable file system whose initial contents are
4809 .Em pool/home/bob@yesterday .
4811 # zfs clone pool/home/bob@yesterday pool/clone
4813 .It Sy Example 10 No Promoting a ZFS Clone
4814 The following commands illustrate how to test out changes to a file system, and
4815 then replace the original file system with the changed one, using clones, clone
4816 promotion, and renaming:
4818 # zfs create pool/project/production
4819 populate /pool/project/production with data
4820 # zfs snapshot pool/project/production@today
4821 # zfs clone pool/project/production@today pool/project/beta
4822 make changes to /pool/project/beta and test them
4823 # zfs promote pool/project/beta
4824 # zfs rename pool/project/production pool/project/legacy
4825 # zfs rename pool/project/beta pool/project/production
4826 once the legacy version is no longer needed, it can be destroyed
4827 # zfs destroy pool/project/legacy
4829 .It Sy Example 11 No Inheriting ZFS Properties
4830 The following command causes
4836 property from their parent.
4838 # zfs inherit checksum pool/home/bob pool/home/anne
4840 .It Sy Example 12 No Remotely Replicating ZFS Data
4841 The following commands send a full stream and then an incremental stream to a
4842 remote machine, restoring them into
4843 .Em poolB/received/fs@a
4845 .Em poolB/received/fs@b ,
4848 must contain the file system
4849 .Em poolB/received ,
4850 and must not initially contain
4851 .Em poolB/received/fs .
4853 # zfs send pool/fs@a | \e
4854 ssh host zfs receive poolB/received/fs@a
4855 # zfs send -i a pool/fs@b | \e
4856 ssh host zfs receive poolB/received/fs
4858 .It Sy Example 13 No Using the zfs receive -d Option
4859 The following command sends a full stream of
4860 .Em poolA/fsA/fsB@snap
4861 to a remote machine, receiving it into
4862 .Em poolB/received/fsA/fsB@snap .
4865 portion of the received snapshot's name is determined from the name of the sent
4868 must contain the file system
4869 .Em poolB/received .
4871 .Em poolB/received/fsA
4872 does not exist, it is created as an empty file system.
4874 # zfs send poolA/fsA/fsB@snap | \e
4875 ssh host zfs receive -d poolB/received
4877 .It Sy Example 14 No Setting User Properties
4878 The following example sets the user-defined
4879 .Sy com.example:department
4880 property for a dataset.
4882 # zfs set com.example:department=12345 tank/accounting
4884 .It Sy Example 15 No Performing a Rolling Snapshot
4885 The following example shows how to maintain a history of snapshots with a
4886 consistent naming scheme.
4887 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4888 renames the remaining snapshots, and then creates a new snapshot, as follows:
4890 # zfs destroy -r pool/users@7daysago
4891 # zfs rename -r pool/users@6daysago @7daysago
4892 # zfs rename -r pool/users@5daysago @6daysago
4893 # zfs rename -r pool/users@4daysago @5daysago
4894 # zfs rename -r pool/users@3daysago @4daysago
4895 # zfs rename -r pool/users@2daysago @3daysago
4896 # zfs rename -r pool/users@yesterday @2daysago
4897 # zfs rename -r pool/users@today @yesterday
4898 # zfs snapshot -r pool/users@today
4900 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4901 The following commands show how to set
4903 property options to enable
4907 addresses and to enable root access for system
4913 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4918 for host name resolution, specify the fully qualified hostname.
4919 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4920 The following example shows how to set permissions so that user
4922 can create, destroy, mount, and take snapshots on
4928 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4929 # zfs allow tank/cindys
4930 ---- Permissions on tank/cindys --------------------------------------
4931 Local+Descendent permissions:
4932 user cindys create,destroy,mount,snapshot
4937 mount point permission is set to 755 by default, user
4939 will be unable to mount file systems under
4941 Add an ACE similar to the following syntax to provide mount point access:
4943 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4945 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4946 The following example shows how to grant anyone in the group
4948 to create file systems in
4950 This syntax also allows staff members to destroy their own file systems, but not
4951 destroy anyone else's file system.
4956 # zfs allow staff create,mount tank/users
4957 # zfs allow -c destroy tank/users
4958 # zfs allow tank/users
4959 ---- Permissions on tank/users ---------------------------------------
4962 Local+Descendent permissions:
4963 group staff create,mount
4965 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4966 The following example shows how to define and grant a permission set on the
4973 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4974 # zfs allow staff @pset tank/users
4975 # zfs allow tank/users
4976 ---- Permissions on tank/users ---------------------------------------
4978 @pset create,destroy,mount,snapshot
4979 Local+Descendent permissions:
4982 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4983 The following example shows to grant the ability to set quotas and reservations
4991 # zfs allow cindys quota,reservation users/home
4992 # zfs allow users/home
4993 ---- Permissions on users/home ---------------------------------------
4994 Local+Descendent permissions:
4995 user cindys quota,reservation
4996 cindys% zfs set quota=10G users/home/marks
4997 cindys% zfs get quota users/home/marks
4998 NAME PROPERTY VALUE SOURCE
4999 users/home/marks quota 10G local
5001 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
5002 The following example shows how to remove the snapshot permission from the
5011 # zfs unallow staff snapshot tank/users
5012 # zfs allow tank/users
5013 ---- Permissions on tank/users ---------------------------------------
5015 @pset create,destroy,mount,snapshot
5016 Local+Descendent permissions:
5019 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
5020 The following example shows how to see what has changed between a prior
5021 snapshot of a ZFS dataset and its current state.
5024 option is used to indicate type information for the files affected.
5026 # zfs diff -F tank/test@before tank/test
5028 M F /tank/test/linked (+1)
5029 R F /tank/test/oldname -> /tank/test/newname
5030 - F /tank/test/deleted
5031 + F /tank/test/created
5032 M F /tank/test/modified
5034 .It Sy Example 23 No Creating a bookmark
5035 The following example create a bookmark to a snapshot. This bookmark
5036 can then be used instead of snapshot in send streams.
5038 # zfs bookmark rpool@snapshot rpool#bookmark
5040 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
5041 The following example show how to share SMB filesystem through ZFS. Note that
5042 that a user and his/her password must be given.
5044 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
5045 -o user=workgroup/turbo,password=obrut,uid=1000
5049 .Em /etc/samba/smb.conf
5050 configuration required:
5052 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
5053 communicate with Samba. This is the default behavior for most Linux
5056 Samba must be able to authenticate a user. This can be done in a number of
5057 ways, depending on if using the system password file, LDAP or the Samba
5058 specific smbpasswd file. How to do this is outside the scope of this manual.
5061 man page for more information.
5064 .Sy USERSHARE section
5067 man page for all configuration options in case you need to modify any options
5068 to the share afterwards. Do note that any changes done with the
5070 command will be undone if the share is ever unshared (such as at a reboot etc).
5072 .Sh INTERFACE STABILITY
projects / mirror_zfs.git / blob