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
324 .Op Fl L Ar keylocation
325 .Fl a | Ar filesystem
329 .Fl a | Ar filesystem
333 .Op Fl o Ar keylocation Ns = Ns Ar value
334 .Op Fl o Ar keyformat Ns = Ns Ar value
335 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
347 command configures ZFS datasets within a ZFS storage pool, as described in
349 A dataset is identified by a unique path within the ZFS namespace.
352 pool/{filesystem,volume,snapshot}
355 where the maximum length of a dataset name is
358 and the maximum amount of nesting allowed in a path is 50 levels deep.
360 A dataset can be one of the following:
361 .Bl -tag -width "file system"
363 A ZFS dataset of type
365 can be mounted within the standard system namespace and behaves like other file
367 While ZFS file systems are designed to be POSIX compliant, known issues exist
368 that prevent compliance in some cases.
369 Applications that depend on standards conformance might fail due to non-standard
370 behavior when checking file system free space.
372 A logical volume exported as a raw or block device.
373 This type of dataset should only be used when a block device is required.
374 File systems are typically used in most environments.
376 A read-only version of a file system or volume at a given point in time.
378 .Ar filesystem Ns @ Ns Ar name
380 .Ar volume Ns @ Ns Ar name .
384 but without the hold on on-disk data. It can be used as the source of a send
385 (but not for a receive). It is specified as
386 .Ar filesystem Ns # Ns Ar name
388 .Ar volume Ns # Ns Ar name .
390 .Ss ZFS File System Hierarchy
391 A ZFS storage pool is a logical collection of devices that provide space for
393 A storage pool is also the root of the ZFS file system hierarchy.
395 The root of the pool can be accessed as a file system, such as mounting and
396 unmounting, taking snapshots, and setting properties.
397 The physical storage characteristics, however, are managed by the
403 for more information on creating and administering pools.
405 A snapshot is a read-only copy of a file system or volume.
406 Snapshots can be created extremely quickly, and initially consume no additional
407 space within the pool.
408 As data within the active dataset changes, the snapshot consumes more data than
409 would otherwise be shared with the active dataset.
411 Snapshots can have arbitrary names.
412 Snapshots of volumes can be cloned or rolled back, visibility is determined
415 property of the parent volume.
417 File system snapshots can be accessed under the
419 directory in the root of the file system.
420 Snapshots are automatically mounted on demand and may be unmounted at regular
422 The visibility of the
424 directory can be controlled by the
428 A bookmark is like a snapshot, a read-only copy of a file system or volume.
429 Bookmarks can be created extremely quickly, compared to snapshots, and they
430 consume no additional space within the pool. Bookmarks can also have arbitrary
431 names, much like snapshots.
433 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
434 way. From a storage standpoint a bookmark just provides a way to reference
435 when a snapshot was created as a distinct object. Bookmarks are initially
436 tied to a snapshot, not the filesystem or volume, and they will survive if the
437 snapshot itself is destroyed. Since they are very light weight there's little
438 incentive to destroy them.
440 A clone is a writable volume or file system whose initial contents are the same
442 As with snapshots, creating a clone is nearly instantaneous, and initially
443 consumes no additional space.
445 Clones can only be created from a snapshot.
446 When a snapshot is cloned, it creates an implicit dependency between the parent
448 Even though the clone is created somewhere else in the dataset hierarchy, the
449 original snapshot cannot be destroyed as long as a clone exists.
452 property exposes this dependency, and the
454 command lists any such dependencies, if they exist.
456 The clone parent-child dependency relationship can be reversed by using the
461 file system to become a clone of the specified file system, which makes it
462 possible to destroy the file system that the clone was created from.
464 Creating a ZFS file system is a simple operation, so the number of file systems
465 per system is likely to be numerous.
466 To cope with this, ZFS automatically manages mounting and unmounting file
467 systems without the need to edit the
470 All automatically managed file systems are mounted by ZFS at boot time.
472 By default, file systems are mounted under
476 is the name of the file system in the ZFS namespace.
477 Directories are created and destroyed as needed.
479 A file system can also have a mount point set in the
482 This directory is created as needed, and ZFS automatically mounts the file
484 .Nm zfs Cm mount Fl a
491 property can be inherited, so if
497 automatically inherits a mount point of
498 .Pa /export/stuff/user .
504 prevents the file system from being mounted.
506 If needed, ZFS file systems can also be managed with traditional tools
512 If a file system's mount point is set to
514 ZFS makes no attempt to manage the file system, and the administrator is
515 responsible for mounting and unmounting the file system. Because pools must
516 be imported before a legacy mount can succeed, administrators should ensure
517 that legacy mounts are only attempted after the zpool import process
518 finishes at boot time. For example, on machines using systemd, the mount
521 .Nm x-systemd.requires=zfs-import.target
523 will ensure that the zfs-import completes before systemd attempts mounting
524 the filesystem. See systemd.mount(5) for details.
526 Deduplication is the process for removing redundant data at the block level,
527 reducing the total amount of data stored. If a file system has the
529 property enabled, duplicate data blocks are removed synchronously. The result
530 is that only unique data is stored and common components are shared among files.
532 Deduplicating data is a very resource-intensive operation. It is generally
533 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
534 you enable deduplication. Calculating the exact requirement depends heavily
535 on the type of data stored in the pool.
537 Enabling deduplication on an improperly-designed system can result in
538 performance issues (slow IO and administrative operations). It can potentially
539 lead to problems importing a pool due to memory exhaustion. Deduplication
540 can consume significant processing power (CPU) and memory as well as generate
543 Before creating a pool with deduplication enabled, ensure that you have planned
544 your hardware requirements appropriately and implemented appropriate recovery
545 practices, such as regular backups. As an alternative to deduplication
548 as a less resource-intensive alternative.
549 .Ss Native Properties
550 Properties are divided into two types, native properties and user-defined
555 Native properties either export internal statistics or control ZFS behavior.
556 In addition, native properties are either editable or read-only.
557 User properties have no effect on ZFS behavior, but you can use them to annotate
558 datasets in a way that is meaningful in your environment.
559 For more information about user properties, see the
563 Every dataset has a set of properties that export statistics about the dataset
564 as well as control various behaviors.
565 Properties are inherited from the parent unless overridden by the child.
566 Some properties apply only to certain types of datasets
567 .Pq file systems, volumes, or snapshots .
569 The values of numeric properties can be specified using human-readable suffixes
579 The following are all valid
582 .Li 1536M, 1.5g, 1.50GB .
584 The values of non-numeric properties are case sensitive and must be lowercase,
591 The following native properties consist of read-only statistics about the
593 These properties can be neither set, nor inherited.
594 Native properties apply to all dataset types unless otherwise noted.
595 .Bl -tag -width "usedbyrefreservation"
597 The amount of space available to the dataset and all its children, assuming that
598 there is no other activity in the pool.
599 Because space is shared within a pool, availability can be limited by any number
600 of factors, including physical pool size, quotas, reservations, or other
601 datasets within the pool.
603 This property can also be referred to by its shortened column name,
606 For non-snapshots, the compression ratio achieved for the
608 space of this dataset, expressed as a multiplier.
611 property includes descendant datasets, and, for clones, does not include the
612 space shared with the origin snapshot.
618 Compression can be turned on by running:
619 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
623 The transaction group (txg) in which the dataset was created. Bookmarks have
626 as the snapshot they are initially tied to. This property is suitable for
627 ordering a list of snapshots, e.g. for incremental send and receive.
629 The time this dataset was created.
631 For snapshots, this property is a comma-separated list of filesystems or volumes
632 which are clones of this snapshot.
635 property is this snapshot.
638 property is not empty, then this snapshot can not be destroyed
645 The roles of origin and clone can be swapped by promoting the clone with the
651 if the snapshot has been marked for deferred destroy by using the
652 .Nm zfs Cm destroy Fl d
654 Otherwise, the property is
656 .It Sy encryptionroot
657 For encrypted datasets, indicates where the dataset is currently inheriting its
658 encryption key from. Loading or unloading a key for the
660 will implicitly load / unload the key for any inheriting datasets (see
663 .Nm zfs Cm unload-key
665 Clones will always share an
666 encryption key with their origin. See the
669 .It Sy filesystem_count
670 The total number of filesystems and volumes that exist under this location in
672 This value is only available when a
674 has been set somewhere in the tree under which the dataset resides.
676 Indicates if an encryption key is currently loaded into ZFS. The possible
685 .Nm zfs Cm unload-key .
687 The 64 bit GUID of this dataset or bookmark which does not change over its
688 entire lifetime. When a snapshot is sent to another pool, the received
689 snapshot has the same GUID. Thus, the
691 is suitable to identify a snapshot across pools.
692 .It Sy logicalreferenced
693 The amount of space that is
695 accessible by this dataset.
699 The logical space ignores the effect of the
703 properties, giving a quantity closer to the amount of data that applications
705 However, it does include space consumed by metadata.
707 This property can also be referred to by its shortened column name,
710 The amount of space that is
712 consumed by this dataset and all its descendents.
716 The logical space ignores the effect of the
720 properties, giving a quantity closer to the amount of data that applications
722 However, it does include space consumed by metadata.
724 This property can also be referred to by its shortened column name,
727 For file systems, indicates whether the file system is currently mounted.
728 This property can be either
733 A unique identifier for this dataset within the pool. Unlike the dataset's
737 of a dataset is not transferred to other pools when the snapshot is copied
738 with a send/receive operation.
741 can be reused (for a new dataset) after the dataset is deleted.
743 For cloned file systems or volumes, the snapshot from which the clone was
748 .It Sy receive_resume_token
749 For filesystems or volumes which have saved partially-completed state from
751 this opaque token can be provided to
753 to resume and complete the
756 For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
758 For snapshots, this is the list of snapshot guids the snapshot is redacted with
761 The amount of data that is accessible by this dataset, which may or may not be
762 shared with other datasets in the pool.
763 When a snapshot or clone is created, it initially references the same amount of
764 space as the file system or snapshot it was created from, since its contents are
767 This property can also be referred to by its shortened column name,
769 .It Sy refcompressratio
770 The compression ratio achieved for the
772 space of this dataset, expressed as a multiplier.
776 .It Sy snapshot_count
777 The total number of snapshots that exist under this location in the dataset
779 This value is only available when a
781 has been set somewhere in the tree under which the dataset resides.
789 The amount of space consumed by this dataset and all its descendents.
790 This is the value that is checked against this dataset's quota and reservation.
791 The space used does not include this dataset's reservation, but does take into
792 account the reservations of any descendent datasets.
793 The amount of space that a dataset consumes from its parent, as well as the
794 amount of space that is freed if this dataset is recursively destroyed, is the
795 greater of its space used and its reservation.
797 The used space of a snapshot
802 is space that is referenced exclusively by this snapshot.
803 If this snapshot is destroyed, the amount of
806 Space that is shared by multiple snapshots isn't accounted for in this metric.
807 When a snapshot is destroyed, space that was previously shared with this
808 snapshot can become unique to snapshots adjacent to it, thus changing the used
809 space of those snapshots.
810 The used space of the latest snapshot can also be affected by changes in the
814 space of a snapshot is a subset of the
816 space of the snapshot.
818 The amount of space used, available, or referenced does not take into account
820 Pending changes are generally accounted for within a few seconds.
821 Committing a change to a disk using
825 does not necessarily guarantee that the space usage information is updated
830 properties decompose the
832 properties into the various reasons that space is used.
835 .Sy usedbychildren No +
836 .Sy usedbydataset No +
837 .Sy usedbyrefreservation No +
838 .Sy usedbysnapshots .
839 These properties are only available for datasets created on
843 .It Sy usedbychildren
844 The amount of space used by children of this dataset, which would be freed if
845 all the dataset's children were destroyed.
847 The amount of space used by this dataset itself, which would be freed if the
848 dataset were destroyed
849 .Po after first removing any
851 and destroying any necessary snapshots or descendents
853 .It Sy usedbyrefreservation
854 The amount of space used by a
856 set on this dataset, which would be freed if the
859 .It Sy usedbysnapshots
860 The amount of space consumed by snapshots of this dataset.
861 In particular, it is the amount of space that would be freed if all of this
862 dataset's snapshots were destroyed.
863 Note that this is not simply the sum of the snapshots'
865 properties because space can be shared by multiple snapshots.
866 .It Sy userused Ns @ Ns Em user
867 The amount of space consumed by the specified user in this dataset.
868 Space is charged to the owner of each file, as displayed by
870 The amount of space charged is displayed by
876 subcommand for more information.
878 Unprivileged users can access only their own space usage.
879 The root user, or a user who has been granted the
883 can access everyone's usage.
886 .Sy userused Ns @ Ns Em ...
887 properties are not displayed by
888 .Nm zfs Cm get Sy all .
889 The user's name must be appended after the @ symbol, using one of the following
891 .Bl -bullet -width ""
905 .Sy joe.smith@mydomain
914 Files created on Linux always have POSIX owners.
915 .It Sy userobjused Ns @ Ns Em user
918 property is similar to
920 but instead it counts the number of objects consumed by a user. This property
921 counts all objects allocated on behalf of the user, it may differ from the
922 results of system tools such as
927 is set on a file system additional objects will be created per-file to store
928 extended attributes. These additional objects are reflected in the
930 value and are counted against the user's
932 When a file system is configured to use
934 no additional internal objects are normally required.
936 This property is set to the number of user holds on this snapshot.
937 User holds are set by using the
940 .It Sy groupused Ns @ Ns Em group
941 The amount of space consumed by the specified group in this dataset.
942 Space is charged to the group of each file, as displayed by
945 .Sy userused Ns @ Ns Em user
946 property for more information.
948 Unprivileged users can only access their own groups' space usage.
949 The root user, or a user who has been granted the
953 can access all groups' usage.
954 .It Sy groupobjused Ns @ Ns Em group
955 The number of objects consumed by the specified group in this dataset.
956 Multiple objects may be charged to the group for each file when extended
957 attributes are in use. See the
958 .Sy userobjused Ns @ Ns Em user
959 property for more information.
961 Unprivileged users can only access their own groups' space usage.
962 The root user, or a user who has been granted the
966 can access all groups' usage.
967 .It Sy projectused Ns @ Ns Em project
968 The amount of space consumed by the specified project in this dataset. Project
969 is identified via the project identifier (ID) that is object-based numeral
970 attribute. An object can inherit the project ID from its parent object (if the
971 parent has the flag of inherit project ID that can be set and changed via
974 .Nm zfs project Fl s )
975 when being created. The privileged user can set and change object's project
980 anytime. Space is charged to the project of each file, as displayed by
985 .Sy userused Ns @ Ns Em user
986 property for more information.
988 The root user, or a user who has been granted the
992 can access all projects' usage.
993 .It Sy projectobjused Ns @ Ns Em project
998 but instead it counts the number of objects consumed by project. When the
1001 is set on a fileset, ZFS will create additional objects per-file to store
1002 extended attributes. These additional objects are reflected in the
1004 value and are counted against the project's
1005 .Sy projectobjquota .
1006 When a filesystem is configured to use
1008 no additional internal objects are required. See the
1009 .Sy userobjused Ns @ Ns Em user
1010 property for more information.
1012 The root user, or a user who has been granted the
1016 can access all projects' objects usage.
1018 For volumes, specifies the block size of the volume.
1021 cannot be changed once the volume has been written, so it should be set at
1022 volume creation time.
1025 for volumes is 8 Kbytes.
1026 Any power of 2 from 512 bytes to 128 Kbytes is valid.
1028 This property can also be referred to by its shortened column name,
1033 by this dataset, that was written since the previous snapshot
1034 .Pq i.e. that is not referenced by the previous snapshot .
1035 .It Sy written Ns @ Ns Em snapshot
1038 space written to this dataset since the specified snapshot.
1039 This is the space that is referenced by this dataset but was not referenced by
1040 the specified snapshot.
1044 may be specified as a short snapshot name
1045 .Po just the part after the
1048 in which case it will be interpreted as a snapshot in the same filesystem as
1052 may be a full snapshot name
1053 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1054 which for clones may be a snapshot in the origin's filesystem
1055 .Pq or the origin of the origin's filesystem, etc.
1058 The following native properties can be used to change the behavior of a ZFS
1062 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1063 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1065 Controls how ACEs are inherited when files and directories are created.
1066 .Bl -tag -width "passthrough-x"
1068 does not inherit any ACEs.
1070 only inherits inheritable ACEs that specify
1074 default, removes the
1078 permissions when the ACE is inherited.
1080 inherits all inheritable ACEs without any modifications.
1081 .It Sy passthrough-x
1089 ACEs inherit the execute permission only if the file creation mode also requests
1093 When the property value is set to
1095 files are created with a mode determined by the inheritable ACEs.
1096 If no inheritable ACEs exist that affect the mode, then the mode is set in
1097 accordance to the requested mode from the application.
1101 property does not apply to POSIX ACLs.
1102 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1103 Controls whether ACLs are enabled and if so what type of ACL to use.
1104 .Bl -tag -width "posixacl"
1106 default, when a file system has the
1108 property set to off then ACLs are disabled.
1113 indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are
1114 not functional on other platforms. POSIX ACLs are stored as an extended
1115 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1119 To obtain the best performance when setting
1121 users are strongly encouraged to set the
1123 property. This will result in the POSIX ACL being stored more efficiently on
1124 disk. But as a consequence, all new extended attributes will only be
1125 accessible from OpenZFS implementations which support the
1129 property for more details.
1130 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1131 Controls whether the access time for files is updated when they are read.
1132 Turning this property off avoids producing write traffic when reading files and
1133 can result in significant performance gains, though it might confuse mailers
1134 and other similar utilities. The values
1138 are equivalent to the
1142 mount options. The default value is
1147 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1148 If this property is set to
1150 the file system cannot be mounted, and is ignored by
1151 .Nm zfs Cm mount Fl a .
1152 Setting this property to
1154 is similar to setting the
1158 except that the dataset still has a normal
1160 property, which can be inherited.
1161 Setting this property to
1163 allows datasets to be used solely as a mechanism to inherit properties.
1164 One example of setting
1165 .Sy canmount Ns = Ns Sy off
1166 is to have two datasets with the same
1168 so that the children of both datasets appear in the same directory, but might
1169 have different inherited characteristics.
1173 a dataset can only be mounted and unmounted explicitly.
1174 The dataset is not mounted automatically when the dataset is created or
1175 imported, nor is it mounted by the
1176 .Nm zfs Cm mount Fl a
1177 command or unmounted by the
1178 .Nm zfs Cm unmount Fl a
1181 This property is not inherited.
1183 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1184 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1185 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1187 Controls the checksum used to verify data integrity.
1188 The default value is
1190 which automatically selects an appropriate algorithm
1193 but this may change in future releases
1197 disables integrity checking on user data.
1200 not only disables integrity but also disables maintaining parity for user data.
1201 This setting is used internally by a dump device residing on a RAID-Z pool and
1202 should not be used by any other dataset.
1203 Disabling checksums is
1205 a recommended practice.
1212 checksum algorithms require enabling the appropriate features on the pool.
1213 These pool features are not supported by GRUB and must not be used on the
1214 pool if GRUB needs to access the pool (e.g. for /boot).
1217 .Xr zpool-features 5
1218 for more information on these algorithms.
1220 Changing this property affects only newly-written data.
1222 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1223 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1225 Controls the compression algorithm used for this dataset.
1227 Setting compression to
1229 indicates that the current default compression algorithm should be used.
1230 The default balances compression and decompression speed, with compression ratio
1231 and is expected to work well on a wide variety of workloads.
1232 Unlike all other settings for this property,
1234 does not select a fixed compression type.
1235 As new compression algorithms are added to ZFS and enabled on a pool, the
1236 default compression algorithm may change.
1237 The current default compression algorithm is either
1246 compression algorithm is a high-performance replacement for the
1249 It features significantly faster compression and decompression, as well as a
1250 moderately higher compression ratio than
1252 but can only be used on pools with the
1257 .Xr zpool-features 5
1258 for details on ZFS feature flags and the
1264 compression algorithm is optimized for performance while providing decent data
1269 compression algorithm uses the same compression as the
1274 level by using the value
1278 is an integer from 1
1281 .Pq best compression ratio .
1286 .Po which is also the default for
1292 compression algorithm compresses runs of zeros.
1294 This property can also be referred to by its shortened column name
1296 Changing this property affects only newly-written data.
1298 When any setting except
1300 is selected, compression will explicitly check for blocks consisting of only
1301 zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
1302 a hole and not compressed using the indicated compression algorithm.
1304 Any block being compressed must be no larger than 7/8 of its original size
1305 after compression, otherwise the compression will not be considered worthwhile
1306 and the block saved uncompressed. Note that when the logical block is less than
1307 8 times the disk sector size this effectively reduces the necessary compression
1308 ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
1309 or less of their original size.
1311 .Sy context Ns = Ns Sy none Ns | Ns
1312 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1314 This flag sets the SELinux context for all files in the file system under
1315 a mount point for that file system. See
1317 for more information.
1319 .Sy fscontext Ns = Ns Sy none Ns | Ns
1320 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1322 This flag sets the SELinux context for the file system file system being
1325 for more information.
1327 .Sy defcontext Ns = Ns Sy none Ns | Ns
1328 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1330 This flag sets the SELinux default context for unlabeled files. See
1332 for more information.
1334 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1335 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1337 This flag sets the SELinux context for the root inode of the file system. See
1339 for more information.
1340 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1341 Controls the number of copies of data stored for this dataset.
1342 These copies are in addition to any redundancy provided by the pool, for
1343 example, mirroring or RAID-Z.
1344 The copies are stored on different disks, if possible.
1345 The space used by multiple copies is charged to the associated file and dataset,
1348 property and counting against quotas and reservations.
1350 Changing this property only affects newly-written data.
1351 Therefore, set this property at file system creation time by using the
1352 .Fl o Sy copies Ns = Ns Ar N
1355 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1357 create, for example a two-disk striped pool and set
1359 on some datasets thinking you have setup redundancy for them. When a disk
1360 fails you will not be able to import the pool and will have lost all of your
1363 Encrypted datasets may not have
1364 .Sy copies Ns = Ns Em 3
1365 since the implementation stores some encryption metadata where the third copy
1367 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1368 Controls whether device nodes can be opened on this file system.
1369 The default value is
1375 are equivalent to the
1381 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1382 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1385 Configures deduplication for a dataset. The default value is
1387 The default deduplication checksum is
1389 (this may change in the future). When
1391 is enabled, the checksum defined here overrides the
1393 property. Setting the value to
1395 has the same effect as the setting
1400 ZFS will do a byte-to-byte comparison in case of two blocks having the same
1401 signature to make sure the block contents are identical. Specifying
1403 is mandatory for the
1407 Unless necessary, deduplication should NOT be enabled on a system. See
1411 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1412 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1414 Specifies a compatibility mode or literal value for the size of dnodes in the
1415 file system. The default value is
1417 Setting this property to a value other than
1419 requires the large_dnode pool feature to be enabled.
1425 if the dataset uses the
1427 property setting and the workload makes heavy use of extended attributes. This
1428 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1429 servers, for example. Literal values are supported for cases where the optimal
1430 size is known in advance and for performance testing.
1436 if you need to receive a send stream of this dataset on a pool that doesn't
1437 enable the large_dnode feature, or if you need to import this pool on a system
1438 that doesn't support the large_dnode feature.
1440 This property can also be referred to by its shortened column name,
1443 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1444 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1445 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1447 Controls the encryption cipher suite (block cipher, key length, and mode) used
1448 for this dataset. Requires the
1450 feature to be enabled on the pool.
1453 to be set at dataset creation time.
1456 .Sy encryption Ns = Ns Sy on
1457 when creating a dataset indicates that the default encryption suite will be
1458 selected, which is currently
1460 In order to provide consistent data protection, encryption must be specified at
1461 dataset creation time and it cannot be changed afterwards.
1463 For more details and caveats about encryption see the
1466 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1467 Controls what format the user's encryption key will be provided as. This
1468 property is only set when the dataset is encrypted.
1470 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1471 encryption suite) and must be randomly generated. A raw key can be generated
1472 with the following command:
1474 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1477 Passphrases must be between 8 and 512 bytes long and will be processed through
1478 PBKDF2 before being used (see the
1480 property). Even though the
1481 encryption suite cannot be changed after dataset creation, the keyformat can be
1483 .Nm zfs Cm change-key .
1485 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1487 Controls where the user's encryption key will be loaded from by default for
1491 .Nm zfs Cm mount Cm -l .
1492 This property is only set for encrypted datasets which are encryption roots. If
1493 unspecified, the default is
1496 Even though the encryption suite cannot be changed after dataset creation, the
1497 keylocation can be with either
1500 .Nm zfs Cm change-key .
1503 is selected ZFS will ask for the key at the command prompt when it is required
1504 to access the encrypted data (see
1506 for details). This setting will also allow the key to be passed in via STDIN,
1507 but users should be careful not to place keys which should be kept secret on
1508 the command line. If a file URI is selected, the key will be loaded from the
1509 specified absolute file path.
1510 .It Sy pbkdf2iters Ns = Ns Ar iterations
1511 Controls the number of PBKDF2 iterations that a
1513 encryption key should be run through when processing it into an encryption key.
1514 This property is only defined when encryption is enabled and a keyformat of
1516 is selected. The goal of PBKDF2 is to significantly increase the
1517 computational difficulty needed to brute force a user's passphrase. This is
1518 accomplished by forcing the attacker to run each passphrase through a
1519 computationally expensive hashing function many times before they arrive at the
1520 resulting key. A user who actually knows the passphrase will only have to pay
1521 this cost once. As CPUs become better at processing, this number should be
1522 raised to ensure that a brute force attack is still not possible. The current
1527 This property may be changed with
1528 .Nm zfs Cm change-key .
1529 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1530 Controls whether processes can be executed from within this file system.
1531 The default value is
1537 are equivalent to the
1542 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1543 Limits the number of filesystems and volumes that can exist under this point in
1545 The limit is not enforced if the user is allowed to change the limit.
1547 .Sy filesystem_limit
1550 a descendent of a filesystem that already has a
1551 .Sy filesystem_limit
1552 does not override the ancestor's
1553 .Sy filesystem_limit ,
1554 but rather imposes an additional limit.
1555 This feature must be enabled to be used
1557 .Xr zpool-features 5
1559 .It Sy special_small_blocks Ns = Ns Em size
1560 This value represents the threshold block size for including small file
1561 blocks into the special allocation class. Blocks smaller than or equal to this
1562 value will be assigned to the special allocation class while greater blocks
1563 will be assigned to the regular class. Valid values are zero or a power of two
1564 from 512B up to 128K. The default size is 0 which means no small file blocks
1565 will be allocated in the special class.
1567 Before setting this property, a special class vdev must be added to the
1570 for more details on the special allocation class.
1571 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1572 Controls the mount point used for this file system.
1575 section for more information on how this property is used.
1579 property is changed for a file system, the file system and any children that
1580 inherit the mount point are unmounted.
1583 then they remain unmounted.
1584 Otherwise, they are automatically remounted in the new location if the property
1589 or if they were mounted before the property was changed.
1590 In addition, any shared file systems are unshared and shared in the new
1592 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1593 Controls whether the file system should be mounted with
1595 .Pq Non Blocking mandatory locks .
1596 This is used for SMB clients.
1597 Changes to this property only take effect when the file system is umounted and
1601 for more information on
1603 mounts. This property is not used on Linux.
1604 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1605 Allow mounting on a busy directory or a directory which already contains
1606 files or directories. This is the default mount behavior for Linux file systems.
1607 For consistency with OpenZFS on other platforms overlay mounts are
1611 to enable overlay mounts.
1612 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1613 Controls what is cached in the primary cache
1615 If this property is set to
1617 then both user data and metadata is cached.
1618 If this property is set to
1620 then neither user data nor metadata is cached.
1621 If this property is set to
1623 then only metadata is cached.
1624 The default value is
1626 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1627 Limits the amount of space a dataset and its descendents can consume.
1628 This property enforces a hard limit on the amount of space used.
1629 This includes all space consumed by descendents, including file systems and
1631 Setting a quota on a descendent of a dataset that already has a quota does not
1632 override the ancestor's quota, but rather imposes an additional limit.
1634 Quotas cannot be set on volumes, as the
1636 property acts as an implicit quota.
1637 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1638 Limits the number of snapshots that can be created on a dataset and its
1642 on a descendent of a dataset that already has a
1644 does not override the ancestor's
1645 .Sy snapshot_limit ,
1646 but rather imposes an additional limit.
1647 The limit is not enforced if the user is allowed to change the limit.
1648 For example, this means that recursive snapshots taken from the global zone are
1649 counted against each delegated dataset within a zone.
1650 This feature must be enabled to be used
1652 .Xr zpool-features 5
1654 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1655 Limits the amount of space consumed by the specified user.
1656 User space consumption is identified by the
1657 .Sy userspace@ Ns Em user
1660 Enforcement of user quotas may be delayed by several seconds.
1661 This delay means that a user might exceed their quota before the system notices
1662 that they are over quota and begins to refuse additional writes with the
1666 .Nm zfs Cm userspace
1667 subcommand for more information.
1669 Unprivileged users can only access their own groups' space usage.
1670 The root user, or a user who has been granted the
1674 can get and set everyone's quota.
1676 This property is not available on volumes, on file systems before version 4, or
1677 on pools before version 15.
1679 .Sy userquota@ Ns Em ...
1680 properties are not displayed by
1681 .Nm zfs Cm get Sy all .
1682 The user's name must be appended after the
1684 symbol, using one of the following forms:
1692 .Em POSIX numeric ID
1699 .Sy joe.smith@mydomain
1708 Files created on Linux always have POSIX owners.
1709 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1714 but it limits the number of objects a user can create. Please refer to
1716 for more information about how objects are counted.
1717 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1718 Limits the amount of space consumed by the specified group.
1719 Group space consumption is identified by the
1720 .Sy groupused@ Ns Em group
1723 Unprivileged users can access only their own groups' space usage.
1724 The root user, or a user who has been granted the
1728 can get and set all groups' quotas.
1729 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1734 but it limits number of objects a group can consume. Please refer to
1736 for more information about how objects are counted.
1737 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1738 Limits the amount of space consumed by the specified project. Project
1739 space consumption is identified by the
1740 .Sy projectused@ Ns Em project
1741 property. Please refer to
1743 for more information about how project is identified and set/changed.
1745 The root user, or a user who has been granted the
1749 can access all projects' quota.
1750 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1755 but it limits number of objects a project can consume. Please refer to
1757 for more information about how objects are counted.
1758 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1759 Controls whether this dataset can be modified.
1760 The default value is
1766 are equivalent to the
1772 This property can also be referred to by its shortened column name,
1774 .It Sy recordsize Ns = Ns Em size
1775 Specifies a suggested block size for files in the file system.
1776 This property is designed solely for use with database workloads that access
1777 files in fixed-size records.
1778 ZFS automatically tunes block sizes according to internal algorithms optimized
1779 for typical access patterns.
1781 For databases that create very large files but access them in small random
1782 chunks, these algorithms may be suboptimal.
1785 greater than or equal to the record size of the database can result in
1786 significant performance gains.
1787 Use of this property for general purpose file systems is strongly discouraged,
1788 and may adversely affect performance.
1790 The size specified must be a power of two greater than or equal to 512 and less
1791 than or equal to 128 Kbytes.
1794 feature is enabled on the pool, the size may be up to 1 Mbyte.
1796 .Xr zpool-features 5
1797 for details on ZFS feature flags.
1799 Changing the file system's
1801 affects only files created afterward; existing files are unaffected.
1803 This property can also be referred to by its shortened column name,
1805 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1806 Controls what types of metadata are stored redundantly.
1807 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1808 the amount of user data lost is limited.
1809 This extra copy is in addition to any redundancy provided at the pool level
1810 .Pq e.g. by mirroring or RAID-Z ,
1811 and is in addition to an extra copy specified by the
1814 .Pq up to a total of 3 copies .
1815 For example if the pool is mirrored,
1816 .Sy copies Ns = Ns 2 ,
1818 .Sy redundant_metadata Ns = Ns Sy most ,
1819 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1824 ZFS stores an extra copy of all metadata.
1825 If a single on-disk block is corrupt, at worst a single block of user data
1834 ZFS stores an extra copy of most types of metadata.
1835 This can improve performance of random writes, because less metadata must be
1837 In practice, at worst about 100 blocks
1842 of user data can be lost if a single on-disk block is corrupt.
1843 The exact behavior of which metadata blocks are stored redundantly may change in
1846 The default value is
1848 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1849 Limits the amount of space a dataset can consume.
1850 This property enforces a hard limit on the amount of space used.
1851 This hard limit does not include space used by descendents, including file
1852 systems and snapshots.
1853 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1854 The minimum amount of space guaranteed to a dataset, not including its
1856 When the amount of space used is below this value, the dataset is treated as if
1857 it were taking up the amount of space specified by
1858 .Sy refreservation .
1861 reservation is accounted for in the parent datasets' space used, and counts
1862 against the parent datasets' quotas and reservations.
1866 is set, a snapshot is only allowed if there is enough free pool space outside of
1867 this reservation to accommodate the current number of
1869 bytes in the dataset.
1875 a volume is thick provisioned
1879 .Sy refreservation Ns = Ns Sy auto
1880 is only supported on volumes.
1884 .Sx Native Properties
1885 section for more information about sparse volumes.
1887 This property can also be referred to by its shortened column name,
1889 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1890 Controls the manner in which the access time is updated when
1892 is set. Turning this property on causes the access time to be updated relative
1893 to the modify or change time. Access time is only updated if the previous
1894 access time was earlier than the current modify or change time or if the
1895 existing access time hasn't been updated within the past 24 hours. The default
1902 are equivalent to the
1907 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1908 The minimum amount of space guaranteed to a dataset and its descendants.
1909 When the amount of space used is below this value, the dataset is treated as if
1910 it were taking up the amount of space specified by its reservation.
1911 Reservations are accounted for in the parent datasets' space used, and count
1912 against the parent datasets' quotas and reservations.
1914 This property can also be referred to by its shortened column name,
1916 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1917 Controls what is cached in the secondary cache
1919 If this property is set to
1921 then both user data and metadata is cached.
1922 If this property is set to
1924 then neither user data nor metadata is cached.
1925 If this property is set to
1927 then only metadata is cached.
1928 The default value is
1930 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1931 Controls whether the setuid bit is respected for the file system.
1932 The default value is
1938 are equivalent to the
1943 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1944 Controls whether the file system is shared by using
1945 .Sy Samba USERSHARES
1946 and what options are to be used. Otherwise, the file system is automatically
1947 shared and unshared with the
1951 commands. If the property is set to on, the
1953 command is invoked to create a
1956 Because SMB shares requires a resource name, a unique resource name is
1957 constructed from the dataset name. The constructed name is a copy of the
1958 dataset name except that the characters in the dataset name, which would be
1959 invalid in the resource name, are replaced with underscore (_) characters.
1960 Linux does not currently support additional options which might be available
1967 the file systems are unshared.
1969 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1970 stands for "full permissions", ie. read and write permissions) and no guest
1971 access (which means Samba must be able to authenticate a real user, system
1972 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1973 additional access control (disallow specific user specific access etc) must
1974 be done on the underlying file system.
1975 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1976 Controls whether the file system is shared via NFS, and what options are to be
1978 A file system with a
1984 command and entries in the
1987 Otherwise, the file system is automatically shared and unshared with the
1992 If the property is set to
1994 the dataset is shared using the default options:
1996 .Em sec=sys,rw,crossmnt,no_subtree_check
2000 for the meaning of the default options. Otherwise, the
2002 command is invoked with options equivalent to the contents of this property.
2006 property is changed for a dataset, the dataset and any children inheriting the
2007 property are re-shared with the new options, only if the property was previously
2009 or if they were shared before the property was changed.
2010 If the new property is
2012 the file systems are unshared.
2013 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
2014 Provide a hint to ZFS about handling of synchronous requests in this dataset.
2020 ZFS will use pool log devices
2022 to handle the requests at low latency.
2027 ZFS will not use configured pool log devices.
2028 ZFS will instead optimize synchronous operations for global pool throughput and
2029 efficient use of resources.
2030 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
2031 Controls whether the volume snapshot devices under
2032 .Em /dev/zvol/<pool>
2033 are hidden or visible. The default value is
2035 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
2036 Controls whether the
2038 directory is hidden or visible in the root of the file system as discussed in
2042 The default value is
2044 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
2045 Controls the behavior of synchronous requests
2046 .Pq e.g. fsync, O_DSYNC .
2050 specified behavior of ensuring all synchronous requests are written to stable
2051 storage and all devices are flushed to ensure data is not cached by device
2053 .Pq this is the default .
2055 causes every file system transaction to be written and flushed before its
2056 system call returns.
2057 This has a large performance penalty.
2059 disables synchronous requests.
2060 File system transactions are only committed to stable storage periodically.
2061 This option will give the highest performance.
2062 However, it is very dangerous as ZFS would be ignoring the synchronous
2063 transaction demands of applications such as databases or NFS.
2064 Administrators should only use this option when the risks are understood.
2065 .It Sy version Ns = Ns Em N Ns | Ns Sy current
2066 The on-disk version of this file system, which is independent of the pool
2068 This property can only be set to later supported versions.
2072 .It Sy volsize Ns = Ns Em size
2073 For volumes, specifies the logical size of the volume.
2074 By default, creating a volume establishes a reservation of equal size.
2075 For storage pools with a version number of 9 or higher, a
2080 are reflected in an equivalent change to the reservation
2086 can only be set to a multiple of
2090 The reservation is kept equal to the volume's logical size to prevent unexpected
2091 behavior for consumers.
2092 Without the reservation, the volume could run out of space, resulting in
2093 undefined behavior or data corruption, depending on how the volume is used.
2094 These effects can also occur when the volume size is changed while it is in use
2095 .Pq particularly when shrinking the size .
2096 Extreme care should be used when adjusting the volume size.
2098 Though not recommended, a
2101 .Qq thin provisioned
2103 can be created by specifying the
2106 .Nm zfs Cm create Fl V
2107 command, or by changing the value of the
2112 property on pool version 8 or earlier
2114 after the volume has been created.
2117 is a volume where the value of
2119 is less than the size of the volume plus the space required to store its
2121 Consequently, writes to a sparse volume can fail with
2123 when the pool is low on space.
2124 For a sparse volume, changes to
2126 are not reflected in the
2128 A volume that is not sparse is said to be
2129 .Qq thick provisioned .
2130 A sparse volume can become thick provisioned by setting
2134 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2135 This property specifies how volumes should be exposed to the OS.
2138 exposes volumes as fully fledged block devices, providing maximal
2139 functionality. The value
2141 is just an alias for
2143 and is kept for compatibility.
2146 hides its partitions.
2147 Volumes with property set to
2149 are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
2150 that can be suitable for backup purposes.
2153 means that volumes exposition is controlled by system-wide tunable
2160 are encoded as 1, 2 and 3 respectively.
2161 The default values is
2163 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2164 Controls whether regular files should be scanned for viruses when a file is
2166 In addition to enabling this property, the virus scan service must also be
2167 enabled for virus scanning to occur.
2168 The default value is
2170 This property is not used on Linux.
2171 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2172 Controls whether extended attributes are enabled for this file system. Two
2173 styles of extended attributes are supported either directory based or system
2176 The default value of
2178 enables directory based extended attributes. This style of extended attribute
2179 imposes no practical limit on either the size or number of attributes which
2180 can be set on a file. Although under Linux the
2184 system calls limit the maximum size to 64K. This is the most compatible
2185 style of extended attribute and is supported by all OpenZFS implementations.
2187 System attribute based xattrs can be enabled by setting the value to
2189 The key advantage of this type of xattr is improved performance. Storing
2190 extended attributes as system attributes significantly decreases the amount of
2191 disk IO required. Up to 64K of data may be stored per-file in the space
2192 reserved for system attributes. If there is not enough space available for
2193 an extended attribute then it will be automatically written as a directory
2194 based xattr. System attribute based extended attributes are not accessible
2195 on platforms which do not support the
2199 The use of system attribute based xattrs is strongly encouraged for users of
2200 SELinux or POSIX ACLs. Both of these features heavily rely of extended
2201 attributes and benefit significantly from the reduced access time.
2207 are equivalent to the
2212 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2213 Controls whether the dataset is managed from a non-global zone. Zones are a
2214 Solaris feature and are not relevant on Linux. The default value is
2218 The following three properties cannot be changed after the file system is
2219 created, and therefore, should be set when the file system is created.
2220 If the properties are not set with the
2224 commands, these properties are inherited from the parent dataset.
2225 If the parent dataset lacks these properties due to having been created prior to
2226 these features being supported, the new file system will have the default values
2227 for these properties.
2230 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2231 .Sy insensitive Ns | Ns Sy mixed
2233 Indicates whether the file name matching algorithm used by the file system
2234 should be case-sensitive, case-insensitive, or allow a combination of both
2236 The default value for the
2244 file systems have case-sensitive file names.
2250 property indicates that the file system can support requests for both
2251 case-sensitive and case-insensitive matching behavior.
2252 Currently, case-insensitive matching behavior on a file system that supports
2253 mixed behavior is limited to the SMB server product.
2254 For more information about the
2256 value behavior, see the "ZFS Administration Guide".
2258 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2259 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2261 Indicates whether the file system should perform a
2263 normalization of file names whenever two file names are compared, and which
2264 normalization algorithm should be used.
2265 File names are always stored unmodified, names are normalized as part of any
2267 If this property is set to a legal value other than
2271 property was left unspecified, the
2273 property is automatically set to
2275 The default value of the
2279 This property cannot be changed after the file system is created.
2280 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2281 Indicates whether the file system should reject file names that include
2282 characters that are not present in the
2285 If this property is explicitly set to
2287 the normalization property must either not be explicitly set or be set to
2289 The default value for the
2293 This property cannot be changed after the file system is created.
2297 .Sy casesensitivity ,
2301 properties are also new permissions that can be assigned to non-privileged users
2302 by using the ZFS delegated administration feature.
2303 .Ss "Temporary Mount Point Properties"
2304 When a file system is mounted, either through
2306 for legacy mounts or the
2308 command for normal file systems, its mount options are set according to its
2310 The correlation between properties and mount options is as follows:
2312 PROPERTY MOUNT OPTION
2314 canmount auto/noauto
2318 relatime relatime/norelatime
2323 In addition, these options can be set on a per-mount basis using the
2325 option, without affecting the property that is stored on disk.
2326 The values specified on the command line override the values stored in the
2330 option is an alias for
2331 .Sy nodevices Ns \&, Ns Sy nosetuid .
2332 These properties are reported as
2337 If the properties are changed while the dataset is mounted, the new setting
2338 overrides any temporary settings.
2339 .Ss "User Properties"
2340 In addition to the standard native properties, ZFS supports arbitrary user
2342 User properties have no effect on ZFS behavior, but applications or
2343 administrators can use them to annotate datasets
2344 .Pq file systems, volumes, and snapshots .
2346 User property names must contain a colon
2348 character to distinguish them from native properties.
2349 They may contain lowercase letters, numbers, and the following punctuation
2358 The expected convention is that the property name is divided into two portions
2360 .Em module Ns \&: Ns Em property ,
2361 but this namespace is not enforced by ZFS.
2362 User property names can be at most 256 characters, and cannot begin with a dash
2365 When making programmatic use of user properties, it is strongly suggested to use
2370 component of property names to reduce the chance that two
2371 independently-developed packages use the same property name for different
2374 The values of user properties are arbitrary strings, are always inherited, and
2375 are never validated.
2376 All of the commands that operate on properties
2377 .Po Nm zfs Cm list ,
2382 can be used to manipulate both native properties and user properties.
2385 command to clear a user property.
2386 If the property is not defined in any parent dataset, it is removed entirely.
2387 Property values are limited to 8192 bytes.
2388 .Ss ZFS Volumes as Swap
2389 ZFS volumes may be used as swap devices. After creating the volume with the
2390 .Nm zfs Cm create Fl V
2391 command set up and enable the swap area using the
2395 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2396 configuration is not supported.
2400 feature allows for the creation of encrypted filesystems and volumes. ZFS
2401 will encrypt file and zvol data, file attributes, ACLs, permission bits,
2402 directory listings, FUID mappings, and
2406 data. ZFS will not encrypt metadata related to the pool structure, including
2407 dataset and snapshot names, dataset hierarchy, properties, file size, file
2408 holes, and deduplication tables (though the deduplicated data itself is
2411 Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase)
2412 does not require re-encrypting the entire dataset. Datasets can be scrubbed,
2413 resilvered, renamed, and deleted without the encryption keys being loaded (see the
2415 subcommand for more info on key loading).
2417 Creating an encrypted dataset requires specifying the
2421 properties at creation time, along with an optional
2425 After entering an encryption key, the
2426 created dataset will become an encryption root. Any descendant datasets will
2427 inherit their encryption key from the encryption root by default, meaning that
2428 loading, unloading, or changing the key for the encryption root will implicitly
2429 do the same for all inheriting datasets. If this inheritance is not desired,
2432 when creating the child dataset or use
2433 .Nm zfs Cm change-key
2434 to break an existing relationship, creating a new encryption root on the child.
2435 Note that the child's
2437 may match that of the parent while still creating a new encryption root, and
2440 property alone does not create a new encryption root; this would simply use a
2441 different cipher suite with the same key as its encryption root. The one
2442 exception is that clones will always use their origin's encryption key.
2443 As a result of this exception, some encryption-related properties (namely
2449 do not inherit like other ZFS properties and instead use the value determined
2450 by their encryption root. Encryption root inheritance can be tracked via the
2455 Encryption changes the behavior of a few ZFS
2456 operations. Encryption is applied after compression so compression ratios are
2457 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2458 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2459 the encryption suite, which provides additional protection against maliciously
2460 altered data. Deduplication is still possible with encryption enabled but for
2461 security, datasets will only dedup against themselves, their snapshots, and
2464 There are a few limitations on encrypted datasets. Encrypted data cannot be
2467 feature. Encrypted datasets may not have
2468 .Sy copies Ns = Ns Em 3
2469 since the implementation stores some encryption metadata where the third copy
2470 would normally be. Since compression is applied before encryption datasets may
2471 be vulnerable to a CRIME-like attack if applications accessing the data allow
2472 for it. Deduplication with encryption will leak information about which blocks
2473 are equivalent in a dataset and will incur an extra CPU cost per block written.
2475 ZFS has support for a limited version of data subsetting, in the form of
2476 redaction. Using the
2479 .Sy redaction bookmark
2480 can be created that stores a list of blocks containing sensitive information. When
2486 to occur. Redacted sends omit the blocks containing sensitive information,
2487 replacing them with REDACT records. When these send streams are received, a
2488 .Sy redacted dataset
2489 is created. A redacted dataset cannot be mounted by default, since it is
2490 incomplete. It can be used to receive other send streams. In this way datasets
2491 can be used for data backup and replication, with all the benefits that zfs send
2492 and receive have to offer, while protecting sensitive information from being
2493 stored on less-trusted machines or services.
2495 For the purposes of redaction, there are two steps to the process. A redact
2496 step, and a send/receive step. First, a redaction bookmark is created. This is
2497 done by providing the
2499 command with a parent snapshot, a bookmark to be created, and a number of
2500 redaction snapshots. These redaction snapshots must be descendants of the
2501 parent snapshot, and they should modify data that is considered sensitive in
2502 some way. Any blocks of data modified by all of the redaction snapshots will
2503 be listed in the redaction bookmark, because it represents the truly sensitive
2504 information. When it comes to the send step, the send process will not send
2505 the blocks listed in the redaction bookmark, instead replacing them with
2506 REDACT records. When received on the target system, this will create a
2507 redacted dataset, missing the data that corresponds to the blocks in the
2508 redaction bookmark on the sending system. The incremental send streams from
2509 the original parent to the redaction snapshots can then also be received on
2510 the target system, and this will produce a complete snapshot that can be used
2511 normally. Incrementals from one snapshot on the parent filesystem and another
2512 can also be done by sending from the redaction bookmark, rather than the
2513 snapshots themselves.
2515 In order to make the purpose of the feature more clear, an example is
2516 provided. Consider a zfs filesystem containing four files. These files
2517 represent information for an online shopping service. One file contains a list
2518 of usernames and passwords, another contains purchase histories, a third
2519 contains click tracking data, and a fourth contains user preferences. The
2520 owner of this data wants to make it available for their development teams to
2521 test against, and their market research teams to do analysis on. The
2522 development teams need information about user preferences and the click
2523 tracking data, while the market research teams need information about purchase
2524 histories and user preferences. Neither needs access to the usernames and
2525 passwords. However, because all of this data is stored in one ZFS filesystem,
2526 it must all be sent and received together. In addition, the owner of the data
2527 wants to take advantage of features like compression, checksumming, and
2528 snapshots, so they do want to continue to use ZFS to store and transmit their
2529 data. Redaction can help them do so. First, they would make two clones of a
2530 snapshot of the data on the source. In one clone, they create the setup they
2531 want their market research team to see; they delete the usernames and
2532 passwords file, and overwrite the click tracking data with dummy
2533 information. In another, they create the setup they want the development teams
2534 to see, by replacing the passwords with fake information and replacing the
2535 purchase histories with randomly generated ones. They would then create a
2536 redaction bookmark on the parent snapshot, using snapshots on the two clones
2537 as redaction snapshots. The parent can then be sent, redacted, to the target
2538 server where the research and development teams have access. Finally,
2539 incremental sends from the parent snapshot to each of the clones can be send
2540 to and received on the target server; these snapshots are identical to the
2541 ones on the source, and are ready to be used, while the parent snapshot on the
2542 target contains none of the username and password data present on the source,
2543 because it was removed by the redacted send operation.
2545 All subcommands that modify state are logged persistently to the pool in their
2549 Displays a help message.
2561 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2564 Creates a new ZFS file system.
2565 The file system is automatically mounted according to the
2567 property inherited from the parent.
2568 .Bl -tag -width "-o"
2569 .It Fl o Ar property Ns = Ns Ar value
2570 Sets the specified property as if the command
2571 .Nm zfs Cm set Ar property Ns = Ns Ar value
2572 was invoked at the same time the dataset was created.
2573 Any editable ZFS property can also be set at creation time.
2576 options can be specified.
2577 An error results if the same property is specified in multiple
2581 Creates all the non-existing parent datasets.
2582 Datasets created in this manner are automatically mounted according to the
2584 property inherited from their parent.
2585 Any property specified on the command line using the
2588 If the target filesystem already exists, the operation completes successfully.
2593 No datasets will be created.
2594 This is useful in conjunction with the
2598 flags to validate properties that are passed via
2600 options and those implied by other options.
2601 The actual dataset creation can still fail due to insufficient privileges or
2604 Print machine-parsable verbose information about the created dataset.
2605 Each line of output contains a key and one or two values, all separated by tabs.
2607 .Sy create_ancestors
2612 as their only value.
2614 .Sy create_ancestors
2615 key only appears if the
2620 key has two values, a property name that property's value.
2623 key may appear zero or more times, once for each property that will be set local
2626 due to the use of the
2630 Print verbose information about the created dataset.
2636 .Op Fl b Ar blocksize
2637 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2638 .Fl V Ar size Ar volume
2640 Creates a volume of the given size.
2641 The volume is exported as a block device in
2642 .Pa /dev/zvol/path ,
2645 is the name of the volume in the ZFS namespace.
2646 The size represents the logical size as exported by the device.
2647 By default, a reservation of equal size is created.
2650 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2651 has an integral number of blocks regardless of
2653 .Bl -tag -width "-b"
2654 .It Fl b Ar blocksize
2656 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2657 If this option is specified in conjunction with
2658 .Fl o Sy volblocksize ,
2659 the resulting behavior is undefined.
2660 .It Fl o Ar property Ns = Ns Ar value
2661 Sets the specified property as if the
2662 .Nm zfs Cm set Ar property Ns = Ns Ar value
2663 command was invoked at the same time the dataset was created.
2664 Any editable ZFS property can also be set at creation time.
2667 options can be specified.
2668 An error results if the same property is specified in multiple
2672 Creates all the non-existing parent datasets.
2673 Datasets created in this manner are automatically mounted according to the
2675 property inherited from their parent.
2676 Any property specified on the command line using the
2679 If the target filesystem already exists, the operation completes successfully.
2681 Creates a sparse volume with no reservation.
2685 .Sx Native Properties
2686 section for more information about sparse volumes.
2691 No datasets will be created.
2692 This is useful in conjunction with the
2696 flags to validate properties that are passed via
2698 options and those implied by other options.
2699 The actual dataset creation can still fail due to insufficient privileges or
2702 Print machine-parsable verbose information about the created dataset.
2703 Each line of output contains a key and one or two values, all separated by tabs.
2705 .Sy create_ancestors
2710 as their only value.
2712 .Sy create_ancestors
2713 key only appears if the
2718 key has two values, a property name that property's value.
2721 key may appear zero or more times, once for each property that will be set local
2724 due to the use of the
2730 if the volume is not sparse.
2732 Print verbose information about the created dataset.
2738 .Ar filesystem Ns | Ns Ar volume
2740 Destroys the given dataset.
2741 By default, the command unshares any file systems that are currently shared,
2742 unmounts any file systems that are currently mounted, and refuses to destroy a
2743 dataset that has active dependents
2744 .Pq children or clones .
2745 .Bl -tag -width "-R"
2747 Recursively destroy all dependents, including cloned file systems outside the
2750 Force an unmount of any file systems using the
2753 This option has no effect on non-file systems or unmounted file systems.
2758 No data will be deleted.
2759 This is useful in conjunction with the
2763 flags to determine what data would be deleted.
2765 Print machine-parsable verbose information about the deleted data.
2767 Recursively destroy all children.
2769 Print verbose information about the deleted data.
2772 Extreme care should be taken when applying either the
2776 options, as they can destroy large portions of a pool and cause unexpected
2777 behavior for mounted file systems in use.
2782 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2783 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2785 The given snapshots are destroyed immediately if and only if the
2789 option would have destroyed it.
2790 Such immediate destruction would occur, for example, if the snapshot had no
2791 clones and the user-initiated reference count were zero.
2793 If a snapshot does not qualify for immediate destruction, it is marked for
2795 In this state, it exists as a usable, visible snapshot until both of the
2796 preconditions listed above are met, at which point it is destroyed.
2798 An inclusive range of snapshots may be specified by separating the first and
2799 last snapshots with a percent sign.
2800 The first and/or last snapshots may be left blank, in which case the
2801 filesystem's oldest or newest snapshot will be implied.
2804 .Pq or ranges of snapshots
2805 of the same filesystem or volume may be specified in a comma-separated list of
2807 Only the snapshot's short name
2808 .Po the part after the
2811 should be specified when using a range or comma-separated list to identify
2813 .Bl -tag -width "-R"
2815 Recursively destroy all clones of these snapshots, including the clones,
2816 snapshots, and children.
2817 If this flag is specified, the
2819 flag will have no effect.
2821 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2822 deferred destruction.
2827 No data will be deleted.
2828 This is useful in conjunction with the
2832 flags to determine what data would be deleted.
2834 Print machine-parsable verbose information about the deleted data.
2837 .Pq or mark for deferred deletion
2838 all snapshots with this name in descendent file systems.
2840 Print verbose information about the deleted data.
2842 Extreme care should be taken when applying either the
2846 options, as they can destroy large portions of a pool and cause unexpected
2847 behavior for mounted file systems in use.
2852 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2854 The given bookmark is destroyed.
2859 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2860 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2862 Creates snapshots with the given names.
2863 All previous modifications by successful system calls to the file system are
2864 part of the snapshots.
2865 Snapshots are taken atomically, so that all snapshots correspond to the same
2868 can be used as an alias for
2869 .Nm zfs Cm snapshot.
2872 section for details.
2873 .Bl -tag -width "-o"
2874 .It Fl o Ar property Ns = Ns Ar value
2875 Sets the specified property; see
2879 Recursively create snapshots of all descendent datasets
2887 Roll back the given dataset to a previous snapshot.
2888 When a dataset is rolled back, all data that has changed since the snapshot is
2889 discarded, and the dataset reverts to the state at the time of the snapshot.
2890 By default, the command refuses to roll back to a snapshot other than the most
2892 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2899 options do not recursively destroy the child snapshots of a recursive snapshot.
2900 Only direct snapshots of the specified filesystem are destroyed by either of
2902 To completely roll back a recursive snapshot, you must rollback the individual
2904 .Bl -tag -width "-R"
2906 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2911 option to force an unmount of any clone file systems that are to be destroyed.
2913 Destroy any snapshots and bookmarks more recent than the one specified.
2919 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2920 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2922 Creates a clone of the given snapshot.
2925 section for details.
2926 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2927 as the same type as the original.
2928 .Bl -tag -width "-o"
2929 .It Fl o Ar property Ns = Ns Ar value
2930 Sets the specified property; see
2934 Creates all the non-existing parent datasets.
2935 Datasets created in this manner are automatically mounted according to the
2937 property inherited from their parent.
2938 If the target filesystem or volume already exists, the operation completes
2944 .Ar clone-filesystem
2946 Promotes a clone file system to no longer be dependent on its
2949 This makes it possible to destroy the file system that the clone was created
2951 The clone parent-child dependency relationship is reversed, so that the origin
2952 file system becomes a clone of the specified file system.
2954 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2955 now owned by the promoted clone.
2956 The space they use moves from the origin file system to the promoted clone, so
2957 enough space must be available to accommodate these snapshots.
2958 No new space is consumed by this operation, but the space accounting is
2960 The promoted clone must not have any conflicting snapshot names of its own.
2963 subcommand can be used to rename any conflicting snapshots.
2968 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2969 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2975 .Ar filesystem Ns | Ns Ar volume
2976 .Ar filesystem Ns | Ns Ar volume
2978 Renames the given dataset.
2979 The new target can be located anywhere in the ZFS hierarchy, with the exception
2981 Snapshots can only be renamed within the parent file system or volume.
2982 When renaming a snapshot, the parent file system of the snapshot does not need
2983 to be specified as part of the second argument.
2984 Renamed file systems can inherit new mount points, in which case they are
2985 unmounted and remounted at the new mount point.
2986 .Bl -tag -width "-a"
2988 Force unmount any filesystems that need to be unmounted in the process.
2990 Creates all the nonexistent parent datasets.
2991 Datasets created in this manner are automatically mounted according to the
2993 property inherited from their parent.
2999 .Ar snapshot Ar snapshot
3001 Recursively rename the snapshots of all descendent datasets.
3002 Snapshots are the only dataset that can be renamed recursively.
3006 .Op Fl r Ns | Ns Fl d Ar depth
3008 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
3009 .Oo Fl s Ar property Oc Ns ...
3010 .Oo Fl S Ar property Oc Ns ...
3011 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3012 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
3014 Lists the property information for the given datasets in tabular form.
3015 If specified, you can list property information by the absolute pathname or the
3017 By default, all file systems and volumes are displayed.
3018 Snapshots are displayed if the
3025 The following fields are displayed:
3026 .Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns .
3027 .Bl -tag -width "-H"
3029 Used for scripting mode.
3030 Do not print headers and separate fields by a single tab instead of arbitrary
3032 .It Fl S Ar property
3035 option, but sorts by property in descending order.
3037 Recursively display any children of the dataset, limiting the recursion to
3043 will display only the dataset and its direct children.
3044 .It Fl o Ar property
3045 A comma-separated list of properties to display.
3046 The property must be:
3049 One of the properties described in the
3050 .Sx Native Properties
3057 to display the dataset name
3061 to display space usage properties on file systems and volumes.
3062 This is a shortcut for specifying
3063 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
3064 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
3065 .Sy filesystem Ns \&, Ns Sy volume
3069 Display numbers in parsable
3073 Recursively display any children of the dataset on the command line.
3074 .It Fl s Ar property
3075 A property for sorting the output by column in ascending order based on the
3076 value of the property.
3077 The property must be one of the properties described in the
3079 section or the value
3081 to sort by the dataset name.
3082 Multiple properties can be specified at one time using multiple
3087 options are evaluated from left to right in decreasing order of importance.
3088 The following is a list of sorting criteria:
3091 Numeric types sort in numeric order.
3093 String types sort in alphabetical order.
3095 Types inappropriate for a row sort that row to the literal bottom, regardless of
3096 the specified ordering.
3099 If no sorting options are specified the existing behavior of
3103 A comma-separated list of types to display, where
3112 For example, specifying
3114 displays only snapshots.
3119 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
3120 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3122 Sets the property or list of properties to the given value(s) for each dataset.
3123 Only some properties can be edited.
3126 section for more information on what properties can be set and acceptable
3128 Numeric values can be specified as exact values, or in a human-readable form
3130 .Sy B , K , M , G , T , P , E , Z
3131 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
3132 or zettabytes, respectively
3134 User properties can be set on snapshots.
3135 For more information, see the
3141 .Op Fl r Ns | Ns Fl d Ar depth
3143 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3144 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
3145 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3146 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
3147 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ...
3149 Displays properties for the given datasets.
3150 If no datasets are specified, then the command displays properties for all
3151 datasets on the system.
3152 For each property, the following columns are displayed:
3155 property Property name
3156 value Property value
3157 source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP,
3158 \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP).
3161 All columns are displayed by default, though this can be controlled by using the
3164 This command takes a comma-separated list of properties as described in the
3165 .Sx Native Properties
3172 can be used to display all properties that apply to the given dataset's type
3173 .Pq filesystem, volume, snapshot, or bookmark .
3174 .Bl -tag -width "-H"
3176 Display output in a form more easily parsed by scripts.
3177 Any headers are omitted, and fields are explicitly separated by a single tab
3178 instead of an arbitrary amount of space.
3180 Recursively display any children of the dataset, limiting the recursion to
3184 will display only the dataset and its direct children.
3186 A comma-separated list of columns to display.
3187 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
3188 is the default value.
3190 Display numbers in parsable
3194 Recursively display properties for any children.
3196 A comma-separated list of sources to display.
3197 Those properties coming from a source other than those in this list are ignored.
3198 Each source must be one of the following:
3206 The default value is all sources.
3208 A comma-separated list of types to display, where
3222 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
3224 Clears the specified property, causing it to be inherited from an ancestor,
3225 restored to default if no ancestor has the property set, or with the
3227 option reverted to the received value if one exists.
3230 section for a listing of default values, and details on which properties can be
3232 .Bl -tag -width "-r"
3234 Recursively inherit the given property for all children.
3236 Revert the property to the received value if one exists; otherwise operate as
3239 option was not specified.
3245 Displays a list of file systems that are not the most recent version.
3251 Displays a list of currently supported file system versions.
3257 .Fl a | Ar filesystem
3259 Upgrades file systems to a new on-disk version.
3260 Once this is done, the file systems will no longer be accessible on systems
3261 running older versions of the software.
3263 streams generated from new snapshots of these file systems cannot be accessed on
3264 systems running older versions of the software.
3266 In general, the file system version is independent of the pool version.
3269 for information on the
3270 .Nm zpool Cm upgrade
3273 In some cases, the file system version and the pool version are interrelated and
3274 the pool version must be upgraded before the file system version can be
3276 .Bl -tag -width "-V"
3278 Upgrade to the specified
3282 flag is not specified, this command upgrades to the most recent version.
3284 option can only be used to increase the version number, and only up to the most
3285 recent version supported by this software.
3287 Upgrade all file systems on all imported pools.
3289 Upgrade the specified file system.
3291 Upgrade the specified file system and all descendent file systems.
3297 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3298 .Oo Fl s Ar field Oc Ns ...
3299 .Oo Fl S Ar field Oc Ns ...
3300 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3301 .Ar filesystem Ns | Ns Ar snapshot
3303 Displays space consumed by, and quotas on, each user in the specified filesystem
3305 This corresponds to the
3306 .Sy userused@ Ns Em user ,
3307 .Sy userobjused@ Ns Em user ,
3308 .Sy userquota@ Ns Em user,
3310 .Sy userobjquota@ Ns Em user
3312 .Bl -tag -width "-H"
3314 Do not print headers, use tab-delimited output.
3316 Sort by this field in reverse order.
3320 Translate SID to POSIX ID.
3321 The POSIX ID may be ephemeral if no mapping exists.
3322 Normal POSIX interfaces
3327 perform this translation, so the
3329 option allows the output from
3330 .Nm zfs Cm userspace
3331 to be compared directly with those utilities.
3334 may lead to confusion if some files were created by an SMB user before a
3335 SMB-to-POSIX name mapping was established.
3336 In such a case, some files will be owned by the SMB entity and some by the POSIX
3340 option will report that the POSIX entity has the total usage and quota for both.
3342 Print numeric ID instead of user/group name.
3343 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3344 Display only the specified fields from the following set:
3349 The default is to display all fields.
3355 Sort output by this field.
3360 flags may be specified multiple times to sort first by one field, then by
3363 .Fl s Sy type Fl s Sy name .
3364 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3365 Print only the specified types from the following set:
3372 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3373 The default can be changed to include group types.
3379 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3380 .Oo Fl s Ar field Oc Ns ...
3381 .Oo Fl S Ar field Oc Ns ...
3382 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3383 .Ar filesystem Ns | Ns Ar snapshot
3385 Displays space consumed by, and quotas on, each group in the specified
3386 filesystem or snapshot.
3387 This subcommand is identical to
3388 .Nm zfs Cm userspace ,
3389 except that the default types to display are
3390 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3395 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3396 .Oo Fl s Ar field Oc Ns ...
3397 .Oo Fl S Ar field Oc Ns ...
3398 .Ar filesystem Ns | Ns Ar snapshot
3400 Displays space consumed by, and quotas on, each project in the specified
3401 filesystem or snapshot. This subcommand is identical to
3402 .Nm zfs Cm userspace ,
3403 except that the project identifier is numeral, not name. So need neither
3406 for SID to POSIX ID nor
3414 .Oo Fl d Ns | Ns Fl r Ns Oc
3415 .Ar file Ns | Ns Ar directory Ns ...
3417 List project identifier (ID) and inherit flag of file(s) or directories.
3418 .Bl -tag -width "-d"
3420 Show the directory project ID and inherit flag, not its children. It will
3421 overwrite the former specified
3425 Show on subdirectories recursively. It will overwrite the former specified
3434 .Ar file Ns | Ns Ar directory Ns ...
3436 Clear project inherit flag and/or ID on the file(s) or directories.
3437 .Bl -tag -width "-k"
3439 Keep the project ID unchanged. If not specified, the project ID will be reset
3442 Clear on subdirectories recursively.
3449 .Oo Fl d Ns | Ns Fl r Ns Oc
3451 .Ar file Ns | Ns Ar directory Ns ...
3453 Check project ID and inherit flag on the file(s) or directories, report the
3454 entries without project inherit flag or with different project IDs from the
3457 option) value or the target directory's project ID.
3458 .Bl -tag -width "-0"
3460 Print file name with a trailing NUL instead of newline (by default), like
3463 Check the directory project ID and inherit flag, not its children. It will
3464 overwrite the former specified
3468 Specify the referenced ID for comparing with the target file(s) or directories'
3469 project IDs. If not specified, the target (top) directory's project ID will be
3470 used as the referenced one.
3472 Check on subdirectories recursively. It will overwrite the former specified
3481 .Ar file Ns | Ns Ar directory Ns ...
3483 .Bl -tag -width "-p"
3484 Set project ID and/or inherit flag on the file(s) or directories.
3486 Set the file(s)' or directories' project ID with the given value.
3488 Set on subdirectories recursively.
3490 Set project inherit flag on the given file(s) or directories. It is usually used
3491 for setup tree quota on the directory target with
3493 option specified together. When setup tree quota, by default the directory's
3494 project ID will be set to all its descendants unless you specify the project
3503 Displays all ZFS file systems currently mounted.
3509 .Fl a | Ar filesystem
3511 Mount ZFS filesystem on a path described by its
3513 property, if the path exists and is empty. If
3517 the filesystem should be instead mounted using
3519 .Bl -tag -width "-O"
3521 Perform an overlay mount. Allows mounting in non-empty
3525 for more information.
3527 Mount all available ZFS file systems.
3528 Invoked automatically as part of the boot process if configured.
3530 Mount the specified filesystem.
3532 An optional, comma-separated list of mount options to use temporarily for the
3533 duration of the mount.
3535 .Sx Temporary Mount Point Properties
3536 section for details.
3538 Load keys for encrypted filesystems as they are being mounted. This is
3539 equivalent to executing
3541 on each encryption root before mounting it. Note that if a filesystem has a
3545 this will cause the terminal to interactively block after asking for the key.
3547 Report mount progress.
3549 Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets).
3555 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3557 Unmounts currently mounted ZFS file systems.
3558 .Bl -tag -width "-a"
3560 Unmount all available ZFS file systems.
3561 Invoked automatically as part of the shutdown process.
3563 Forcefully unmount the file system, even if it is currently in use.
3565 Unload keys for any encryption roots unmounted by this command.
3567 .It Ar filesystem Ns | Ns Ar mountpoint
3568 Unmount the specified filesystem.
3569 The command can also be given a path to a ZFS file system mount point on the
3574 .Fl a | Ar filesystem
3576 Shares available ZFS file systems.
3577 .Bl -tag -width "-a"
3579 Share all available ZFS file systems.
3580 Invoked automatically as part of the boot process.
3582 Share the specified filesystem according to the
3587 File systems are shared when the
3596 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3598 Unshares currently shared ZFS file systems.
3599 .Bl -tag -width "-a"
3601 Unshare all available ZFS file systems.
3602 Invoked automatically as part of the shutdown process.
3603 .It Ar filesystem Ns | Ns Ar mountpoint
3604 Unshare the specified filesystem.
3605 The command can also be given a path to a ZFS file system shared on the system.
3610 .Ar snapshot bookmark
3612 Creates a bookmark of the given snapshot.
3613 Bookmarks mark the point in time when the snapshot was created, and can be used
3614 as the incremental source for a
3618 This feature must be enabled to be used.
3620 .Xr zpool-features 5
3621 for details on ZFS feature flags and the
3628 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3631 Creates a stream representation of the second
3633 which is written to standard output.
3634 The output can be redirected to a file or to a different system
3635 .Po for example, using
3638 By default, a full stream is generated.
3639 .Bl -tag -width "-D"
3641 Generate a deduplicated stream.
3642 Blocks which would have been sent multiple times in the send stream will only be
3644 The receiving system must also support this feature to receive a deduplicated
3646 This flag can be used regardless of the dataset's
3648 property, but performance will be much better if the filesystem uses a
3649 dedup-capable checksum
3653 .It Fl I Ar snapshot
3654 Generate a stream package that sends all intermediary snapshots from the first
3655 snapshot to the second snapshot.
3659 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3660 The incremental source may be specified as with the
3663 .It Fl L, -large-block
3664 Generate a stream which may contain blocks larger than 128KB.
3665 This flag has no effect if the
3667 pool feature is disabled, or if the
3669 property of this filesystem has never been set above 128KB.
3670 The receiving system must have the
3672 pool feature enabled as well.
3674 .Xr zpool-features 5
3675 for details on ZFS feature flags and the
3679 Print machine-parsable verbose information about the stream package generated.
3680 .It Fl R, -replicate
3681 Generate a replication stream package, which will replicate the specified
3682 file system, and all descendent file systems, up to the named snapshot.
3683 When received, all properties, snapshots, descendent file systems, and clones
3690 flags are used in conjunction with the
3692 flag, an incremental replication stream is generated.
3693 The current values of properties, and current snapshot and file system names are
3694 set when the stream is received.
3697 flag is specified when this stream is received, snapshots and file systems that
3698 do not exist on the sending side are destroyed. If the
3700 flag is used to send encrypted datasets, then
3702 must also be specified.
3704 Generate a more compact stream by using
3706 records for blocks which are stored more compactly on disk by the
3709 This flag has no effect if the
3711 feature is disabled.
3712 The receiving system must have the
3717 feature is active on the sending system, then the receiving system must have
3718 that feature enabled as well. Datasets that are sent with this flag may not be
3719 received as an encrypted dataset, since encrypted datasets cannot use the
3723 .Xr zpool-features 5
3724 for details on ZFS feature flags and the
3728 Sends only received property values whether or not they are overridden by local
3729 settings, but only if the dataset has ever been received. Use this option when
3732 to restore received properties backed up on the sent dataset and to avoid
3733 sending local settings that may have nothing to do with the source dataset,
3734 but only with how the data is backed up.
3735 .It Fl c, -compressed
3736 Generate a more compact stream by using compressed WRITE records for blocks
3737 which are compressed on disk and in memory
3740 property for details
3744 feature is active on the sending system, then the receiving system must have
3745 that feature enabled as well.
3748 feature is enabled on the sending system but the
3750 option is not supplied in conjunction with
3752 then the data will be decompressed before sending so it can be split into
3753 smaller block sizes.
3755 For encrypted datasets, send data exactly as it exists on disk. This allows
3756 backups to be taken even if encryption keys are not currently loaded. The
3757 backup may then be received on an untrusted machine since that machine will
3758 not have the encryption keys to read the protected data or alter it without
3759 being detected. Upon being received, the dataset will have the same encryption
3760 keys as it did on the send side, although the
3762 property will be defaulted to
3764 if not otherwise provided. For unencrypted datasets, this flag will be
3767 Note that if you do not use this flag for sending encrypted datasets, data will
3768 be sent unencrypted and may be re-encrypted with a different encryption key on
3769 the receiving system, which will disable the ability to do a raw send to that
3770 system for incrementals.
3772 Generate a stream package that includes any snapshot holds (created with the
3774 command), and indicating to
3776 that the holds be applied to the dataset on the receiving system.
3777 .It Fl i Ar snapshot
3778 Generate an incremental stream from the first
3780 .Pq the incremental source
3783 .Pq the incremental target .
3784 The incremental source can be specified as the last component of the snapshot
3788 character and following
3790 and it is assumed to be from the same file system as the incremental target.
3792 If the destination is a clone, the source may be the origin snapshot, which must
3795 .Em pool/fs@origin ,
3803 Do not generate any actual send data.
3804 This is useful in conjunction with the
3808 flags to determine what data will be sent.
3809 In this case, the verbose output will be written to standard output
3810 .Po contrast with a non-dry-run, where the stream is written to standard output
3811 and the verbose output goes to standard error
3814 Include the dataset's properties in the stream.
3815 This flag is implicit when
3818 The receiving system must also support this feature. Sends of encrypted datasets
3821 when using this flag.
3823 Print verbose information about the stream package generated.
3824 This information includes a per-second report of how much data has been sent.
3826 The format of the stream is committed.
3827 You will be able to receive your streams on future versions of ZFS.
3833 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3834 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3836 Generate a send stream, which may be of a filesystem, and may be incremental
3838 If the destination is a filesystem or volume, the pool must be read-only, or the
3839 filesystem must not be mounted.
3840 When the stream generated from a filesystem or volume is received, the default
3841 snapshot name will be
3843 .Bl -tag -width "-L"
3844 .It Fl L, -large-block
3845 Generate a stream which may contain blocks larger than 128KB.
3846 This flag has no effect if the
3848 pool feature is disabled, or if the
3850 property of this filesystem has never been set above 128KB.
3851 The receiving system must have the
3853 pool feature enabled as well.
3855 .Xr zpool-features 5
3856 for details on ZFS feature flags and the
3860 Print machine-parsable verbose information about the stream package generated.
3861 .It Fl c, -compressed
3862 Generate a more compact stream by using compressed WRITE records for blocks
3863 which are compressed on disk and in memory
3866 property for details
3870 feature is active on the sending system, then the receiving system must have
3871 that feature enabled as well.
3874 feature is enabled on the sending system but the
3876 option is not supplied in conjunction with
3878 then the data will be decompressed before sending so it can be split into
3879 smaller block sizes.
3881 For encrypted datasets, send data exactly as it exists on disk. This allows
3882 backups to be taken even if encryption keys are not currently loaded. The
3883 backup may then be received on an untrusted machine since that machine will
3884 not have the encryption keys to read the protected data or alter it without
3885 being detected. Upon being received, the dataset will have the same encryption
3886 keys as it did on the send side, although the
3888 property will be defaulted to
3890 if not otherwise provided. For unencrypted datasets, this flag will be
3893 Note that if you do not use this flag for sending encrypted datasets, data will
3894 be sent unencrypted and may be re-encrypted with a different encryption key on
3895 the receiving system, which will disable the ability to do a raw send to that
3896 system for incrementals.
3898 Generate a more compact stream by using
3900 records for blocks which are stored more compactly on disk by the
3903 This flag has no effect if the
3905 feature is disabled.
3906 The receiving system must have the
3911 feature is active on the sending system, then the receiving system must have
3912 that feature enabled as well. Datasets that are sent with this flag may not be
3913 received as an encrypted dataset, since encrypted datasets cannot use the
3917 .Xr zpool-features 5
3918 for details on ZFS feature flags and the
3921 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3922 Generate an incremental send stream.
3923 The incremental source must be an earlier snapshot in the destination's history.
3924 It will commonly be an earlier snapshot in the destination's file system, in
3925 which case it can be specified as the last component of the name
3930 character and following
3933 If the incremental target is a clone, the incremental source can be the origin
3934 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3940 Do not generate any actual send data.
3941 This is useful in conjunction with the
3945 flags to determine what data will be sent.
3946 In this case, the verbose output will be written to standard output
3947 .Po contrast with a non-dry-run, where the stream is written to standard output
3948 and the verbose output goes to standard error
3951 Print verbose information about the stream package generated.
3952 This information includes a per-second report of how much data has been sent.
3957 .Fl -redact Ar redaction_bookmark
3960 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3963 Generate a redacted send stream.
3964 This send stream contains all blocks from the snapshot being sent that aren't
3965 included in the redaction list contained in the bookmark specified by the
3970 The resulting send stream is said to be redacted with respect to the snapshots
3971 the bookmark specified by the
3972 .Fl -redact No flag was created with.
3973 The bookmark must have been created by running
3975 on the snapshot being sent.
3977 This feature can be used to allow clones of a filesystem to be made available on
3978 a remote system, in the case where their parent need not (or needs to not) be
3980 For example, if a filesystem contains sensitive data, and it has clones where
3981 that sensitive data has been secured or replaced with dummy data, redacted sends
3982 can be used to replicate the secured data without replicating the original
3983 sensitive data, while still sharing all possible blocks.
3984 A snapshot that has been redacted with respect to a set of snapshots will
3985 contain all blocks referenced by at least one snapshot in the set, but will
3986 contain none of the blocks referenced by none of the snapshots in the set.
3987 In other words, if all snapshots in the set have modified a given block in the
3988 parent, that block will not be sent; but if one or more snapshots have not
3989 modified a block in the parent, they will still reference the parent's block, so
3990 that block will be sent.
3991 Note that only user data will be redacted.
3993 When the redacted send stream is received, we will generate a redacted
3995 Due to the nature of redaction, a redacted dataset can only be used in the
3998 1. To receive, as a clone, an incremental send from the original snapshot to one
3999 of the snapshots it was redacted with respect to.
4000 In this case, the stream will produce a valid dataset when received because all
4001 blocks that were redacted in the parent are guaranteed to be present in the
4002 child's send stream.
4003 This use case will produce a normal snapshot, which can be used just like other
4006 2. To receive an incremental send from the original snapshot to something
4007 redacted with respect to a subset of the set of snapshots the initial snapshot
4008 was redacted with respect to.
4009 In this case, each block that was redacted in the original is still redacted
4010 (redacting with respect to additional snapshots causes less data to be redacted
4011 (because the snapshots define what is permitted, and everything else is
4013 This use case will produce a new redacted snapshot.
4015 3. To receive an incremental send from a redaction bookmark of the original
4016 snapshot that was created when redacting with respect to a subset of the set of
4017 snapshots the initial snapshot was created with respect to
4019 A send stream from such a redaction bookmark will contain all of the blocks
4020 necessary to fill in any redacted data, should it be needed, because the sending
4021 system is aware of what blocks were originally redacted.
4022 This will either produce a normal snapshot or a redacted one, depending on
4023 whether the new send stream is redacted.
4025 4. To receive an incremental send from a redacted version of the initial
4026 snapshot that is redacted with respect to a subject of the set of snapshots the
4027 initial snapshot was created with respect to.
4028 A send stream from a compatible redacted dataset will contain all of the blocks
4029 necessary to fill in any redacted data.
4030 This will either produce a normal snapshot or a redacted one, depending on
4031 whether the new send stream is redacted.
4033 5. To receive a full send as a clone of the redacted snapshot.
4034 Since the stream is a full send, it definitionally contains all the data needed
4035 to create a new dataset.
4036 This use case will either produce a normal snapshot or a redacted one, depending
4037 on whether the full send stream was redacted.
4039 These restrictions are detected and enforced by \fBzfs receive\fR; a
4040 redacted send stream will contain the list of snapshots that the stream is
4041 redacted with respect to.
4042 These are stored with the redacted snapshot, and are used to detect and
4043 correctly handle the cases above. Note that for technical reasons, raw sends
4044 and redacted sends cannot be combined at this time.
4050 .Ar receive_resume_token
4052 Creates a send stream which resumes an interrupted receive.
4054 .Ar receive_resume_token
4055 is the value of this property on the filesystem or volume that was being
4057 See the documentation for
4064 .Op Fl o Sy origin Ns = Ns Ar snapshot
4065 .Op Fl o Ar property Ns = Ns Ar value
4066 .Op Fl x Ar property
4067 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
4073 .Op Fl d Ns | Ns Fl e
4074 .Op Fl o Sy origin Ns = Ns Ar snapshot
4075 .Op Fl o Ar property Ns = Ns Ar value
4076 .Op Fl x Ar property
4079 Creates a snapshot whose contents are as specified in the stream provided on
4081 If a full stream is received, then a new file system is created as well.
4082 Streams are created using the
4084 subcommand, which by default creates a full stream.
4086 can be used as an alias for
4089 If an incremental stream is received, then the destination file system must
4090 already exist, and its most recent snapshot must match the incremental stream's
4094 the destination device link is destroyed and recreated, which means the
4096 cannot be accessed during the
4100 When a snapshot replication package stream that is generated by using the
4101 .Nm zfs Cm send Fl R
4102 command is received, any snapshots that do not exist on the sending location are
4103 destroyed by using the
4104 .Nm zfs Cm destroy Fl d
4108 .Fl o Em property Ns = Ns Ar value
4111 is specified, it applies to the effective value of the property throughout
4112 the entire subtree of replicated datasets. Effective property values will be
4117 ) on the topmost in the replicated subtree. In descendant datasets, if the
4118 property is set by the send stream, it will be overridden by forcing the
4119 property to be inherited from the top‐most file system. Received properties
4120 are retained in spite of being overridden and may be restored with
4121 .Nm zfs Cm inherit Fl S .
4123 .Fl o Sy origin Ns = Ns Em snapshot
4124 is a special case because, even if
4126 is a read-only property and cannot be set, it's allowed to receive the send
4127 stream as a clone of the given snapshot.
4129 Raw encrypted send streams (created with
4130 .Nm zfs Cm send Fl w
4131 ) may only be received as is, and cannot be re-encrypted, decrypted, or
4132 recompressed by the receive process. Unencrypted streams can be received as
4133 encrypted datasets, either through inheritance or by specifying encryption
4136 options. Note that the
4138 property cannot be overridden to
4140 during a receive. This is because the receive process itself is already using
4141 stdin for the send stream. Instead, the property can be overridden after the
4144 The added security provided by raw sends adds some restrictions to the send
4145 and receive process. ZFS will not allow a mix of raw receives and non-raw
4146 receives. Specifically, any raw incremental receives that are attempted after
4147 a non-raw receive will fail. Non-raw receives do not have this restriction and,
4148 therefore, are always possible. Because of this, it is best practice to always
4149 use either raw sends for their security benefits or non-raw sends for their
4150 flexibility when working with encrypted datasets, but not a combination.
4152 The reason for this restriction stems from the inherent restrictions of the
4153 AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption,
4154 each block of data is encrypted against a randomly generated number known as
4155 the "initialization vector" (IV), which is stored in the filesystem metadata.
4156 This number is required by the encryption algorithms whenever the data is to
4157 be decrypted. Together, all of the IVs provided for all of the blocks in a
4158 given snapshot are collectively called an "IV set". When ZFS performs a raw
4159 send, the IV set is transferred from the source to the destination in the send
4160 stream. When ZFS performs a non-raw send, the data is decrypted by the source
4161 system and re-encrypted by the destination system, creating a snapshot with
4162 effectively the same data, but a different IV set. In order for decryption to
4163 work after a raw send, ZFS must ensure that the IV set used on both the source
4164 and destination side match. When an incremental raw receive is performed on
4165 top of an existing snapshot, ZFS will check to confirm that the "from"
4166 snapshot on both the source and destination were using the same IV set,
4167 ensuring the new IV set is consistent.
4169 The name of the snapshot
4170 .Pq and file system, if a full stream is received
4171 that this subcommand creates depends on the argument type and the use of the
4177 If the argument is a snapshot name, the specified
4180 If the argument is a file system or volume name, a snapshot with the same name
4181 as the sent snapshot is created within the specified
4189 options are specified, the provided target snapshot name is used exactly as
4196 options cause the file system name of the target snapshot to be determined by
4197 appending a portion of the sent snapshot's name to the specified target
4201 option is specified, all but the first element of the sent snapshot's file
4203 .Pq usually the pool name
4204 is used and any required intermediate file systems within the specified one are
4208 option is specified, then only the last element of the sent snapshot's file
4210 .Pq i.e. the name of the source file system itself
4211 is used as the target file system name.
4212 .Bl -tag -width "-F"
4214 Force a rollback of the file system to the most recent snapshot before
4215 performing the receive operation.
4216 If receiving an incremental replication stream
4217 .Po for example, one generated by
4218 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
4220 destroy snapshots and file systems that do not exist on the sending side.
4222 Discard the first element of the sent snapshot's file system name, using the
4223 remaining elements to determine the name of the target file system for the new
4224 snapshot as described in the paragraph above.
4226 Discard all but the last element of the sent snapshot's file system name, using
4227 that element to determine the name of the target file system for the new
4228 snapshot as described in the paragraph above.
4230 Skip the receive of holds. There is no effect if holds are not sent.
4232 Do not actually receive the stream.
4233 This can be useful in conjunction with the
4235 option to verify the name the receive operation would use.
4236 .It Fl o Sy origin Ns = Ns Ar snapshot
4237 Forces the stream to be received as a clone of the given snapshot.
4238 If the stream is a full send stream, this will create the filesystem
4239 described by the stream as a clone of the specified snapshot.
4240 Which snapshot was specified will not affect the success or failure of the
4241 receive, as long as the snapshot does exist.
4242 If the stream is an incremental send stream, all the normal verification will be
4244 .It Fl o Em property Ns = Ns Ar value
4245 Sets the specified property as if the command
4246 .Nm zfs Cm set Em property Ns = Ns Ar value
4247 was invoked immediately before the receive. When receiving a stream from
4248 .Nm zfs Cm send Fl R ,
4249 causes the property to be inherited by all descendant datasets, as through
4250 .Nm zfs Cm inherit Em property
4251 was run on any descendant datasets that have this property set on the
4254 Any editable property can be set at receive time. Set-once properties bound
4255 to the received data, such as
4258 .Sy casesensitivity ,
4259 cannot be set at receive time even when the datasets are newly created by
4260 .Nm zfs Cm receive .
4261 Additionally both settable properties
4265 cannot be set at receive time.
4269 option may be specified multiple times, for different properties. An error
4270 results if the same property is specified in multiple
4278 option may also be used to override encryption properties upon initial
4279 receive. This allows unencrypted streams to be received as encrypted datasets.
4280 To cause the received dataset (or root dataset of a recursive stream) to be
4281 received as an encryption root, specify encryption properties in the same
4282 manner as is required for
4287 # zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile
4291 .Op Fl o Ar keylocation Ns = Ns Ar prompt
4292 may not be specified here, since stdin is already being utilized for the send
4293 stream. Once the receive has completed, you can use
4296 to change this setting after the fact. Similarly, you can receive a dataset as
4297 an encrypted child by specifying
4298 .Op Fl x Ar encryption
4299 to force the property to be inherited. Overriding encryption properties (except
4301 .Sy keylocation Ns )
4302 is not possible with raw send streams.
4304 If the receive is interrupted, save the partially received state, rather
4306 Interruption may be due to premature termination of the stream
4307 .Po e.g. due to network failure or failure of the remote system
4308 if the stream is being read over a network connection
4310 a checksum error in the stream, termination of the
4312 process, or unclean shutdown of the system.
4314 The receive can be resumed with a stream generated by
4315 .Nm zfs Cm send Fl t Ar token ,
4319 .Sy receive_resume_token
4320 property of the filesystem or volume which is received into.
4322 To use this flag, the storage pool must have the
4323 .Sy extensible_dataset
4326 .Xr zpool-features 5
4327 for details on ZFS feature flags.
4329 File system that is associated with the received stream is not mounted.
4331 Print verbose information about the stream and the time required to perform the
4333 .It Fl x Em property
4334 Ensures that the effective value of the specified property after the
4335 receive is unaffected by the value of that property in the send stream (if any),
4336 as if the property had been excluded from the send stream.
4338 If the specified property is not present in the send stream, this option does
4341 If a received property needs to be overridden, the effective value will be
4342 set or inherited, depending on whether the property is inheritable or not.
4344 In the case of an incremental update,
4346 leaves any existing local setting or explicit inheritance unchanged.
4350 restrictions (e.g. set-once) apply equally to
4357 .Ar filesystem Ns | Ns Ar volume
4359 Abort an interrupted
4360 .Nm zfs Cm receive Fl s ,
4361 deleting its saved partially received state.
4365 .Ar snapshot redaction_bookmark
4366 .Ar redaction_snapshot Ns ...
4368 Generate a new redaction bookmark.
4369 In addition to the typical bookmark information, a redaction bookmark contains
4370 the list of redacted blocks and the list of redaction snapshots specified.
4371 The redacted blocks are blocks in the snapshot which are not referenced by any
4372 of the redaction snapshots.
4373 These blocks are found by iterating over the metadata in each redaction snapshot
4374 to determine what has been changed since the target snapshot.
4375 Redaction is designed to support redacted zfs sends; see the entry for
4377 for more information on the purpose of this operation.
4378 If a redact operation fails partway through (due to an error or a system
4379 failure), the redaction can be resumed by rerunning the same command.
4383 .Ar filesystem Ns | Ns Ar volume
4385 Displays permissions that have been delegated on the specified filesystem or
4387 See the other forms of
4389 for more information.
4391 Delegations are supported under Linux with the exception of
4399 These permissions cannot be delegated because the Linux
4401 command restricts modifications of the global namespace to the root user.
4406 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4407 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4408 .Ar setname Oc Ns ...
4409 .Ar filesystem Ns | Ns Ar volume
4415 .Fl e Ns | Ns Sy everyone
4416 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4417 .Ar setname Oc Ns ...
4418 .Ar filesystem Ns | Ns Ar volume
4420 Delegates ZFS administration permission for the file systems to non-privileged
4422 .Bl -tag -width "-d"
4424 Allow only for the descendent file systems.
4425 .It Fl e Ns | Ns Sy everyone
4426 Specifies that the permissions be delegated to everyone.
4427 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
4428 Explicitly specify that permissions are delegated to the group.
4432 only for the specified file system.
4433 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
4434 Explicitly specify that permissions are delegated to the user.
4435 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4436 Specifies to whom the permissions are delegated.
4437 Multiple entities can be specified as a comma-separated list.
4440 options are specified, then the argument is interpreted preferentially as the
4443 then as a user name, and lastly as a group name.
4444 To specify a user or group named
4451 To specify a group with the same name as a user, use the
4455 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4456 .Ar setname Oc Ns ...
4458 The permissions to delegate.
4459 Multiple permissions may be specified as a comma-separated list.
4460 Permission names are the same as ZFS subcommand and property names.
4461 See the property list below.
4462 Property set names, which begin with
4467 form below for details.
4472 options are specified, or both are, then the permissions are allowed for the
4473 file system or volume, and all of its descendents.
4475 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4477 The following permissions are available:
4480 allow subcommand Must also have the permission that is
4482 clone subcommand Must also have the 'create' ability and
4483 'mount' ability in the origin file system
4484 create subcommand Must also have the 'mount' ability.
4485 Must also have the 'refreservation' ability to
4486 create a non-sparse volume.
4487 destroy subcommand Must also have the 'mount' ability
4488 diff subcommand Allows lookup of paths within a dataset
4489 given an object number, and the ability
4490 to create snapshots necessary to
4492 load-key subcommand Allows loading and unloading of encryption key
4493 (see 'zfs load-key' and 'zfs unload-key').
4494 change-key subcommand Allows changing an encryption key via
4496 mount subcommand Allows mount/umount of ZFS datasets
4497 promote subcommand Must also have the 'mount' and 'promote'
4498 ability in the origin file system
4499 receive subcommand Must also have the 'mount' and 'create'
4501 rename subcommand Must also have the 'mount' and 'create'
4502 ability in the new parent
4503 rollback subcommand Must also have the 'mount' ability
4505 share subcommand Allows sharing file systems over NFS
4507 snapshot subcommand Must also have the 'mount' ability
4509 groupquota other Allows accessing any groupquota@...
4511 groupused other Allows reading any groupused@... property
4512 userprop other Allows changing any user property
4513 userquota other Allows accessing any userquota@...
4515 userused other Allows reading any userused@... property
4516 projectobjquota other Allows accessing any projectobjquota@...
4518 projectquota other Allows accessing any projectquota@... property
4519 projectobjused other Allows reading any projectobjused@... property
4520 projectused other Allows reading any projectused@... property
4526 casesensitivity property
4528 compression property
4532 filesystem_limit property
4535 normalization property
4536 primarycache property
4541 refreservation property
4542 reservation property
4543 secondarycache property
4548 snapshot_limit property
4551 volblocksize property
4561 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4562 .Ar setname Oc Ns ...
4563 .Ar filesystem Ns | Ns Ar volume
4568 These permissions are granted
4570 to the creator of any newly-created descendent file system.
4574 .Fl s No @ Ns Ar setname
4575 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4576 .Ar setname Oc Ns ...
4577 .Ar filesystem Ns | Ns Ar volume
4579 Defines or adds permissions to a permission set.
4580 The set can be used by other
4582 commands for the specified file system and its descendents.
4583 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4584 Permission sets follow the same naming restrictions as ZFS file systems, but the
4585 name must begin with
4587 and can be no more than 64 characters long.
4592 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4593 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4594 .Ar setname Oc Ns ... Oc
4595 .Ar filesystem Ns | Ns Ar volume
4601 .Fl e Ns | Ns Sy everyone
4602 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4603 .Ar setname Oc Ns ... Oc
4604 .Ar filesystem Ns | Ns Ar volume
4611 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4612 .Ar setname Oc Ns ... Oc
4613 .Ar filesystem Ns | Ns Ar volume
4615 Removes permissions that were granted with the
4618 No permissions are explicitly denied, so other permissions granted are still in
4620 For example, if the permission is granted by an ancestor.
4621 If no permissions are specified, then all permissions for the specified
4633 only removes the permissions that were granted to everyone, not all permissions
4634 for every user and group.
4637 command for a description of the
4640 .Bl -tag -width "-r"
4642 Recursively remove the permissions from this file system and all descendents.
4648 .Fl s No @ Ns Ar setname
4649 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4650 .Ar setname Oc Ns ... Oc
4651 .Ar filesystem Ns | Ns Ar volume
4653 Removes permissions from a permission set.
4654 If no permissions are specified, then all permissions are removed, thus removing
4660 .Ar tag Ar snapshot Ns ...
4662 Adds a single reference, named with the
4664 argument, to the specified snapshot or snapshots.
4665 Each snapshot has its own tag namespace, and tags must be unique within that
4668 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4672 .Bl -tag -width "-r"
4674 Specifies that a hold with the given tag is applied recursively to the snapshots
4675 of all descendent file systems.
4683 Lists all existing user references for the given snapshot or snapshots.
4684 .Bl -tag -width "-r"
4686 Lists the holds that are set on the named descendent snapshots, in addition to
4687 listing the holds on the named snapshot.
4689 Do not print headers, use tab-delimited output.
4695 .Ar tag Ar snapshot Ns ...
4697 Removes a single reference, named with the
4699 argument, from the specified snapshot or snapshots.
4700 The tag must already exist for each snapshot.
4701 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4705 .Bl -tag -width "-r"
4707 Recursively releases a hold with the given tag on the snapshots of all
4708 descendent file systems.
4714 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4716 Display the difference between a snapshot of a given filesystem and another
4717 snapshot of that filesystem from a later time or the current contents of the
4719 The first column is a character indicating the type of change, the other columns
4720 indicate pathname, new pathname
4721 .Pq in case of rename ,
4722 change in link count, and optionally file type and/or change time.
4723 The types of change are:
4725 - The path has been removed
4726 + The path has been created
4727 M The path has been modified
4728 R The path has been renamed
4730 .Bl -tag -width "-F"
4732 Display an indication of the type of file, in a manner similar to the
4748 Give more parsable tab-separated output, without header lines and without
4751 Display the path's inode change time as the first column of output.
4757 .Op Fl t Ar instruction-limit
4758 .Op Fl m Ar memory-limit
4765 as a ZFS channel program on
4768 program interface allows ZFS administrative operations to be run
4769 programmatically via a Lua script.
4770 The entire script is executed atomically, with no other administrative
4771 operations taking effect concurrently.
4772 A library of ZFS calls is made available to channel program scripts.
4773 Channel programs may only be run with root privileges.
4775 For full documentation of the ZFS channel program interface, see the manual
4780 Display channel program output in JSON format. When this flag is specified and
4781 standard output is empty - channel program encountered an error. The details of
4782 such an error will be printed to standard error in plain text.
4784 Executes a read-only channel program, which runs faster.
4785 The program cannot change on-disk state by calling functions from
4786 the zfs.sync submodule.
4787 The program can be used to gather information such as properties and
4788 determining if changes would succeed (zfs.check.*).
4789 Without this flag, all pending changes must be synced to disk before
4790 a channel program can complete.
4791 .It Fl t Ar instruction-limit
4792 Limit the number of Lua instructions to execute.
4793 If a channel program executes more than the specified number of instructions,
4794 it will be stopped and an error will be returned.
4795 The default limit is 10 million instructions, and it can be set to a maximum of
4796 100 million instructions.
4797 .It Fl m Ar memory-limit
4798 Memory limit, in bytes.
4799 If a channel program attempts to allocate more memory than the given limit,
4800 it will be stopped and an error returned.
4801 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4803 All remaining argument strings are passed directly to the channel program as
4807 for more information.
4813 .Op Fl L Ar keylocation
4814 .Fl a | Ar filesystem
4818 allowing it and all children that inherit the
4820 property to be accessed. The key will be expected in the format specified by the
4822 and location specified by the
4824 property. Note that if the
4828 the terminal will interactively wait for the key to be entered. Loading a key
4829 will not automatically mount the dataset. If that functionality is desired,
4830 .Nm zfs Cm mount Sy -l
4831 will ask for the key and mount the dataset. Once the key is loaded the
4833 property will become
4835 .Bl -tag -width "-r"
4837 Recursively loads the keys for the specified filesystem and all descendent
4840 Loads the keys for all encryption roots in all imported pools.
4844 load-key. This will cause zfs to simply check that the
4845 provided key is correct. This command may be run even if the key is already
4847 .It Fl L Ar keylocation
4852 property. This will not change the value of the property on the dataset. Note
4853 that if used with either
4858 may only be given as
4865 .Fl a | Ar filesystem
4867 Unloads a key from ZFS, removing the ability to access the dataset and all of
4868 its children that inherit the
4870 property. This requires that the dataset is not currently open or mounted. Once
4871 the key is unloaded the
4873 property will become
4875 .Bl -tag -width "-r"
4877 Recursively unloads the keys for the specified filesystem and all descendent
4880 Unloads the keys for all encryption roots in all imported pools.
4886 .Op Fl o Ar keylocation Ns = Ns Ar value
4887 .Op Fl o Ar keyformat Ns = Ns Ar value
4888 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4898 Allows a user to change the encryption key used to access a dataset. This
4899 command requires that the existing key for the dataset is already loaded into
4900 ZFS. This command may also be used to change the
4905 properties as needed. If the dataset was not previously an encryption root it
4906 will become one. Alternatively, the
4908 flag may be provided to cause an encryption root to inherit the parent's key
4910 .Bl -tag -width "-r"
4912 Ensures the key is loaded before attempting to change the key. This is
4913 effectively equivalent to
4914 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4915 .It Fl o Ar property Ns = Ns Ar value
4916 Allows the user to set encryption key properties (
4921 ) while changing the key. This is the only way to alter
4925 after the dataset has been created.
4927 Indicates that zfs should make
4929 inherit the key of its parent. Note that this command can only be run on an
4930 encryption root that has an encrypted parent.
4936 Displays the software version of the
4938 userland utility and the zfs kernel module.
4943 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4944 options were specified.
4947 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4948 The following commands create a file system named
4950 and a file system named
4954 is set for the parent file system, and is automatically inherited by the child
4957 # zfs create pool/home
4958 # zfs set mountpoint=/export/home pool/home
4959 # zfs create pool/home/bob
4961 .It Sy Example 2 No Creating a ZFS Snapshot
4962 The following command creates a snapshot named
4964 This snapshot is mounted on demand in the
4966 directory at the root of the
4970 # zfs snapshot pool/home/bob@yesterday
4972 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4973 The following command creates snapshots named
4977 and all of its descendent file systems.
4978 Each snapshot is mounted on demand in the
4980 directory at the root of its file system.
4981 The second command destroys the newly created snapshots.
4983 # zfs snapshot -r pool/home@yesterday
4984 # zfs destroy -r pool/home@yesterday
4986 .It Sy Example 4 No Disabling and Enabling File System Compression
4987 The following command disables the
4989 property for all file systems under
4991 The next command explicitly enables
4994 .Em pool/home/anne .
4996 # zfs set compression=off pool/home
4997 # zfs set compression=on pool/home/anne
4999 .It Sy Example 5 No Listing ZFS Datasets
5000 The following command lists all active file systems and volumes in the system.
5001 Snapshots are displayed if the
5009 for more information on pool properties.
5012 NAME USED AVAIL REFER MOUNTPOINT
5013 pool 450K 457G 18K /pool
5014 pool/home 315K 457G 21K /export/home
5015 pool/home/anne 18K 457G 18K /export/home/anne
5016 pool/home/bob 276K 457G 276K /export/home/bob
5018 .It Sy Example 6 No Setting a Quota on a ZFS File System
5019 The following command sets a quota of 50 Gbytes for
5022 # zfs set quota=50G pool/home/bob
5024 .It Sy Example 7 No Listing ZFS Properties
5025 The following command lists all properties for
5028 # zfs get all pool/home/bob
5029 NAME PROPERTY VALUE SOURCE
5030 pool/home/bob type filesystem -
5031 pool/home/bob creation Tue Jul 21 15:53 2009 -
5032 pool/home/bob used 21K -
5033 pool/home/bob available 20.0G -
5034 pool/home/bob referenced 21K -
5035 pool/home/bob compressratio 1.00x -
5036 pool/home/bob mounted yes -
5037 pool/home/bob quota 20G local
5038 pool/home/bob reservation none default
5039 pool/home/bob recordsize 128K default
5040 pool/home/bob mountpoint /pool/home/bob default
5041 pool/home/bob sharenfs off default
5042 pool/home/bob checksum on default
5043 pool/home/bob compression on local
5044 pool/home/bob atime on default
5045 pool/home/bob devices on default
5046 pool/home/bob exec on default
5047 pool/home/bob setuid on default
5048 pool/home/bob readonly off default
5049 pool/home/bob zoned off default
5050 pool/home/bob snapdir hidden default
5051 pool/home/bob acltype off default
5052 pool/home/bob aclinherit restricted default
5053 pool/home/bob canmount on default
5054 pool/home/bob xattr on default
5055 pool/home/bob copies 1 default
5056 pool/home/bob version 4 -
5057 pool/home/bob utf8only off -
5058 pool/home/bob normalization none -
5059 pool/home/bob casesensitivity sensitive -
5060 pool/home/bob vscan off default
5061 pool/home/bob nbmand off default
5062 pool/home/bob sharesmb off default
5063 pool/home/bob refquota none default
5064 pool/home/bob refreservation none default
5065 pool/home/bob primarycache all default
5066 pool/home/bob secondarycache all default
5067 pool/home/bob usedbysnapshots 0 -
5068 pool/home/bob usedbydataset 21K -
5069 pool/home/bob usedbychildren 0 -
5070 pool/home/bob usedbyrefreservation 0 -
5073 The following command gets a single property value.
5075 # zfs get -H -o value compression pool/home/bob
5078 The following command lists all properties with local settings for
5081 # zfs get -r -s local -o name,property,value all pool/home/bob
5083 pool/home/bob quota 20G
5084 pool/home/bob compression on
5086 .It Sy Example 8 No Rolling Back a ZFS File System
5087 The following command reverts the contents of
5089 to the snapshot named
5091 deleting all intermediate snapshots.
5093 # zfs rollback -r pool/home/anne@yesterday
5095 .It Sy Example 9 No Creating a ZFS Clone
5096 The following command creates a writable file system whose initial contents are
5098 .Em pool/home/bob@yesterday .
5100 # zfs clone pool/home/bob@yesterday pool/clone
5102 .It Sy Example 10 No Promoting a ZFS Clone
5103 The following commands illustrate how to test out changes to a file system, and
5104 then replace the original file system with the changed one, using clones, clone
5105 promotion, and renaming:
5107 # zfs create pool/project/production
5108 populate /pool/project/production with data
5109 # zfs snapshot pool/project/production@today
5110 # zfs clone pool/project/production@today pool/project/beta
5111 make changes to /pool/project/beta and test them
5112 # zfs promote pool/project/beta
5113 # zfs rename pool/project/production pool/project/legacy
5114 # zfs rename pool/project/beta pool/project/production
5115 once the legacy version is no longer needed, it can be destroyed
5116 # zfs destroy pool/project/legacy
5118 .It Sy Example 11 No Inheriting ZFS Properties
5119 The following command causes
5125 property from their parent.
5127 # zfs inherit checksum pool/home/bob pool/home/anne
5129 .It Sy Example 12 No Remotely Replicating ZFS Data
5130 The following commands send a full stream and then an incremental stream to a
5131 remote machine, restoring them into
5132 .Em poolB/received/fs@a
5134 .Em poolB/received/fs@b ,
5137 must contain the file system
5138 .Em poolB/received ,
5139 and must not initially contain
5140 .Em poolB/received/fs .
5142 # zfs send pool/fs@a | \e
5143 ssh host zfs receive poolB/received/fs@a
5144 # zfs send -i a pool/fs@b | \e
5145 ssh host zfs receive poolB/received/fs
5147 .It Sy Example 13 No Using the zfs receive -d Option
5148 The following command sends a full stream of
5149 .Em poolA/fsA/fsB@snap
5150 to a remote machine, receiving it into
5151 .Em poolB/received/fsA/fsB@snap .
5154 portion of the received snapshot's name is determined from the name of the sent
5157 must contain the file system
5158 .Em poolB/received .
5160 .Em poolB/received/fsA
5161 does not exist, it is created as an empty file system.
5163 # zfs send poolA/fsA/fsB@snap | \e
5164 ssh host zfs receive -d poolB/received
5166 .It Sy Example 14 No Setting User Properties
5167 The following example sets the user-defined
5168 .Sy com.example:department
5169 property for a dataset.
5171 # zfs set com.example:department=12345 tank/accounting
5173 .It Sy Example 15 No Performing a Rolling Snapshot
5174 The following example shows how to maintain a history of snapshots with a
5175 consistent naming scheme.
5176 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
5177 renames the remaining snapshots, and then creates a new snapshot, as follows:
5179 # zfs destroy -r pool/users@7daysago
5180 # zfs rename -r pool/users@6daysago @7daysago
5181 # zfs rename -r pool/users@5daysago @6daysago
5182 # zfs rename -r pool/users@4daysago @5daysago
5183 # zfs rename -r pool/users@3daysago @4daysago
5184 # zfs rename -r pool/users@2daysago @3daysago
5185 # zfs rename -r pool/users@yesterday @2daysago
5186 # zfs rename -r pool/users@today @yesterday
5187 # zfs snapshot -r pool/users@today
5189 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
5190 The following commands show how to set
5192 property options to enable
5196 addresses and to enable root access for system
5202 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
5207 for host name resolution, specify the fully qualified hostname.
5208 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
5209 The following example shows how to set permissions so that user
5211 can create, destroy, mount, and take snapshots on
5217 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
5218 # zfs allow tank/cindys
5219 ---- Permissions on tank/cindys --------------------------------------
5220 Local+Descendent permissions:
5221 user cindys create,destroy,mount,snapshot
5226 mount point permission is set to 755 by default, user
5228 will be unable to mount file systems under
5230 Add an ACE similar to the following syntax to provide mount point access:
5232 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
5234 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
5235 The following example shows how to grant anyone in the group
5237 to create file systems in
5239 This syntax also allows staff members to destroy their own file systems, but not
5240 destroy anyone else's file system.
5245 # zfs allow staff create,mount tank/users
5246 # zfs allow -c destroy tank/users
5247 # zfs allow tank/users
5248 ---- Permissions on tank/users ---------------------------------------
5251 Local+Descendent permissions:
5252 group staff create,mount
5254 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
5255 The following example shows how to define and grant a permission set on the
5262 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
5263 # zfs allow staff @pset tank/users
5264 # zfs allow tank/users
5265 ---- Permissions on tank/users ---------------------------------------
5267 @pset create,destroy,mount,snapshot
5268 Local+Descendent permissions:
5271 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
5272 The following example shows to grant the ability to set quotas and reservations
5280 # zfs allow cindys quota,reservation users/home
5281 # zfs allow users/home
5282 ---- Permissions on users/home ---------------------------------------
5283 Local+Descendent permissions:
5284 user cindys quota,reservation
5285 cindys% zfs set quota=10G users/home/marks
5286 cindys% zfs get quota users/home/marks
5287 NAME PROPERTY VALUE SOURCE
5288 users/home/marks quota 10G local
5290 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
5291 The following example shows how to remove the snapshot permission from the
5300 # zfs unallow staff snapshot tank/users
5301 # zfs allow tank/users
5302 ---- Permissions on tank/users ---------------------------------------
5304 @pset create,destroy,mount,snapshot
5305 Local+Descendent permissions:
5308 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
5309 The following example shows how to see what has changed between a prior
5310 snapshot of a ZFS dataset and its current state.
5313 option is used to indicate type information for the files affected.
5315 # zfs diff -F tank/test@before tank/test
5317 M F /tank/test/linked (+1)
5318 R F /tank/test/oldname -> /tank/test/newname
5319 - F /tank/test/deleted
5320 + F /tank/test/created
5321 M F /tank/test/modified
5323 .It Sy Example 23 No Creating a bookmark
5324 The following example create a bookmark to a snapshot. This bookmark
5325 can then be used instead of snapshot in send streams.
5327 # zfs bookmark rpool@snapshot rpool#bookmark
5329 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
5330 The following example show how to share SMB filesystem through ZFS. Note that
5331 that a user and his/her password must be given.
5333 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
5334 -o user=workgroup/turbo,password=obrut,uid=1000
5338 .Em /etc/samba/smb.conf
5339 configuration required:
5341 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
5342 communicate with Samba. This is the default behavior for most Linux
5345 Samba must be able to authenticate a user. This can be done in a number of
5346 ways, depending on if using the system password file, LDAP or the Samba
5347 specific smbpasswd file. How to do this is outside the scope of this manual.
5350 man page for more information.
5353 .Sy USERSHARE section
5356 man page for all configuration options in case you need to modify any options
5357 to the share afterwards. Do note that any changes done with the
5359 command will be undone if the share is ever unshared (such as at a reboot etc).
5361 .Sh INTERFACE STABILITY
projects / zfs / blob