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 2019 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 .Oo Fl i Ar snapshot Ns | Ns Ar bookmark
206 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
209 .Fl -redact Ar redaction_bookmark
211 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
216 .Fl t Ar receive_resume_token
220 .Op Fl o Sy origin Ns = Ns Ar snapshot
221 .Op Fl o Ar property Ns = Ns Ar value
223 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
227 .Op Fl d Ns | Ns Fl e
228 .Op Fl o Sy origin Ns = Ns Ar snapshot
229 .Op Fl o Ar property Ns = Ns Ar value
235 .Ar filesystem Ns | Ns Ar volume
238 .Ar snapshot redaction_bookmark
239 .Ar redaction_snapshot Ns ...
242 .Ar filesystem Ns | Ns Ar volume
246 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
247 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
248 .Ar setname Oc Ns ...
249 .Ar filesystem Ns | Ns Ar volume
253 .Fl e Ns | Ns Sy everyone
254 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
255 .Ar setname Oc Ns ...
256 .Ar filesystem Ns | Ns Ar volume
260 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
261 .Ar setname Oc Ns ...
262 .Ar filesystem Ns | Ns Ar volume
265 .Fl s No @ Ns Ar setname
266 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
267 .Ar setname Oc Ns ...
268 .Ar filesystem Ns | Ns Ar volume
272 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
273 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
274 .Ar setname Oc Ns ... Oc
275 .Ar filesystem Ns | Ns Ar volume
279 .Fl e Ns | Ns Sy everyone
280 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
281 .Ar setname Oc Ns ... Oc
282 .Ar filesystem Ns | Ns Ar volume
287 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
288 .Ar setname Oc Ns ... Oc
289 .Ar filesystem Ns | Ns Ar volume
293 .Fl s @ Ns Ar setname
294 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
295 .Ar setname Oc Ns ... Oc
296 .Ar filesystem Ns | Ns Ar volume
300 .Ar tag Ar snapshot Ns ...
308 .Ar tag Ar snapshot Ns ...
312 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
316 .Op Fl t Ar instruction-limit
317 .Op Fl m Ar memory-limit
323 .Op Fl L Ar keylocation
324 .Fl a | Ar filesystem
328 .Fl a | Ar filesystem
332 .Op Fl o Ar keylocation Ns = Ns Ar value
333 .Op Fl o Ar keyformat Ns = Ns Ar value
334 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
346 command configures ZFS datasets within a ZFS storage pool, as described in
348 A dataset is identified by a unique path within the ZFS namespace.
351 pool/{filesystem,volume,snapshot}
354 where the maximum length of a dataset name is
357 and the maximum amount of nesting allowed in a path is 50 levels deep.
359 A dataset can be one of the following:
360 .Bl -tag -width "file system"
362 A ZFS dataset of type
364 can be mounted within the standard system namespace and behaves like other file
366 While ZFS file systems are designed to be POSIX compliant, known issues exist
367 that prevent compliance in some cases.
368 Applications that depend on standards conformance might fail due to non-standard
369 behavior when checking file system free space.
371 A logical volume exported as a raw or block device.
372 This type of dataset should only be used when a block device is required.
373 File systems are typically used in most environments.
375 A read-only version of a file system or volume at a given point in time.
377 .Ar filesystem Ns @ Ns Ar name
379 .Ar volume Ns @ Ns Ar name .
383 but without the hold on on-disk data. It can be used as the source of a send
384 (but not for a receive). It is specified as
385 .Ar filesystem Ns # Ns Ar name
387 .Ar volume Ns # Ns Ar name .
389 .Ss ZFS File System Hierarchy
390 A ZFS storage pool is a logical collection of devices that provide space for
392 A storage pool is also the root of the ZFS file system hierarchy.
394 The root of the pool can be accessed as a file system, such as mounting and
395 unmounting, taking snapshots, and setting properties.
396 The physical storage characteristics, however, are managed by the
402 for more information on creating and administering pools.
404 A snapshot is a read-only copy of a file system or volume.
405 Snapshots can be created extremely quickly, and initially consume no additional
406 space within the pool.
407 As data within the active dataset changes, the snapshot consumes more data than
408 would otherwise be shared with the active dataset.
410 Snapshots can have arbitrary names.
411 Snapshots of volumes can be cloned or rolled back, visibility is determined
414 property of the parent volume.
416 File system snapshots can be accessed under the
418 directory in the root of the file system.
419 Snapshots are automatically mounted on demand and may be unmounted at regular
421 The visibility of the
423 directory can be controlled by the
427 A bookmark is like a snapshot, a read-only copy of a file system or volume.
428 Bookmarks can be created extremely quickly, compared to snapshots, and they
429 consume no additional space within the pool. Bookmarks can also have arbitrary
430 names, much like snapshots.
432 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
433 way. From a storage standpoint a bookmark just provides a way to reference
434 when a snapshot was created as a distinct object. Bookmarks are initially
435 tied to a snapshot, not the filesystem or volume, and they will survive if the
436 snapshot itself is destroyed. Since they are very light weight there's little
437 incentive to destroy them.
439 A clone is a writable volume or file system whose initial contents are the same
441 As with snapshots, creating a clone is nearly instantaneous, and initially
442 consumes no additional space.
444 Clones can only be created from a snapshot.
445 When a snapshot is cloned, it creates an implicit dependency between the parent
447 Even though the clone is created somewhere else in the dataset hierarchy, the
448 original snapshot cannot be destroyed as long as a clone exists.
451 property exposes this dependency, and the
453 command lists any such dependencies, if they exist.
455 The clone parent-child dependency relationship can be reversed by using the
460 file system to become a clone of the specified file system, which makes it
461 possible to destroy the file system that the clone was created from.
463 Creating a ZFS file system is a simple operation, so the number of file systems
464 per system is likely to be numerous.
465 To cope with this, ZFS automatically manages mounting and unmounting file
466 systems without the need to edit the
469 All automatically managed file systems are mounted by ZFS at boot time.
471 By default, file systems are mounted under
475 is the name of the file system in the ZFS namespace.
476 Directories are created and destroyed as needed.
478 A file system can also have a mount point set in the
481 This directory is created as needed, and ZFS automatically mounts the file
483 .Nm zfs Cm mount Fl a
490 property can be inherited, so if
496 automatically inherits a mount point of
497 .Pa /export/stuff/user .
503 prevents the file system from being mounted.
505 If needed, ZFS file systems can also be managed with traditional tools
511 If a file system's mount point is set to
513 ZFS makes no attempt to manage the file system, and the administrator is
514 responsible for mounting and unmounting the file system. Because pools must
515 be imported before a legacy mount can succeed, administrators should ensure
516 that legacy mounts are only attempted after the zpool import process
517 finishes at boot time. For example, on machines using systemd, the mount
520 .Nm x-systemd.requires=zfs-import.target
522 will ensure that the zfs-import completes before systemd attempts mounting
523 the filesystem. See systemd.mount(5) for details.
525 Deduplication is the process for removing redundant data at the block level,
526 reducing the total amount of data stored. If a file system has the
528 property enabled, duplicate data blocks are removed synchronously. The result
529 is that only unique data is stored and common components are shared among files.
531 Deduplicating data is a very resource-intensive operation. It is generally
532 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
533 you enable deduplication. Calculating the exact requirement depends heavily
534 on the type of data stored in the pool.
536 Enabling deduplication on an improperly-designed system can result in
537 performance issues (slow IO and administrative operations). It can potentially
538 lead to problems importing a pool due to memory exhaustion. Deduplication
539 can consume significant processing power (CPU) and memory as well as generate
542 Before creating a pool with deduplication enabled, ensure that you have planned
543 your hardware requirements appropriately and implemented appropriate recovery
544 practices, such as regular backups. As an alternative to deduplication
547 as a less resource-intensive alternative.
548 .Ss Native Properties
549 Properties are divided into two types, native properties and user-defined
554 Native properties either export internal statistics or control ZFS behavior.
555 In addition, native properties are either editable or read-only.
556 User properties have no effect on ZFS behavior, but you can use them to annotate
557 datasets in a way that is meaningful in your environment.
558 For more information about user properties, see the
562 Every dataset has a set of properties that export statistics about the dataset
563 as well as control various behaviors.
564 Properties are inherited from the parent unless overridden by the child.
565 Some properties apply only to certain types of datasets
566 .Pq file systems, volumes, or snapshots .
568 The values of numeric properties can be specified using human-readable suffixes
578 The following are all valid
581 .Li 1536M, 1.5g, 1.50GB .
583 The values of non-numeric properties are case sensitive and must be lowercase,
590 The following native properties consist of read-only statistics about the
592 These properties can be neither set, nor inherited.
593 Native properties apply to all dataset types unless otherwise noted.
594 .Bl -tag -width "usedbyrefreservation"
596 The amount of space available to the dataset and all its children, assuming that
597 there is no other activity in the pool.
598 Because space is shared within a pool, availability can be limited by any number
599 of factors, including physical pool size, quotas, reservations, or other
600 datasets within the pool.
602 This property can also be referred to by its shortened column name,
605 For non-snapshots, the compression ratio achieved for the
607 space of this dataset, expressed as a multiplier.
610 property includes descendant datasets, and, for clones, does not include the
611 space shared with the origin snapshot.
617 Compression can be turned on by running:
618 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
622 The transaction group (txg) in which the dataset was created. Bookmarks have
625 as the snapshot they are initially tied to. This property is suitable for
626 ordering a list of snapshots, e.g. for incremental send and receive.
628 The time this dataset was created.
630 For snapshots, this property is a comma-separated list of filesystems or volumes
631 which are clones of this snapshot.
634 property is this snapshot.
637 property is not empty, then this snapshot can not be destroyed
644 The roles of origin and clone can be swapped by promoting the clone with the
650 if the snapshot has been marked for deferred destroy by using the
651 .Nm zfs Cm destroy Fl d
653 Otherwise, the property is
655 .It Sy encryptionroot
656 For encrypted datasets, indicates where the dataset is currently inheriting its
657 encryption key from. Loading or unloading a key for the
659 will implicitly load / unload the key for any inheriting datasets (see
662 .Nm zfs Cm unload-key
664 Clones will always share an
665 encryption key with their origin. See the
668 .It Sy filesystem_count
669 The total number of filesystems and volumes that exist under this location in
671 This value is only available when a
673 has been set somewhere in the tree under which the dataset resides.
675 Indicates if an encryption key is currently loaded into ZFS. The possible
684 .Nm zfs Cm unload-key .
686 The 64 bit GUID of this dataset or bookmark which does not change over its
687 entire lifetime. When a snapshot is sent to another pool, the received
688 snapshot has the same GUID. Thus, the
690 is suitable to identify a snapshot across pools.
691 .It Sy logicalreferenced
692 The amount of space that is
694 accessible by this dataset.
698 The logical space ignores the effect of the
702 properties, giving a quantity closer to the amount of data that applications
704 However, it does include space consumed by metadata.
706 This property can also be referred to by its shortened column name,
709 The amount of space that is
711 consumed by this dataset and all its descendents.
715 The logical space ignores the effect of the
719 properties, giving a quantity closer to the amount of data that applications
721 However, it does include space consumed by metadata.
723 This property can also be referred to by its shortened column name,
726 For file systems, indicates whether the file system is currently mounted.
727 This property can be either
732 A unique identifier for this dataset within the pool. Unlike the dataset's
736 of a dataset is not transferred to other pools when the snapshot is copied
737 with a send/receive operation.
740 can be reused (for a new dataset) after the dataset is deleted.
742 For cloned file systems or volumes, the snapshot from which the clone was
747 .It Sy receive_resume_token
748 For filesystems or volumes which have saved partially-completed state from
750 this opaque token can be provided to
752 to resume and complete the
755 For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
757 For snapshots, this is the list of snapshot guids the snapshot is redacted with
760 The amount of data that is accessible by this dataset, which may or may not be
761 shared with other datasets in the pool.
762 When a snapshot or clone is created, it initially references the same amount of
763 space as the file system or snapshot it was created from, since its contents are
766 This property can also be referred to by its shortened column name,
768 .It Sy refcompressratio
769 The compression ratio achieved for the
771 space of this dataset, expressed as a multiplier.
775 .It Sy snapshot_count
776 The total number of snapshots that exist under this location in the dataset
778 This value is only available when a
780 has been set somewhere in the tree under which the dataset resides.
788 The amount of space consumed by this dataset and all its descendents.
789 This is the value that is checked against this dataset's quota and reservation.
790 The space used does not include this dataset's reservation, but does take into
791 account the reservations of any descendent datasets.
792 The amount of space that a dataset consumes from its parent, as well as the
793 amount of space that is freed if this dataset is recursively destroyed, is the
794 greater of its space used and its reservation.
796 The used space of a snapshot
801 is space that is referenced exclusively by this snapshot.
802 If this snapshot is destroyed, the amount of
805 Space that is shared by multiple snapshots isn't accounted for in this metric.
806 When a snapshot is destroyed, space that was previously shared with this
807 snapshot can become unique to snapshots adjacent to it, thus changing the used
808 space of those snapshots.
809 The used space of the latest snapshot can also be affected by changes in the
813 space of a snapshot is a subset of the
815 space of the snapshot.
817 The amount of space used, available, or referenced does not take into account
819 Pending changes are generally accounted for within a few seconds.
820 Committing a change to a disk using
824 does not necessarily guarantee that the space usage information is updated
829 properties decompose the
831 properties into the various reasons that space is used.
834 .Sy usedbychildren No +
835 .Sy usedbydataset No +
836 .Sy usedbyrefreservation No +
837 .Sy usedbysnapshots .
838 These properties are only available for datasets created on
842 .It Sy usedbychildren
843 The amount of space used by children of this dataset, which would be freed if
844 all the dataset's children were destroyed.
846 The amount of space used by this dataset itself, which would be freed if the
847 dataset were destroyed
848 .Po after first removing any
850 and destroying any necessary snapshots or descendents
852 .It Sy usedbyrefreservation
853 The amount of space used by a
855 set on this dataset, which would be freed if the
858 .It Sy usedbysnapshots
859 The amount of space consumed by snapshots of this dataset.
860 In particular, it is the amount of space that would be freed if all of this
861 dataset's snapshots were destroyed.
862 Note that this is not simply the sum of the snapshots'
864 properties because space can be shared by multiple snapshots.
865 .It Sy userused Ns @ Ns Em user
866 The amount of space consumed by the specified user in this dataset.
867 Space is charged to the owner of each file, as displayed by
869 The amount of space charged is displayed by
875 subcommand for more information.
877 Unprivileged users can access only their own space usage.
878 The root user, or a user who has been granted the
882 can access everyone's usage.
885 .Sy userused Ns @ Ns Em ...
886 properties are not displayed by
887 .Nm zfs Cm get Sy all .
888 The user's name must be appended after the @ symbol, using one of the following
890 .Bl -bullet -width ""
904 .Sy joe.smith@mydomain
913 Files created on Linux always have POSIX owners.
914 .It Sy userobjused Ns @ Ns Em user
917 property is similar to
919 but instead it counts the number of objects consumed by a user. This property
920 counts all objects allocated on behalf of the user, it may differ from the
921 results of system tools such as
926 is set on a file system additional objects will be created per-file to store
927 extended attributes. These additional objects are reflected in the
929 value and are counted against the user's
931 When a file system is configured to use
933 no additional internal objects are normally required.
935 This property is set to the number of user holds on this snapshot.
936 User holds are set by using the
939 .It Sy groupused Ns @ Ns Em group
940 The amount of space consumed by the specified group in this dataset.
941 Space is charged to the group of each file, as displayed by
944 .Sy userused Ns @ Ns Em user
945 property for more information.
947 Unprivileged users can only access their own groups' space usage.
948 The root user, or a user who has been granted the
952 can access all groups' usage.
953 .It Sy groupobjused Ns @ Ns Em group
954 The number of objects consumed by the specified group in this dataset.
955 Multiple objects may be charged to the group for each file when extended
956 attributes are in use. See the
957 .Sy userobjused Ns @ Ns Em user
958 property for more information.
960 Unprivileged users can only access their own groups' space usage.
961 The root user, or a user who has been granted the
965 can access all groups' usage.
966 .It Sy projectused Ns @ Ns Em project
967 The amount of space consumed by the specified project in this dataset. Project
968 is identified via the project identifier (ID) that is object-based numeral
969 attribute. An object can inherit the project ID from its parent object (if the
970 parent has the flag of inherit project ID that can be set and changed via
973 .Nm zfs project Fl s )
974 when being created. The privileged user can set and change object's project
979 anytime. Space is charged to the project of each file, as displayed by
984 .Sy userused Ns @ Ns Em user
985 property for more information.
987 The root user, or a user who has been granted the
991 can access all projects' usage.
992 .It Sy projectobjused Ns @ Ns Em project
997 but instead it counts the number of objects consumed by project. When the
1000 is set on a fileset, ZFS will create additional objects per-file to store
1001 extended attributes. These additional objects are reflected in the
1003 value and are counted against the project's
1004 .Sy projectobjquota .
1005 When a filesystem is configured to use
1007 no additional internal objects are required. See the
1008 .Sy userobjused Ns @ Ns Em user
1009 property for more information.
1011 The root user, or a user who has been granted the
1015 can access all projects' objects usage.
1017 For volumes, specifies the block size of the volume.
1020 cannot be changed once the volume has been written, so it should be set at
1021 volume creation time.
1024 for volumes is 8 Kbytes.
1025 Any power of 2 from 512 bytes to 128 Kbytes is valid.
1027 This property can also be referred to by its shortened column name,
1032 by this dataset, that was written since the previous snapshot
1033 .Pq i.e. that is not referenced by the previous snapshot .
1034 .It Sy written Ns @ Ns Em snapshot
1037 space written to this dataset since the specified snapshot.
1038 This is the space that is referenced by this dataset but was not referenced by
1039 the specified snapshot.
1043 may be specified as a short snapshot name
1044 .Po just the part after the
1047 in which case it will be interpreted as a snapshot in the same filesystem as
1051 may be a full snapshot name
1052 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1053 which for clones may be a snapshot in the origin's filesystem
1054 .Pq or the origin of the origin's filesystem, etc.
1057 The following native properties can be used to change the behavior of a ZFS
1061 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1062 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1064 Controls how ACEs are inherited when files and directories are created.
1065 .Bl -tag -width "passthrough-x"
1067 does not inherit any ACEs.
1069 only inherits inheritable ACEs that specify
1073 default, removes the
1077 permissions when the ACE is inherited.
1079 inherits all inheritable ACEs without any modifications.
1080 .It Sy passthrough-x
1088 ACEs inherit the execute permission only if the file creation mode also requests
1092 When the property value is set to
1094 files are created with a mode determined by the inheritable ACEs.
1095 If no inheritable ACEs exist that affect the mode, then the mode is set in
1096 accordance to the requested mode from the application.
1100 property does not apply to POSIX ACLs.
1101 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1102 Controls whether ACLs are enabled and if so what type of ACL to use.
1103 .Bl -tag -width "posixacl"
1105 default, when a file system has the
1107 property set to off then ACLs are disabled.
1112 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
1113 not functional on other platforms. POSIX ACLs are stored as an extended
1114 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1118 To obtain the best performance when setting
1120 users are strongly encouraged to set the
1122 property. This will result in the POSIX ACL being stored more efficiently on
1123 disk. But as a consequence, all new extended attributes will only be
1124 accessible from OpenZFS implementations which support the
1128 property for more details.
1129 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1130 Controls whether the access time for files is updated when they are read.
1131 Turning this property off avoids producing write traffic when reading files and
1132 can result in significant performance gains, though it might confuse mailers
1133 and other similar utilities. The values
1137 are equivalent to the
1141 mount options. The default value is
1146 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1147 If this property is set to
1149 the file system cannot be mounted, and is ignored by
1150 .Nm zfs Cm mount Fl a .
1151 Setting this property to
1153 is similar to setting the
1157 except that the dataset still has a normal
1159 property, which can be inherited.
1160 Setting this property to
1162 allows datasets to be used solely as a mechanism to inherit properties.
1163 One example of setting
1164 .Sy canmount Ns = Ns Sy off
1165 is to have two datasets with the same
1167 so that the children of both datasets appear in the same directory, but might
1168 have different inherited characteristics.
1172 a dataset can only be mounted and unmounted explicitly.
1173 The dataset is not mounted automatically when the dataset is created or
1174 imported, nor is it mounted by the
1175 .Nm zfs Cm mount Fl a
1176 command or unmounted by the
1177 .Nm zfs Cm unmount Fl a
1180 This property is not inherited.
1182 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1183 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1184 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1186 Controls the checksum used to verify data integrity.
1187 The default value is
1189 which automatically selects an appropriate algorithm
1192 but this may change in future releases
1196 disables integrity checking on user data.
1199 not only disables integrity but also disables maintaining parity for user data.
1200 This setting is used internally by a dump device residing on a RAID-Z pool and
1201 should not be used by any other dataset.
1202 Disabling checksums is
1204 a recommended practice.
1211 checksum algorithms require enabling the appropriate features on the pool.
1212 These pool features are not supported by GRUB and must not be used on the
1213 pool if GRUB needs to access the pool (e.g. for /boot).
1216 .Xr zpool-features 5
1217 for more information on these algorithms.
1219 Changing this property affects only newly-written data.
1221 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1222 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1224 Controls the compression algorithm used for this dataset.
1226 Setting compression to
1228 indicates that the current default compression algorithm should be used.
1229 The default balances compression and decompression speed, with compression ratio
1230 and is expected to work well on a wide variety of workloads.
1231 Unlike all other settings for this property,
1233 does not select a fixed compression type.
1234 As new compression algorithms are added to ZFS and enabled on a pool, the
1235 default compression algorithm may change.
1236 The current default compression algorithm is either
1245 compression algorithm is a high-performance replacement for the
1248 It features significantly faster compression and decompression, as well as a
1249 moderately higher compression ratio than
1251 but can only be used on pools with the
1256 .Xr zpool-features 5
1257 for details on ZFS feature flags and the
1263 compression algorithm is optimized for performance while providing decent data
1268 compression algorithm uses the same compression as the
1273 level by using the value
1277 is an integer from 1
1280 .Pq best compression ratio .
1285 .Po which is also the default for
1291 compression algorithm compresses runs of zeros.
1293 This property can also be referred to by its shortened column name
1295 Changing this property affects only newly-written data.
1297 When any setting except
1299 is selected, compression will explicitly check for blocks consisting of only
1300 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
1301 a hole and not compressed using the indicated compression algorithm.
1303 Any block being compressed must be no larger than 7/8 of its original size
1304 after compression, otherwise the compression will not be considered worthwhile
1305 and the block saved uncompressed. Note that when the logical block is less than
1306 8 times the disk sector size this effectively reduces the necessary compression
1307 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
1308 or less of their original size.
1310 .Sy context Ns = Ns Sy none Ns | Ns
1311 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1313 This flag sets the SELinux context for all files in the file system under
1314 a mount point for that file system. See
1316 for more information.
1318 .Sy fscontext Ns = Ns Sy none Ns | Ns
1319 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1321 This flag sets the SELinux context for the file system file system being
1324 for more information.
1326 .Sy defcontext Ns = Ns Sy none Ns | Ns
1327 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1329 This flag sets the SELinux default context for unlabeled files. See
1331 for more information.
1333 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1334 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1336 This flag sets the SELinux context for the root inode of the file system. See
1338 for more information.
1339 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1340 Controls the number of copies of data stored for this dataset.
1341 These copies are in addition to any redundancy provided by the pool, for
1342 example, mirroring or RAID-Z.
1343 The copies are stored on different disks, if possible.
1344 The space used by multiple copies is charged to the associated file and dataset,
1347 property and counting against quotas and reservations.
1349 Changing this property only affects newly-written data.
1350 Therefore, set this property at file system creation time by using the
1351 .Fl o Sy copies Ns = Ns Ar N
1354 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1356 create, for example a two-disk striped pool and set
1358 on some datasets thinking you have setup redundancy for them. When a disk
1359 fails you will not be able to import the pool and will have lost all of your
1362 Encrypted datasets may not have
1363 .Sy copies Ns = Ns Em 3
1364 since the implementation stores some encryption metadata where the third copy
1366 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1367 Controls whether device nodes can be opened on this file system.
1368 The default value is
1374 are equivalent to the
1380 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1381 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1384 Configures deduplication for a dataset. The default value is
1386 The default deduplication checksum is
1388 (this may change in the future). When
1390 is enabled, the checksum defined here overrides the
1392 property. Setting the value to
1394 has the same effect as the setting
1399 ZFS will do a byte-to-byte comparison in case of two blocks having the same
1400 signature to make sure the block contents are identical. Specifying
1402 is mandatory for the
1406 Unless necessary, deduplication should NOT be enabled on a system. See
1410 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1411 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1413 Specifies a compatibility mode or literal value for the size of dnodes in the
1414 file system. The default value is
1416 Setting this property to a value other than
1418 requires the large_dnode pool feature to be enabled.
1424 if the dataset uses the
1426 property setting and the workload makes heavy use of extended attributes. This
1427 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1428 servers, for example. Literal values are supported for cases where the optimal
1429 size is known in advance and for performance testing.
1435 if you need to receive a send stream of this dataset on a pool that doesn't
1436 enable the large_dnode feature, or if you need to import this pool on a system
1437 that doesn't support the large_dnode feature.
1439 This property can also be referred to by its shortened column name,
1442 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1443 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1444 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1446 Controls the encryption cipher suite (block cipher, key length, and mode) used
1447 for this dataset. Requires the
1449 feature to be enabled on the pool.
1452 to be set at dataset creation time.
1455 .Sy encryption Ns = Ns Sy on
1456 when creating a dataset indicates that the default encryption suite will be
1457 selected, which is currently
1459 In order to provide consistent data protection, encryption must be specified at
1460 dataset creation time and it cannot be changed afterwards.
1462 For more details and caveats about encryption see the
1465 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1466 Controls what format the user's encryption key will be provided as. This
1467 property is only set when the dataset is encrypted.
1469 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1470 encryption suite) and must be randomly generated. A raw key can be generated
1471 with the following command:
1473 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1476 Passphrases must be between 8 and 512 bytes long and will be processed through
1477 PBKDF2 before being used (see the
1479 property). Even though the
1480 encryption suite cannot be changed after dataset creation, the keyformat can be
1482 .Nm zfs Cm change-key .
1484 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1486 Controls where the user's encryption key will be loaded from by default for
1490 .Nm zfs Cm mount Cm -l .
1491 This property is only set for encrypted datasets which are encryption roots. If
1492 unspecified, the default is
1495 Even though the encryption suite cannot be changed after dataset creation, the
1496 keylocation can be with either
1499 .Nm zfs Cm change-key .
1502 is selected ZFS will ask for the key at the command prompt when it is required
1503 to access the encrypted data (see
1505 for details). This setting will also allow the key to be passed in via STDIN,
1506 but users should be careful not to place keys which should be kept secret on
1507 the command line. If a file URI is selected, the key will be loaded from the
1508 specified absolute file path.
1509 .It Sy pbkdf2iters Ns = Ns Ar iterations
1510 Controls the number of PBKDF2 iterations that a
1512 encryption key should be run through when processing it into an encryption key.
1513 This property is only defined when encryption is enabled and a keyformat of
1515 is selected. The goal of PBKDF2 is to significantly increase the
1516 computational difficulty needed to brute force a user's passphrase. This is
1517 accomplished by forcing the attacker to run each passphrase through a
1518 computationally expensive hashing function many times before they arrive at the
1519 resulting key. A user who actually knows the passphrase will only have to pay
1520 this cost once. As CPUs become better at processing, this number should be
1521 raised to ensure that a brute force attack is still not possible. The current
1526 This property may be changed with
1527 .Nm zfs Cm change-key .
1528 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1529 Controls whether processes can be executed from within this file system.
1530 The default value is
1536 are equivalent to the
1541 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1542 Limits the number of filesystems and volumes that can exist under this point in
1544 The limit is not enforced if the user is allowed to change the limit.
1546 .Sy filesystem_limit
1549 a descendent of a filesystem that already has a
1550 .Sy filesystem_limit
1551 does not override the ancestor's
1552 .Sy filesystem_limit ,
1553 but rather imposes an additional limit.
1554 This feature must be enabled to be used
1556 .Xr zpool-features 5
1558 .It Sy special_small_blocks Ns = Ns Em size
1559 This value represents the threshold block size for including small file
1560 blocks into the special allocation class. Blocks smaller than or equal to this
1561 value will be assigned to the special allocation class while greater blocks
1562 will be assigned to the regular class. Valid values are zero or a power of two
1563 from 512B up to 128K. The default size is 0 which means no small file blocks
1564 will be allocated in the special class.
1566 Before setting this property, a special class vdev must be added to the
1569 for more details on the special allocation class.
1570 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1571 Controls the mount point used for this file system.
1574 section for more information on how this property is used.
1578 property is changed for a file system, the file system and any children that
1579 inherit the mount point are unmounted.
1582 then they remain unmounted.
1583 Otherwise, they are automatically remounted in the new location if the property
1588 or if they were mounted before the property was changed.
1589 In addition, any shared file systems are unshared and shared in the new
1591 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1592 Controls whether the file system should be mounted with
1594 .Pq Non Blocking mandatory locks .
1595 This is used for SMB clients.
1596 Changes to this property only take effect when the file system is umounted and
1600 for more information on
1602 mounts. This property is not used on Linux.
1603 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1604 Allow mounting on a busy directory or a directory which already contains
1605 files or directories. This is the default mount behavior for Linux file systems.
1606 For consistency with OpenZFS on other platforms overlay mounts are
1610 to enable overlay mounts.
1611 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1612 Controls what is cached in the primary cache
1614 If this property is set to
1616 then both user data and metadata is cached.
1617 If this property is set to
1619 then neither user data nor metadata is cached.
1620 If this property is set to
1622 then only metadata is cached.
1623 The default value is
1625 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1626 Limits the amount of space a dataset and its descendents can consume.
1627 This property enforces a hard limit on the amount of space used.
1628 This includes all space consumed by descendents, including file systems and
1630 Setting a quota on a descendent of a dataset that already has a quota does not
1631 override the ancestor's quota, but rather imposes an additional limit.
1633 Quotas cannot be set on volumes, as the
1635 property acts as an implicit quota.
1636 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1637 Limits the number of snapshots that can be created on a dataset and its
1641 on a descendent of a dataset that already has a
1643 does not override the ancestor's
1644 .Sy snapshot_limit ,
1645 but rather imposes an additional limit.
1646 The limit is not enforced if the user is allowed to change the limit.
1647 For example, this means that recursive snapshots taken from the global zone are
1648 counted against each delegated dataset within a zone.
1649 This feature must be enabled to be used
1651 .Xr zpool-features 5
1653 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1654 Limits the amount of space consumed by the specified user.
1655 User space consumption is identified by the
1656 .Sy userspace@ Ns Em user
1659 Enforcement of user quotas may be delayed by several seconds.
1660 This delay means that a user might exceed their quota before the system notices
1661 that they are over quota and begins to refuse additional writes with the
1665 .Nm zfs Cm userspace
1666 subcommand for more information.
1668 Unprivileged users can only access their own groups' space usage.
1669 The root user, or a user who has been granted the
1673 can get and set everyone's quota.
1675 This property is not available on volumes, on file systems before version 4, or
1676 on pools before version 15.
1678 .Sy userquota@ Ns Em ...
1679 properties are not displayed by
1680 .Nm zfs Cm get Sy all .
1681 The user's name must be appended after the
1683 symbol, using one of the following forms:
1691 .Em POSIX numeric ID
1698 .Sy joe.smith@mydomain
1707 Files created on Linux always have POSIX owners.
1708 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1713 but it limits the number of objects a user can create. Please refer to
1715 for more information about how objects are counted.
1716 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1717 Limits the amount of space consumed by the specified group.
1718 Group space consumption is identified by the
1719 .Sy groupused@ Ns Em group
1722 Unprivileged users can access only their own groups' space usage.
1723 The root user, or a user who has been granted the
1727 can get and set all groups' quotas.
1728 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1733 but it limits number of objects a group can consume. Please refer to
1735 for more information about how objects are counted.
1736 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1737 Limits the amount of space consumed by the specified project. Project
1738 space consumption is identified by the
1739 .Sy projectused@ Ns Em project
1740 property. Please refer to
1742 for more information about how project is identified and set/changed.
1744 The root user, or a user who has been granted the
1748 can access all projects' quota.
1749 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1754 but it limits number of objects a project can consume. Please refer to
1756 for more information about how objects are counted.
1757 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1758 Controls whether this dataset can be modified.
1759 The default value is
1765 are equivalent to the
1771 This property can also be referred to by its shortened column name,
1773 .It Sy recordsize Ns = Ns Em size
1774 Specifies a suggested block size for files in the file system.
1775 This property is designed solely for use with database workloads that access
1776 files in fixed-size records.
1777 ZFS automatically tunes block sizes according to internal algorithms optimized
1778 for typical access patterns.
1780 For databases that create very large files but access them in small random
1781 chunks, these algorithms may be suboptimal.
1784 greater than or equal to the record size of the database can result in
1785 significant performance gains.
1786 Use of this property for general purpose file systems is strongly discouraged,
1787 and may adversely affect performance.
1789 The size specified must be a power of two greater than or equal to 512 and less
1790 than or equal to 128 Kbytes.
1793 feature is enabled on the pool, the size may be up to 1 Mbyte.
1795 .Xr zpool-features 5
1796 for details on ZFS feature flags.
1798 Changing the file system's
1800 affects only files created afterward; existing files are unaffected.
1802 This property can also be referred to by its shortened column name,
1804 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1805 Controls what types of metadata are stored redundantly.
1806 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1807 the amount of user data lost is limited.
1808 This extra copy is in addition to any redundancy provided at the pool level
1809 .Pq e.g. by mirroring or RAID-Z ,
1810 and is in addition to an extra copy specified by the
1813 .Pq up to a total of 3 copies .
1814 For example if the pool is mirrored,
1815 .Sy copies Ns = Ns 2 ,
1817 .Sy redundant_metadata Ns = Ns Sy most ,
1818 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1823 ZFS stores an extra copy of all metadata.
1824 If a single on-disk block is corrupt, at worst a single block of user data
1833 ZFS stores an extra copy of most types of metadata.
1834 This can improve performance of random writes, because less metadata must be
1836 In practice, at worst about 100 blocks
1841 of user data can be lost if a single on-disk block is corrupt.
1842 The exact behavior of which metadata blocks are stored redundantly may change in
1845 The default value is
1847 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1848 Limits the amount of space a dataset can consume.
1849 This property enforces a hard limit on the amount of space used.
1850 This hard limit does not include space used by descendents, including file
1851 systems and snapshots.
1852 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1853 The minimum amount of space guaranteed to a dataset, not including its
1855 When the amount of space used is below this value, the dataset is treated as if
1856 it were taking up the amount of space specified by
1857 .Sy refreservation .
1860 reservation is accounted for in the parent datasets' space used, and counts
1861 against the parent datasets' quotas and reservations.
1865 is set, a snapshot is only allowed if there is enough free pool space outside of
1866 this reservation to accommodate the current number of
1868 bytes in the dataset.
1874 a volume is thick provisioned
1878 .Sy refreservation Ns = Ns Sy auto
1879 is only supported on volumes.
1883 .Sx Native Properties
1884 section for more information about sparse volumes.
1886 This property can also be referred to by its shortened column name,
1888 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1889 Controls the manner in which the access time is updated when
1891 is set. Turning this property on causes the access time to be updated relative
1892 to the modify or change time. Access time is only updated if the previous
1893 access time was earlier than the current modify or change time or if the
1894 existing access time hasn't been updated within the past 24 hours. The default
1901 are equivalent to the
1906 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1907 The minimum amount of space guaranteed to a dataset and its descendants.
1908 When the amount of space used is below this value, the dataset is treated as if
1909 it were taking up the amount of space specified by its reservation.
1910 Reservations are accounted for in the parent datasets' space used, and count
1911 against the parent datasets' quotas and reservations.
1913 This property can also be referred to by its shortened column name,
1915 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1916 Controls what is cached in the secondary cache
1918 If this property is set to
1920 then both user data and metadata is cached.
1921 If this property is set to
1923 then neither user data nor metadata is cached.
1924 If this property is set to
1926 then only metadata is cached.
1927 The default value is
1929 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1930 Controls whether the setuid bit is respected for the file system.
1931 The default value is
1937 are equivalent to the
1942 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1943 Controls whether the file system is shared by using
1944 .Sy Samba USERSHARES
1945 and what options are to be used. Otherwise, the file system is automatically
1946 shared and unshared with the
1950 commands. If the property is set to on, the
1952 command is invoked to create a
1955 Because SMB shares requires a resource name, a unique resource name is
1956 constructed from the dataset name. The constructed name is a copy of the
1957 dataset name except that the characters in the dataset name, which would be
1958 invalid in the resource name, are replaced with underscore (_) characters.
1959 Linux does not currently support additional options which might be available
1966 the file systems are unshared.
1968 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1969 stands for "full permissions", ie. read and write permissions) and no guest
1970 access (which means Samba must be able to authenticate a real user, system
1971 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1972 additional access control (disallow specific user specific access etc) must
1973 be done on the underlying file system.
1974 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1975 Controls whether the file system is shared via NFS, and what options are to be
1977 A file system with a
1983 command and entries in the
1986 Otherwise, the file system is automatically shared and unshared with the
1991 If the property is set to
1993 the dataset is shared using the default options:
1995 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1999 for the meaning of the default options. Otherwise, the
2001 command is invoked with options equivalent to the contents of this property.
2005 property is changed for a dataset, the dataset and any children inheriting the
2006 property are re-shared with the new options, only if the property was previously
2008 or if they were shared before the property was changed.
2009 If the new property is
2011 the file systems are unshared.
2012 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
2013 Provide a hint to ZFS about handling of synchronous requests in this dataset.
2019 ZFS will use pool log devices
2021 to handle the requests at low latency.
2026 ZFS will not use configured pool log devices.
2027 ZFS will instead optimize synchronous operations for global pool throughput and
2028 efficient use of resources.
2029 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
2030 Controls whether the volume snapshot devices under
2031 .Em /dev/zvol/<pool>
2032 are hidden or visible. The default value is
2034 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
2035 Controls whether the
2037 directory is hidden or visible in the root of the file system as discussed in
2041 The default value is
2043 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
2044 Controls the behavior of synchronous requests
2045 .Pq e.g. fsync, O_DSYNC .
2049 specified behavior of ensuring all synchronous requests are written to stable
2050 storage and all devices are flushed to ensure data is not cached by device
2052 .Pq this is the default .
2054 causes every file system transaction to be written and flushed before its
2055 system call returns.
2056 This has a large performance penalty.
2058 disables synchronous requests.
2059 File system transactions are only committed to stable storage periodically.
2060 This option will give the highest performance.
2061 However, it is very dangerous as ZFS would be ignoring the synchronous
2062 transaction demands of applications such as databases or NFS.
2063 Administrators should only use this option when the risks are understood.
2064 .It Sy version Ns = Ns Em N Ns | Ns Sy current
2065 The on-disk version of this file system, which is independent of the pool
2067 This property can only be set to later supported versions.
2071 .It Sy volsize Ns = Ns Em size
2072 For volumes, specifies the logical size of the volume.
2073 By default, creating a volume establishes a reservation of equal size.
2074 For storage pools with a version number of 9 or higher, a
2079 are reflected in an equivalent change to the reservation
2085 can only be set to a multiple of
2089 The reservation is kept equal to the volume's logical size to prevent unexpected
2090 behavior for consumers.
2091 Without the reservation, the volume could run out of space, resulting in
2092 undefined behavior or data corruption, depending on how the volume is used.
2093 These effects can also occur when the volume size is changed while it is in use
2094 .Pq particularly when shrinking the size .
2095 Extreme care should be used when adjusting the volume size.
2097 Though not recommended, a
2100 .Qq thin provisioned
2102 can be created by specifying the
2105 .Nm zfs Cm create Fl V
2106 command, or by changing the value of the
2111 property on pool version 8 or earlier
2113 after the volume has been created.
2116 is a volume where the value of
2118 is less than the size of the volume plus the space required to store its
2120 Consequently, writes to a sparse volume can fail with
2122 when the pool is low on space.
2123 For a sparse volume, changes to
2125 are not reflected in the
2127 A volume that is not sparse is said to be
2128 .Qq thick provisioned .
2129 A sparse volume can become thick provisioned by setting
2133 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2134 This property specifies how volumes should be exposed to the OS.
2137 exposes volumes as fully fledged block devices, providing maximal
2138 functionality. The value
2140 is just an alias for
2142 and is kept for compatibility.
2145 hides its partitions.
2146 Volumes with property set to
2148 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
2149 that can be suitable for backup purposes.
2152 means that volumes exposition is controlled by system-wide tunable
2159 are encoded as 1, 2 and 3 respectively.
2160 The default values is
2162 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2163 Controls whether regular files should be scanned for viruses when a file is
2165 In addition to enabling this property, the virus scan service must also be
2166 enabled for virus scanning to occur.
2167 The default value is
2169 This property is not used on Linux.
2170 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2171 Controls whether extended attributes are enabled for this file system. Two
2172 styles of extended attributes are supported either directory based or system
2175 The default value of
2177 enables directory based extended attributes. This style of extended attribute
2178 imposes no practical limit on either the size or number of attributes which
2179 can be set on a file. Although under Linux the
2183 system calls limit the maximum size to 64K. This is the most compatible
2184 style of extended attribute and is supported by all OpenZFS implementations.
2186 System attribute based xattrs can be enabled by setting the value to
2188 The key advantage of this type of xattr is improved performance. Storing
2189 extended attributes as system attributes significantly decreases the amount of
2190 disk IO required. Up to 64K of data may be stored per-file in the space
2191 reserved for system attributes. If there is not enough space available for
2192 an extended attribute then it will be automatically written as a directory
2193 based xattr. System attribute based extended attributes are not accessible
2194 on platforms which do not support the
2198 The use of system attribute based xattrs is strongly encouraged for users of
2199 SELinux or POSIX ACLs. Both of these features heavily rely of extended
2200 attributes and benefit significantly from the reduced access time.
2206 are equivalent to the
2211 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2212 Controls whether the dataset is managed from a non-global zone. Zones are a
2213 Solaris feature and are not relevant on Linux. The default value is
2217 The following three properties cannot be changed after the file system is
2218 created, and therefore, should be set when the file system is created.
2219 If the properties are not set with the
2223 commands, these properties are inherited from the parent dataset.
2224 If the parent dataset lacks these properties due to having been created prior to
2225 these features being supported, the new file system will have the default values
2226 for these properties.
2229 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2230 .Sy insensitive Ns | Ns Sy mixed
2232 Indicates whether the file name matching algorithm used by the file system
2233 should be case-sensitive, case-insensitive, or allow a combination of both
2235 The default value for the
2243 file systems have case-sensitive file names.
2249 property indicates that the file system can support requests for both
2250 case-sensitive and case-insensitive matching behavior.
2251 Currently, case-insensitive matching behavior on a file system that supports
2252 mixed behavior is limited to the SMB server product.
2253 For more information about the
2255 value behavior, see the "ZFS Administration Guide".
2257 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2258 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2260 Indicates whether the file system should perform a
2262 normalization of file names whenever two file names are compared, and which
2263 normalization algorithm should be used.
2264 File names are always stored unmodified, names are normalized as part of any
2266 If this property is set to a legal value other than
2270 property was left unspecified, the
2272 property is automatically set to
2274 The default value of the
2278 This property cannot be changed after the file system is created.
2279 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2280 Indicates whether the file system should reject file names that include
2281 characters that are not present in the
2284 If this property is explicitly set to
2286 the normalization property must either not be explicitly set or be set to
2288 The default value for the
2292 This property cannot be changed after the file system is created.
2296 .Sy casesensitivity ,
2300 properties are also new permissions that can be assigned to non-privileged users
2301 by using the ZFS delegated administration feature.
2302 .Ss "Temporary Mount Point Properties"
2303 When a file system is mounted, either through
2305 for legacy mounts or the
2307 command for normal file systems, its mount options are set according to its
2309 The correlation between properties and mount options is as follows:
2311 PROPERTY MOUNT OPTION
2313 canmount auto/noauto
2317 relatime relatime/norelatime
2322 In addition, these options can be set on a per-mount basis using the
2324 option, without affecting the property that is stored on disk.
2325 The values specified on the command line override the values stored in the
2329 option is an alias for
2330 .Sy nodevices Ns \&, Ns Sy nosetuid .
2331 These properties are reported as
2336 If the properties are changed while the dataset is mounted, the new setting
2337 overrides any temporary settings.
2338 .Ss "User Properties"
2339 In addition to the standard native properties, ZFS supports arbitrary user
2341 User properties have no effect on ZFS behavior, but applications or
2342 administrators can use them to annotate datasets
2343 .Pq file systems, volumes, and snapshots .
2345 User property names must contain a colon
2347 character to distinguish them from native properties.
2348 They may contain lowercase letters, numbers, and the following punctuation
2357 The expected convention is that the property name is divided into two portions
2359 .Em module Ns \&: Ns Em property ,
2360 but this namespace is not enforced by ZFS.
2361 User property names can be at most 256 characters, and cannot begin with a dash
2364 When making programmatic use of user properties, it is strongly suggested to use
2369 component of property names to reduce the chance that two
2370 independently-developed packages use the same property name for different
2373 The values of user properties are arbitrary strings, are always inherited, and
2374 are never validated.
2375 All of the commands that operate on properties
2376 .Po Nm zfs Cm list ,
2381 can be used to manipulate both native properties and user properties.
2384 command to clear a user property.
2385 If the property is not defined in any parent dataset, it is removed entirely.
2386 Property values are limited to 8192 bytes.
2387 .Ss ZFS Volumes as Swap
2388 ZFS volumes may be used as swap devices. After creating the volume with the
2389 .Nm zfs Cm create Fl V
2390 command set up and enable the swap area using the
2394 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2395 configuration is not supported.
2399 feature allows for the creation of encrypted filesystems and volumes. ZFS
2400 will encrypt file and zvol data, file attributes, ACLs, permission bits,
2401 directory listings, FUID mappings, and
2405 data. ZFS will not encrypt metadata related to the pool structure, including
2406 dataset and snapshot names, dataset hierarchy, properties, file size, file
2407 holes, and deduplication tables (though the deduplicated data itself is
2410 Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase)
2411 does not require re-encrypting the entire dataset. Datasets can be scrubbed,
2412 resilvered, renamed, and deleted without the encryption keys being loaded (see the
2414 subcommand for more info on key loading).
2416 Creating an encrypted dataset requires specifying the
2420 properties at creation time, along with an optional
2424 After entering an encryption key, the
2425 created dataset will become an encryption root. Any descendant datasets will
2426 inherit their encryption key from the encryption root by default, meaning that
2427 loading, unloading, or changing the key for the encryption root will implicitly
2428 do the same for all inheriting datasets. If this inheritance is not desired,
2431 when creating the child dataset or use
2432 .Nm zfs Cm change-key
2433 to break an existing relationship, creating a new encryption root on the child.
2434 Note that the child's
2436 may match that of the parent while still creating a new encryption root, and
2439 property alone does not create a new encryption root; this would simply use a
2440 different cipher suite with the same key as its encryption root. The one
2441 exception is that clones will always use their origin's encryption key.
2442 As a result of this exception, some encryption-related properties (namely
2448 do not inherit like other ZFS properties and instead use the value determined
2449 by their encryption root. Encryption root inheritance can be tracked via the
2454 Encryption changes the behavior of a few ZFS
2455 operations. Encryption is applied after compression so compression ratios are
2456 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2457 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2458 the encryption suite, which provides additional protection against maliciously
2459 altered data. Deduplication is still possible with encryption enabled but for
2460 security, datasets will only dedup against themselves, their snapshots, and
2463 There are a few limitations on encrypted datasets. Encrypted data cannot be
2466 feature. Encrypted datasets may not have
2467 .Sy copies Ns = Ns Em 3
2468 since the implementation stores some encryption metadata where the third copy
2469 would normally be. Since compression is applied before encryption datasets may
2470 be vulnerable to a CRIME-like attack if applications accessing the data allow
2471 for it. Deduplication with encryption will leak information about which blocks
2472 are equivalent in a dataset and will incur an extra CPU cost per block written.
2474 ZFS has support for a limited version of data subsetting, in the form of
2475 redaction. Using the
2478 .Sy redaction bookmark
2479 can be created that stores a list of blocks containing sensitive information. When
2485 to occur. Redacted sends omit the blocks containing sensitive information,
2486 replacing them with REDACT records. When these send streams are received, a
2487 .Sy redacted dataset
2488 is created. A redacted dataset cannot be mounted by default, since it is
2489 incomplete. It can be used to receive other send streams. In this way datasets
2490 can be used for data backup and replication, with all the benefits that zfs send
2491 and receive have to offer, while protecting sensitive information from being
2492 stored on less-trusted machines or services.
2494 For the purposes of redaction, there are two steps to the process. A redact
2495 step, and a send/receive step. First, a redaction bookmark is created. This is
2496 done by providing the
2498 command with a parent snapshot, a bookmark to be created, and a number of
2499 redaction snapshots. These redaction snapshots must be descendants of the
2500 parent snapshot, and they should modify data that is considered sensitive in
2501 some way. Any blocks of data modified by all of the redaction snapshots will
2502 be listed in the redaction bookmark, because it represents the truly sensitive
2503 information. When it comes to the send step, the send process will not send
2504 the blocks listed in the redaction bookmark, instead replacing them with
2505 REDACT records. When received on the target system, this will create a
2506 redacted dataset, missing the data that corresponds to the blocks in the
2507 redaction bookmark on the sending system. The incremental send streams from
2508 the original parent to the redaction snapshots can then also be received on
2509 the target system, and this will produce a complete snapshot that can be used
2510 normally. Incrementals from one snapshot on the parent filesystem and another
2511 can also be done by sending from the redaction bookmark, rather than the
2512 snapshots themselves.
2514 In order to make the purpose of the feature more clear, an example is
2515 provided. Consider a zfs filesystem containing four files. These files
2516 represent information for an online shopping service. One file contains a list
2517 of usernames and passwords, another contains purchase histories, a third
2518 contains click tracking data, and a fourth contains user preferences. The
2519 owner of this data wants to make it available for their development teams to
2520 test against, and their market research teams to do analysis on. The
2521 development teams need information about user preferences and the click
2522 tracking data, while the market research teams need information about purchase
2523 histories and user preferences. Neither needs access to the usernames and
2524 passwords. However, because all of this data is stored in one ZFS filesystem,
2525 it must all be sent and received together. In addition, the owner of the data
2526 wants to take advantage of features like compression, checksumming, and
2527 snapshots, so they do want to continue to use ZFS to store and transmit their
2528 data. Redaction can help them do so. First, they would make two clones of a
2529 snapshot of the data on the source. In one clone, they create the setup they
2530 want their market research team to see; they delete the usernames and
2531 passwords file, and overwrite the click tracking data with dummy
2532 information. In another, they create the setup they want the development teams
2533 to see, by replacing the passwords with fake information and replacing the
2534 purchase histories with randomly generated ones. They would then create a
2535 redaction bookmark on the parent snapshot, using snapshots on the two clones
2536 as redaction snapshots. The parent can then be sent, redacted, to the target
2537 server where the research and development teams have access. Finally,
2538 incremental sends from the parent snapshot to each of the clones can be send
2539 to and received on the target server; these snapshots are identical to the
2540 ones on the source, and are ready to be used, while the parent snapshot on the
2541 target contains none of the username and password data present on the source,
2542 because it was removed by the redacted send operation.
2544 All subcommands that modify state are logged persistently to the pool in their
2548 Displays a help message.
2560 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2563 Creates a new ZFS file system.
2564 The file system is automatically mounted according to the
2566 property inherited from the parent.
2567 .Bl -tag -width "-o"
2568 .It Fl o Ar property Ns = Ns Ar value
2569 Sets the specified property as if the command
2570 .Nm zfs Cm set Ar property Ns = Ns Ar value
2571 was invoked at the same time the dataset was created.
2572 Any editable ZFS property can also be set at creation time.
2575 options can be specified.
2576 An error results if the same property is specified in multiple
2580 Creates all the non-existing parent datasets.
2581 Datasets created in this manner are automatically mounted according to the
2583 property inherited from their parent.
2584 Any property specified on the command line using the
2587 If the target filesystem already exists, the operation completes successfully.
2592 No datasets will be created.
2593 This is useful in conjunction with the
2597 flags to validate properties that are passed via
2599 options and those implied by other options.
2600 The actual dataset creation can still fail due to insufficient privileges or
2603 Print machine-parsable verbose information about the created dataset.
2604 Each line of output contains a key and one or two values, all separated by tabs.
2606 .Sy create_ancestors
2611 as their only value.
2613 .Sy create_ancestors
2614 key only appears if the
2619 key has two values, a property name that property's value.
2622 key may appear zero or more times, once for each property that will be set local
2625 due to the use of the
2629 Print verbose information about the created dataset.
2635 .Op Fl b Ar blocksize
2636 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2637 .Fl V Ar size Ar volume
2639 Creates a volume of the given size.
2640 The volume is exported as a block device in
2641 .Pa /dev/zvol/path ,
2644 is the name of the volume in the ZFS namespace.
2645 The size represents the logical size as exported by the device.
2646 By default, a reservation of equal size is created.
2649 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2650 has an integral number of blocks regardless of
2652 .Bl -tag -width "-b"
2653 .It Fl b Ar blocksize
2655 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2656 If this option is specified in conjunction with
2657 .Fl o Sy volblocksize ,
2658 the resulting behavior is undefined.
2659 .It Fl o Ar property Ns = Ns Ar value
2660 Sets the specified property as if the
2661 .Nm zfs Cm set Ar property Ns = Ns Ar value
2662 command was invoked at the same time the dataset was created.
2663 Any editable ZFS property can also be set at creation time.
2666 options can be specified.
2667 An error results if the same property is specified in multiple
2671 Creates all the non-existing parent datasets.
2672 Datasets created in this manner are automatically mounted according to the
2674 property inherited from their parent.
2675 Any property specified on the command line using the
2678 If the target filesystem already exists, the operation completes successfully.
2680 Creates a sparse volume with no reservation.
2684 .Sx Native Properties
2685 section for more information about sparse volumes.
2690 No datasets will be created.
2691 This is useful in conjunction with the
2695 flags to validate properties that are passed via
2697 options and those implied by other options.
2698 The actual dataset creation can still fail due to insufficient privileges or
2701 Print machine-parsable verbose information about the created dataset.
2702 Each line of output contains a key and one or two values, all separated by tabs.
2704 .Sy create_ancestors
2709 as their only value.
2711 .Sy create_ancestors
2712 key only appears if the
2717 key has two values, a property name that property's value.
2720 key may appear zero or more times, once for each property that will be set local
2723 due to the use of the
2729 if the volume is not sparse.
2731 Print verbose information about the created dataset.
2737 .Ar filesystem Ns | Ns Ar volume
2739 Destroys the given dataset.
2740 By default, the command unshares any file systems that are currently shared,
2741 unmounts any file systems that are currently mounted, and refuses to destroy a
2742 dataset that has active dependents
2743 .Pq children or clones .
2744 .Bl -tag -width "-R"
2746 Recursively destroy all dependents, including cloned file systems outside the
2749 Force an unmount of any file systems using the
2752 This option has no effect on non-file systems or unmounted file systems.
2757 No data will be deleted.
2758 This is useful in conjunction with the
2762 flags to determine what data would be deleted.
2764 Print machine-parsable verbose information about the deleted data.
2766 Recursively destroy all children.
2768 Print verbose information about the deleted data.
2771 Extreme care should be taken when applying either the
2775 options, as they can destroy large portions of a pool and cause unexpected
2776 behavior for mounted file systems in use.
2781 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2782 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2784 The given snapshots are destroyed immediately if and only if the
2788 option would have destroyed it.
2789 Such immediate destruction would occur, for example, if the snapshot had no
2790 clones and the user-initiated reference count were zero.
2792 If a snapshot does not qualify for immediate destruction, it is marked for
2794 In this state, it exists as a usable, visible snapshot until both of the
2795 preconditions listed above are met, at which point it is destroyed.
2797 An inclusive range of snapshots may be specified by separating the first and
2798 last snapshots with a percent sign.
2799 The first and/or last snapshots may be left blank, in which case the
2800 filesystem's oldest or newest snapshot will be implied.
2803 .Pq or ranges of snapshots
2804 of the same filesystem or volume may be specified in a comma-separated list of
2806 Only the snapshot's short name
2807 .Po the part after the
2810 should be specified when using a range or comma-separated list to identify
2812 .Bl -tag -width "-R"
2814 Recursively destroy all clones of these snapshots, including the clones,
2815 snapshots, and children.
2816 If this flag is specified, the
2818 flag will have no effect.
2820 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2821 deferred destruction.
2826 No data will be deleted.
2827 This is useful in conjunction with the
2831 flags to determine what data would be deleted.
2833 Print machine-parsable verbose information about the deleted data.
2836 .Pq or mark for deferred deletion
2837 all snapshots with this name in descendent file systems.
2839 Print verbose information about the deleted data.
2841 Extreme care should be taken when applying either the
2845 options, as they can destroy large portions of a pool and cause unexpected
2846 behavior for mounted file systems in use.
2851 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2853 The given bookmark is destroyed.
2858 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2859 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2861 Creates snapshots with the given names.
2862 All previous modifications by successful system calls to the file system are
2863 part of the snapshots.
2864 Snapshots are taken atomically, so that all snapshots correspond to the same
2867 can be used as an alias for
2868 .Nm zfs Cm snapshot.
2871 section for details.
2872 .Bl -tag -width "-o"
2873 .It Fl o Ar property Ns = Ns Ar value
2874 Sets the specified property; see
2878 Recursively create snapshots of all descendent datasets
2886 Roll back the given dataset to a previous snapshot.
2887 When a dataset is rolled back, all data that has changed since the snapshot is
2888 discarded, and the dataset reverts to the state at the time of the snapshot.
2889 By default, the command refuses to roll back to a snapshot other than the most
2891 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2898 options do not recursively destroy the child snapshots of a recursive snapshot.
2899 Only direct snapshots of the specified filesystem are destroyed by either of
2901 To completely roll back a recursive snapshot, you must rollback the individual
2903 .Bl -tag -width "-R"
2905 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2910 option to force an unmount of any clone file systems that are to be destroyed.
2912 Destroy any snapshots and bookmarks more recent than the one specified.
2918 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2919 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2921 Creates a clone of the given snapshot.
2924 section for details.
2925 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2926 as the same type as the original.
2927 .Bl -tag -width "-o"
2928 .It Fl o Ar property Ns = Ns Ar value
2929 Sets the specified property; see
2933 Creates all the non-existing parent datasets.
2934 Datasets created in this manner are automatically mounted according to the
2936 property inherited from their parent.
2937 If the target filesystem or volume already exists, the operation completes
2943 .Ar clone-filesystem
2945 Promotes a clone file system to no longer be dependent on its
2948 This makes it possible to destroy the file system that the clone was created
2950 The clone parent-child dependency relationship is reversed, so that the origin
2951 file system becomes a clone of the specified file system.
2953 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2954 now owned by the promoted clone.
2955 The space they use moves from the origin file system to the promoted clone, so
2956 enough space must be available to accommodate these snapshots.
2957 No new space is consumed by this operation, but the space accounting is
2959 The promoted clone must not have any conflicting snapshot names of its own.
2962 subcommand can be used to rename any conflicting snapshots.
2967 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2968 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2974 .Ar filesystem Ns | Ns Ar volume
2975 .Ar filesystem Ns | Ns Ar volume
2977 Renames the given dataset.
2978 The new target can be located anywhere in the ZFS hierarchy, with the exception
2980 Snapshots can only be renamed within the parent file system or volume.
2981 When renaming a snapshot, the parent file system of the snapshot does not need
2982 to be specified as part of the second argument.
2983 Renamed file systems can inherit new mount points, in which case they are
2984 unmounted and remounted at the new mount point.
2985 .Bl -tag -width "-a"
2987 Force unmount any filesystems that need to be unmounted in the process.
2989 Creates all the nonexistent parent datasets.
2990 Datasets created in this manner are automatically mounted according to the
2992 property inherited from their parent.
2998 .Ar snapshot Ar snapshot
3000 Recursively rename the snapshots of all descendent datasets.
3001 Snapshots are the only dataset that can be renamed recursively.
3005 .Op Fl r Ns | Ns Fl d Ar depth
3007 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
3008 .Oo Fl s Ar property Oc Ns ...
3009 .Oo Fl S Ar property Oc Ns ...
3010 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3011 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
3013 Lists the property information for the given datasets in tabular form.
3014 If specified, you can list property information by the absolute pathname or the
3016 By default, all file systems and volumes are displayed.
3017 Snapshots are displayed if the
3024 The following fields are displayed:
3025 .Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns .
3026 .Bl -tag -width "-H"
3028 Used for scripting mode.
3029 Do not print headers and separate fields by a single tab instead of arbitrary
3031 .It Fl S Ar property
3034 option, but sorts by property in descending order.
3036 Recursively display any children of the dataset, limiting the recursion to
3042 will display only the dataset and its direct children.
3043 .It Fl o Ar property
3044 A comma-separated list of properties to display.
3045 The property must be:
3048 One of the properties described in the
3049 .Sx Native Properties
3056 to display the dataset name
3060 to display space usage properties on file systems and volumes.
3061 This is a shortcut for specifying
3062 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
3063 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
3064 .Sy filesystem Ns \&, Ns Sy volume
3068 Display numbers in parsable
3072 Recursively display any children of the dataset on the command line.
3073 .It Fl s Ar property
3074 A property for sorting the output by column in ascending order based on the
3075 value of the property.
3076 The property must be one of the properties described in the
3078 section or the value
3080 to sort by the dataset name.
3081 Multiple properties can be specified at one time using multiple
3086 options are evaluated from left to right in decreasing order of importance.
3087 The following is a list of sorting criteria:
3090 Numeric types sort in numeric order.
3092 String types sort in alphabetical order.
3094 Types inappropriate for a row sort that row to the literal bottom, regardless of
3095 the specified ordering.
3098 If no sorting options are specified the existing behavior of
3102 A comma-separated list of types to display, where
3111 For example, specifying
3113 displays only snapshots.
3118 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
3119 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3121 Sets the property or list of properties to the given value(s) for each dataset.
3122 Only some properties can be edited.
3125 section for more information on what properties can be set and acceptable
3127 Numeric values can be specified as exact values, or in a human-readable form
3129 .Sy B , K , M , G , T , P , E , Z
3130 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
3131 or zettabytes, respectively
3133 User properties can be set on snapshots.
3134 For more information, see the
3140 .Op Fl r Ns | Ns Fl d Ar depth
3142 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3143 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
3144 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3145 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
3146 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ...
3148 Displays properties for the given datasets.
3149 If no datasets are specified, then the command displays properties for all
3150 datasets on the system.
3151 For each property, the following columns are displayed:
3154 property Property name
3155 value Property value
3156 source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP,
3157 \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP).
3160 All columns are displayed by default, though this can be controlled by using the
3163 This command takes a comma-separated list of properties as described in the
3164 .Sx Native Properties
3171 can be used to display all properties that apply to the given dataset's type
3172 .Pq filesystem, volume, snapshot, or bookmark .
3173 .Bl -tag -width "-H"
3175 Display output in a form more easily parsed by scripts.
3176 Any headers are omitted, and fields are explicitly separated by a single tab
3177 instead of an arbitrary amount of space.
3179 Recursively display any children of the dataset, limiting the recursion to
3183 will display only the dataset and its direct children.
3185 A comma-separated list of columns to display.
3186 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
3187 is the default value.
3189 Display numbers in parsable
3193 Recursively display properties for any children.
3195 A comma-separated list of sources to display.
3196 Those properties coming from a source other than those in this list are ignored.
3197 Each source must be one of the following:
3205 The default value is all sources.
3207 A comma-separated list of types to display, where
3221 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3223 Clears the specified property, causing it to be inherited from an ancestor,
3224 restored to default if no ancestor has the property set, or with the
3226 option reverted to the received value if one exists.
3229 section for a listing of default values, and details on which properties can be
3231 .Bl -tag -width "-r"
3233 Recursively inherit the given property for all children.
3235 Revert the property to the received value if one exists; otherwise operate as
3238 option was not specified.
3244 Displays a list of file systems that are not the most recent version.
3250 Displays a list of currently supported file system versions.
3256 .Fl a | Ar filesystem
3258 Upgrades file systems to a new on-disk version.
3259 Once this is done, the file systems will no longer be accessible on systems
3260 running older versions of the software.
3262 streams generated from new snapshots of these file systems cannot be accessed on
3263 systems running older versions of the software.
3265 In general, the file system version is independent of the pool version.
3268 for information on the
3269 .Nm zpool Cm upgrade
3272 In some cases, the file system version and the pool version are interrelated and
3273 the pool version must be upgraded before the file system version can be
3275 .Bl -tag -width "-V"
3277 Upgrade to the specified
3281 flag is not specified, this command upgrades to the most recent version.
3283 option can only be used to increase the version number, and only up to the most
3284 recent version supported by this software.
3286 Upgrade all file systems on all imported pools.
3288 Upgrade the specified file system.
3290 Upgrade the specified file system and all descendent file systems.
3296 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3297 .Oo Fl s Ar field Oc Ns ...
3298 .Oo Fl S Ar field Oc Ns ...
3299 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3300 .Ar filesystem Ns | Ns Ar snapshot
3302 Displays space consumed by, and quotas on, each user in the specified filesystem
3304 This corresponds to the
3305 .Sy userused@ Ns Em user ,
3306 .Sy userobjused@ Ns Em user ,
3307 .Sy userquota@ Ns Em user,
3309 .Sy userobjquota@ Ns Em user
3311 .Bl -tag -width "-H"
3313 Do not print headers, use tab-delimited output.
3315 Sort by this field in reverse order.
3319 Translate SID to POSIX ID.
3320 The POSIX ID may be ephemeral if no mapping exists.
3321 Normal POSIX interfaces
3326 perform this translation, so the
3328 option allows the output from
3329 .Nm zfs Cm userspace
3330 to be compared directly with those utilities.
3333 may lead to confusion if some files were created by an SMB user before a
3334 SMB-to-POSIX name mapping was established.
3335 In such a case, some files will be owned by the SMB entity and some by the POSIX
3339 option will report that the POSIX entity has the total usage and quota for both.
3341 Print numeric ID instead of user/group name.
3342 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3343 Display only the specified fields from the following set:
3348 The default is to display all fields.
3354 Sort output by this field.
3359 flags may be specified multiple times to sort first by one field, then by
3362 .Fl s Sy type Fl s Sy name .
3363 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3364 Print only the specified types from the following set:
3371 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3372 The default can be changed to include group types.
3378 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3379 .Oo Fl s Ar field Oc Ns ...
3380 .Oo Fl S Ar field Oc Ns ...
3381 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3382 .Ar filesystem Ns | Ns Ar snapshot
3384 Displays space consumed by, and quotas on, each group in the specified
3385 filesystem or snapshot.
3386 This subcommand is identical to
3387 .Nm zfs Cm userspace ,
3388 except that the default types to display are
3389 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3394 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3395 .Oo Fl s Ar field Oc Ns ...
3396 .Oo Fl S Ar field Oc Ns ...
3397 .Ar filesystem Ns | Ns Ar snapshot
3399 Displays space consumed by, and quotas on, each project in the specified
3400 filesystem or snapshot. This subcommand is identical to
3401 .Nm zfs Cm userspace ,
3402 except that the project identifier is numeral, not name. So need neither
3405 for SID to POSIX ID nor
3413 .Oo Fl d Ns | Ns Fl r Ns Oc
3414 .Ar file Ns | Ns Ar directory Ns ...
3416 List project identifier (ID) and inherit flag of file(s) or directories.
3417 .Bl -tag -width "-d"
3419 Show the directory project ID and inherit flag, not its children. It will
3420 overwrite the former specified
3424 Show on subdirectories recursively. It will overwrite the former specified
3433 .Ar file Ns | Ns Ar directory Ns ...
3435 Clear project inherit flag and/or ID on the file(s) or directories.
3436 .Bl -tag -width "-k"
3438 Keep the project ID unchanged. If not specified, the project ID will be reset
3441 Clear on subdirectories recursively.
3448 .Oo Fl d Ns | Ns Fl r Ns Oc
3450 .Ar file Ns | Ns Ar directory Ns ...
3452 Check project ID and inherit flag on the file(s) or directories, report the
3453 entries without project inherit flag or with different project IDs from the
3456 option) value or the target directory's project ID.
3457 .Bl -tag -width "-0"
3459 Print file name with a trailing NUL instead of newline (by default), like
3462 Check the directory project ID and inherit flag, not its children. It will
3463 overwrite the former specified
3467 Specify the referenced ID for comparing with the target file(s) or directories'
3468 project IDs. If not specified, the target (top) directory's project ID will be
3469 used as the referenced one.
3471 Check on subdirectories recursively. It will overwrite the former specified
3480 .Ar file Ns | Ns Ar directory Ns ...
3482 .Bl -tag -width "-p"
3483 Set project ID and/or inherit flag on the file(s) or directories.
3485 Set the file(s)' or directories' project ID with the given value.
3487 Set on subdirectories recursively.
3489 Set project inherit flag on the given file(s) or directories. It is usually used
3490 for setup tree quota on the directory target with
3492 option specified together. When setup tree quota, by default the directory's
3493 project ID will be set to all its descendants unless you specify the project
3502 Displays all ZFS file systems currently mounted.
3508 .Fl a | Ar filesystem
3510 Mount ZFS filesystem on a path described by its
3512 property, if the path exists and is empty. If
3516 the filesystem should be instead mounted using
3518 .Bl -tag -width "-O"
3520 Perform an overlay mount. Allows mounting in non-empty
3524 for more information.
3526 Mount all available ZFS file systems.
3527 Invoked automatically as part of the boot process if configured.
3529 Mount the specified filesystem.
3531 An optional, comma-separated list of mount options to use temporarily for the
3532 duration of the mount.
3534 .Sx Temporary Mount Point Properties
3535 section for details.
3537 Load keys for encrypted filesystems as they are being mounted. This is
3538 equivalent to executing
3540 on each encryption root before mounting it. Note that if a filesystem has a
3544 this will cause the terminal to interactively block after asking for the key.
3546 Report mount progress.
3548 Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets).
3554 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3556 Unmounts currently mounted ZFS file systems.
3557 .Bl -tag -width "-a"
3559 Unmount all available ZFS file systems.
3560 Invoked automatically as part of the shutdown process.
3562 Forcefully unmount the file system, even if it is currently in use.
3564 Unload keys for any encryption roots unmounted by this command.
3566 .It Ar filesystem Ns | Ns Ar mountpoint
3567 Unmount the specified filesystem.
3568 The command can also be given a path to a ZFS file system mount point on the
3573 .Fl a | Ar filesystem
3575 Shares available ZFS file systems.
3576 .Bl -tag -width "-a"
3578 Share all available ZFS file systems.
3579 Invoked automatically as part of the boot process.
3581 Share the specified filesystem according to the
3586 File systems are shared when the
3595 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3597 Unshares currently shared ZFS file systems.
3598 .Bl -tag -width "-a"
3600 Unshare all available ZFS file systems.
3601 Invoked automatically as part of the shutdown process.
3602 .It Ar filesystem Ns | Ns Ar mountpoint
3603 Unshare the specified filesystem.
3604 The command can also be given a path to a ZFS file system shared on the system.
3609 .Ar snapshot bookmark
3611 Creates a bookmark of the given snapshot.
3612 Bookmarks mark the point in time when the snapshot was created, and can be used
3613 as the incremental source for a
3617 This feature must be enabled to be used.
3619 .Xr zpool-features 5
3620 for details on ZFS feature flags and the
3627 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3630 Creates a stream representation of the second
3632 which is written to standard output.
3633 The output can be redirected to a file or to a different system
3634 .Po for example, using
3637 By default, a full stream is generated.
3638 .Bl -tag -width "-D"
3640 Generate a deduplicated stream.
3641 Blocks which would have been sent multiple times in the send stream will only be
3643 The receiving system must also support this feature to receive a deduplicated
3645 This flag can be used regardless of the dataset's
3647 property, but performance will be much better if the filesystem uses a
3648 dedup-capable checksum
3652 .It Fl I Ar snapshot
3653 Generate a stream package that sends all intermediary snapshots from the first
3654 snapshot to the second snapshot.
3658 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3659 The incremental source may be specified as with the
3662 .It Fl L, -large-block
3663 Generate a stream which may contain blocks larger than 128KB.
3664 This flag has no effect if the
3666 pool feature is disabled, or if the
3668 property of this filesystem has never been set above 128KB.
3669 The receiving system must have the
3671 pool feature enabled as well.
3673 .Xr zpool-features 5
3674 for details on ZFS feature flags and the
3678 Print machine-parsable verbose information about the stream package generated.
3679 .It Fl R, -replicate
3680 Generate a replication stream package, which will replicate the specified
3681 file system, and all descendent file systems, up to the named snapshot.
3682 When received, all properties, snapshots, descendent file systems, and clones
3689 flags are used in conjunction with the
3691 flag, an incremental replication stream is generated.
3692 The current values of properties, and current snapshot and file system names are
3693 set when the stream is received.
3696 flag is specified when this stream is received, snapshots and file systems that
3697 do not exist on the sending side are destroyed. If the
3699 flag is used to send encrypted datasets, then
3701 must also be specified.
3703 Generate a more compact stream by using
3705 records for blocks which are stored more compactly on disk by the
3708 This flag has no effect if the
3710 feature is disabled.
3711 The receiving system must have the
3716 feature is active on the sending system, then the receiving system must have
3717 that feature enabled as well. Datasets that are sent with this flag may not be
3718 received as an encrypted dataset, since encrypted datasets cannot use the
3722 .Xr zpool-features 5
3723 for details on ZFS feature flags and the
3727 Sends only received property values whether or not they are overridden by local
3728 settings, but only if the dataset has ever been received. Use this option when
3731 to restore received properties backed up on the sent dataset and to avoid
3732 sending local settings that may have nothing to do with the source dataset,
3733 but only with how the data is backed up.
3734 .It Fl c, -compressed
3735 Generate a more compact stream by using compressed WRITE records for blocks
3736 which are compressed on disk and in memory
3739 property for details
3743 feature is active on the sending system, then the receiving system must have
3744 that feature enabled as well.
3747 feature is enabled on the sending system but the
3749 option is not supplied in conjunction with
3751 then the data will be decompressed before sending so it can be split into
3752 smaller block sizes.
3754 For encrypted datasets, send data exactly as it exists on disk. This allows
3755 backups to be taken even if encryption keys are not currently loaded. The
3756 backup may then be received on an untrusted machine since that machine will
3757 not have the encryption keys to read the protected data or alter it without
3758 being detected. Upon being received, the dataset will have the same encryption
3759 keys as it did on the send side, although the
3761 property will be defaulted to
3763 if not otherwise provided. For unencrypted datasets, this flag will be
3766 Note that if you do not use this flag for sending encrypted datasets, data will
3767 be sent unencrypted and may be re-encrypted with a different encryption key on
3768 the receiving system, which will disable the ability to do a raw send to that
3769 system for incrementals.
3771 Generate a stream package that includes any snapshot holds (created with the
3773 command), and indicating to
3775 that the holds be applied to the dataset on the receiving system.
3776 .It Fl i Ar snapshot
3777 Generate an incremental stream from the first
3779 .Pq the incremental source
3782 .Pq the incremental target .
3783 The incremental source can be specified as the last component of the snapshot
3787 character and following
3789 and it is assumed to be from the same file system as the incremental target.
3791 If the destination is a clone, the source may be the origin snapshot, which must
3794 .Em pool/fs@origin ,
3802 Do not generate any actual send data.
3803 This is useful in conjunction with the
3807 flags to determine what data will be sent.
3808 In this case, the verbose output will be written to standard output
3809 .Po contrast with a non-dry-run, where the stream is written to standard output
3810 and the verbose output goes to standard error
3813 Include the dataset's properties in the stream.
3814 This flag is implicit when
3817 The receiving system must also support this feature. Sends of encrypted datasets
3820 when using this flag.
3822 Print verbose information about the stream package generated.
3823 This information includes a per-second report of how much data has been sent.
3825 The format of the stream is committed.
3826 You will be able to receive your streams on future versions of ZFS.
3832 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3833 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3835 Generate a send stream, which may be of a filesystem, and may be incremental
3837 If the destination is a filesystem or volume, the pool must be read-only, or the
3838 filesystem must not be mounted.
3839 When the stream generated from a filesystem or volume is received, the default
3840 snapshot name will be
3842 .Bl -tag -width "-L"
3843 .It Fl L, -large-block
3844 Generate a stream which may contain blocks larger than 128KB.
3845 This flag has no effect if the
3847 pool feature is disabled, or if the
3849 property of this filesystem has never been set above 128KB.
3850 The receiving system must have the
3852 pool feature enabled as well.
3854 .Xr zpool-features 5
3855 for details on ZFS feature flags and the
3859 Print machine-parsable verbose information about the stream package generated.
3860 .It Fl c, -compressed
3861 Generate a more compact stream by using compressed WRITE records for blocks
3862 which are compressed on disk and in memory
3865 property for details
3869 feature is active on the sending system, then the receiving system must have
3870 that feature enabled as well.
3873 feature is enabled on the sending system but the
3875 option is not supplied in conjunction with
3877 then the data will be decompressed before sending so it can be split into
3878 smaller block sizes.
3880 For encrypted datasets, send data exactly as it exists on disk. This allows
3881 backups to be taken even if encryption keys are not currently loaded. The
3882 backup may then be received on an untrusted machine since that machine will
3883 not have the encryption keys to read the protected data or alter it without
3884 being detected. Upon being received, the dataset will have the same encryption
3885 keys as it did on the send side, although the
3887 property will be defaulted to
3889 if not otherwise provided. For unencrypted datasets, this flag will be
3892 Note that if you do not use this flag for sending encrypted datasets, data will
3893 be sent unencrypted and may be re-encrypted with a different encryption key on
3894 the receiving system, which will disable the ability to do a raw send to that
3895 system for incrementals.
3897 Generate a more compact stream by using
3899 records for blocks which are stored more compactly on disk by the
3902 This flag has no effect if the
3904 feature is disabled.
3905 The receiving system must have the
3910 feature is active on the sending system, then the receiving system must have
3911 that feature enabled as well. Datasets that are sent with this flag may not be
3912 received as an encrypted dataset, since encrypted datasets cannot use the
3916 .Xr zpool-features 5
3917 for details on ZFS feature flags and the
3920 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3921 Generate an incremental send stream.
3922 The incremental source must be an earlier snapshot in the destination's history.
3923 It will commonly be an earlier snapshot in the destination's file system, in
3924 which case it can be specified as the last component of the name
3929 character and following
3932 If the incremental target is a clone, the incremental source can be the origin
3933 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3939 Do not generate any actual send data.
3940 This is useful in conjunction with the
3944 flags to determine what data will be sent.
3945 In this case, the verbose output will be written to standard output
3946 .Po contrast with a non-dry-run, where the stream is written to standard output
3947 and the verbose output goes to standard error
3950 Print verbose information about the stream package generated.
3951 This information includes a per-second report of how much data has been sent.
3956 .Fl -redact Ar redaction_bookmark
3959 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3962 Generate a redacted send stream.
3963 This send stream contains all blocks from the snapshot being sent that aren't
3964 included in the redaction list contained in the bookmark specified by the
3969 The resulting send stream is said to be redacted with respect to the snapshots
3970 the bookmark specified by the
3971 .Fl -redact No flag was created with.
3972 The bookmark must have been created by running
3974 on the snapshot being sent.
3976 This feature can be used to allow clones of a filesystem to be made available on
3977 a remote system, in the case where their parent need not (or needs to not) be
3979 For example, if a filesystem contains sensitive data, and it has clones where
3980 that sensitive data has been secured or replaced with dummy data, redacted sends
3981 can be used to replicate the secured data without replicating the original
3982 sensitive data, while still sharing all possible blocks.
3983 A snapshot that has been redacted with respect to a set of snapshots will
3984 contain all blocks referenced by at least one snapshot in the set, but will
3985 contain none of the blocks referenced by none of the snapshots in the set.
3986 In other words, if all snapshots in the set have modified a given block in the
3987 parent, that block will not be sent; but if one or more snapshots have not
3988 modified a block in the parent, they will still reference the parent's block, so
3989 that block will be sent.
3990 Note that only user data will be redacted.
3992 When the redacted send stream is received, we will generate a redacted
3994 Due to the nature of redaction, a redacted dataset can only be used in the
3997 1. To receive, as a clone, an incremental send from the original snapshot to one
3998 of the snapshots it was redacted with respect to.
3999 In this case, the stream will produce a valid dataset when received because all
4000 blocks that were redacted in the parent are guaranteed to be present in the
4001 child's send stream.
4002 This use case will produce a normal snapshot, which can be used just like other
4005 2. To receive an incremental send from the original snapshot to something
4006 redacted with respect to a subset of the set of snapshots the initial snapshot
4007 was redacted with respect to.
4008 In this case, each block that was redacted in the original is still redacted
4009 (redacting with respect to additional snapshots causes less data to be redacted
4010 (because the snapshots define what is permitted, and everything else is
4012 This use case will produce a new redacted snapshot.
4014 3. To receive an incremental send from a redaction bookmark of the original
4015 snapshot that was created when redacting with respect to a subset of the set of
4016 snapshots the initial snapshot was created with respect to
4018 A send stream from such a redaction bookmark will contain all of the blocks
4019 necessary to fill in any redacted data, should it be needed, because the sending
4020 system is aware of what blocks were originally redacted.
4021 This will either produce a normal snapshot or a redacted one, depending on
4022 whether the new send stream is redacted.
4024 4. To receive an incremental send from a redacted version of the initial
4025 snapshot that is redacted with respect to a subject of the set of snapshots the
4026 initial snapshot was created with respect to.
4027 A send stream from a compatible redacted dataset will contain all of the blocks
4028 necessary to fill in any redacted data.
4029 This will either produce a normal snapshot or a redacted one, depending on
4030 whether the new send stream is redacted.
4032 5. To receive a full send as a clone of the redacted snapshot.
4033 Since the stream is a full send, it definitionally contains all the data needed
4034 to create a new dataset.
4035 This use case will either produce a normal snapshot or a redacted one, depending
4036 on whether the full send stream was redacted.
4038 These restrictions are detected and enforced by \fBzfs receive\fR; a
4039 redacted send stream will contain the list of snapshots that the stream is
4040 redacted with respect to.
4041 These are stored with the redacted snapshot, and are used to detect and
4042 correctly handle the cases above. Note that for technical reasons, raw sends
4043 and redacted sends cannot be combined at this time.
4049 .Ar receive_resume_token
4051 Creates a send stream which resumes an interrupted receive.
4053 .Ar receive_resume_token
4054 is the value of this property on the filesystem or volume that was being
4056 See the documentation for
4063 .Op Fl o Sy origin Ns = Ns Ar snapshot
4064 .Op Fl o Ar property Ns = Ns Ar value
4065 .Op Fl x Ar property
4066 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
4072 .Op Fl d Ns | Ns Fl e
4073 .Op Fl o Sy origin Ns = Ns Ar snapshot
4074 .Op Fl o Ar property Ns = Ns Ar value
4075 .Op Fl x Ar property
4078 Creates a snapshot whose contents are as specified in the stream provided on
4080 If a full stream is received, then a new file system is created as well.
4081 Streams are created using the
4083 subcommand, which by default creates a full stream.
4085 can be used as an alias for
4088 If an incremental stream is received, then the destination file system must
4089 already exist, and its most recent snapshot must match the incremental stream's
4093 the destination device link is destroyed and recreated, which means the
4095 cannot be accessed during the
4099 When a snapshot replication package stream that is generated by using the
4100 .Nm zfs Cm send Fl R
4101 command is received, any snapshots that do not exist on the sending location are
4102 destroyed by using the
4103 .Nm zfs Cm destroy Fl d
4107 .Fl o Em property Ns = Ns Ar value
4110 is specified, it applies to the effective value of the property throughout
4111 the entire subtree of replicated datasets. Effective property values will be
4116 ) on the topmost in the replicated subtree. In descendant datasets, if the
4117 property is set by the send stream, it will be overridden by forcing the
4118 property to be inherited from the top‐most file system. Received properties
4119 are retained in spite of being overridden and may be restored with
4120 .Nm zfs Cm inherit Fl S .
4122 .Fl o Sy origin Ns = Ns Em snapshot
4123 is a special case because, even if
4125 is a read-only property and cannot be set, it's allowed to receive the send
4126 stream as a clone of the given snapshot.
4128 Raw encrypted send streams (created with
4129 .Nm zfs Cm send Fl w
4130 ) may only be received as is, and cannot be re-encrypted, decrypted, or
4131 recompressed by the receive process. Unencrypted streams can be received as
4132 encrypted datasets, either through inheritance or by specifying encryption
4135 options. Note that the
4137 property cannot be overridden to
4139 during a receive. This is because the receive process itself is already using
4140 stdin for the send stream. Instead, the property can be overridden after the
4143 The added security provided by raw sends adds some restrictions to the send
4144 and receive process. ZFS will not allow a mix of raw receives and non-raw
4145 receives. Specifically, any raw incremental receives that are attempted after
4146 a non-raw receive will fail. Non-raw receives do not have this restriction and,
4147 therefore, are always possible. Because of this, it is best practice to always
4148 use either raw sends for their security benefits or non-raw sends for their
4149 flexibility when working with encrypted datasets, but not a combination.
4151 The reason for this restriction stems from the inherent restrictions of the
4152 AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption,
4153 each block of data is encrypted against a randomly generated number known as
4154 the "initialization vector" (IV), which is stored in the filesystem metadata.
4155 This number is required by the encryption algorithms whenever the data is to
4156 be decrypted. Together, all of the IVs provided for all of the blocks in a
4157 given snapshot are collectively called an "IV set". When ZFS performs a raw
4158 send, the IV set is transferred from the source to the destination in the send
4159 stream. When ZFS performs a non-raw send, the data is decrypted by the source
4160 system and re-encrypted by the destination system, creating a snapshot with
4161 effectively the same data, but a different IV set. In order for decryption to
4162 work after a raw send, ZFS must ensure that the IV set used on both the source
4163 and destination side match. When an incremental raw receive is performed on
4164 top of an existing snapshot, ZFS will check to confirm that the "from"
4165 snapshot on both the source and destination were using the same IV set,
4166 ensuring the new IV set is consistent.
4168 The name of the snapshot
4169 .Pq and file system, if a full stream is received
4170 that this subcommand creates depends on the argument type and the use of the
4176 If the argument is a snapshot name, the specified
4179 If the argument is a file system or volume name, a snapshot with the same name
4180 as the sent snapshot is created within the specified
4188 options are specified, the provided target snapshot name is used exactly as
4195 options cause the file system name of the target snapshot to be determined by
4196 appending a portion of the sent snapshot's name to the specified target
4200 option is specified, all but the first element of the sent snapshot's file
4202 .Pq usually the pool name
4203 is used and any required intermediate file systems within the specified one are
4207 option is specified, then only the last element of the sent snapshot's file
4209 .Pq i.e. the name of the source file system itself
4210 is used as the target file system name.
4211 .Bl -tag -width "-F"
4213 Force a rollback of the file system to the most recent snapshot before
4214 performing the receive operation.
4215 If receiving an incremental replication stream
4216 .Po for example, one generated by
4217 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
4219 destroy snapshots and file systems that do not exist on the sending side.
4221 Discard the first element of the sent snapshot's file system name, using the
4222 remaining elements to determine the name of the target file system for the new
4223 snapshot as described in the paragraph above.
4225 Discard all but the last element of the sent snapshot's file system name, using
4226 that element to determine the name of the target file system for the new
4227 snapshot as described in the paragraph above.
4229 Skip the receive of holds. There is no effect if holds are not sent.
4231 Do not actually receive the stream.
4232 This can be useful in conjunction with the
4234 option to verify the name the receive operation would use.
4235 .It Fl o Sy origin Ns = Ns Ar snapshot
4236 Forces the stream to be received as a clone of the given snapshot.
4237 If the stream is a full send stream, this will create the filesystem
4238 described by the stream as a clone of the specified snapshot.
4239 Which snapshot was specified will not affect the success or failure of the
4240 receive, as long as the snapshot does exist.
4241 If the stream is an incremental send stream, all the normal verification will be
4243 .It Fl o Em property Ns = Ns Ar value
4244 Sets the specified property as if the command
4245 .Nm zfs Cm set Em property Ns = Ns Ar value
4246 was invoked immediately before the receive. When receiving a stream from
4247 .Nm zfs Cm send Fl R ,
4248 causes the property to be inherited by all descendant datasets, as through
4249 .Nm zfs Cm inherit Em property
4250 was run on any descendant datasets that have this property set on the
4253 Any editable property can be set at receive time. Set-once properties bound
4254 to the received data, such as
4257 .Sy casesensitivity ,
4258 cannot be set at receive time even when the datasets are newly created by
4259 .Nm zfs Cm receive .
4260 Additionally both settable properties
4264 cannot be set at receive time.
4268 option may be specified multiple times, for different properties. An error
4269 results if the same property is specified in multiple
4277 option may also be used to override encryption properties upon initial
4278 receive. This allows unencrypted streams to be received as encrypted datasets.
4279 To cause the received dataset (or root dataset of a recursive stream) to be
4280 received as an encryption root, specify encryption properties in the same
4281 manner as is required for
4286 # zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile
4290 .Op Fl o Ar keylocation Ns = Ns Ar prompt
4291 may not be specified here, since stdin is already being utilized for the send
4292 stream. Once the receive has completed, you can use
4295 to change this setting after the fact. Similarly, you can receive a dataset as
4296 an encrypted child by specifying
4297 .Op Fl x Ar encryption
4298 to force the property to be inherited. Overriding encryption properties (except
4300 .Sy keylocation Ns )
4301 is not possible with raw send streams.
4303 If the receive is interrupted, save the partially received state, rather
4305 Interruption may be due to premature termination of the stream
4306 .Po e.g. due to network failure or failure of the remote system
4307 if the stream is being read over a network connection
4309 a checksum error in the stream, termination of the
4311 process, or unclean shutdown of the system.
4313 The receive can be resumed with a stream generated by
4314 .Nm zfs Cm send Fl t Ar token ,
4318 .Sy receive_resume_token
4319 property of the filesystem or volume which is received into.
4321 To use this flag, the storage pool must have the
4322 .Sy extensible_dataset
4325 .Xr zpool-features 5
4326 for details on ZFS feature flags.
4328 File system that is associated with the received stream is not mounted.
4330 Print verbose information about the stream and the time required to perform the
4332 .It Fl x Em property
4333 Ensures that the effective value of the specified property after the
4334 receive is unaffected by the value of that property in the send stream (if any),
4335 as if the property had been excluded from the send stream.
4337 If the specified property is not present in the send stream, this option does
4340 If a received property needs to be overridden, the effective value will be
4341 set or inherited, depending on whether the property is inheritable or not.
4343 In the case of an incremental update,
4345 leaves any existing local setting or explicit inheritance unchanged.
4349 restrictions (e.g. set-once) apply equally to
4356 .Ar filesystem Ns | Ns Ar volume
4358 Abort an interrupted
4359 .Nm zfs Cm receive Fl s ,
4360 deleting its saved partially received state.
4364 .Ar snapshot redaction_bookmark
4365 .Ar redaction_snapshot Ns ...
4367 Generate a new redaction bookmark.
4368 In addition to the typical bookmark information, a redaction bookmark contains
4369 the list of redacted blocks and the list of redaction snapshots specified.
4370 The redacted blocks are blocks in the snapshot which are not referenced by any
4371 of the redaction snapshots.
4372 These blocks are found by iterating over the metadata in each redaction snapshot
4373 to determine what has been changed since the target snapshot.
4374 Redaction is designed to support redacted zfs sends; see the entry for
4376 for more information on the purpose of this operation.
4377 If a redact operation fails partway through (due to an error or a system
4378 failure), the redaction can be resumed by rerunning the same command.
4382 .Ar filesystem Ns | Ns Ar volume
4384 Displays permissions that have been delegated on the specified filesystem or
4386 See the other forms of
4388 for more information.
4390 Delegations are supported under Linux with the exception of
4398 These permissions cannot be delegated because the Linux
4400 command restricts modifications of the global namespace to the root user.
4405 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4406 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4407 .Ar setname Oc Ns ...
4408 .Ar filesystem Ns | Ns Ar volume
4414 .Fl e Ns | Ns Sy everyone
4415 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4416 .Ar setname Oc Ns ...
4417 .Ar filesystem Ns | Ns Ar volume
4419 Delegates ZFS administration permission for the file systems to non-privileged
4421 .Bl -tag -width "-d"
4423 Allow only for the descendent file systems.
4424 .It Fl e Ns | Ns Sy everyone
4425 Specifies that the permissions be delegated to everyone.
4426 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
4427 Explicitly specify that permissions are delegated to the group.
4431 only for the specified file system.
4432 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
4433 Explicitly specify that permissions are delegated to the user.
4434 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4435 Specifies to whom the permissions are delegated.
4436 Multiple entities can be specified as a comma-separated list.
4439 options are specified, then the argument is interpreted preferentially as the
4442 then as a user name, and lastly as a group name.
4443 To specify a user or group named
4450 To specify a group with the same name as a user, use the
4454 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4455 .Ar setname Oc Ns ...
4457 The permissions to delegate.
4458 Multiple permissions may be specified as a comma-separated list.
4459 Permission names are the same as ZFS subcommand and property names.
4460 See the property list below.
4461 Property set names, which begin with
4466 form below for details.
4471 options are specified, or both are, then the permissions are allowed for the
4472 file system or volume, and all of its descendents.
4474 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4476 The following permissions are available:
4479 allow subcommand Must also have the permission that is
4481 clone subcommand Must also have the 'create' ability and
4482 'mount' ability in the origin file system
4483 create subcommand Must also have the 'mount' ability.
4484 Must also have the 'refreservation' ability to
4485 create a non-sparse volume.
4486 destroy subcommand Must also have the 'mount' ability
4487 diff subcommand Allows lookup of paths within a dataset
4488 given an object number, and the ability
4489 to create snapshots necessary to
4491 load-key subcommand Allows loading and unloading of encryption key
4492 (see 'zfs load-key' and 'zfs unload-key').
4493 change-key subcommand Allows changing an encryption key via
4495 mount subcommand Allows mount/umount of ZFS datasets
4496 promote subcommand Must also have the 'mount' and 'promote'
4497 ability in the origin file system
4498 receive subcommand Must also have the 'mount' and 'create'
4500 rename subcommand Must also have the 'mount' and 'create'
4501 ability in the new parent
4502 rollback subcommand Must also have the 'mount' ability
4504 share subcommand Allows sharing file systems over NFS
4506 snapshot subcommand Must also have the 'mount' ability
4508 groupquota other Allows accessing any groupquota@...
4510 groupused other Allows reading any groupused@... property
4511 userprop other Allows changing any user property
4512 userquota other Allows accessing any userquota@...
4514 userused other Allows reading any userused@... property
4515 projectobjquota other Allows accessing any projectobjquota@...
4517 projectquota other Allows accessing any projectquota@... property
4518 projectobjused other Allows reading any projectobjused@... property
4519 projectused other Allows reading any projectused@... property
4525 casesensitivity property
4527 compression property
4531 filesystem_limit property
4534 normalization property
4535 primarycache property
4540 refreservation property
4541 reservation property
4542 secondarycache property
4547 snapshot_limit property
4550 volblocksize property
4560 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4561 .Ar setname Oc Ns ...
4562 .Ar filesystem Ns | Ns Ar volume
4567 These permissions are granted
4569 to the creator of any newly-created descendent file system.
4573 .Fl s No @ Ns Ar setname
4574 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4575 .Ar setname Oc Ns ...
4576 .Ar filesystem Ns | Ns Ar volume
4578 Defines or adds permissions to a permission set.
4579 The set can be used by other
4581 commands for the specified file system and its descendents.
4582 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4583 Permission sets follow the same naming restrictions as ZFS file systems, but the
4584 name must begin with
4586 and can be no more than 64 characters long.
4591 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4592 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4593 .Ar setname Oc Ns ... Oc
4594 .Ar filesystem Ns | Ns Ar volume
4600 .Fl e Ns | Ns Sy everyone
4601 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4602 .Ar setname Oc Ns ... Oc
4603 .Ar filesystem Ns | Ns Ar volume
4610 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4611 .Ar setname Oc Ns ... Oc
4612 .Ar filesystem Ns | Ns Ar volume
4614 Removes permissions that were granted with the
4617 No permissions are explicitly denied, so other permissions granted are still in
4619 For example, if the permission is granted by an ancestor.
4620 If no permissions are specified, then all permissions for the specified
4632 only removes the permissions that were granted to everyone, not all permissions
4633 for every user and group.
4636 command for a description of the
4639 .Bl -tag -width "-r"
4641 Recursively remove the permissions from this file system and all descendents.
4647 .Fl s No @ Ns Ar setname
4648 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4649 .Ar setname Oc Ns ... Oc
4650 .Ar filesystem Ns | Ns Ar volume
4652 Removes permissions from a permission set.
4653 If no permissions are specified, then all permissions are removed, thus removing
4659 .Ar tag Ar snapshot Ns ...
4661 Adds a single reference, named with the
4663 argument, to the specified snapshot or snapshots.
4664 Each snapshot has its own tag namespace, and tags must be unique within that
4667 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4671 .Bl -tag -width "-r"
4673 Specifies that a hold with the given tag is applied recursively to the snapshots
4674 of all descendent file systems.
4682 Lists all existing user references for the given snapshot or snapshots.
4683 .Bl -tag -width "-r"
4685 Lists the holds that are set on the named descendent snapshots, in addition to
4686 listing the holds on the named snapshot.
4688 Do not print headers, use tab-delimited output.
4694 .Ar tag Ar snapshot Ns ...
4696 Removes a single reference, named with the
4698 argument, from the specified snapshot or snapshots.
4699 The tag must already exist for each snapshot.
4700 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4704 .Bl -tag -width "-r"
4706 Recursively releases a hold with the given tag on the snapshots of all
4707 descendent file systems.
4713 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4715 Display the difference between a snapshot of a given filesystem and another
4716 snapshot of that filesystem from a later time or the current contents of the
4718 The first column is a character indicating the type of change, the other columns
4719 indicate pathname, new pathname
4720 .Pq in case of rename ,
4721 change in link count, and optionally file type and/or change time.
4722 The types of change are:
4724 - The path has been removed
4725 + The path has been created
4726 M The path has been modified
4727 R The path has been renamed
4729 .Bl -tag -width "-F"
4731 Display an indication of the type of file, in a manner similar to the
4747 Give more parsable tab-separated output, without header lines and without
4750 Display the path's inode change time as the first column of output.
4756 .Op Fl t Ar instruction-limit
4757 .Op Fl m Ar memory-limit
4763 as a ZFS channel program on
4766 program interface allows ZFS administrative operations to be run
4767 programmatically via a Lua script.
4768 The entire script is executed atomically, with no other administrative
4769 operations taking effect concurrently.
4770 A library of ZFS calls is made available to channel program scripts.
4771 Channel programs may only be run with root privileges.
4773 For full documentation of the ZFS channel program interface, see the manual
4778 Display channel program output in JSON format. When this flag is specified and
4779 standard output is empty - channel program encountered an error. The details of
4780 such an error will be printed to standard error in plain text.
4782 Executes a read-only channel program, which runs faster.
4783 The program cannot change on-disk state by calling functions from
4784 the zfs.sync submodule.
4785 The program can be used to gather information such as properties and
4786 determining if changes would succeed (zfs.check.*).
4787 Without this flag, all pending changes must be synced to disk before
4788 a channel program can complete.
4789 .It Fl t Ar instruction-limit
4790 Limit the number of Lua instructions to execute.
4791 If a channel program executes more than the specified number of instructions,
4792 it will be stopped and an error will be returned.
4793 The default limit is 10 million instructions, and it can be set to a maximum of
4794 100 million instructions.
4795 .It Fl m Ar memory-limit
4796 Memory limit, in bytes.
4797 If a channel program attempts to allocate more memory than the given limit,
4798 it will be stopped and an error returned.
4799 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4801 All remaining argument strings are passed directly to the channel program as
4805 for more information.
4811 .Op Fl L Ar keylocation
4812 .Fl a | Ar filesystem
4816 allowing it and all children that inherit the
4818 property to be accessed. The key will be expected in the format specified by the
4820 and location specified by the
4822 property. Note that if the
4826 the terminal will interactively wait for the key to be entered. Loading a key
4827 will not automatically mount the dataset. If that functionality is desired,
4828 .Nm zfs Cm mount Sy -l
4829 will ask for the key and mount the dataset. Once the key is loaded the
4831 property will become
4833 .Bl -tag -width "-r"
4835 Recursively loads the keys for the specified filesystem and all descendent
4838 Loads the keys for all encryption roots in all imported pools.
4842 load-key. This will cause zfs to simply check that the
4843 provided key is correct. This command may be run even if the key is already
4845 .It Fl L Ar keylocation
4850 property. This will not change the value of the property on the dataset. Note
4851 that if used with either
4856 may only be given as
4863 .Fl a | Ar filesystem
4865 Unloads a key from ZFS, removing the ability to access the dataset and all of
4866 its children that inherit the
4868 property. This requires that the dataset is not currently open or mounted. Once
4869 the key is unloaded the
4871 property will become
4873 .Bl -tag -width "-r"
4875 Recursively unloads the keys for the specified filesystem and all descendent
4878 Unloads the keys for all encryption roots in all imported pools.
4884 .Op Fl o Ar keylocation Ns = Ns Ar value
4885 .Op Fl o Ar keyformat Ns = Ns Ar value
4886 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4896 Allows a user to change the encryption key used to access a dataset. This
4897 command requires that the existing key for the dataset is already loaded into
4898 ZFS. This command may also be used to change the
4903 properties as needed. If the dataset was not previously an encryption root it
4904 will become one. Alternatively, the
4906 flag may be provided to cause an encryption root to inherit the parent's key
4908 .Bl -tag -width "-r"
4910 Ensures the key is loaded before attempting to change the key. This is
4911 effectively equivalent to
4912 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4913 .It Fl o Ar property Ns = Ns Ar value
4914 Allows the user to set encryption key properties (
4919 ) while changing the key. This is the only way to alter
4923 after the dataset has been created.
4925 Indicates that zfs should make
4927 inherit the key of its parent. Note that this command can only be run on an
4928 encryption root that has an encrypted parent.
4934 Displays the software version of the
4936 userland utility and the zfs kernel module.
4941 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4942 options were specified.
4945 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4946 The following commands create a file system named
4948 and a file system named
4952 is set for the parent file system, and is automatically inherited by the child
4955 # zfs create pool/home
4956 # zfs set mountpoint=/export/home pool/home
4957 # zfs create pool/home/bob
4959 .It Sy Example 2 No Creating a ZFS Snapshot
4960 The following command creates a snapshot named
4962 This snapshot is mounted on demand in the
4964 directory at the root of the
4968 # zfs snapshot pool/home/bob@yesterday
4970 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4971 The following command creates snapshots named
4975 and all of its descendent file systems.
4976 Each snapshot is mounted on demand in the
4978 directory at the root of its file system.
4979 The second command destroys the newly created snapshots.
4981 # zfs snapshot -r pool/home@yesterday
4982 # zfs destroy -r pool/home@yesterday
4984 .It Sy Example 4 No Disabling and Enabling File System Compression
4985 The following command disables the
4987 property for all file systems under
4989 The next command explicitly enables
4992 .Em pool/home/anne .
4994 # zfs set compression=off pool/home
4995 # zfs set compression=on pool/home/anne
4997 .It Sy Example 5 No Listing ZFS Datasets
4998 The following command lists all active file systems and volumes in the system.
4999 Snapshots are displayed if the
5007 for more information on pool properties.
5010 NAME USED AVAIL REFER MOUNTPOINT
5011 pool 450K 457G 18K /pool
5012 pool/home 315K 457G 21K /export/home
5013 pool/home/anne 18K 457G 18K /export/home/anne
5014 pool/home/bob 276K 457G 276K /export/home/bob
5016 .It Sy Example 6 No Setting a Quota on a ZFS File System
5017 The following command sets a quota of 50 Gbytes for
5020 # zfs set quota=50G pool/home/bob
5022 .It Sy Example 7 No Listing ZFS Properties
5023 The following command lists all properties for
5026 # zfs get all pool/home/bob
5027 NAME PROPERTY VALUE SOURCE
5028 pool/home/bob type filesystem -
5029 pool/home/bob creation Tue Jul 21 15:53 2009 -
5030 pool/home/bob used 21K -
5031 pool/home/bob available 20.0G -
5032 pool/home/bob referenced 21K -
5033 pool/home/bob compressratio 1.00x -
5034 pool/home/bob mounted yes -
5035 pool/home/bob quota 20G local
5036 pool/home/bob reservation none default
5037 pool/home/bob recordsize 128K default
5038 pool/home/bob mountpoint /pool/home/bob default
5039 pool/home/bob sharenfs off default
5040 pool/home/bob checksum on default
5041 pool/home/bob compression on local
5042 pool/home/bob atime on default
5043 pool/home/bob devices on default
5044 pool/home/bob exec on default
5045 pool/home/bob setuid on default
5046 pool/home/bob readonly off default
5047 pool/home/bob zoned off default
5048 pool/home/bob snapdir hidden default
5049 pool/home/bob acltype off default
5050 pool/home/bob aclinherit restricted default
5051 pool/home/bob canmount on default
5052 pool/home/bob xattr on default
5053 pool/home/bob copies 1 default
5054 pool/home/bob version 4 -
5055 pool/home/bob utf8only off -
5056 pool/home/bob normalization none -
5057 pool/home/bob casesensitivity sensitive -
5058 pool/home/bob vscan off default
5059 pool/home/bob nbmand off default
5060 pool/home/bob sharesmb off default
5061 pool/home/bob refquota none default
5062 pool/home/bob refreservation none default
5063 pool/home/bob primarycache all default
5064 pool/home/bob secondarycache all default
5065 pool/home/bob usedbysnapshots 0 -
5066 pool/home/bob usedbydataset 21K -
5067 pool/home/bob usedbychildren 0 -
5068 pool/home/bob usedbyrefreservation 0 -
5071 The following command gets a single property value.
5073 # zfs get -H -o value compression pool/home/bob
5076 The following command lists all properties with local settings for
5079 # zfs get -r -s local -o name,property,value all pool/home/bob
5081 pool/home/bob quota 20G
5082 pool/home/bob compression on
5084 .It Sy Example 8 No Rolling Back a ZFS File System
5085 The following command reverts the contents of
5087 to the snapshot named
5089 deleting all intermediate snapshots.
5091 # zfs rollback -r pool/home/anne@yesterday
5093 .It Sy Example 9 No Creating a ZFS Clone
5094 The following command creates a writable file system whose initial contents are
5096 .Em pool/home/bob@yesterday .
5098 # zfs clone pool/home/bob@yesterday pool/clone
5100 .It Sy Example 10 No Promoting a ZFS Clone
5101 The following commands illustrate how to test out changes to a file system, and
5102 then replace the original file system with the changed one, using clones, clone
5103 promotion, and renaming:
5105 # zfs create pool/project/production
5106 populate /pool/project/production with data
5107 # zfs snapshot pool/project/production@today
5108 # zfs clone pool/project/production@today pool/project/beta
5109 make changes to /pool/project/beta and test them
5110 # zfs promote pool/project/beta
5111 # zfs rename pool/project/production pool/project/legacy
5112 # zfs rename pool/project/beta pool/project/production
5113 once the legacy version is no longer needed, it can be destroyed
5114 # zfs destroy pool/project/legacy
5116 .It Sy Example 11 No Inheriting ZFS Properties
5117 The following command causes
5123 property from their parent.
5125 # zfs inherit checksum pool/home/bob pool/home/anne
5127 .It Sy Example 12 No Remotely Replicating ZFS Data
5128 The following commands send a full stream and then an incremental stream to a
5129 remote machine, restoring them into
5130 .Em poolB/received/fs@a
5132 .Em poolB/received/fs@b ,
5135 must contain the file system
5136 .Em poolB/received ,
5137 and must not initially contain
5138 .Em poolB/received/fs .
5140 # zfs send pool/fs@a | \e
5141 ssh host zfs receive poolB/received/fs@a
5142 # zfs send -i a pool/fs@b | \e
5143 ssh host zfs receive poolB/received/fs
5145 .It Sy Example 13 No Using the zfs receive -d Option
5146 The following command sends a full stream of
5147 .Em poolA/fsA/fsB@snap
5148 to a remote machine, receiving it into
5149 .Em poolB/received/fsA/fsB@snap .
5152 portion of the received snapshot's name is determined from the name of the sent
5155 must contain the file system
5156 .Em poolB/received .
5158 .Em poolB/received/fsA
5159 does not exist, it is created as an empty file system.
5161 # zfs send poolA/fsA/fsB@snap | \e
5162 ssh host zfs receive -d poolB/received
5164 .It Sy Example 14 No Setting User Properties
5165 The following example sets the user-defined
5166 .Sy com.example:department
5167 property for a dataset.
5169 # zfs set com.example:department=12345 tank/accounting
5171 .It Sy Example 15 No Performing a Rolling Snapshot
5172 The following example shows how to maintain a history of snapshots with a
5173 consistent naming scheme.
5174 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
5175 renames the remaining snapshots, and then creates a new snapshot, as follows:
5177 # zfs destroy -r pool/users@7daysago
5178 # zfs rename -r pool/users@6daysago @7daysago
5179 # zfs rename -r pool/users@5daysago @6daysago
5180 # zfs rename -r pool/users@4daysago @5daysago
5181 # zfs rename -r pool/users@3daysago @4daysago
5182 # zfs rename -r pool/users@2daysago @3daysago
5183 # zfs rename -r pool/users@yesterday @2daysago
5184 # zfs rename -r pool/users@today @yesterday
5185 # zfs snapshot -r pool/users@today
5187 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
5188 The following commands show how to set
5190 property options to enable
5194 addresses and to enable root access for system
5200 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
5205 for host name resolution, specify the fully qualified hostname.
5206 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
5207 The following example shows how to set permissions so that user
5209 can create, destroy, mount, and take snapshots on
5215 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
5216 # zfs allow tank/cindys
5217 ---- Permissions on tank/cindys --------------------------------------
5218 Local+Descendent permissions:
5219 user cindys create,destroy,mount,snapshot
5224 mount point permission is set to 755 by default, user
5226 will be unable to mount file systems under
5228 Add an ACE similar to the following syntax to provide mount point access:
5230 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
5232 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
5233 The following example shows how to grant anyone in the group
5235 to create file systems in
5237 This syntax also allows staff members to destroy their own file systems, but not
5238 destroy anyone else's file system.
5243 # zfs allow staff create,mount tank/users
5244 # zfs allow -c destroy tank/users
5245 # zfs allow tank/users
5246 ---- Permissions on tank/users ---------------------------------------
5249 Local+Descendent permissions:
5250 group staff create,mount
5252 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
5253 The following example shows how to define and grant a permission set on the
5260 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
5261 # zfs allow staff @pset tank/users
5262 # zfs allow tank/users
5263 ---- Permissions on tank/users ---------------------------------------
5265 @pset create,destroy,mount,snapshot
5266 Local+Descendent permissions:
5269 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
5270 The following example shows to grant the ability to set quotas and reservations
5278 # zfs allow cindys quota,reservation users/home
5279 # zfs allow users/home
5280 ---- Permissions on users/home ---------------------------------------
5281 Local+Descendent permissions:
5282 user cindys quota,reservation
5283 cindys% zfs set quota=10G users/home/marks
5284 cindys% zfs get quota users/home/marks
5285 NAME PROPERTY VALUE SOURCE
5286 users/home/marks quota 10G local
5288 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
5289 The following example shows how to remove the snapshot permission from the
5298 # zfs unallow staff snapshot tank/users
5299 # zfs allow tank/users
5300 ---- Permissions on tank/users ---------------------------------------
5302 @pset create,destroy,mount,snapshot
5303 Local+Descendent permissions:
5306 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
5307 The following example shows how to see what has changed between a prior
5308 snapshot of a ZFS dataset and its current state.
5311 option is used to indicate type information for the files affected.
5313 # zfs diff -F tank/test@before tank/test
5315 M F /tank/test/linked (+1)
5316 R F /tank/test/oldname -> /tank/test/newname
5317 - F /tank/test/deleted
5318 + F /tank/test/created
5319 M F /tank/test/modified
5321 .It Sy Example 23 No Creating a bookmark
5322 The following example create a bookmark to a snapshot. This bookmark
5323 can then be used instead of snapshot in send streams.
5325 # zfs bookmark rpool@snapshot rpool#bookmark
5327 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
5328 The following example show how to share SMB filesystem through ZFS. Note that
5329 that a user and his/her password must be given.
5331 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
5332 -o user=workgroup/turbo,password=obrut,uid=1000
5336 .Em /etc/samba/smb.conf
5337 configuration required:
5339 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
5340 communicate with Samba. This is the default behavior for most Linux
5343 Samba must be able to authenticate a user. This can be done in a number of
5344 ways, depending on if using the system password file, LDAP or the Samba
5345 specific smbpasswd file. How to do this is outside the scope of this manual.
5348 man page for more information.
5351 .Sy USERSHARE section
5354 man page for all configuration options in case you need to modify any options
5355 to the share afterwards. Do note that any changes done with the
5357 command will be undone if the share is ever unshared (such as at a reboot etc).
5359 .Sh INTERFACE STABILITY
projects / zfs / blob