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, 2017 by Delphix. All rights reserved.
25 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
26 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
27 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
28 .\" Copyright (c) 2014 Integros [integros.com]
29 .\" Copyright 2016 Richard Laager. All rights reserved.
30 .\" Copyright 2017 Nexenta Systems, Inc.
37 .Nd configures ZFS file systems
44 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
50 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Fl V Ar size Ar volume
55 .Ar filesystem Ns | Ns Ar volume
59 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
60 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
63 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
67 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
68 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
76 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
77 .Ar snapshot Ar filesystem Ns | Ns Ar volume
84 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
89 .Ar filesystem Ns | Ns Ar volume
90 .Ar filesystem Ns | Ns Ar volume
94 .Ar snapshot Ar snapshot
97 .Op Fl r Ns | Ns Fl d Ar depth
99 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
100 .Oo Fl s Ar property Oc Ns ...
101 .Oo Fl S Ar property Oc Ns ...
102 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
103 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
106 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
107 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
110 .Op Fl r Ns | Ns Fl d Ar depth
112 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
113 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
114 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
115 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
116 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
120 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
130 .Fl a | Ar filesystem
134 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
135 .Oo Fl s Ar field Oc Ns ...
136 .Oo Fl S Ar field Oc Ns ...
137 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
138 .Ar filesystem Ns | Ns Ar snapshot
142 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
143 .Oo Fl s Ar field Oc Ns ...
144 .Oo Fl S Ar field Oc Ns ...
145 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
146 .Ar filesystem Ns | Ns Ar snapshot
150 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
151 .Oo Fl s Ar field Oc Ns ...
152 .Oo Fl S Ar field Oc Ns ...
153 .Ar filesystem Ns | Ns Ar snapshot
156 .Oo Fl d Ns | Ns Fl r Ns Oc
157 .Ar file Ns | Ns Ar directory Ns ...
162 .Ar file Ns | Ns Ar directory Ns ...
167 .Oo Fl d Ns | Ns Fl r Ns Oc
169 .Ar file Ns | Ns Ar directory Ns ...
174 .Ar file Ns | Ns Ar directory Ns ...
181 .Fl a | Ar filesystem
185 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
188 .Fl a | Ar filesystem
191 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
194 .Ar snapshot bookmark
198 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
203 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
204 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
208 .Fl t Ar receive_resume_token
212 .Op Fl o Sy origin Ns = Ns Ar snapshot
213 .Op Fl o Ar property Ns = Ns Ar value
215 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
219 .Op Fl d Ns | Ns Fl e
220 .Op Fl o Sy origin Ns = Ns Ar snapshot
221 .Op Fl o Ar property Ns = Ns Ar value
227 .Ar filesystem Ns | Ns Ar volume
230 .Ar filesystem Ns | Ns Ar volume
234 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
235 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
236 .Ar setname Oc Ns ...
237 .Ar filesystem Ns | Ns Ar volume
241 .Fl e Ns | Ns Sy everyone
242 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
243 .Ar setname Oc Ns ...
244 .Ar filesystem Ns | Ns Ar volume
248 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
249 .Ar setname Oc Ns ...
250 .Ar filesystem Ns | Ns Ar volume
253 .Fl s No @ Ns Ar setname
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 user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
261 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
262 .Ar setname Oc Ns ... Oc
263 .Ar filesystem Ns | Ns Ar volume
267 .Fl e Ns | Ns Sy everyone
268 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
269 .Ar setname Oc Ns ... Oc
270 .Ar filesystem Ns | Ns Ar volume
275 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
276 .Ar setname Oc Ns ... Oc
277 .Ar filesystem Ns | Ns Ar volume
281 .Fl s @ Ns Ar setname
282 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
283 .Ar setname Oc Ns ... Oc
284 .Ar filesystem Ns | Ns Ar volume
288 .Ar tag Ar snapshot Ns ...
296 .Ar tag Ar snapshot Ns ...
300 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
305 .Op Fl m Ar memory_limit
311 .Op Fl L Ar keylocation
312 .Fl a | Ar filesystem
316 .Fl a | Ar filesystem
320 .Op Fl o Ar keylocation Ns = Ns Ar value
321 .Op Fl o Ar keyformat Ns = Ns Ar value
322 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
332 command configures ZFS datasets within a ZFS storage pool, as described in
334 A dataset is identified by a unique path within the ZFS namespace.
337 pool/{filesystem,volume,snapshot}
340 where the maximum length of a dataset name is
344 A dataset can be one of the following:
345 .Bl -tag -width "file system"
347 A ZFS dataset of type
349 can be mounted within the standard system namespace and behaves like other file
351 While ZFS file systems are designed to be POSIX compliant, known issues exist
352 that prevent compliance in some cases.
353 Applications that depend on standards conformance might fail due to non-standard
354 behavior when checking file system free space.
356 A logical volume exported as a raw or block device.
357 This type of dataset should only be used under special circumstances.
358 File systems are typically used in most environments.
360 A read-only version of a file system or volume at a given point in time.
362 .Ar filesystem Ns @ Ns Ar name
364 .Ar volume Ns @ Ns Ar name .
368 but without the hold on on-disk data. It can be used as the source of a send
369 (but not for a receive). It is specified as
370 .Ar filesystem Ns # Ns Ar name
372 .Ar volume Ns # Ns Ar name .
374 .Ss ZFS File System Hierarchy
375 A ZFS storage pool is a logical collection of devices that provide space for
377 A storage pool is also the root of the ZFS file system hierarchy.
379 The root of the pool can be accessed as a file system, such as mounting and
380 unmounting, taking snapshots, and setting properties.
381 The physical storage characteristics, however, are managed by the
387 for more information on creating and administering pools.
389 A snapshot is a read-only copy of a file system or volume.
390 Snapshots can be created extremely quickly, and initially consume no additional
391 space within the pool.
392 As data within the active dataset changes, the snapshot consumes more data than
393 would otherwise be shared with the active dataset.
395 Snapshots can have arbitrary names.
396 Snapshots of volumes can be cloned or rolled back, visibility is determined
399 property of the parent volume.
401 File system snapshots can be accessed under the
403 directory in the root of the file system.
404 Snapshots are automatically mounted on demand and may be unmounted at regular
406 The visibility of the
408 directory can be controlled by the
412 A bookmark is like a snapshot, a read-only copy of a file system or volume.
413 Bookmarks can be created extremely quickly, compared to snapshots, and they
414 consume no additional space within the pool. Bookmarks can also have arbitrary
415 names, much like snapshots.
417 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
418 way. From a storage standpoint a bookmark just provides a way to reference
419 when a snapshot was created as a distinct object. Bookmarks are initially
420 tied to a snapshot, not the filesystem or volume, and they will survive if the
421 snapshot itself is destroyed. Since they are very light weight there's little
422 incentive to destroy them.
424 A clone is a writable volume or file system whose initial contents are the same
426 As with snapshots, creating a clone is nearly instantaneous, and initially
427 consumes no additional space.
429 Clones can only be created from a snapshot.
430 When a snapshot is cloned, it creates an implicit dependency between the parent
432 Even though the clone is created somewhere else in the dataset hierarchy, the
433 original snapshot cannot be destroyed as long as a clone exists.
436 property exposes this dependency, and the
438 command lists any such dependencies, if they exist.
440 The clone parent-child dependency relationship can be reversed by using the
445 file system to become a clone of the specified file system, which makes it
446 possible to destroy the file system that the clone was created from.
448 Creating a ZFS file system is a simple operation, so the number of file systems
449 per system is likely to be numerous.
450 To cope with this, ZFS automatically manages mounting and unmounting file
451 systems without the need to edit the
454 All automatically managed file systems are mounted by ZFS at boot time.
456 By default, file systems are mounted under
460 is the name of the file system in the ZFS namespace.
461 Directories are created and destroyed as needed.
463 A file system can also have a mount point set in the
466 This directory is created as needed, and ZFS automatically mounts the file
468 .Nm zfs Cm mount Fl a
475 property can be inherited, so if
481 automatically inherits a mount point of
482 .Pa /export/stuff/user .
488 prevents the file system from being mounted.
490 If needed, ZFS file systems can also be managed with traditional tools
496 If a file system's mount point is set to
498 ZFS makes no attempt to manage the file system, and the administrator is
499 responsible for mounting and unmounting the file system. Because pools must
500 be imported before a legacy mount can succeed, administrators should ensure
501 that legacy mounts are only attempted after the zpool import process
502 finishes at boot time. For example, on machines using systemd, the mount
505 .Nm x-systemd.requires=zfs-import.target
507 will ensure that the zfs-import completes before systemd attempts mounting
508 the filesystem. See systemd.mount(5) for details.
510 Deduplication is the process for removing redundant data at the block level,
511 reducing the total amount of data stored. If a file system has the
513 property enabled, duplicate data blocks are removed synchronously. The result
514 is that only unique data is stored and common components are shared among files.
516 Deduplicating data is a very resource-intensive operation. It is generally
517 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
518 you enable deduplication. Calculating the exact requirement depends heavily
519 on the type of data stored in the pool.
521 Enabling deduplication on an improperly-designed system can result in
522 performance issues (slow IO and administrative operations). It can potentially
523 lead to problems importing a pool due to memory exhaustion. Deduplication
524 can consume significant processing power (CPU) and memory as well as generate
527 Before creating a pool with deduplication enabled, ensure that you have planned
528 your hardware requirements appropriately and implemented appropriate recovery
529 practices, such as regular backups. As an alternative to deduplication
532 as a less resource-intensive alternative.
533 .Ss Native Properties
534 Properties are divided into two types, native properties and user-defined
539 Native properties either export internal statistics or control ZFS behavior.
540 In addition, native properties are either editable or read-only.
541 User properties have no effect on ZFS behavior, but you can use them to annotate
542 datasets in a way that is meaningful in your environment.
543 For more information about user properties, see the
547 Every dataset has a set of properties that export statistics about the dataset
548 as well as control various behaviors.
549 Properties are inherited from the parent unless overridden by the child.
550 Some properties apply only to certain types of datasets
551 .Pq file systems, volumes, or snapshots .
553 The values of numeric properties can be specified using human-readable suffixes
563 The following are all valid
566 .Li 1536M, 1.5g, 1.50GB .
568 The values of non-numeric properties are case sensitive and must be lowercase,
575 The following native properties consist of read-only statistics about the
577 These properties can be neither set, nor inherited.
578 Native properties apply to all dataset types unless otherwise noted.
579 .Bl -tag -width "usedbyrefreservation"
581 The amount of space available to the dataset and all its children, assuming that
582 there is no other activity in the pool.
583 Because space is shared within a pool, availability can be limited by any number
584 of factors, including physical pool size, quotas, reservations, or other
585 datasets within the pool.
587 This property can also be referred to by its shortened column name,
590 For non-snapshots, the compression ratio achieved for the
592 space of this dataset, expressed as a multiplier.
595 property includes descendant datasets, and, for clones, does not include the
596 space shared with the origin snapshot.
602 Compression can be turned on by running:
603 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
607 The transaction group (txg) in which the dataset was created. Bookmarks have
610 as the snapshot they are initially tied to. This property is suitable for
611 ordering a list of snapshots, e.g. for incremental send and receive.
613 The time this dataset was created.
615 For snapshots, this property is a comma-separated list of filesystems or volumes
616 which are clones of this snapshot.
619 property is this snapshot.
622 property is not empty, then this snapshot can not be destroyed
629 The roles of origin and clone can be swapped by promoting the clone with the
635 if the snapshot has been marked for deferred destroy by using the
636 .Nm zfs Cm destroy Fl d
638 Otherwise, the property is
640 .It Sy encryptionroot
641 For encrypted datasets, indicates where the dataset is currently inheriting its
642 encryption key from. Loading or unloading a key for the
644 will implicitly load / unload the key for any inheriting datasets (see
647 .Nm zfs Cm unload-key
649 Clones will always share an
650 encryption key with their origin. See the
653 .It Sy filesystem_count
654 The total number of filesystems and volumes that exist under this location in
656 This value is only available when a
658 has been set somewhere in the tree under which the dataset resides.
660 Indicates if an encryption key is currently loaded into ZFS. The possible
669 .Nm zfs Cm unload-key .
671 The 64 bit GUID of this dataset or bookmark which does not change over its
672 entire lifetime. When a snapshot is sent to another pool, the received
673 snapshot has the same GUID. Thus, the
675 is suitable to identify a snapshot across pools.
676 .It Sy logicalreferenced
677 The amount of space that is
679 accessible by this dataset.
683 The logical space ignores the effect of the
687 properties, giving a quantity closer to the amount of data that applications
689 However, it does include space consumed by metadata.
691 This property can also be referred to by its shortened column name,
694 The amount of space that is
696 consumed by this dataset and all its descendents.
700 The logical space ignores the effect of the
704 properties, giving a quantity closer to the amount of data that applications
706 However, it does include space consumed by metadata.
708 This property can also be referred to by its shortened column name,
711 For file systems, indicates whether the file system is currently mounted.
712 This property can be either
717 For cloned file systems or volumes, the snapshot from which the clone was
722 .It Sy receive_resume_token
723 For filesystems or volumes which have saved partially-completed state from
725 this opaque token can be provided to
727 to resume and complete the
730 The amount of data that is accessible by this dataset, which may or may not be
731 shared with other datasets in the pool.
732 When a snapshot or clone is created, it initially references the same amount of
733 space as the file system or snapshot it was created from, since its contents are
736 This property can also be referred to by its shortened column name,
738 .It Sy refcompressratio
739 The compression ratio achieved for the
741 space of this dataset, expressed as a multiplier.
745 .It Sy snapshot_count
746 The total number of snapshots that exist under this location in the dataset
748 This value is only available when a
750 has been set somewhere in the tree under which the dataset resides.
758 The amount of space consumed by this dataset and all its descendents.
759 This is the value that is checked against this dataset's quota and reservation.
760 The space used does not include this dataset's reservation, but does take into
761 account the reservations of any descendent datasets.
762 The amount of space that a dataset consumes from its parent, as well as the
763 amount of space that is freed if this dataset is recursively destroyed, is the
764 greater of its space used and its reservation.
766 The used space of a snapshot
771 is space that is referenced exclusively by this snapshot.
772 If this snapshot is destroyed, the amount of
775 Space that is shared by multiple snapshots isn't accounted for in this metric.
776 When a snapshot is destroyed, space that was previously shared with this
777 snapshot can become unique to snapshots adjacent to it, thus changing the used
778 space of those snapshots.
779 The used space of the latest snapshot can also be affected by changes in the
783 space of a snapshot is a subset of the
785 space of the snapshot.
787 The amount of space used, available, or referenced does not take into account
789 Pending changes are generally accounted for within a few seconds.
790 Committing a change to a disk using
794 does not necessarily guarantee that the space usage information is updated
799 properties decompose the
801 properties into the various reasons that space is used.
804 .Sy usedbychildren No +
805 .Sy usedbydataset No +
806 .Sy usedbyrefreservation No +
807 .Sy usedbysnapshots .
808 These properties are only available for datasets created on
812 .It Sy usedbychildren
813 The amount of space used by children of this dataset, which would be freed if
814 all the dataset's children were destroyed.
816 The amount of space used by this dataset itself, which would be freed if the
817 dataset were destroyed
818 .Po after first removing any
820 and destroying any necessary snapshots or descendents
822 .It Sy usedbyrefreservation
823 The amount of space used by a
825 set on this dataset, which would be freed if the
828 .It Sy usedbysnapshots
829 The amount of space consumed by snapshots of this dataset.
830 In particular, it is the amount of space that would be freed if all of this
831 dataset's snapshots were destroyed.
832 Note that this is not simply the sum of the snapshots'
834 properties because space can be shared by multiple snapshots.
835 .It Sy userused Ns @ Ns Em user
836 The amount of space consumed by the specified user in this dataset.
837 Space is charged to the owner of each file, as displayed by
839 The amount of space charged is displayed by
845 subcommand for more information.
847 Unprivileged users can access only their own space usage.
848 The root user, or a user who has been granted the
852 can access everyone's usage.
855 .Sy userused Ns @ Ns Em ...
856 properties are not displayed by
857 .Nm zfs Cm get Sy all .
858 The user's name must be appended after the @ symbol, using one of the following
860 .Bl -bullet -width ""
874 .Sy joe.smith@mydomain
883 Files created on Linux always have POSIX owners.
884 .It Sy userobjused Ns @ Ns Em user
887 property is similar to
889 but instead it counts the number of objects consumed by a user. This property
890 counts all objects allocated on behalf of the user, it may differ from the
891 results of system tools such as
896 is set on a file system additional objects will be created per-file to store
897 extended attributes. These additional objects are reflected in the
899 value and are counted against the user's
901 When a file system is configured to use
903 no additional internal objects are normally required.
905 This property is set to the number of user holds on this snapshot.
906 User holds are set by using the
909 .It Sy groupused Ns @ Ns Em group
910 The amount of space consumed by the specified group in this dataset.
911 Space is charged to the group of each file, as displayed by
914 .Sy userused Ns @ Ns Em user
915 property for more information.
917 Unprivileged users can only access their own groups' space usage.
918 The root user, or a user who has been granted the
922 can access all groups' usage.
923 .It Sy groupobjused Ns @ Ns Em group
924 The number of objects consumed by the specified group in this dataset.
925 Multiple objects may be charged to the group for each file when extended
926 attributes are in use. See the
927 .Sy userobjused Ns @ Ns Em user
928 property for more information.
930 Unprivileged users can only access their own groups' space usage.
931 The root user, or a user who has been granted the
935 can access all groups' usage.
936 .It Sy projectused Ns @ Ns Em project
937 The amount of space consumed by the specified project in this dataset. Project
938 is identified via the project identifier (ID) that is object-based numeral
939 attribute. An object can inherit the project ID from its parent object (if the
940 parent has the flag of inherit project ID that can be set and changed via
943 .Nm zfs project Fl s )
944 when being created. The privileged user can set and change object's project
949 anytime. Space is charged to the project of each file, as displayed by
954 .Sy userused Ns @ Ns Em user
955 property for more information.
957 The root user, or a user who has been granted the
961 can access all projects' usage.
962 .It Sy projectobjused Ns @ Ns Em project
967 but instead it counts the number of objects consumed by project. When the
970 is set on a fileset, ZFS will create additional objects per-file to store
971 extended attributes. These additional objects are reflected in the
973 value and are counted against the project's
974 .Sy projectobjquota .
975 When a filesystem is configured to use
977 no additional internal objects are required. See the
978 .Sy userobjused Ns @ Ns Em user
979 property for more information.
981 The root user, or a user who has been granted the
985 can access all projects' objects usage.
987 For volumes, specifies the block size of the volume.
990 cannot be changed once the volume has been written, so it should be set at
991 volume creation time.
994 for volumes is 8 Kbytes.
995 Any power of 2 from 512 bytes to 128 Kbytes is valid.
997 This property can also be referred to by its shortened column name,
1002 by this dataset, that was written since the previous snapshot
1003 .Pq i.e. that is not referenced by the previous snapshot .
1004 .It Sy written Ns @ Ns Em snapshot
1007 space written to this dataset since the specified snapshot.
1008 This is the space that is referenced by this dataset but was not referenced by
1009 the specified snapshot.
1013 may be specified as a short snapshot name
1014 .Po just the part after the
1017 in which case it will be interpreted as a snapshot in the same filesystem as
1021 may be a full snapshot name
1022 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1023 which for clones may be a snapshot in the origin's filesystem
1024 .Pq or the origin of the origin's filesystem, etc.
1027 The following native properties can be used to change the behavior of a ZFS
1031 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1032 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1034 Controls how ACEs are inherited when files and directories are created.
1035 .Bl -tag -width "passthrough-x"
1037 does not inherit any ACEs.
1039 only inherits inheritable ACEs that specify
1043 default, removes the
1047 permissions when the ACE is inherited.
1049 inherits all inheritable ACEs without any modifications.
1050 .It Sy passthrough-x
1058 ACEs inherit the execute permission only if the file creation mode also requests
1062 When the property value is set to
1064 files are created with a mode determined by the inheritable ACEs.
1065 If no inheritable ACEs exist that affect the mode, then the mode is set in
1066 accordance to the requested mode from the application.
1070 property does not apply to posix ACLs.
1071 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1072 Controls whether ACLs are enabled and if so what type of ACL to use.
1073 .Bl -tag -width "posixacl"
1075 default, when a file system has the
1077 property set to off then ACLs are disabled.
1082 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
1083 not functional on other platforms. Posix ACLs are stored as an extended
1084 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1088 To obtain the best performance when setting
1090 users are strongly encouraged to set the
1092 property. This will result in the posix ACL being stored more efficiently on
1093 disk. But as a consequence of this all new extended attributes will only be
1094 accessible from OpenZFS implementations which support the
1098 property for more details.
1099 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1100 Controls whether the access time for files is updated when they are read.
1101 Turning this property off avoids producing write traffic when reading files and
1102 can result in significant performance gains, though it might confuse mailers
1103 and other similar utilities. The values
1107 are equivalent to the
1111 mount options. The default value is
1116 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1117 If this property is set to
1119 the file system cannot be mounted, and is ignored by
1120 .Nm zfs Cm mount Fl a .
1121 Setting this property to
1123 is similar to setting the
1127 except that the dataset still has a normal
1129 property, which can be inherited.
1130 Setting this property to
1132 allows datasets to be used solely as a mechanism to inherit properties.
1133 One example of setting
1134 .Sy canmount Ns = Ns Sy off
1135 is to have two datasets with the same
1137 so that the children of both datasets appear in the same directory, but might
1138 have different inherited characteristics.
1142 a dataset can only be mounted and unmounted explicitly.
1143 The dataset is not mounted automatically when the dataset is created or
1144 imported, nor is it mounted by the
1145 .Nm zfs Cm mount Fl a
1146 command or unmounted by the
1147 .Nm zfs Cm unmount Fl a
1150 This property is not inherited.
1152 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1153 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1154 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1156 Controls the checksum used to verify data integrity.
1157 The default value is
1159 which automatically selects an appropriate algorithm
1162 but this may change in future releases
1166 disables integrity checking on user data.
1169 not only disables integrity but also disables maintaining parity for user data.
1170 This setting is used internally by a dump device residing on a RAID-Z pool and
1171 should not be used by any other dataset.
1172 Disabling checksums is
1174 a recommended practice.
1181 checksum algorithms require enabling the appropriate features on the pool.
1183 .Xr zpool-features 5
1184 for more information on these algorithms.
1186 Changing this property affects only newly-written data.
1188 Salted checksum algorithms
1189 .Pq Cm edonr , skein
1190 are currently not supported for any filesystem on the boot pools.
1192 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1193 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1195 Controls the compression algorithm used for this dataset.
1197 Setting compression to
1199 indicates that the current default compression algorithm should be used.
1200 The default balances compression and decompression speed, with compression ratio
1201 and is expected to work well on a wide variety of workloads.
1202 Unlike all other settings for this property,
1204 does not select a fixed compression type.
1205 As new compression algorithms are added to ZFS and enabled on a pool, the
1206 default compression algorithm may change.
1207 The current default compression algorithm is either
1216 compression algorithm is a high-performance replacement for the
1219 It features significantly faster compression and decompression, as well as a
1220 moderately higher compression ratio than
1222 but can only be used on pools with the
1227 .Xr zpool-features 5
1228 for details on ZFS feature flags and the
1234 compression algorithm is optimized for performance while providing decent data
1239 compression algorithm uses the same compression as the
1244 level by using the value
1248 is an integer from 1
1251 .Pq best compression ratio .
1256 .Po which is also the default for
1262 compression algorithm compresses runs of zeros.
1264 This property can also be referred to by its shortened column name
1266 Changing this property affects only newly-written data.
1268 .Sy context Ns = Ns Sy none Ns | Ns
1269 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1271 This flag sets the SELinux context for all files in the file system under
1272 a mount point for that file system. See
1274 for more information.
1276 .Sy fscontext Ns = Ns Sy none Ns | Ns
1277 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1279 This flag sets the SELinux context for the file system file system being
1282 for more information.
1284 .Sy defcontext Ns = Ns Sy none Ns | Ns
1285 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1287 This flag sets the SELinux default context for unlabeled files. See
1289 for more information.
1291 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1292 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1294 This flag sets the SELinux context for the root inode of the file system. See
1296 for more information.
1297 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1298 Controls the number of copies of data stored for this dataset.
1299 These copies are in addition to any redundancy provided by the pool, for
1300 example, mirroring or RAID-Z.
1301 The copies are stored on different disks, if possible.
1302 The space used by multiple copies is charged to the associated file and dataset,
1305 property and counting against quotas and reservations.
1307 Changing this property only affects newly-written data.
1308 Therefore, set this property at file system creation time by using the
1309 .Fl o Sy copies Ns = Ns Ar N
1312 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1314 create, for example a two-disk striped pool and set
1316 on some datasets thinking you have setup redundancy for them. When a disk
1317 fails you will not be able to import the pool and will have lost all of your
1319 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1320 Controls whether device nodes can be opened on this file system.
1321 The default value is
1327 are equivalent to the
1333 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1334 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1337 Configures deduplication for a dataset. The default value is
1339 The default deduplication checksum is
1341 (this may change in the future). When
1343 is enabled, the checksum defined here overrides the
1345 property. Setting the value to
1347 has the same effect as the setting
1352 ZFS will do a byte-to-byte comparsion in case of two blocks having the same
1353 signature to make sure the block contents are identical. Specifying
1355 is mandatory for the
1359 Unless necessary, deduplication should NOT be enabled on a system. See
1363 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1364 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1366 Specifies a compatibility mode or literal value for the size of dnodes in the
1367 file system. The default value is
1369 Setting this property to a value other than
1371 requires the large_dnode pool feature to be enabled.
1377 if the dataset uses the
1379 property setting and the workload makes heavy use of extended attributes. This
1380 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1381 servers, for example. Literal values are supported for cases where the optimal
1382 size is known in advance and for performance testing.
1388 if you need to receive a send stream of this dataset on a pool that doesn't
1389 enable the large_dnode feature, or if you need to import this pool on a system
1390 that doesn't support the large_dnode feature.
1392 This property can also be referred to by its shortened column name,
1395 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1396 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1397 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1399 Controls the encryption cipher suite (block cipher, key length, and mode) used
1400 for this dataset. Requires the
1402 feature to be enabled on the pool.
1405 to be set at dataset creation time.
1408 .Sy encryption Ns = Ns Sy on
1409 when creating a dataset indicates that the default encryption suite will be
1410 selected, which is currently
1412 In order to provide consistent data protection, encryption must be specified at
1413 dataset creation time and it cannot be changed afterwards.
1415 For more details and caveats about encryption see the
1418 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1419 Controls what format the user's encryption key will be provided as. This
1420 property is only set when the dataset is encrypted.
1422 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1423 encryption suite) and must be randomly generated. A raw key can be generated
1424 with the following command:
1426 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1429 Passphrases must be between 8 and 512 bytes long and will be processed through
1430 PBKDF2 before being used (see the
1432 property). Even though the
1433 encryption suite cannot be changed after dataset creation, the keyformat can be
1435 .Nm zfs Cm change-key .
1437 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1439 Controls where the user's encryption key will be loaded from by default for
1443 .Nm zfs Cm mount Cm -l . This property is
1444 only set for encrypted datasets which are encryption roots. If unspecified, the
1448 Even though the encryption suite cannot be changed after dataset creation, the
1449 keylocation can be with either
1452 .Nm zfs Cm change-key .
1455 is selected ZFS will ask for the key at the command prompt when it is required
1456 to access the encrypted data (see
1458 for details). This setting will also allow the key to be passed in via STDIN,
1459 but users should be careful not to place keys which should be kept secret on
1460 the command line. If a file URI is selected, the key will be loaded from the
1461 specified absolute file path.
1462 .It Sy pbkdf2iters Ns = Ns Ar iterations
1463 Controls the number of PBKDF2 iterations that a
1465 encryption key should be run through when processing it into an encryption key.
1466 This property is only defined when encryption is enabled and a keyformat of
1468 is selected. The goal of PBKDF2 is to significantly increase the
1469 computational difficulty needed to brute force a user's passphrase. This is
1470 accomplished by forcing the attacker to run each passphrase through a
1471 computationally expensive hashing function many times before they arrive at the
1472 resulting key. A user who actually knows the passphrase will only have to pay
1473 this cost once. As CPUs become better at processing, this number should be
1474 raised to ensure that a brute force attack is still not possible. The current
1479 This property may be changed with
1480 .Nm zfs Cm change-key .
1481 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1482 Controls whether processes can be executed from within this file system.
1483 The default value is
1489 are equivalent to the
1494 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1495 Limits the number of filesystems and volumes that can exist under this point in
1497 The limit is not enforced if the user is allowed to change the limit.
1499 .Sy filesystem_limit
1502 a descendent of a filesystem that already has a
1503 .Sy filesystem_limit
1504 does not override the ancestor's
1505 .Sy filesystem_limit ,
1506 but rather imposes an additional limit.
1507 This feature must be enabled to be used
1509 .Xr zpool-features 5
1511 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1512 Controls the mount point used for this file system.
1515 section for more information on how this property is used.
1519 property is changed for a file system, the file system and any children that
1520 inherit the mount point are unmounted.
1523 then they remain unmounted.
1524 Otherwise, they are automatically remounted in the new location if the property
1529 or if they were mounted before the property was changed.
1530 In addition, any shared file systems are unshared and shared in the new
1532 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1533 Controls whether the file system should be mounted with
1535 .Pq Non Blocking mandatory locks .
1536 This is used for SMB clients.
1537 Changes to this property only take effect when the file system is umounted and
1541 for more information on
1543 mounts. This property is not used on Linux.
1544 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1545 Allow mounting on a busy directory or a directory which already contains
1546 files or directories. This is the default mount behavior for Linux file systems.
1547 For consistency with OpenZFS on other platforms overlay mounts are
1551 to enable overlay mounts.
1552 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1553 Controls what is cached in the primary cache
1555 If this property is set to
1557 then both user data and metadata is cached.
1558 If this property is set to
1560 then neither user data nor metadata is cached.
1561 If this property is set to
1563 then only metadata is cached.
1564 The default value is
1566 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1567 Limits the amount of space a dataset and its descendents can consume.
1568 This property enforces a hard limit on the amount of space used.
1569 This includes all space consumed by descendents, including file systems and
1571 Setting a quota on a descendent of a dataset that already has a quota does not
1572 override the ancestor's quota, but rather imposes an additional limit.
1574 Quotas cannot be set on volumes, as the
1576 property acts as an implicit quota.
1577 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1578 Limits the number of snapshots that can be created on a dataset and its
1582 on a descendent of a dataset that already has a
1584 does not override the ancestor's
1585 .Sy snapshot_limit ,
1586 but rather imposes an additional limit.
1587 The limit is not enforced if the user is allowed to change the limit.
1588 For example, this means that recursive snapshots taken from the global zone are
1589 counted against each delegated dataset within a zone.
1590 This feature must be enabled to be used
1592 .Xr zpool-features 5
1594 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1595 Limits the amount of space consumed by the specified user.
1596 User space consumption is identified by the
1597 .Sy userspace@ Ns Em user
1600 Enforcement of user quotas may be delayed by several seconds.
1601 This delay means that a user might exceed their quota before the system notices
1602 that they are over quota and begins to refuse additional writes with the
1606 .Nm zfs Cm userspace
1607 subcommand for more information.
1609 Unprivileged users can only access their own groups' space usage.
1610 The root user, or a user who has been granted the
1614 can get and set everyone's quota.
1616 This property is not available on volumes, on file systems before version 4, or
1617 on pools before version 15.
1619 .Sy userquota@ Ns Em ...
1620 properties are not displayed by
1621 .Nm zfs Cm get Sy all .
1622 The user's name must be appended after the
1624 symbol, using one of the following forms:
1632 .Em POSIX numeric ID
1639 .Sy joe.smith@mydomain
1648 Files created on Linux always have POSIX owners.
1649 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1654 but it limits the number of objects a user can create. Please refer to
1656 for more information about how objects are counted.
1657 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1658 Limits the amount of space consumed by the specified group.
1659 Group space consumption is identified by the
1660 .Sy groupused@ Ns Em group
1663 Unprivileged users can access only their own groups' space usage.
1664 The root user, or a user who has been granted the
1668 can get and set all groups' quotas.
1669 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1674 but it limits number of objects a group can consume. Please refer to
1676 for more information about how objects are counted.
1677 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1678 Limits the amount of space consumed by the specified project. Project
1679 space consumption is identified by the
1680 .Sy projectused@ Ns Em project
1681 property. Please refer to
1683 for more information about how project is identified and set/changed.
1685 The root user, or a user who has been granted the
1689 can access all projects' quota.
1690 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1695 but it limits number of objects a project can consume. Please refer to
1697 for more information about how objects are counted.
1698 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1699 Controls whether this dataset can be modified.
1700 The default value is
1706 are equivalent to the
1712 This property can also be referred to by its shortened column name,
1714 .It Sy recordsize Ns = Ns Em size
1715 Specifies a suggested block size for files in the file system.
1716 This property is designed solely for use with database workloads that access
1717 files in fixed-size records.
1718 ZFS automatically tunes block sizes according to internal algorithms optimized
1719 for typical access patterns.
1721 For databases that create very large files but access them in small random
1722 chunks, these algorithms may be suboptimal.
1725 greater than or equal to the record size of the database can result in
1726 significant performance gains.
1727 Use of this property for general purpose file systems is strongly discouraged,
1728 and may adversely affect performance.
1730 The size specified must be a power of two greater than or equal to 512 and less
1731 than or equal to 128 Kbytes.
1734 feature is enabled on the pool, the size may be up to 1 Mbyte.
1736 .Xr zpool-features 5
1737 for details on ZFS feature flags.
1739 Changing the file system's
1741 affects only files created afterward; existing files are unaffected.
1743 This property can also be referred to by its shortened column name,
1745 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1746 Controls what types of metadata are stored redundantly.
1747 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1748 the amount of user data lost is limited.
1749 This extra copy is in addition to any redundancy provided at the pool level
1750 .Pq e.g. by mirroring or RAID-Z ,
1751 and is in addition to an extra copy specified by the
1754 .Pq up to a total of 3 copies .
1755 For example if the pool is mirrored,
1756 .Sy copies Ns = Ns 2 ,
1758 .Sy redundant_metadata Ns = Ns Sy most ,
1759 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1764 ZFS stores an extra copy of all metadata.
1765 If a single on-disk block is corrupt, at worst a single block of user data
1774 ZFS stores an extra copy of most types of metadata.
1775 This can improve performance of random writes, because less metadata must be
1777 In practice, at worst about 100 blocks
1782 of user data can be lost if a single on-disk block is corrupt.
1783 The exact behavior of which metadata blocks are stored redundantly may change in
1786 The default value is
1788 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1789 Limits the amount of space a dataset can consume.
1790 This property enforces a hard limit on the amount of space used.
1791 This hard limit does not include space used by descendents, including file
1792 systems and snapshots.
1793 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1794 The minimum amount of space guaranteed to a dataset, not including its
1796 When the amount of space used is below this value, the dataset is treated as if
1797 it were taking up the amount of space specified by
1798 .Sy refreservation .
1801 reservation is accounted for in the parent datasets' space used, and counts
1802 against the parent datasets' quotas and reservations.
1806 is set, a snapshot is only allowed if there is enough free pool space outside of
1807 this reservation to accommodate the current number of
1809 bytes in the dataset.
1811 This property can also be referred to by its shortened column name,
1813 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1814 Controls the manner in which the access time is updated when
1816 is set. Turning this property on causes the access time to be updated relative
1817 to the modify or change time. Access time is only updated if the previous
1818 access time was earlier than the current modify or change time or if the
1819 existing access time hasn't been updated within the past 24 hours. The default
1826 are equivalent to the
1831 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1832 The minimum amount of space guaranteed to a dataset and its descendants.
1833 When the amount of space used is below this value, the dataset is treated as if
1834 it were taking up the amount of space specified by its reservation.
1835 Reservations are accounted for in the parent datasets' space used, and count
1836 against the parent datasets' quotas and reservations.
1838 This property can also be referred to by its shortened column name,
1840 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1841 Controls what is cached in the secondary cache
1843 If this property is set to
1845 then both user data and metadata is cached.
1846 If this property is set to
1848 then neither user data nor metadata is cached.
1849 If this property is set to
1851 then only metadata is cached.
1852 The default value is
1854 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1855 Controls whether the setuid bit is respected for the file system.
1856 The default value is
1862 are equivalent to the
1867 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1868 Controls whether the file system is shared by using
1869 .Sy Samba USERSHARES
1870 and what options are to be used. Otherwise, the file system is automatically
1871 shared and unshared with the
1875 commands. If the property is set to on, the
1877 command is invoked to create a
1880 Because SMB shares requires a resource name, a unique resource name is
1881 constructed from the dataset name. The constructed name is a copy of the
1882 dataset name except that the characters in the dataset name, which would be
1883 invalid in the resource name, are replaced with underscore (_) characters.
1884 Linux does not currently support additional options which might be available
1891 the file systems are unshared.
1893 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1894 stands for "full permissions", ie. read and write permissions) and no guest
1895 access (which means Samba must be able to authenticate a real user, system
1896 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1897 additional access control (disallow specific user specific access etc) must
1898 be done on the underlying file system.
1899 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1900 Controls whether the file system is shared via NFS, and what options are to be
1902 A file system with a
1908 command and entries in the
1911 Otherwise, the file system is automatically shared and unshared with the
1916 If the property is set to
1918 the dataset is shared using the default options:
1920 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1924 for the meaning of the default options. Otherwise, the
1926 command is invoked with options equivalent to the contents of this property.
1930 property is changed for a dataset, the dataset and any children inheriting the
1931 property are re-shared with the new options, only if the property was previously
1933 or if they were shared before the property was changed.
1934 If the new property is
1936 the file systems are unshared.
1937 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1938 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1944 ZFS will use pool log devices
1946 to handle the requests at low latency.
1951 ZFS will not use configured pool log devices.
1952 ZFS will instead optimize synchronous operations for global pool throughput and
1953 efficient use of resources.
1954 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1955 Controls whether the volume snapshot devices under
1956 .Em /dev/zvol/<pool>
1957 are hidden or visible. The default value is
1959 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1960 Controls whether the
1962 directory is hidden or visible in the root of the file system as discussed in
1966 The default value is
1968 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1969 Controls the behavior of synchronous requests
1970 .Pq e.g. fsync, O_DSYNC .
1974 specified behavior of ensuring all synchronous requests are written to stable
1975 storage and all devices are flushed to ensure data is not cached by device
1977 .Pq this is the default .
1979 causes every file system transaction to be written and flushed before its
1980 system call returns.
1981 This has a large performance penalty.
1983 disables synchronous requests.
1984 File system transactions are only committed to stable storage periodically.
1985 This option will give the highest performance.
1986 However, it is very dangerous as ZFS would be ignoring the synchronous
1987 transaction demands of applications such as databases or NFS.
1988 Administrators should only use this option when the risks are understood.
1989 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1990 The on-disk version of this file system, which is independent of the pool
1992 This property can only be set to later supported versions.
1996 .It Sy volsize Ns = Ns Em size
1997 For volumes, specifies the logical size of the volume.
1998 By default, creating a volume establishes a reservation of equal size.
1999 For storage pools with a version number of 9 or higher, a
2004 are reflected in an equivalent change to the reservation
2010 can only be set to a multiple of
2014 The reservation is kept equal to the volume's logical size to prevent unexpected
2015 behavior for consumers.
2016 Without the reservation, the volume could run out of space, resulting in
2017 undefined behavior or data corruption, depending on how the volume is used.
2018 These effects can also occur when the volume size is changed while it is in use
2019 .Pq particularly when shrinking the size .
2020 Extreme care should be used when adjusting the volume size.
2022 Though not recommended, a
2025 .Qq thin provisioning
2027 can be created by specifying the
2030 .Nm zfs Cm create Fl V
2031 command, or by changing the reservation after the volume has been created.
2034 is a volume where the reservation is less then the volume size.
2035 Consequently, writes to a sparse volume can fail with
2037 when the pool is low on space.
2038 For a sparse volume, changes to
2040 are not reflected in the reservation.
2041 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2042 This property specifies how volumes should be exposed to the OS.
2045 exposes volumes as fully fledged block devices, providing maximal
2046 functionality. The value
2048 is just an alias for
2050 and is kept for compatibility.
2053 hides its partitions.
2054 Volumes with property set to
2056 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
2057 that can be suitable for backup purposes.
2060 means that volumes exposition is controlled by system-wide tunable
2067 are encoded as 1, 2 and 3 respectively.
2068 The default values is
2070 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2071 Controls whether regular files should be scanned for viruses when a file is
2073 In addition to enabling this property, the virus scan service must also be
2074 enabled for virus scanning to occur.
2075 The default value is
2077 This property is not used on Linux.
2078 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2079 Controls whether extended attributes are enabled for this file system. Two
2080 styles of extended attributes are supported either directory based or system
2083 The default value of
2085 enables directory based extended attributes. This style of extended attribute
2086 imposes no practical limit on either the size or number of attributes which
2087 can be set on a file. Although under Linux the
2091 system calls limit the maximum size to 64K. This is the most compatible
2092 style of extended attribute and is supported by all OpenZFS implementations.
2094 System attribute based xattrs can be enabled by setting the value to
2096 The key advantage of this type of xattr is improved performance. Storing
2097 extended attributes as system attributes significantly decreases the amount of
2098 disk IO required. Up to 64K of data may be stored per-file in the space
2099 reserved for system attributes. If there is not enough space available for
2100 an extended attribute then it will be automatically written as a directory
2101 based xattr. System attribute based extended attributes are not accessible
2102 on platforms which do not support the
2106 The use of system attribute based xattrs is strongly encouraged for users of
2107 SELinux or posix ACLs. Both of these features heavily rely of extended
2108 attributes and benefit significantly from the reduced access time.
2114 are equivalent to the
2119 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2120 Controls whether the dataset is managed from a non-global zone. Zones are a
2121 Solaris feature and are not relevant on Linux. The default value is
2125 The following three properties cannot be changed after the file system is
2126 created, and therefore, should be set when the file system is created.
2127 If the properties are not set with the
2131 commands, these properties are inherited from the parent dataset.
2132 If the parent dataset lacks these properties due to having been created prior to
2133 these features being supported, the new file system will have the default values
2134 for these properties.
2137 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2138 .Sy insensitive Ns | Ns Sy mixed
2140 Indicates whether the file name matching algorithm used by the file system
2141 should be case-sensitive, case-insensitive, or allow a combination of both
2143 The default value for the
2151 file systems have case-sensitive file names.
2157 property indicates that the file system can support requests for both
2158 case-sensitive and case-insensitive matching behavior.
2159 Currently, case-insensitive matching behavior on a file system that supports
2160 mixed behavior is limited to the SMB server product.
2161 For more information about the
2163 value behavior, see the "ZFS Administration Guide".
2165 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2166 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2168 Indicates whether the file system should perform a
2170 normalization of file names whenever two file names are compared, and which
2171 normalization algorithm should be used.
2172 File names are always stored unmodified, names are normalized as part of any
2174 If this property is set to a legal value other than
2178 property was left unspecified, the
2180 property is automatically set to
2182 The default value of the
2186 This property cannot be changed after the file system is created.
2187 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2188 Indicates whether the file system should reject file names that include
2189 characters that are not present in the
2192 If this property is explicitly set to
2194 the normalization property must either not be explicitly set or be set to
2196 The default value for the
2200 This property cannot be changed after the file system is created.
2204 .Sy casesensitivity ,
2208 properties are also new permissions that can be assigned to non-privileged users
2209 by using the ZFS delegated administration feature.
2210 .Ss "Temporary Mount Point Properties"
2211 When a file system is mounted, either through
2213 for legacy mounts or the
2215 command for normal file systems, its mount options are set according to its
2217 The correlation between properties and mount options is as follows:
2219 PROPERTY MOUNT OPTION
2221 canmount auto/noauto
2225 relatime relatime/norelatime
2230 In addition, these options can be set on a per-mount basis using the
2232 option, without affecting the property that is stored on disk.
2233 The values specified on the command line override the values stored in the
2237 option is an alias for
2238 .Sy nodevices Ns \&, Ns Sy nosetuid .
2239 These properties are reported as
2244 If the properties are changed while the dataset is mounted, the new setting
2245 overrides any temporary settings.
2246 .Ss "User Properties"
2247 In addition to the standard native properties, ZFS supports arbitrary user
2249 User properties have no effect on ZFS behavior, but applications or
2250 administrators can use them to annotate datasets
2251 .Pq file systems, volumes, and snapshots .
2253 User property names must contain a colon
2255 character to distinguish them from native properties.
2256 They may contain lowercase letters, numbers, and the following punctuation
2265 The expected convention is that the property name is divided into two portions
2267 .Em module Ns \&: Ns Em property ,
2268 but this namespace is not enforced by ZFS.
2269 User property names can be at most 256 characters, and cannot begin with a dash
2272 When making programmatic use of user properties, it is strongly suggested to use
2277 component of property names to reduce the chance that two
2278 independently-developed packages use the same property name for different
2281 The values of user properties are arbitrary strings, are always inherited, and
2282 are never validated.
2283 All of the commands that operate on properties
2284 .Po Nm zfs Cm list ,
2289 can be used to manipulate both native properties and user properties.
2292 command to clear a user property.
2293 If the property is not defined in any parent dataset, it is removed entirely.
2294 Property values are limited to 8192 bytes.
2295 .Ss ZFS Volumes as Swap
2296 ZFS volumes may be used as swap devices. After creating the volume with the
2297 .Nm zfs Cm create Fl V
2298 command set up and enable the swap area using the
2302 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2303 configuration is not supported.
2307 feature allows for the creation of encrypted filesystems and volumes.
2309 will encrypt all user data including file and zvol data, file attributes,
2310 ACLs, permission bits, directory listings, FUID mappings, and userused /
2313 will not encrypt metadata related to the pool structure, including dataset
2314 names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
2315 is managed internally by the kernel module and changing the user's key does not
2316 require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
2317 renamed, and deleted without the encryption keys being loaded (see the
2319 subcommand for more info on key loading).
2321 Creating an encrypted dataset requires specifying the
2325 properties at creation time, along with an optional
2329 After entering an encryption key, the
2330 created dataset will become an encryption root. Any descendant datasets will
2331 inherit their encryption key from the encryption root by default, meaning that
2332 loading, unloading, or changing the key for the encryption root will implicitly
2333 do the same for all inheriting datasets. If this inheritance is not desired,
2336 when creating the child dataset or use
2337 .Nm zfs Cm change-key
2338 to break an existing relationship, creating a new encryption root on the child.
2339 Note that the child's
2341 may match that of the parent while still creating a new encryption root, and
2344 property alone does not create a new encryption root; this would simply use a
2345 different cipher suite with the same key as its encryption root. The one
2346 exception is that clones will always use their origin's encryption key.
2347 As a result of this exception, some encryption-related properties (namely
2353 do not inherit like other ZFS properties and instead use the value determined
2354 by their encryption root. Encryption root inheritance can be tracked via the
2359 Encryption changes the behavior of a few
2361 operations. Encryption is applied after compression so compression ratios are
2362 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2363 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2364 the encryption suite, which provides additional protection against maliciously
2365 altered data. Deduplication is still possible with encryption enabled but for
2366 security, datasets will only dedup against themselves, their snapshots, and
2369 There are a few limitations on encrypted datasets. Encrypted data cannot be
2372 feature. Encrypted datasets may not have
2373 .Sy copies Ns = Ns Em 3
2374 since the implementation stores some encryption metadata where the third copy
2375 would normally be. Since compression is applied before encryption datasets may
2376 be vulnerable to a CRIME-like attack if applications accessing the data allow
2377 for it. Deduplication with encryption will leak information about which blocks
2378 are equivalent in a dataset and will incur an extra CPU cost per block written.
2380 All subcommands that modify state are logged persistently to the pool in their
2384 Displays a help message.
2389 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2392 Creates a new ZFS file system.
2393 The file system is automatically mounted according to the
2395 property inherited from the parent.
2396 .Bl -tag -width "-o"
2397 .It Fl o Ar property Ns = Ns Ar value
2398 Sets the specified property as if the command
2399 .Nm zfs Cm set Ar property Ns = Ns Ar value
2400 was invoked at the same time the dataset was created.
2401 Any editable ZFS property can also be set at creation time.
2404 options can be specified.
2405 An error results if the same property is specified in multiple
2409 Creates all the non-existing parent datasets.
2410 Datasets created in this manner are automatically mounted according to the
2412 property inherited from their parent.
2413 Any property specified on the command line using the
2416 If the target filesystem already exists, the operation completes successfully.
2422 .Op Fl b Ar blocksize
2423 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2424 .Fl V Ar size Ar volume
2426 Creates a volume of the given size.
2427 The volume is exported as a block device in
2428 .Pa /dev/zvol/path ,
2431 is the name of the volume in the ZFS namespace.
2432 The size represents the logical size as exported by the device.
2433 By default, a reservation of equal size is created.
2436 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2437 has an integral number of blocks regardless of
2439 .Bl -tag -width "-b"
2440 .It Fl b Ar blocksize
2442 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2443 If this option is specified in conjunction with
2444 .Fl o Sy volblocksize ,
2445 the resulting behavior is undefined.
2446 .It Fl o Ar property Ns = Ns Ar value
2447 Sets the specified property as if the
2448 .Nm zfs Cm set Ar property Ns = Ns Ar value
2449 command was invoked at the same time the dataset was created.
2450 Any editable ZFS property can also be set at creation time.
2453 options can be specified.
2454 An error results if the same property is specified in multiple
2458 Creates all the non-existing parent datasets.
2459 Datasets created in this manner are automatically mounted according to the
2461 property inherited from their parent.
2462 Any property specified on the command line using the
2465 If the target filesystem already exists, the operation completes successfully.
2467 Creates a sparse volume with no reservation.
2471 .Sx Native Properties
2472 section for more information about sparse volumes.
2478 .Ar filesystem Ns | Ns Ar volume
2480 Destroys the given dataset.
2481 By default, the command unshares any file systems that are currently shared,
2482 unmounts any file systems that are currently mounted, and refuses to destroy a
2483 dataset that has active dependents
2484 .Pq children or clones .
2485 .Bl -tag -width "-R"
2487 Recursively destroy all dependents, including cloned file systems outside the
2490 Force an unmount of any file systems using the
2493 This option has no effect on non-file systems or unmounted file systems.
2498 No data will be deleted.
2499 This is useful in conjunction with the
2503 flags to determine what data would be deleted.
2505 Print machine-parsable verbose information about the deleted data.
2507 Recursively destroy all children.
2509 Print verbose information about the deleted data.
2512 Extreme care should be taken when applying either the
2516 options, as they can destroy large portions of a pool and cause unexpected
2517 behavior for mounted file systems in use.
2522 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2523 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2525 The given snapshots are destroyed immediately if and only if the
2529 option would have destroyed it.
2530 Such immediate destruction would occur, for example, if the snapshot had no
2531 clones and the user-initiated reference count were zero.
2533 If a snapshot does not qualify for immediate destruction, it is marked for
2535 In this state, it exists as a usable, visible snapshot until both of the
2536 preconditions listed above are met, at which point it is destroyed.
2538 An inclusive range of snapshots may be specified by separating the first and
2539 last snapshots with a percent sign.
2540 The first and/or last snapshots may be left blank, in which case the
2541 filesystem's oldest or newest snapshot will be implied.
2544 .Pq or ranges of snapshots
2545 of the same filesystem or volume may be specified in a comma-separated list of
2547 Only the snapshot's short name
2548 .Po the part after the
2551 should be specified when using a range or comma-separated list to identify
2553 .Bl -tag -width "-R"
2555 Recursively destroy all clones of these snapshots, including the clones,
2556 snapshots, and children.
2557 If this flag is specified, the
2559 flag will have no effect.
2561 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2562 deferred destruction.
2567 No data will be deleted.
2568 This is useful in conjunction with the
2572 flags to determine what data would be deleted.
2574 Print machine-parsable verbose information about the deleted data.
2577 .Pq or mark for deferred deletion
2578 all snapshots with this name in descendent file systems.
2580 Print verbose information about the deleted data.
2582 Extreme care should be taken when applying either the
2586 options, as they can destroy large portions of a pool and cause unexpected
2587 behavior for mounted file systems in use.
2592 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2594 The given bookmark is destroyed.
2599 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2600 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2602 Creates snapshots with the given names.
2603 All previous modifications by successful system calls to the file system are
2604 part of the snapshots.
2605 Snapshots are taken atomically, so that all snapshots correspond to the same
2608 can be used as an alias for
2609 .Nm zfs Cm snapshot.
2612 section for details.
2613 .Bl -tag -width "-o"
2614 .It Fl o Ar property Ns = Ns Ar value
2615 Sets the specified property; see
2619 Recursively create snapshots of all descendent datasets
2627 Roll back the given dataset to a previous snapshot.
2628 When a dataset is rolled back, all data that has changed since the snapshot is
2629 discarded, and the dataset reverts to the state at the time of the snapshot.
2630 By default, the command refuses to roll back to a snapshot other than the most
2632 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2639 options do not recursively destroy the child snapshots of a recursive snapshot.
2640 Only direct snapshots of the specified filesystem are destroyed by either of
2642 To completely roll back a recursive snapshot, you must rollback the individual
2644 .Bl -tag -width "-R"
2646 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2651 option to force an unmount of any clone file systems that are to be destroyed.
2653 Destroy any snapshots and bookmarks more recent than the one specified.
2659 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2660 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2662 Creates a clone of the given snapshot.
2665 section for details.
2666 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2667 as the same type as the original.
2668 .Bl -tag -width "-o"
2669 .It Fl o Ar property Ns = Ns Ar value
2670 Sets the specified property; see
2674 Creates all the non-existing parent datasets.
2675 Datasets created in this manner are automatically mounted according to the
2677 property inherited from their parent.
2678 If the target filesystem or volume already exists, the operation completes
2684 .Ar clone-filesystem
2686 Promotes a clone file system to no longer be dependent on its
2689 This makes it possible to destroy the file system that the clone was created
2691 The clone parent-child dependency relationship is reversed, so that the origin
2692 file system becomes a clone of the specified file system.
2694 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2695 now owned by the promoted clone.
2696 The space they use moves from the origin file system to the promoted clone, so
2697 enough space must be available to accommodate these snapshots.
2698 No new space is consumed by this operation, but the space accounting is
2700 The promoted clone must not have any conflicting snapshot names of its own.
2703 subcommand can be used to rename any conflicting snapshots.
2708 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2709 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2715 .Ar filesystem Ns | Ns Ar volume
2716 .Ar filesystem Ns | Ns Ar volume
2718 Renames the given dataset.
2719 The new target can be located anywhere in the ZFS hierarchy, with the exception
2721 Snapshots can only be renamed within the parent file system or volume.
2722 When renaming a snapshot, the parent file system of the snapshot does not need
2723 to be specified as part of the second argument.
2724 Renamed file systems can inherit new mount points, in which case they are
2725 unmounted and remounted at the new mount point.
2726 .Bl -tag -width "-a"
2728 Force unmount any filesystems that need to be unmounted in the process.
2730 Creates all the nonexistent parent datasets.
2731 Datasets created in this manner are automatically mounted according to the
2733 property inherited from their parent.
2739 .Ar snapshot Ar snapshot
2741 Recursively rename the snapshots of all descendent datasets.
2742 Snapshots are the only dataset that can be renamed recursively.
2746 .Op Fl r Ns | Ns Fl d Ar depth
2748 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2749 .Oo Fl s Ar property Oc Ns ...
2750 .Oo Fl S Ar property Oc Ns ...
2751 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2752 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2754 Lists the property information for the given datasets in tabular form.
2755 If specified, you can list property information by the absolute pathname or the
2757 By default, all file systems and volumes are displayed.
2758 Snapshots are displayed if the
2765 The following fields are displayed,
2766 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2768 .Bl -tag -width "-H"
2770 Used for scripting mode.
2771 Do not print headers and separate fields by a single tab instead of arbitrary
2773 .It Fl S Ar property
2776 option, but sorts by property in descending order.
2778 Recursively display any children of the dataset, limiting the recursion to
2784 will display only the dataset and its direct children.
2785 .It Fl o Ar property
2786 A comma-separated list of properties to display.
2787 The property must be:
2790 One of the properties described in the
2791 .Sx Native Properties
2798 to display the dataset name
2802 to display space usage properties on file systems and volumes.
2803 This is a shortcut for specifying
2804 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2805 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2806 .Sy filesystem Ns \&, Ns Sy volume
2810 Display numbers in parsable
2814 Recursively display any children of the dataset on the command line.
2815 .It Fl s Ar property
2816 A property for sorting the output by column in ascending order based on the
2817 value of the property.
2818 The property must be one of the properties described in the
2820 section, or the special value
2822 to sort by the dataset name.
2823 Multiple properties can be specified at one time using multiple
2828 options are evaluated from left to right in decreasing order of importance.
2829 The following is a list of sorting criteria:
2832 Numeric types sort in numeric order.
2834 String types sort in alphabetical order.
2836 Types inappropriate for a row sort that row to the literal bottom, regardless of
2837 the specified ordering.
2840 If no sorting options are specified the existing behavior of
2844 A comma-separated list of types to display, where
2853 For example, specifying
2855 displays only snapshots.
2860 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2861 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2863 Sets the property or list of properties to the given value(s) for each dataset.
2864 Only some properties can be edited.
2867 section for more information on what properties can be set and acceptable
2869 Numeric values can be specified as exact values, or in a human-readable form
2871 .Sy B , K , M , G , T , P , E , Z
2872 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2873 or zettabytes, respectively
2875 User properties can be set on snapshots.
2876 For more information, see the
2882 .Op Fl r Ns | Ns Fl d Ar depth
2884 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2885 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2886 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2887 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2888 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2890 Displays properties for the given datasets.
2891 If no datasets are specified, then the command displays properties for all
2892 datasets on the system.
2893 For each property, the following columns are displayed:
2896 property Property name
2897 value Property value
2898 source Property source. Can either be local, default,
2899 temporary, inherited, or none (-).
2902 All columns are displayed by default, though this can be controlled by using the
2905 This command takes a comma-separated list of properties as described in the
2906 .Sx Native Properties
2913 can be used to display all properties that apply to the given dataset's type
2914 .Pq filesystem, volume, snapshot, or bookmark .
2915 .Bl -tag -width "-H"
2917 Display output in a form more easily parsed by scripts.
2918 Any headers are omitted, and fields are explicitly separated by a single tab
2919 instead of an arbitrary amount of space.
2921 Recursively display any children of the dataset, limiting the recursion to
2925 will display only the dataset and its direct children.
2927 A comma-separated list of columns to display.
2928 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2929 is the default value.
2931 Display numbers in parsable
2935 Recursively display properties for any children.
2937 A comma-separated list of sources to display.
2938 Those properties coming from a source other than those in this list are ignored.
2939 Each source must be one of the following:
2946 The default value is all sources.
2948 A comma-separated list of types to display, where
2962 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2964 Clears the specified property, causing it to be inherited from an ancestor,
2965 restored to default if no ancestor has the property set, or with the
2967 option reverted to the received value if one exists.
2970 section for a listing of default values, and details on which properties can be
2972 .Bl -tag -width "-r"
2974 Recursively inherit the given property for all children.
2976 Revert the property to the received value if one exists; otherwise operate as
2979 option was not specified.
2985 Displays a list of file systems that are not the most recent version.
2991 Displays a list of currently supported file system versions.
2997 .Fl a | Ar filesystem
2999 Upgrades file systems to a new on-disk version.
3000 Once this is done, the file systems will no longer be accessible on systems
3001 running older versions of the software.
3003 streams generated from new snapshots of these file systems cannot be accessed on
3004 systems running older versions of the software.
3006 In general, the file system version is independent of the pool version.
3009 for information on the
3010 .Nm zpool Cm upgrade
3013 In some cases, the file system version and the pool version are interrelated and
3014 the pool version must be upgraded before the file system version can be
3016 .Bl -tag -width "-V"
3018 Upgrade to the specified
3022 flag is not specified, this command upgrades to the most recent version.
3024 option can only be used to increase the version number, and only up to the most
3025 recent version supported by this software.
3027 Upgrade all file systems on all imported pools.
3029 Upgrade the specified file system.
3031 Upgrade the specified file system and all descendent file systems.
3037 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3038 .Oo Fl s Ar field Oc Ns ...
3039 .Oo Fl S Ar field Oc Ns ...
3040 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3041 .Ar filesystem Ns | Ns Ar snapshot
3043 Displays space consumed by, and quotas on, each user in the specified filesystem
3045 This corresponds to the
3046 .Sy userused@ Ns Em user ,
3047 .Sy userobjused@ Ns Em user ,
3048 .Sy userquota@ Ns Em user,
3050 .Sy userobjquota@ Ns Em user
3052 .Bl -tag -width "-H"
3054 Do not print headers, use tab-delimited output.
3056 Sort by this field in reverse order.
3060 Translate SID to POSIX ID.
3061 The POSIX ID may be ephemeral if no mapping exists.
3062 Normal POSIX interfaces
3067 perform this translation, so the
3069 option allows the output from
3070 .Nm zfs Cm userspace
3071 to be compared directly with those utilities.
3074 may lead to confusion if some files were created by an SMB user before a
3075 SMB-to-POSIX name mapping was established.
3076 In such a case, some files will be owned by the SMB entity and some by the POSIX
3080 option will report that the POSIX entity has the total usage and quota for both.
3082 Print numeric ID instead of user/group name.
3083 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3084 Display only the specified fields from the following set:
3089 The default is to display all fields.
3095 Sort output by this field.
3100 flags may be specified multiple times to sort first by one field, then by
3103 .Fl s Sy type Fl s Sy name .
3104 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3105 Print only the specified types from the following set:
3112 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3113 The default can be changed to include group types.
3119 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3120 .Oo Fl s Ar field Oc Ns ...
3121 .Oo Fl S Ar field Oc Ns ...
3122 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3123 .Ar filesystem Ns | Ns Ar snapshot
3125 Displays space consumed by, and quotas on, each group in the specified
3126 filesystem or snapshot.
3127 This subcommand is identical to
3128 .Nm zfs Cm userspace ,
3129 except that the default types to display are
3130 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3135 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3136 .Oo Fl s Ar field Oc Ns ...
3137 .Oo Fl S Ar field Oc Ns ...
3138 .Ar filesystem Ns | Ns Ar snapshot
3140 Displays space consumed by, and quotas on, each project in the specified
3141 filesystem or snapshot. This subcommand is identical to
3142 .Nm zfs Cm userspace ,
3143 except that the project identifier is numeral, not name. So need neither
3146 for SID to POSIX ID nor
3154 .Oo Fl d Ns | Ns Fl r Ns Oc
3155 .Ar file Ns | Ns Ar directory Ns ...
3157 List project identifier (ID) and inherit flag of file(s) or directories.
3158 .Bl -tag -width "-d"
3160 Show the directory project ID and inherit flag, not its childrens. It will
3161 overwrite the former specified
3165 Show on subdirectories recursively. It will overwrite the former specified
3174 .Ar file Ns | Ns Ar directory Ns ...
3176 Clear project inherit flag and/or ID on the file(s) or directories.
3177 .Bl -tag -width "-k"
3179 Keep the project ID unchanged. If not specified, the project ID will be reset
3182 Clear on subdirectories recursively.
3189 .Oo Fl d Ns | Ns Fl r Ns Oc
3191 .Ar file Ns | Ns Ar directory Ns ...
3193 Check project ID and inherit flag on the file(s) or directories, report the
3194 entries without project inherit flag or with different project IDs from the
3197 option) value or the target directory's project ID.
3198 .Bl -tag -width "-0"
3200 Print file name with a trailing NUL instead of newline (by default), like
3203 Check the directory project ID and inherit flag, not its childrens. It will
3204 overwrite the former specified
3208 Specify the referenced ID for comparing with the target file(s) or directories'
3209 project IDs. If not specified, the target (top) directory's project ID will be
3210 used as the referenced one.
3212 Check on subdirectories recursively. It will overwrite the former specified
3221 .Ar file Ns | Ns Ar directory Ns ...
3223 .Bl -tag -width "-p"
3224 Set project ID and/or inherit flag on the file(s) or directories.
3226 Set the file(s)' or directories' project ID with the given value.
3228 Set on subdirectories recursively.
3230 Set project inherit flag on the given file(s) or directories. It is usually used
3231 for setup tree quota on the directory target with
3233 option specified together. When setup tree quota, by default the directory's
3234 project ID will be set to all its descendants unless you specify the project
3243 Displays all ZFS file systems currently mounted.
3249 .Fl a | Ar filesystem
3251 Mounts ZFS file systems.
3252 .Bl -tag -width "-O"
3254 Perform an overlay mount.
3257 for more information.
3259 Mount all available ZFS file systems.
3260 Invoked automatically as part of the boot process.
3262 Mount the specified filesystem.
3264 An optional, comma-separated list of mount options to use temporarily for the
3265 duration of the mount.
3267 .Sx Temporary Mount Point Properties
3268 section for details.
3270 Load keys for encrypted filesystems as they are being mounted. This is
3271 equivalent to executing
3273 on each encryption root before mounting it. Note that if a filesystem has a
3277 this will cause the terminal to interactively block after asking for the key.
3279 Report mount progress.
3285 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3287 Unmounts currently mounted ZFS file systems.
3288 .Bl -tag -width "-a"
3290 Unmount all available ZFS file systems.
3291 Invoked automatically as part of the shutdown process.
3292 .It Ar filesystem Ns | Ns Ar mountpoint
3293 Unmount the specified filesystem.
3294 The command can also be given a path to a ZFS file system mount point on the
3297 Forcefully unmount the file system, even if it is currently in use.
3302 .Fl a | Ar filesystem
3304 Shares available ZFS file systems.
3305 .Bl -tag -width "-a"
3307 Share all available ZFS file systems.
3308 Invoked automatically as part of the boot process.
3310 Share the specified filesystem according to the
3315 File systems are shared when the
3324 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3326 Unshares currently shared ZFS file systems.
3327 .Bl -tag -width "-a"
3329 Unshare all available ZFS file systems.
3330 Invoked automatically as part of the shutdown process.
3331 .It Ar filesystem Ns | Ns Ar mountpoint
3332 Unshare the specified filesystem.
3333 The command can also be given a path to a ZFS file system shared on the system.
3338 .Ar snapshot bookmark
3340 Creates a bookmark of the given snapshot.
3341 Bookmarks mark the point in time when the snapshot was created, and can be used
3342 as the incremental source for a
3346 This feature must be enabled to be used.
3348 .Xr zpool-features 5
3349 for details on ZFS feature flags and the
3356 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3359 Creates a stream representation of the second
3361 which is written to standard output.
3362 The output can be redirected to a file or to a different system
3363 .Po for example, using
3366 By default, a full stream is generated.
3367 .Bl -tag -width "-D"
3369 Generate a deduplicated stream.
3370 Blocks which would have been sent multiple times in the send stream will only be
3372 The receiving system must also support this feature to receive a deduplicated
3374 This flag can be used regardless of the dataset's
3376 property, but performance will be much better if the filesystem uses a
3377 dedup-capable checksum
3381 .It Fl I Ar snapshot
3382 Generate a stream package that sends all intermediary snapshots from the first
3383 snapshot to the second snapshot.
3387 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3388 The incremental source may be specified as with the
3391 .It Fl L, -large-block
3392 Generate a stream which may contain blocks larger than 128KB.
3393 This flag has no effect if the
3395 pool feature is disabled, or if the
3397 property of this filesystem has never been set above 128KB.
3398 The receiving system must have the
3400 pool feature enabled as well.
3402 .Xr zpool-features 5
3403 for details on ZFS feature flags and the
3407 Print machine-parsable verbose information about the stream package generated.
3408 .It Fl R, -replicate
3409 Generate a replication stream package, which will replicate the specified
3410 file system, and all descendent file systems, up to the named snapshot.
3411 When received, all properties, snapshots, descendent file systems, and clones
3418 flags are used in conjunction with the
3420 flag, an incremental replication stream is generated.
3421 The current values of properties, and current snapshot and file system names are
3422 set when the stream is received.
3425 flag is specified when this stream is received, snapshots and file systems that
3426 do not exist on the sending side are destroyed.
3428 Generate a more compact stream by using
3430 records for blocks which are stored more compactly on disk by the
3433 This flag has no effect if the
3435 feature is disabled.
3436 The receiving system must have the
3441 feature is active on the sending system, then the receiving system must have
3442 that feature enabled as well. Datasets that are sent with this flag may not be
3443 received as an encrypted dataset, since encrypted datasets cannot use the
3447 .Xr zpool-features 5
3448 for details on ZFS feature flags and the
3452 Sends only received property values whether or not they are overridden by local
3453 settings, but only if the dataset has ever been received. Use this option when
3456 to restore received properties backed up on the sent dataset and to avoid
3457 sending local settings that may have nothing to do with the source dataset,
3458 but only with how the data is backed up.
3459 .It Fl c, -compressed
3460 Generate a more compact stream by using compressed WRITE records for blocks
3461 which are compressed on disk and in memory
3464 property for details
3468 feature is active on the sending system, then the receiving system must have
3469 that feature enabled as well.
3472 feature is enabled on the sending system but the
3474 option is not supplied in conjunction with
3476 then the data will be decompressed before sending so it can be split into
3477 smaller block sizes.
3479 For encrypted datasets, send data exactly as it exists on disk. This allows
3480 backups to be taken even if encryption keys are not currently loaded. The
3481 backup may then be received on an untrusted machine since that machine will
3482 not have the encryption keys to read the protected data or alter it without
3483 being detected. Upon being received, the dataset will have the same encryption
3484 keys as it did on the send side, although the
3486 property will be defaulted to
3488 if not otherwise provided. For unencrypted datasets, this flag will be
3491 Note that if you do not use this flag for sending encrypted datasets, data will
3492 be sent unencrypted and may be re-encrypted with a different encryption key on
3493 the receiving system, which will disable the ability to do a raw send to that
3494 system for incrementals.
3495 .It Fl i Ar snapshot
3496 Generate an incremental stream from the first
3498 .Pq the incremental source
3501 .Pq the incremental target .
3502 The incremental source can be specified as the last component of the snapshot
3506 character and following
3508 and it is assumed to be from the same file system as the incremental target.
3510 If the destination is a clone, the source may be the origin snapshot, which must
3513 .Em pool/fs@origin ,
3521 Do not generate any actual send data.
3522 This is useful in conjunction with the
3526 flags to determine what data will be sent.
3527 In this case, the verbose output will be written to standard output
3528 .Po contrast with a non-dry-run, where the stream is written to standard output
3529 and the verbose output goes to standard error
3532 Include the dataset's properties in the stream.
3533 This flag is implicit when
3536 The receiving system must also support this feature. Sends of encrypted datasets
3539 when using this flag.
3541 Print verbose information about the stream package generated.
3542 This information includes a per-second report of how much data has been sent.
3544 The format of the stream is committed.
3545 You will be able to receive your streams on future versions of ZFS.
3551 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3552 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3554 Generate a send stream, which may be of a filesystem, and may be incremental
3556 If the destination is a filesystem or volume, the pool must be read-only, or the
3557 filesystem must not be mounted.
3558 When the stream generated from a filesystem or volume is received, the default
3559 snapshot name will be
3561 .Bl -tag -width "-L"
3562 .It Fl L, -large-block
3563 Generate a stream which may contain blocks larger than 128KB.
3564 This flag has no effect if the
3566 pool feature is disabled, or if the
3568 property of this filesystem has never been set above 128KB.
3569 The receiving system must have the
3571 pool feature enabled as well.
3573 .Xr zpool-features 5
3574 for details on ZFS feature flags and the
3578 Print machine-parsable verbose information about the stream package generated.
3579 .It Fl c, -compressed
3580 Generate a more compact stream by using compressed WRITE records for blocks
3581 which are compressed on disk and in memory
3584 property for details
3588 feature is active on the sending system, then the receiving system must have
3589 that feature enabled as well.
3592 feature is enabled on the sending system but the
3594 option is not supplied in conjunction with
3596 then the data will be decompressed before sending so it can be split into
3597 smaller block sizes.
3599 For encrypted datasets, send data exactly as it exists on disk. This allows
3600 backups to be taken even if encryption keys are not currently loaded. The
3601 backup may then be received on an untrusted machine since that machine will
3602 not have the encryption keys to read the protected data or alter it without
3603 being detected. Upon being received, the dataset will have the same encryption
3604 keys as it did on the send side, although the
3606 property will be defaulted to
3608 if not otherwise provided. For unencrypted datasets, this flag will be
3611 Note that if you do not use this flag for sending encrypted datasets, data will
3612 be sent unencrypted and may be re-encrypted with a different encryption key on
3613 the receiving system, which will disable the ability to do a raw send to that
3614 system for incrementals.
3616 Generate a more compact stream by using
3618 records for blocks which are stored more compactly on disk by the
3621 This flag has no effect if the
3623 feature is disabled.
3624 The receiving system must have the
3629 feature is active on the sending system, then the receiving system must have
3630 that feature enabled as well. Datasets that are sent with this flag may not be
3631 received as an encrypted dataset, since encrypted datasets cannot use the
3635 .Xr zpool-features 5
3636 for details on ZFS feature flags and the
3639 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3640 Generate an incremental send stream.
3641 The incremental source must be an earlier snapshot in the destination's history.
3642 It will commonly be an earlier snapshot in the destination's file system, in
3643 which case it can be specified as the last component of the name
3648 character and following
3651 If the incremental target is a clone, the incremental source can be the origin
3652 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3658 Do not generate any actual send data.
3659 This is useful in conjunction with the
3663 flags to determine what data will be sent.
3664 In this case, the verbose output will be written to standard output
3665 .Po contrast with a non-dry-run, where the stream is written to standard output
3666 and the verbose output goes to standard error
3669 Print verbose information about the stream package generated.
3670 This information includes a per-second report of how much data has been sent.
3677 .Ar receive_resume_token
3679 Creates a send stream which resumes an interrupted receive.
3681 .Ar receive_resume_token
3682 is the value of this property on the filesystem or volume that was being
3684 See the documentation for
3691 .Op Fl o Sy origin Ns = Ns Ar snapshot
3692 .Op Fl o Ar property Ns = Ns Ar value
3693 .Op Fl x Ar property
3694 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3700 .Op Fl d Ns | Ns Fl e
3701 .Op Fl o Sy origin Ns = Ns Ar snapshot
3702 .Op Fl o Ar property Ns = Ns Ar value
3703 .Op Fl x Ar property
3706 Creates a snapshot whose contents are as specified in the stream provided on
3708 If a full stream is received, then a new file system is created as well.
3709 Streams are created using the
3711 subcommand, which by default creates a full stream.
3713 can be used as an alias for
3716 If an incremental stream is received, then the destination file system must
3717 already exist, and its most recent snapshot must match the incremental stream's
3721 the destination device link is destroyed and recreated, which means the
3723 cannot be accessed during the
3727 When a snapshot replication package stream that is generated by using the
3728 .Nm zfs Cm send Fl R
3729 command is received, any snapshots that do not exist on the sending location are
3730 destroyed by using the
3731 .Nm zfs Cm destroy Fl d
3735 .Fl o Em property Ns = Ns Ar value
3738 is specified, it applies to the effective value of the property throughout
3739 the entire subtree of replicated datasets. Effective property values will be
3744 ) on the topmost in the replicated subtree. In descendant datasets, if the
3745 property is set by the send stream, it will be overridden by forcing the
3746 property to be inherited from the top‐most file system. Received properties
3747 are retained in spite of being overridden and may be restored with
3748 .Nm zfs Cm inherit Fl S .
3750 .Fl o Sy origin Ns = Ns Em snapshot
3751 is a special case because, even if
3753 is a read-only property and cannot be set, it's allowed to receive the send
3754 stream as a clone of the given snapshot.
3756 Raw encrypted send streams (created with
3757 .Nm zfs Cm send Fl w
3758 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3759 recompressed by the receive process. Unencrypted streams can be received as
3760 encrypted datasets, either through inheritance or by specifying encryption
3765 The name of the snapshot
3766 .Pq and file system, if a full stream is received
3767 that this subcommand creates depends on the argument type and the use of the
3773 If the argument is a snapshot name, the specified
3776 If the argument is a file system or volume name, a snapshot with the same name
3777 as the sent snapshot is created within the specified
3785 options are specified, the provided target snapshot name is used exactly as
3792 options cause the file system name of the target snapshot to be determined by
3793 appending a portion of the sent snapshot's name to the specified target
3797 option is specified, all but the first element of the sent snapshot's file
3799 .Pq usually the pool name
3800 is used and any required intermediate file systems within the specified one are
3804 option is specified, then only the last element of the sent snapshot's file
3806 .Pq i.e. the name of the source file system itself
3807 is used as the target file system name.
3808 .Bl -tag -width "-F"
3810 Force a rollback of the file system to the most recent snapshot before
3811 performing the receive operation.
3812 If receiving an incremental replication stream
3813 .Po for example, one generated by
3814 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3816 destroy snapshots and file systems that do not exist on the sending side.
3818 Discard the first element of the sent snapshot's file system name, using the
3819 remaining elements to determine the name of the target file system for the new
3820 snapshot as described in the paragraph above.
3822 Discard all but the last element of the sent snapshot's file system name, using
3823 that element to determine the name of the target file system for the new
3824 snapshot as described in the paragraph above.
3826 Do not actually receive the stream.
3827 This can be useful in conjunction with the
3829 option to verify the name the receive operation would use.
3830 .It Fl o Sy origin Ns = Ns Ar snapshot
3831 Forces the stream to be received as a clone of the given snapshot.
3832 If the stream is a full send stream, this will create the filesystem
3833 described by the stream as a clone of the specified snapshot.
3834 Which snapshot was specified will not affect the success or failure of the
3835 receive, as long as the snapshot does exist.
3836 If the stream is an incremental send stream, all the normal verification will be
3838 .It Fl o Em property Ns = Ns Ar value
3839 Sets the specified property as if the command
3840 .Nm zfs Cm set Em property Ns = Ns Ar value
3841 was invoked immediately before the receive. When receiving a stream from
3842 .Nm zfs Cm send Fl R ,
3843 causes the property to be inherited by all descendant datasets, as through
3844 .Nm zfs Cm inherit Em property
3845 was run on any descendant datasets that have this property set on the
3848 Any editable property can be set at receive time. Set-once properties bound
3849 to the received data, such as
3852 .Sy casesensitivity ,
3853 cannot be set at receive time even when the datasets are newly created by
3854 .Nm zfs Cm receive .
3855 Additionally both settable properties
3859 cannot be set at receive time.
3863 option may be specified multiple times, for different properties. An error
3864 results if the same property is specified in multiple
3870 If the receive is interrupted, save the partially received state, rather
3872 Interruption may be due to premature termination of the stream
3873 .Po e.g. due to network failure or failure of the remote system
3874 if the stream is being read over a network connection
3876 a checksum error in the stream, termination of the
3878 process, or unclean shutdown of the system.
3880 The receive can be resumed with a stream generated by
3881 .Nm zfs Cm send Fl t Ar token ,
3885 .Sy receive_resume_token
3886 property of the filesystem or volume which is received into.
3888 To use this flag, the storage pool must have the
3889 .Sy extensible_dataset
3892 .Xr zpool-features 5
3893 for details on ZFS feature flags.
3895 File system that is associated with the received stream is not mounted.
3897 Print verbose information about the stream and the time required to perform the
3899 .It Fl x Em property
3900 Ensures that the effective value of the specified property after the
3901 receive is unaffected by the value of that property in the send stream (if any),
3902 as if the property had been excluded from the send stream.
3904 If the specified property is not present in the send stream, this option does
3907 If a received property needs to be overridden, the effective value will be
3908 set or inherited, depending on whether the property is inheritable or not.
3910 In the case of an incremental update,
3912 leaves any existing local setting or explicit inheritance unchanged.
3916 restrictions on set-once and special properties apply equally to
3923 .Ar filesystem Ns | Ns Ar volume
3925 Abort an interrupted
3926 .Nm zfs Cm receive Fl s ,
3927 deleting its saved partially received state.
3931 .Ar filesystem Ns | Ns Ar volume
3933 Displays permissions that have been delegated on the specified filesystem or
3935 See the other forms of
3937 for more information.
3939 Delegations are supported under Linux with the exception of
3947 These permissions cannot be delegated because the Linux
3949 command restricts modifications of the global namespace to the root user.
3954 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3955 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3956 .Ar setname Oc Ns ...
3957 .Ar filesystem Ns | Ns Ar volume
3962 .Fl e Ns | Ns Sy everyone
3963 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3964 .Ar setname Oc Ns ...
3965 .Ar filesystem Ns | Ns Ar volume
3967 Delegates ZFS administration permission for the file systems to non-privileged
3969 .Bl -tag -width "-d"
3971 Allow only for the descendent file systems.
3972 .It Fl e Ns | Ns Sy everyone
3973 Specifies that the permissions be delegated to everyone.
3974 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3975 Explicitly specify that permissions are delegated to the group.
3979 only for the specified file system.
3980 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3981 Explicitly specify that permissions are delegated to the user.
3982 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3983 Specifies to whom the permissions are delegated.
3984 Multiple entities can be specified as a comma-separated list.
3987 options are specified, then the argument is interpreted preferentially as the
3990 then as a user name, and lastly as a group name.
3991 To specify a user or group named
3998 To specify a group with the same name as a user, use the
4002 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4003 .Ar setname Oc Ns ...
4005 The permissions to delegate.
4006 Multiple permissions may be specified as a comma-separated list.
4007 Permission names are the same as ZFS subcommand and property names.
4008 See the property list below.
4009 Property set names, which begin with
4014 form below for details.
4019 options are specified, or both are, then the permissions are allowed for the
4020 file system or volume, and all of its descendents.
4022 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4024 The following permissions are available:
4027 allow subcommand Must also have the permission that is
4029 clone subcommand Must also have the 'create' ability and
4030 'mount' ability in the origin file system
4031 create subcommand Must also have the 'mount' ability
4032 destroy subcommand Must also have the 'mount' ability
4033 diff subcommand Allows lookup of paths within a dataset
4034 given an object number, and the ability
4035 to create snapshots necessary to
4037 load-key subcommand Allows loading and unloading of encryption key
4038 (see 'zfs load-key' and 'zfs unload-key').
4039 change-key subcommand Allows changing an encryption key via
4041 mount subcommand Allows mount/umount of ZFS datasets
4042 promote subcommand Must also have the 'mount' and 'promote'
4043 ability in the origin file system
4044 receive subcommand Must also have the 'mount' and 'create'
4046 rename subcommand Must also have the 'mount' and 'create'
4047 ability in the new parent
4048 rollback subcommand Must also have the 'mount' ability
4050 share subcommand Allows sharing file systems over NFS
4052 snapshot subcommand Must also have the 'mount' ability
4054 groupquota other Allows accessing any groupquota@...
4056 groupused other Allows reading any groupused@... property
4057 userprop other Allows changing any user property
4058 userquota other Allows accessing any userquota@...
4060 userused other Allows reading any userused@... property
4061 projectobjquota other Allows accessing any projectobjquota@...
4063 projectquota other Allows accessing any projectquota@... property
4064 projectobjused other Allows reading any projectobjused@... property
4065 projectused other Allows reading any projectused@... property
4071 casesensitivity property
4073 compression property
4077 filesystem_limit property
4080 normalization property
4081 primarycache property
4086 refreservation property
4087 reservation property
4088 secondarycache property
4093 snapshot_limit property
4096 volblocksize property
4106 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4107 .Ar setname Oc Ns ...
4108 .Ar filesystem Ns | Ns Ar volume
4113 These permissions are granted
4115 to the creator of any newly-created descendent file system.
4119 .Fl s No @ Ns Ar setname
4120 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4121 .Ar setname Oc Ns ...
4122 .Ar filesystem Ns | Ns Ar volume
4124 Defines or adds permissions to a permission set.
4125 The set can be used by other
4127 commands for the specified file system and its descendents.
4128 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4129 Permission sets follow the same naming restrictions as ZFS file systems, but the
4130 name must begin with
4132 and can be no more than 64 characters long.
4137 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4138 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4139 .Ar setname Oc Ns ... Oc
4140 .Ar filesystem Ns | Ns Ar volume
4145 .Fl e Ns | Ns Sy everyone
4146 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4147 .Ar setname Oc Ns ... Oc
4148 .Ar filesystem Ns | Ns Ar volume
4154 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4155 .Ar setname Oc Ns ... Oc
4156 .Ar filesystem Ns | Ns Ar volume
4158 Removes permissions that were granted with the
4161 No permissions are explicitly denied, so other permissions granted are still in
4163 For example, if the permission is granted by an ancestor.
4164 If no permissions are specified, then all permissions for the specified
4176 only removes the permissions that were granted to everyone, not all permissions
4177 for every user and group.
4180 command for a description of the
4183 .Bl -tag -width "-r"
4185 Recursively remove the permissions from this file system and all descendents.
4191 .Fl s No @ Ns Ar setname
4192 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4193 .Ar setname Oc Ns ... Oc
4194 .Ar filesystem Ns | Ns Ar volume
4196 Removes permissions from a permission set.
4197 If no permissions are specified, then all permissions are removed, thus removing
4203 .Ar tag Ar snapshot Ns ...
4205 Adds a single reference, named with the
4207 argument, to the specified snapshot or snapshots.
4208 Each snapshot has its own tag namespace, and tags must be unique within that
4211 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4215 .Bl -tag -width "-r"
4217 Specifies that a hold with the given tag is applied recursively to the snapshots
4218 of all descendent file systems.
4226 Lists all existing user references for the given snapshot or snapshots.
4227 .Bl -tag -width "-r"
4229 Lists the holds that are set on the named descendent snapshots, in addition to
4230 listing the holds on the named snapshot.
4236 .Ar tag Ar snapshot Ns ...
4238 Removes a single reference, named with the
4240 argument, from the specified snapshot or snapshots.
4241 The tag must already exist for each snapshot.
4242 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4246 .Bl -tag -width "-r"
4248 Recursively releases a hold with the given tag on the snapshots of all
4249 descendent file systems.
4255 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4257 Display the difference between a snapshot of a given filesystem and another
4258 snapshot of that filesystem from a later time or the current contents of the
4260 The first column is a character indicating the type of change, the other columns
4261 indicate pathname, new pathname
4262 .Pq in case of rename ,
4263 change in link count, and optionally file type and/or change time.
4264 The types of change are:
4266 - The path has been removed
4267 + The path has been created
4268 M The path has been modified
4269 R The path has been renamed
4271 .Bl -tag -width "-F"
4273 Display an indication of the type of file, in a manner similar to the
4289 Give more parsable tab-separated output, without header lines and without
4292 Display the path's inode change time as the first column of output.
4299 .Op Fl m Ar memory_limit
4305 as a ZFS channel program on
4308 program interface allows ZFS administrative operations to be run
4309 programmatically via a Lua script.
4310 The entire script is executed atomically, with no other administrative
4311 operations taking effect concurrently.
4312 A library of ZFS calls is made available to channel program scripts.
4313 Channel programs may only be run with root privileges.
4315 For full documentation of the ZFS channel program interface, see the manual
4320 Display channel program output in JSON format. When this flag is specified and
4321 standard output is empty - channel program encountered an error. The details of
4322 such an error will be printed to standard error in plain text.
4324 Executes a read-only channel program, which runs faster.
4325 The program cannot change on-disk state by calling functions from
4326 the zfs.sync submodule.
4327 The program can be used to gather information such as properties and
4328 determining if changes would succeed (zfs.check.*).
4329 Without this flag, all pending changes must be synced to disk before
4330 a channel program can complete.
4332 Execution time limit, in milliseconds.
4333 If a channel program executes for longer than the provided timeout, it will
4334 be stopped and an error will be returned.
4335 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
4336 .It Fl m Ar memory-limit
4337 Memory limit, in bytes.
4338 If a channel program attempts to allocate more memory than the given limit,
4339 it will be stopped and an error returned.
4340 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4342 All remaining argument strings are passed directly to the channel program as
4346 for more information.
4352 .Op Fl L Ar keylocation
4353 .Fl a | Ar filesystem
4357 allowing it and all children that inherit the
4359 property to be accessed. The key will be expected in the format specified by the
4361 and location specified by the
4363 property. Note that if the
4367 the terminal will interactively wait for the key to be entered. Loading a key
4368 will not automatically mount the dataset. If that functionality is desired,
4369 .Nm zfs Cm mount Sy -l
4370 will ask for the key and mount the dataset. Once the key is loaded the
4372 property will become
4374 .Bl -tag -width "-r"
4376 Recursively loads the keys for the specified filesystem and all descendent
4379 Loads the keys for all encryption roots in all imported pools.
4383 load-key. This will cause zfs to simply check that the
4384 provided key is correct. This command may be run even if the key is already
4386 .It Fl L Ar keylocation
4391 property. This will not change the value of the property on the dataset. Note
4392 that if used with either
4397 may only be given as
4404 .Fl a | Ar filesystem
4406 Unloads a key from ZFS, removing the ability to access the dataset and all of
4407 its children that inherit the
4409 property. This requires that the dataset is not currently open or mounted. Once
4410 the key is unloaded the
4412 property will become
4414 .Bl -tag -width "-r"
4416 Recursively unloads the keys for the specified filesystem and all descendent
4419 Unloads the keys for all encryption roots in all imported pools.
4425 .Op Fl o Ar keylocation Ns = Ns Ar value
4426 .Op Fl o Ar keyformat Ns = Ns Ar value
4427 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4437 Allows a user to change the encryption key used to access a dataset. This
4438 command requires that the existing key for the dataset is already loaded into
4439 ZFS. This command may also be used to change the
4444 properties as needed. If the dataset was not previously an encryption root it
4445 will become one. Alternatively, the
4447 flag may be provided to cause an encryption root to inherit the parent's key
4449 .Bl -tag -width "-r"
4451 Ensures the key is loaded before attempting to change the key. This is
4452 effectively equivalent to
4453 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4454 .It Fl o Ar property Ns = Ns Ar value
4455 Allows the user to set encryption key properties (
4460 ) while changing the key. This is the only way to alter
4464 after the dataset has been created.
4466 Indicates that zfs should make
4468 inherit the key of its parent. Note that this command can only be run on an
4469 encryption root that has an encrypted parent.
4475 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4476 options were specified.
4479 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4480 The following commands create a file system named
4482 and a file system named
4486 is set for the parent file system, and is automatically inherited by the child
4489 # zfs create pool/home
4490 # zfs set mountpoint=/export/home pool/home
4491 # zfs create pool/home/bob
4493 .It Sy Example 2 No Creating a ZFS Snapshot
4494 The following command creates a snapshot named
4496 This snapshot is mounted on demand in the
4498 directory at the root of the
4502 # zfs snapshot pool/home/bob@yesterday
4504 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4505 The following command creates snapshots named
4509 and all of its descendent file systems.
4510 Each snapshot is mounted on demand in the
4512 directory at the root of its file system.
4513 The second command destroys the newly created snapshots.
4515 # zfs snapshot -r pool/home@yesterday
4516 # zfs destroy -r pool/home@yesterday
4518 .It Sy Example 4 No Disabling and Enabling File System Compression
4519 The following command disables the
4521 property for all file systems under
4523 The next command explicitly enables
4526 .Em pool/home/anne .
4528 # zfs set compression=off pool/home
4529 # zfs set compression=on pool/home/anne
4531 .It Sy Example 5 No Listing ZFS Datasets
4532 The following command lists all active file systems and volumes in the system.
4533 Snapshots are displayed if the
4541 for more information on pool properties.
4544 NAME USED AVAIL REFER MOUNTPOINT
4545 pool 450K 457G 18K /pool
4546 pool/home 315K 457G 21K /export/home
4547 pool/home/anne 18K 457G 18K /export/home/anne
4548 pool/home/bob 276K 457G 276K /export/home/bob
4550 .It Sy Example 6 No Setting a Quota on a ZFS File System
4551 The following command sets a quota of 50 Gbytes for
4554 # zfs set quota=50G pool/home/bob
4556 .It Sy Example 7 No Listing ZFS Properties
4557 The following command lists all properties for
4560 # zfs get all pool/home/bob
4561 NAME PROPERTY VALUE SOURCE
4562 pool/home/bob type filesystem -
4563 pool/home/bob creation Tue Jul 21 15:53 2009 -
4564 pool/home/bob used 21K -
4565 pool/home/bob available 20.0G -
4566 pool/home/bob referenced 21K -
4567 pool/home/bob compressratio 1.00x -
4568 pool/home/bob mounted yes -
4569 pool/home/bob quota 20G local
4570 pool/home/bob reservation none default
4571 pool/home/bob recordsize 128K default
4572 pool/home/bob mountpoint /pool/home/bob default
4573 pool/home/bob sharenfs off default
4574 pool/home/bob checksum on default
4575 pool/home/bob compression on local
4576 pool/home/bob atime on default
4577 pool/home/bob devices on default
4578 pool/home/bob exec on default
4579 pool/home/bob setuid on default
4580 pool/home/bob readonly off default
4581 pool/home/bob zoned off default
4582 pool/home/bob snapdir hidden default
4583 pool/home/bob acltype off default
4584 pool/home/bob aclinherit restricted default
4585 pool/home/bob canmount on default
4586 pool/home/bob xattr on default
4587 pool/home/bob copies 1 default
4588 pool/home/bob version 4 -
4589 pool/home/bob utf8only off -
4590 pool/home/bob normalization none -
4591 pool/home/bob casesensitivity sensitive -
4592 pool/home/bob vscan off default
4593 pool/home/bob nbmand off default
4594 pool/home/bob sharesmb off default
4595 pool/home/bob refquota none default
4596 pool/home/bob refreservation none default
4597 pool/home/bob primarycache all default
4598 pool/home/bob secondarycache all default
4599 pool/home/bob usedbysnapshots 0 -
4600 pool/home/bob usedbydataset 21K -
4601 pool/home/bob usedbychildren 0 -
4602 pool/home/bob usedbyrefreservation 0 -
4605 The following command gets a single property value.
4607 # zfs get -H -o value compression pool/home/bob
4610 The following command lists all properties with local settings for
4613 # zfs get -r -s local -o name,property,value all pool/home/bob
4615 pool/home/bob quota 20G
4616 pool/home/bob compression on
4618 .It Sy Example 8 No Rolling Back a ZFS File System
4619 The following command reverts the contents of
4621 to the snapshot named
4623 deleting all intermediate snapshots.
4625 # zfs rollback -r pool/home/anne@yesterday
4627 .It Sy Example 9 No Creating a ZFS Clone
4628 The following command creates a writable file system whose initial contents are
4630 .Em pool/home/bob@yesterday .
4632 # zfs clone pool/home/bob@yesterday pool/clone
4634 .It Sy Example 10 No Promoting a ZFS Clone
4635 The following commands illustrate how to test out changes to a file system, and
4636 then replace the original file system with the changed one, using clones, clone
4637 promotion, and renaming:
4639 # zfs create pool/project/production
4640 populate /pool/project/production with data
4641 # zfs snapshot pool/project/production@today
4642 # zfs clone pool/project/production@today pool/project/beta
4643 make changes to /pool/project/beta and test them
4644 # zfs promote pool/project/beta
4645 # zfs rename pool/project/production pool/project/legacy
4646 # zfs rename pool/project/beta pool/project/production
4647 once the legacy version is no longer needed, it can be destroyed
4648 # zfs destroy pool/project/legacy
4650 .It Sy Example 11 No Inheriting ZFS Properties
4651 The following command causes
4657 property from their parent.
4659 # zfs inherit checksum pool/home/bob pool/home/anne
4661 .It Sy Example 12 No Remotely Replicating ZFS Data
4662 The following commands send a full stream and then an incremental stream to a
4663 remote machine, restoring them into
4664 .Em poolB/received/fs@a
4666 .Em poolB/received/fs@b ,
4669 must contain the file system
4670 .Em poolB/received ,
4671 and must not initially contain
4672 .Em poolB/received/fs .
4674 # zfs send pool/fs@a | \e
4675 ssh host zfs receive poolB/received/fs@a
4676 # zfs send -i a pool/fs@b | \e
4677 ssh host zfs receive poolB/received/fs
4679 .It Sy Example 13 No Using the zfs receive -d Option
4680 The following command sends a full stream of
4681 .Em poolA/fsA/fsB@snap
4682 to a remote machine, receiving it into
4683 .Em poolB/received/fsA/fsB@snap .
4686 portion of the received snapshot's name is determined from the name of the sent
4689 must contain the file system
4690 .Em poolB/received .
4692 .Em poolB/received/fsA
4693 does not exist, it is created as an empty file system.
4695 # zfs send poolA/fsA/fsB@snap | \e
4696 ssh host zfs receive -d poolB/received
4698 .It Sy Example 14 No Setting User Properties
4699 The following example sets the user-defined
4700 .Sy com.example:department
4701 property for a dataset.
4703 # zfs set com.example:department=12345 tank/accounting
4705 .It Sy Example 15 No Performing a Rolling Snapshot
4706 The following example shows how to maintain a history of snapshots with a
4707 consistent naming scheme.
4708 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4709 renames the remaining snapshots, and then creates a new snapshot, as follows:
4711 # zfs destroy -r pool/users@7daysago
4712 # zfs rename -r pool/users@6daysago @7daysago
4713 # zfs rename -r pool/users@5daysago @6daysago
4714 # zfs rename -r pool/users@yesterday @5daysago
4715 # zfs rename -r pool/users@yesterday @4daysago
4716 # zfs rename -r pool/users@yesterday @3daysago
4717 # zfs rename -r pool/users@yesterday @2daysago
4718 # zfs rename -r pool/users@today @yesterday
4719 # zfs snapshot -r pool/users@today
4721 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4722 The following commands show how to set
4724 property options to enable
4728 addresses and to enable root access for system
4734 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4739 for host name resolution, specify the fully qualified hostname.
4740 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4741 The following example shows how to set permissions so that user
4743 can create, destroy, mount, and take snapshots on
4749 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4750 # zfs allow tank/cindys
4751 ---- Permissions on tank/cindys --------------------------------------
4752 Local+Descendent permissions:
4753 user cindys create,destroy,mount,snapshot
4758 mount point permission is set to 755 by default, user
4760 will be unable to mount file systems under
4762 Add an ACE similar to the following syntax to provide mount point access:
4764 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4766 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4767 The following example shows how to grant anyone in the group
4769 to create file systems in
4771 This syntax also allows staff members to destroy their own file systems, but not
4772 destroy anyone else's file system.
4777 # zfs allow staff create,mount tank/users
4778 # zfs allow -c destroy tank/users
4779 # zfs allow tank/users
4780 ---- Permissions on tank/users ---------------------------------------
4783 Local+Descendent permissions:
4784 group staff create,mount
4786 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4787 The following example shows how to define and grant a permission set on the
4794 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4795 # zfs allow staff @pset tank/users
4796 # zfs allow tank/users
4797 ---- Permissions on tank/users ---------------------------------------
4799 @pset create,destroy,mount,snapshot
4800 Local+Descendent permissions:
4803 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4804 The following example shows to grant the ability to set quotas and reservations
4812 # zfs allow cindys quota,reservation users/home
4813 # zfs allow users/home
4814 ---- Permissions on users/home ---------------------------------------
4815 Local+Descendent permissions:
4816 user cindys quota,reservation
4817 cindys% zfs set quota=10G users/home/marks
4818 cindys% zfs get quota users/home/marks
4819 NAME PROPERTY VALUE SOURCE
4820 users/home/marks quota 10G local
4822 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4823 The following example shows how to remove the snapshot permission from the
4832 # zfs unallow staff snapshot tank/users
4833 # zfs allow tank/users
4834 ---- Permissions on tank/users ---------------------------------------
4836 @pset create,destroy,mount,snapshot
4837 Local+Descendent permissions:
4840 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4841 The following example shows how to see what has changed between a prior
4842 snapshot of a ZFS dataset and its current state.
4845 option is used to indicate type information for the files affected.
4847 # zfs diff -F tank/test@before tank/test
4849 M F /tank/test/linked (+1)
4850 R F /tank/test/oldname -> /tank/test/newname
4851 - F /tank/test/deleted
4852 + F /tank/test/created
4853 M F /tank/test/modified
4855 .It Sy Example 23 No Creating a bookmark
4856 The following example create a bookmark to a snapshot. This bookmark
4857 can then be used instead of snapshot in send streams.
4859 # zfs bookmark rpool@snapshot rpool#bookmark
4861 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4862 The following example show how to share SMB filesystem through ZFS. Note that
4863 that a user and his/her password must be given.
4865 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4866 -o user=workgroup/turbo,password=obrut,uid=1000
4870 .Em /etc/samba/smb.conf
4871 configuration required:
4873 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4874 communicate with Samba. This is the default behavior for most Linux
4877 Samba must be able to authenticate a user. This can be done in a number of
4878 ways, depending on if using the system password file, LDAP or the Samba
4879 specific smbpasswd file. How to do this is outside the scope of this manual.
4882 man page for more information.
4885 .Sy USERSHARE section
4888 man page for all configuration options in case you need to modify any options
4889 to the share afterwards. Do note that any changes done with the
4891 command will be undone if the share is ever unshared (such as at a reboot etc).
4893 .Sh INTERFACE STABILITY
projects / mirror_zfs.git / blob