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.
31 .\" Copyright 2018 Joyent, Inc.
38 .Nd configures ZFS file systems
45 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
52 .Fl V Ar size Ar volume
56 .Ar filesystem Ns | Ns Ar volume
60 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
61 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
64 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
68 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
69 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
77 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
78 .Ar snapshot Ar filesystem Ns | Ns Ar volume
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
86 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
90 .Ar filesystem Ns | Ns Ar volume
91 .Ar filesystem Ns | Ns Ar volume
95 .Ar snapshot Ar snapshot
98 .Op Fl r Ns | Ns Fl d Ar depth
100 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
101 .Oo Fl s Ar property Oc Ns ...
102 .Oo Fl S Ar property Oc Ns ...
103 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
104 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
107 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
108 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
111 .Op Fl r Ns | Ns Fl d Ar depth
113 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
114 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
115 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
116 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
117 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
121 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
131 .Fl a | Ar filesystem
135 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
136 .Oo Fl s Ar field Oc Ns ...
137 .Oo Fl S Ar field Oc Ns ...
138 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
139 .Ar filesystem Ns | Ns Ar snapshot
143 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
144 .Oo Fl s Ar field Oc Ns ...
145 .Oo Fl S Ar field Oc Ns ...
146 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
147 .Ar filesystem Ns | Ns Ar snapshot
151 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
152 .Oo Fl s Ar field Oc Ns ...
153 .Oo Fl S Ar field Oc Ns ...
154 .Ar filesystem Ns | Ns Ar snapshot
157 .Oo Fl d Ns | Ns Fl r Ns Oc
158 .Ar file Ns | Ns Ar directory Ns ...
163 .Ar file Ns | Ns Ar directory Ns ...
168 .Oo Fl d Ns | Ns Fl r Ns Oc
170 .Ar file Ns | Ns Ar directory Ns ...
175 .Ar file Ns | Ns Ar directory Ns ...
182 .Fl a | Ar filesystem
186 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
189 .Fl a | Ar filesystem
192 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
195 .Ar snapshot bookmark
199 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
204 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
205 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
209 .Fl t Ar receive_resume_token
213 .Op Fl o Sy origin Ns = Ns Ar snapshot
214 .Op Fl o Ar property Ns = Ns Ar value
216 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
220 .Op Fl d Ns | Ns Fl e
221 .Op Fl o Sy origin Ns = Ns Ar snapshot
222 .Op Fl o Ar property Ns = Ns Ar value
228 .Ar filesystem Ns | Ns Ar volume
231 .Ar filesystem Ns | Ns Ar volume
235 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
236 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
237 .Ar setname Oc Ns ...
238 .Ar filesystem Ns | Ns Ar volume
242 .Fl e Ns | Ns Sy everyone
243 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
244 .Ar setname Oc Ns ...
245 .Ar filesystem Ns | Ns Ar volume
249 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
250 .Ar setname Oc Ns ...
251 .Ar filesystem Ns | Ns Ar volume
254 .Fl s No @ Ns Ar setname
255 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
256 .Ar setname Oc Ns ...
257 .Ar filesystem Ns | Ns Ar volume
261 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
262 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
263 .Ar setname Oc Ns ... Oc
264 .Ar filesystem Ns | Ns Ar volume
268 .Fl e Ns | Ns Sy everyone
269 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
270 .Ar setname Oc Ns ... Oc
271 .Ar filesystem Ns | Ns Ar volume
276 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
277 .Ar setname Oc Ns ... Oc
278 .Ar filesystem Ns | Ns Ar volume
282 .Fl s @ Ns Ar setname
283 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
284 .Ar setname Oc Ns ... Oc
285 .Ar filesystem Ns | Ns Ar volume
289 .Ar tag Ar snapshot Ns ...
297 .Ar tag Ar snapshot Ns ...
301 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
306 .Op Fl m Ar memory_limit
312 .Op Fl L Ar keylocation
313 .Fl a | Ar filesystem
317 .Fl a | Ar filesystem
321 .Op Fl o Ar keylocation Ns = Ns Ar value
322 .Op Fl o Ar keyformat Ns = Ns Ar value
323 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
333 command configures ZFS datasets within a ZFS storage pool, as described in
335 A dataset is identified by a unique path within the ZFS namespace.
338 pool/{filesystem,volume,snapshot}
341 where the maximum length of a dataset name is
345 A dataset can be one of the following:
346 .Bl -tag -width "file system"
348 A ZFS dataset of type
350 can be mounted within the standard system namespace and behaves like other file
352 While ZFS file systems are designed to be POSIX compliant, known issues exist
353 that prevent compliance in some cases.
354 Applications that depend on standards conformance might fail due to non-standard
355 behavior when checking file system free space.
357 A logical volume exported as a raw or block device.
358 This type of dataset should only be used under special circumstances.
359 File systems are typically used in most environments.
361 A read-only version of a file system or volume at a given point in time.
363 .Ar filesystem Ns @ Ns Ar name
365 .Ar volume Ns @ Ns Ar name .
369 but without the hold on on-disk data. It can be used as the source of a send
370 (but not for a receive). It is specified as
371 .Ar filesystem Ns # Ns Ar name
373 .Ar volume Ns # Ns Ar name .
375 .Ss ZFS File System Hierarchy
376 A ZFS storage pool is a logical collection of devices that provide space for
378 A storage pool is also the root of the ZFS file system hierarchy.
380 The root of the pool can be accessed as a file system, such as mounting and
381 unmounting, taking snapshots, and setting properties.
382 The physical storage characteristics, however, are managed by the
388 for more information on creating and administering pools.
390 A snapshot is a read-only copy of a file system or volume.
391 Snapshots can be created extremely quickly, and initially consume no additional
392 space within the pool.
393 As data within the active dataset changes, the snapshot consumes more data than
394 would otherwise be shared with the active dataset.
396 Snapshots can have arbitrary names.
397 Snapshots of volumes can be cloned or rolled back, visibility is determined
400 property of the parent volume.
402 File system snapshots can be accessed under the
404 directory in the root of the file system.
405 Snapshots are automatically mounted on demand and may be unmounted at regular
407 The visibility of the
409 directory can be controlled by the
413 A bookmark is like a snapshot, a read-only copy of a file system or volume.
414 Bookmarks can be created extremely quickly, compared to snapshots, and they
415 consume no additional space within the pool. Bookmarks can also have arbitrary
416 names, much like snapshots.
418 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
419 way. From a storage standpoint a bookmark just provides a way to reference
420 when a snapshot was created as a distinct object. Bookmarks are initially
421 tied to a snapshot, not the filesystem or volume, and they will survive if the
422 snapshot itself is destroyed. Since they are very light weight there's little
423 incentive to destroy them.
425 A clone is a writable volume or file system whose initial contents are the same
427 As with snapshots, creating a clone is nearly instantaneous, and initially
428 consumes no additional space.
430 Clones can only be created from a snapshot.
431 When a snapshot is cloned, it creates an implicit dependency between the parent
433 Even though the clone is created somewhere else in the dataset hierarchy, the
434 original snapshot cannot be destroyed as long as a clone exists.
437 property exposes this dependency, and the
439 command lists any such dependencies, if they exist.
441 The clone parent-child dependency relationship can be reversed by using the
446 file system to become a clone of the specified file system, which makes it
447 possible to destroy the file system that the clone was created from.
449 Creating a ZFS file system is a simple operation, so the number of file systems
450 per system is likely to be numerous.
451 To cope with this, ZFS automatically manages mounting and unmounting file
452 systems without the need to edit the
455 All automatically managed file systems are mounted by ZFS at boot time.
457 By default, file systems are mounted under
461 is the name of the file system in the ZFS namespace.
462 Directories are created and destroyed as needed.
464 A file system can also have a mount point set in the
467 This directory is created as needed, and ZFS automatically mounts the file
469 .Nm zfs Cm mount Fl a
476 property can be inherited, so if
482 automatically inherits a mount point of
483 .Pa /export/stuff/user .
489 prevents the file system from being mounted.
491 If needed, ZFS file systems can also be managed with traditional tools
497 If a file system's mount point is set to
499 ZFS makes no attempt to manage the file system, and the administrator is
500 responsible for mounting and unmounting the file system. Because pools must
501 be imported before a legacy mount can succeed, administrators should ensure
502 that legacy mounts are only attempted after the zpool import process
503 finishes at boot time. For example, on machines using systemd, the mount
506 .Nm x-systemd.requires=zfs-import.target
508 will ensure that the zfs-import completes before systemd attempts mounting
509 the filesystem. See systemd.mount(5) for details.
511 Deduplication is the process for removing redundant data at the block level,
512 reducing the total amount of data stored. If a file system has the
514 property enabled, duplicate data blocks are removed synchronously. The result
515 is that only unique data is stored and common components are shared among files.
517 Deduplicating data is a very resource-intensive operation. It is generally
518 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
519 you enable deduplication. Calculating the exact requirement depends heavily
520 on the type of data stored in the pool.
522 Enabling deduplication on an improperly-designed system can result in
523 performance issues (slow IO and administrative operations). It can potentially
524 lead to problems importing a pool due to memory exhaustion. Deduplication
525 can consume significant processing power (CPU) and memory as well as generate
528 Before creating a pool with deduplication enabled, ensure that you have planned
529 your hardware requirements appropriately and implemented appropriate recovery
530 practices, such as regular backups. As an alternative to deduplication
533 as a less resource-intensive alternative.
534 .Ss Native Properties
535 Properties are divided into two types, native properties and user-defined
540 Native properties either export internal statistics or control ZFS behavior.
541 In addition, native properties are either editable or read-only.
542 User properties have no effect on ZFS behavior, but you can use them to annotate
543 datasets in a way that is meaningful in your environment.
544 For more information about user properties, see the
548 Every dataset has a set of properties that export statistics about the dataset
549 as well as control various behaviors.
550 Properties are inherited from the parent unless overridden by the child.
551 Some properties apply only to certain types of datasets
552 .Pq file systems, volumes, or snapshots .
554 The values of numeric properties can be specified using human-readable suffixes
564 The following are all valid
567 .Li 1536M, 1.5g, 1.50GB .
569 The values of non-numeric properties are case sensitive and must be lowercase,
576 The following native properties consist of read-only statistics about the
578 These properties can be neither set, nor inherited.
579 Native properties apply to all dataset types unless otherwise noted.
580 .Bl -tag -width "usedbyrefreservation"
582 The amount of space available to the dataset and all its children, assuming that
583 there is no other activity in the pool.
584 Because space is shared within a pool, availability can be limited by any number
585 of factors, including physical pool size, quotas, reservations, or other
586 datasets within the pool.
588 This property can also be referred to by its shortened column name,
591 For non-snapshots, the compression ratio achieved for the
593 space of this dataset, expressed as a multiplier.
596 property includes descendant datasets, and, for clones, does not include the
597 space shared with the origin snapshot.
603 Compression can be turned on by running:
604 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
608 The transaction group (txg) in which the dataset was created. Bookmarks have
611 as the snapshot they are initially tied to. This property is suitable for
612 ordering a list of snapshots, e.g. for incremental send and receive.
614 The time this dataset was created.
616 For snapshots, this property is a comma-separated list of filesystems or volumes
617 which are clones of this snapshot.
620 property is this snapshot.
623 property is not empty, then this snapshot can not be destroyed
630 The roles of origin and clone can be swapped by promoting the clone with the
636 if the snapshot has been marked for deferred destroy by using the
637 .Nm zfs Cm destroy Fl d
639 Otherwise, the property is
641 .It Sy encryptionroot
642 For encrypted datasets, indicates where the dataset is currently inheriting its
643 encryption key from. Loading or unloading a key for the
645 will implicitly load / unload the key for any inheriting datasets (see
648 .Nm zfs Cm unload-key
650 Clones will always share an
651 encryption key with their origin. See the
654 .It Sy filesystem_count
655 The total number of filesystems and volumes that exist under this location in
657 This value is only available when a
659 has been set somewhere in the tree under which the dataset resides.
661 Indicates if an encryption key is currently loaded into ZFS. The possible
670 .Nm zfs Cm unload-key .
672 The 64 bit GUID of this dataset or bookmark which does not change over its
673 entire lifetime. When a snapshot is sent to another pool, the received
674 snapshot has the same GUID. Thus, the
676 is suitable to identify a snapshot across pools.
677 .It Sy logicalreferenced
678 The amount of space that is
680 accessible by this dataset.
684 The logical space ignores the effect of the
688 properties, giving a quantity closer to the amount of data that applications
690 However, it does include space consumed by metadata.
692 This property can also be referred to by its shortened column name,
695 The amount of space that is
697 consumed by this dataset and all its descendents.
701 The logical space ignores the effect of the
705 properties, giving a quantity closer to the amount of data that applications
707 However, it does include space consumed by metadata.
709 This property can also be referred to by its shortened column name,
712 For file systems, indicates whether the file system is currently mounted.
713 This property can be either
718 For cloned file systems or volumes, the snapshot from which the clone was
723 .It Sy receive_resume_token
724 For filesystems or volumes which have saved partially-completed state from
726 this opaque token can be provided to
728 to resume and complete the
731 The amount of data that is accessible by this dataset, which may or may not be
732 shared with other datasets in the pool.
733 When a snapshot or clone is created, it initially references the same amount of
734 space as the file system or snapshot it was created from, since its contents are
737 This property can also be referred to by its shortened column name,
739 .It Sy refcompressratio
740 The compression ratio achieved for the
742 space of this dataset, expressed as a multiplier.
746 .It Sy snapshot_count
747 The total number of snapshots that exist under this location in the dataset
749 This value is only available when a
751 has been set somewhere in the tree under which the dataset resides.
759 The amount of space consumed by this dataset and all its descendents.
760 This is the value that is checked against this dataset's quota and reservation.
761 The space used does not include this dataset's reservation, but does take into
762 account the reservations of any descendent datasets.
763 The amount of space that a dataset consumes from its parent, as well as the
764 amount of space that is freed if this dataset is recursively destroyed, is the
765 greater of its space used and its reservation.
767 The used space of a snapshot
772 is space that is referenced exclusively by this snapshot.
773 If this snapshot is destroyed, the amount of
776 Space that is shared by multiple snapshots isn't accounted for in this metric.
777 When a snapshot is destroyed, space that was previously shared with this
778 snapshot can become unique to snapshots adjacent to it, thus changing the used
779 space of those snapshots.
780 The used space of the latest snapshot can also be affected by changes in the
784 space of a snapshot is a subset of the
786 space of the snapshot.
788 The amount of space used, available, or referenced does not take into account
790 Pending changes are generally accounted for within a few seconds.
791 Committing a change to a disk using
795 does not necessarily guarantee that the space usage information is updated
800 properties decompose the
802 properties into the various reasons that space is used.
805 .Sy usedbychildren No +
806 .Sy usedbydataset No +
807 .Sy usedbyrefreservation No +
808 .Sy usedbysnapshots .
809 These properties are only available for datasets created on
813 .It Sy usedbychildren
814 The amount of space used by children of this dataset, which would be freed if
815 all the dataset's children were destroyed.
817 The amount of space used by this dataset itself, which would be freed if the
818 dataset were destroyed
819 .Po after first removing any
821 and destroying any necessary snapshots or descendents
823 .It Sy usedbyrefreservation
824 The amount of space used by a
826 set on this dataset, which would be freed if the
829 .It Sy usedbysnapshots
830 The amount of space consumed by snapshots of this dataset.
831 In particular, it is the amount of space that would be freed if all of this
832 dataset's snapshots were destroyed.
833 Note that this is not simply the sum of the snapshots'
835 properties because space can be shared by multiple snapshots.
836 .It Sy userused Ns @ Ns Em user
837 The amount of space consumed by the specified user in this dataset.
838 Space is charged to the owner of each file, as displayed by
840 The amount of space charged is displayed by
846 subcommand for more information.
848 Unprivileged users can access only their own space usage.
849 The root user, or a user who has been granted the
853 can access everyone's usage.
856 .Sy userused Ns @ Ns Em ...
857 properties are not displayed by
858 .Nm zfs Cm get Sy all .
859 The user's name must be appended after the @ symbol, using one of the following
861 .Bl -bullet -width ""
875 .Sy joe.smith@mydomain
884 Files created on Linux always have POSIX owners.
885 .It Sy userobjused Ns @ Ns Em user
888 property is similar to
890 but instead it counts the number of objects consumed by a user. This property
891 counts all objects allocated on behalf of the user, it may differ from the
892 results of system tools such as
897 is set on a file system additional objects will be created per-file to store
898 extended attributes. These additional objects are reflected in the
900 value and are counted against the user's
902 When a file system is configured to use
904 no additional internal objects are normally required.
906 This property is set to the number of user holds on this snapshot.
907 User holds are set by using the
910 .It Sy groupused Ns @ Ns Em group
911 The amount of space consumed by the specified group in this dataset.
912 Space is charged to the group of each file, as displayed by
915 .Sy userused Ns @ Ns Em user
916 property for more information.
918 Unprivileged users can only access their own groups' space usage.
919 The root user, or a user who has been granted the
923 can access all groups' usage.
924 .It Sy groupobjused Ns @ Ns Em group
925 The number of objects consumed by the specified group in this dataset.
926 Multiple objects may be charged to the group for each file when extended
927 attributes are in use. See the
928 .Sy userobjused Ns @ Ns Em user
929 property for more information.
931 Unprivileged users can only access their own groups' space usage.
932 The root user, or a user who has been granted the
936 can access all groups' usage.
937 .It Sy projectused Ns @ Ns Em project
938 The amount of space consumed by the specified project in this dataset. Project
939 is identified via the project identifier (ID) that is object-based numeral
940 attribute. An object can inherit the project ID from its parent object (if the
941 parent has the flag of inherit project ID that can be set and changed via
944 .Nm zfs project Fl s )
945 when being created. The privileged user can set and change object's project
950 anytime. Space is charged to the project of each file, as displayed by
955 .Sy userused Ns @ Ns Em user
956 property for more information.
958 The root user, or a user who has been granted the
962 can access all projects' usage.
963 .It Sy projectobjused Ns @ Ns Em project
968 but instead it counts the number of objects consumed by project. When the
971 is set on a fileset, ZFS will create additional objects per-file to store
972 extended attributes. These additional objects are reflected in the
974 value and are counted against the project's
975 .Sy projectobjquota .
976 When a filesystem is configured to use
978 no additional internal objects are required. See the
979 .Sy userobjused Ns @ Ns Em user
980 property for more information.
982 The root user, or a user who has been granted the
986 can access all projects' objects usage.
988 For volumes, specifies the block size of the volume.
991 cannot be changed once the volume has been written, so it should be set at
992 volume creation time.
995 for volumes is 8 Kbytes.
996 Any power of 2 from 512 bytes to 128 Kbytes is valid.
998 This property can also be referred to by its shortened column name,
1003 by this dataset, that was written since the previous snapshot
1004 .Pq i.e. that is not referenced by the previous snapshot .
1005 .It Sy written Ns @ Ns Em snapshot
1008 space written to this dataset since the specified snapshot.
1009 This is the space that is referenced by this dataset but was not referenced by
1010 the specified snapshot.
1014 may be specified as a short snapshot name
1015 .Po just the part after the
1018 in which case it will be interpreted as a snapshot in the same filesystem as
1022 may be a full snapshot name
1023 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
1024 which for clones may be a snapshot in the origin's filesystem
1025 .Pq or the origin of the origin's filesystem, etc.
1028 The following native properties can be used to change the behavior of a ZFS
1032 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
1033 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
1035 Controls how ACEs are inherited when files and directories are created.
1036 .Bl -tag -width "passthrough-x"
1038 does not inherit any ACEs.
1040 only inherits inheritable ACEs that specify
1044 default, removes the
1048 permissions when the ACE is inherited.
1050 inherits all inheritable ACEs without any modifications.
1051 .It Sy passthrough-x
1059 ACEs inherit the execute permission only if the file creation mode also requests
1063 When the property value is set to
1065 files are created with a mode determined by the inheritable ACEs.
1066 If no inheritable ACEs exist that affect the mode, then the mode is set in
1067 accordance to the requested mode from the application.
1071 property does not apply to posix ACLs.
1072 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
1073 Controls whether ACLs are enabled and if so what type of ACL to use.
1074 .Bl -tag -width "posixacl"
1076 default, when a file system has the
1078 property set to off then ACLs are disabled.
1083 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
1084 not functional on other platforms. Posix ACLs are stored as an extended
1085 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1089 To obtain the best performance when setting
1091 users are strongly encouraged to set the
1093 property. This will result in the posix ACL being stored more efficiently on
1094 disk. But as a consequence of this all new extended attributes will only be
1095 accessible from OpenZFS implementations which support the
1099 property for more details.
1100 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1101 Controls whether the access time for files is updated when they are read.
1102 Turning this property off avoids producing write traffic when reading files and
1103 can result in significant performance gains, though it might confuse mailers
1104 and other similar utilities. The values
1108 are equivalent to the
1112 mount options. The default value is
1117 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1118 If this property is set to
1120 the file system cannot be mounted, and is ignored by
1121 .Nm zfs Cm mount Fl a .
1122 Setting this property to
1124 is similar to setting the
1128 except that the dataset still has a normal
1130 property, which can be inherited.
1131 Setting this property to
1133 allows datasets to be used solely as a mechanism to inherit properties.
1134 One example of setting
1135 .Sy canmount Ns = Ns Sy off
1136 is to have two datasets with the same
1138 so that the children of both datasets appear in the same directory, but might
1139 have different inherited characteristics.
1143 a dataset can only be mounted and unmounted explicitly.
1144 The dataset is not mounted automatically when the dataset is created or
1145 imported, nor is it mounted by the
1146 .Nm zfs Cm mount Fl a
1147 command or unmounted by the
1148 .Nm zfs Cm unmount Fl a
1151 This property is not inherited.
1153 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1154 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1155 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1157 Controls the checksum used to verify data integrity.
1158 The default value is
1160 which automatically selects an appropriate algorithm
1163 but this may change in future releases
1167 disables integrity checking on user data.
1170 not only disables integrity but also disables maintaining parity for user data.
1171 This setting is used internally by a dump device residing on a RAID-Z pool and
1172 should not be used by any other dataset.
1173 Disabling checksums is
1175 a recommended practice.
1182 checksum algorithms require enabling the appropriate features on the pool.
1184 .Xr zpool-features 5
1185 for more information on these algorithms.
1187 Changing this property affects only newly-written data.
1189 Salted checksum algorithms
1190 .Pq Cm edonr , skein
1191 are currently not supported for any filesystem on the boot pools.
1193 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1194 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1196 Controls the compression algorithm used for this dataset.
1198 Setting compression to
1200 indicates that the current default compression algorithm should be used.
1201 The default balances compression and decompression speed, with compression ratio
1202 and is expected to work well on a wide variety of workloads.
1203 Unlike all other settings for this property,
1205 does not select a fixed compression type.
1206 As new compression algorithms are added to ZFS and enabled on a pool, the
1207 default compression algorithm may change.
1208 The current default compression algorithm is either
1217 compression algorithm is a high-performance replacement for the
1220 It features significantly faster compression and decompression, as well as a
1221 moderately higher compression ratio than
1223 but can only be used on pools with the
1228 .Xr zpool-features 5
1229 for details on ZFS feature flags and the
1235 compression algorithm is optimized for performance while providing decent data
1240 compression algorithm uses the same compression as the
1245 level by using the value
1249 is an integer from 1
1252 .Pq best compression ratio .
1257 .Po which is also the default for
1263 compression algorithm compresses runs of zeros.
1265 This property can also be referred to by its shortened column name
1267 Changing this property affects only newly-written data.
1269 .Sy context Ns = Ns Sy none Ns | Ns
1270 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1272 This flag sets the SELinux context for all files in the file system under
1273 a mount point for that file system. See
1275 for more information.
1277 .Sy fscontext Ns = Ns Sy none Ns | Ns
1278 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1280 This flag sets the SELinux context for the file system file system being
1283 for more information.
1285 .Sy defcontext Ns = Ns Sy none Ns | Ns
1286 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1288 This flag sets the SELinux default context for unlabeled files. See
1290 for more information.
1292 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1293 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1295 This flag sets the SELinux context for the root inode of the file system. See
1297 for more information.
1298 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1299 Controls the number of copies of data stored for this dataset.
1300 These copies are in addition to any redundancy provided by the pool, for
1301 example, mirroring or RAID-Z.
1302 The copies are stored on different disks, if possible.
1303 The space used by multiple copies is charged to the associated file and dataset,
1306 property and counting against quotas and reservations.
1308 Changing this property only affects newly-written data.
1309 Therefore, set this property at file system creation time by using the
1310 .Fl o Sy copies Ns = Ns Ar N
1313 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1315 create, for example a two-disk striped pool and set
1317 on some datasets thinking you have setup redundancy for them. When a disk
1318 fails you will not be able to import the pool and will have lost all of your
1320 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1321 Controls whether device nodes can be opened on this file system.
1322 The default value is
1328 are equivalent to the
1334 .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
1335 .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
1338 Configures deduplication for a dataset. The default value is
1340 The default deduplication checksum is
1342 (this may change in the future). When
1344 is enabled, the checksum defined here overrides the
1346 property. Setting the value to
1348 has the same effect as the setting
1353 ZFS will do a byte-to-byte comparsion in case of two blocks having the same
1354 signature to make sure the block contents are identical. Specifying
1356 is mandatory for the
1360 Unless necessary, deduplication should NOT be enabled on a system. See
1364 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1365 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1367 Specifies a compatibility mode or literal value for the size of dnodes in the
1368 file system. The default value is
1370 Setting this property to a value other than
1372 requires the large_dnode pool feature to be enabled.
1378 if the dataset uses the
1380 property setting and the workload makes heavy use of extended attributes. This
1381 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1382 servers, for example. Literal values are supported for cases where the optimal
1383 size is known in advance and for performance testing.
1389 if you need to receive a send stream of this dataset on a pool that doesn't
1390 enable the large_dnode feature, or if you need to import this pool on a system
1391 that doesn't support the large_dnode feature.
1393 This property can also be referred to by its shortened column name,
1396 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1397 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1398 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1400 Controls the encryption cipher suite (block cipher, key length, and mode) used
1401 for this dataset. Requires the
1403 feature to be enabled on the pool.
1406 to be set at dataset creation time.
1409 .Sy encryption Ns = Ns Sy on
1410 when creating a dataset indicates that the default encryption suite will be
1411 selected, which is currently
1413 In order to provide consistent data protection, encryption must be specified at
1414 dataset creation time and it cannot be changed afterwards.
1416 For more details and caveats about encryption see the
1419 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1420 Controls what format the user's encryption key will be provided as. This
1421 property is only set when the dataset is encrypted.
1423 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1424 encryption suite) and must be randomly generated. A raw key can be generated
1425 with the following command:
1427 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1430 Passphrases must be between 8 and 512 bytes long and will be processed through
1431 PBKDF2 before being used (see the
1433 property). Even though the
1434 encryption suite cannot be changed after dataset creation, the keyformat can be
1436 .Nm zfs Cm change-key .
1438 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1440 Controls where the user's encryption key will be loaded from by default for
1444 .Nm zfs Cm mount Cm -l . This property is
1445 only set for encrypted datasets which are encryption roots. If unspecified, the
1449 Even though the encryption suite cannot be changed after dataset creation, the
1450 keylocation can be with either
1453 .Nm zfs Cm change-key .
1456 is selected ZFS will ask for the key at the command prompt when it is required
1457 to access the encrypted data (see
1459 for details). This setting will also allow the key to be passed in via STDIN,
1460 but users should be careful not to place keys which should be kept secret on
1461 the command line. If a file URI is selected, the key will be loaded from the
1462 specified absolute file path.
1463 .It Sy pbkdf2iters Ns = Ns Ar iterations
1464 Controls the number of PBKDF2 iterations that a
1466 encryption key should be run through when processing it into an encryption key.
1467 This property is only defined when encryption is enabled and a keyformat of
1469 is selected. The goal of PBKDF2 is to significantly increase the
1470 computational difficulty needed to brute force a user's passphrase. This is
1471 accomplished by forcing the attacker to run each passphrase through a
1472 computationally expensive hashing function many times before they arrive at the
1473 resulting key. A user who actually knows the passphrase will only have to pay
1474 this cost once. As CPUs become better at processing, this number should be
1475 raised to ensure that a brute force attack is still not possible. The current
1480 This property may be changed with
1481 .Nm zfs Cm change-key .
1482 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1483 Controls whether processes can be executed from within this file system.
1484 The default value is
1490 are equivalent to the
1495 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1496 Limits the number of filesystems and volumes that can exist under this point in
1498 The limit is not enforced if the user is allowed to change the limit.
1500 .Sy filesystem_limit
1503 a descendent of a filesystem that already has a
1504 .Sy filesystem_limit
1505 does not override the ancestor's
1506 .Sy filesystem_limit ,
1507 but rather imposes an additional limit.
1508 This feature must be enabled to be used
1510 .Xr zpool-features 5
1512 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1513 Controls the mount point used for this file system.
1516 section for more information on how this property is used.
1520 property is changed for a file system, the file system and any children that
1521 inherit the mount point are unmounted.
1524 then they remain unmounted.
1525 Otherwise, they are automatically remounted in the new location if the property
1530 or if they were mounted before the property was changed.
1531 In addition, any shared file systems are unshared and shared in the new
1533 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1534 Controls whether the file system should be mounted with
1536 .Pq Non Blocking mandatory locks .
1537 This is used for SMB clients.
1538 Changes to this property only take effect when the file system is umounted and
1542 for more information on
1544 mounts. This property is not used on Linux.
1545 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1546 Allow mounting on a busy directory or a directory which already contains
1547 files or directories. This is the default mount behavior for Linux file systems.
1548 For consistency with OpenZFS on other platforms overlay mounts are
1552 to enable overlay mounts.
1553 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1554 Controls what is cached in the primary cache
1556 If this property is set to
1558 then both user data and metadata is cached.
1559 If this property is set to
1561 then neither user data nor metadata is cached.
1562 If this property is set to
1564 then only metadata is cached.
1565 The default value is
1567 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1568 Limits the amount of space a dataset and its descendents can consume.
1569 This property enforces a hard limit on the amount of space used.
1570 This includes all space consumed by descendents, including file systems and
1572 Setting a quota on a descendent of a dataset that already has a quota does not
1573 override the ancestor's quota, but rather imposes an additional limit.
1575 Quotas cannot be set on volumes, as the
1577 property acts as an implicit quota.
1578 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1579 Limits the number of snapshots that can be created on a dataset and its
1583 on a descendent of a dataset that already has a
1585 does not override the ancestor's
1586 .Sy snapshot_limit ,
1587 but rather imposes an additional limit.
1588 The limit is not enforced if the user is allowed to change the limit.
1589 For example, this means that recursive snapshots taken from the global zone are
1590 counted against each delegated dataset within a zone.
1591 This feature must be enabled to be used
1593 .Xr zpool-features 5
1595 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1596 Limits the amount of space consumed by the specified user.
1597 User space consumption is identified by the
1598 .Sy userspace@ Ns Em user
1601 Enforcement of user quotas may be delayed by several seconds.
1602 This delay means that a user might exceed their quota before the system notices
1603 that they are over quota and begins to refuse additional writes with the
1607 .Nm zfs Cm userspace
1608 subcommand for more information.
1610 Unprivileged users can only access their own groups' space usage.
1611 The root user, or a user who has been granted the
1615 can get and set everyone's quota.
1617 This property is not available on volumes, on file systems before version 4, or
1618 on pools before version 15.
1620 .Sy userquota@ Ns Em ...
1621 properties are not displayed by
1622 .Nm zfs Cm get Sy all .
1623 The user's name must be appended after the
1625 symbol, using one of the following forms:
1633 .Em POSIX numeric ID
1640 .Sy joe.smith@mydomain
1649 Files created on Linux always have POSIX owners.
1650 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1655 but it limits the number of objects a user can create. Please refer to
1657 for more information about how objects are counted.
1658 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1659 Limits the amount of space consumed by the specified group.
1660 Group space consumption is identified by the
1661 .Sy groupused@ Ns Em group
1664 Unprivileged users can access only their own groups' space usage.
1665 The root user, or a user who has been granted the
1669 can get and set all groups' quotas.
1670 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1675 but it limits number of objects a group can consume. Please refer to
1677 for more information about how objects are counted.
1678 .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1679 Limits the amount of space consumed by the specified project. Project
1680 space consumption is identified by the
1681 .Sy projectused@ Ns Em project
1682 property. Please refer to
1684 for more information about how project is identified and set/changed.
1686 The root user, or a user who has been granted the
1690 can access all projects' quota.
1691 .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
1696 but it limits number of objects a project can consume. Please refer to
1698 for more information about how objects are counted.
1699 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1700 Controls whether this dataset can be modified.
1701 The default value is
1707 are equivalent to the
1713 This property can also be referred to by its shortened column name,
1715 .It Sy recordsize Ns = Ns Em size
1716 Specifies a suggested block size for files in the file system.
1717 This property is designed solely for use with database workloads that access
1718 files in fixed-size records.
1719 ZFS automatically tunes block sizes according to internal algorithms optimized
1720 for typical access patterns.
1722 For databases that create very large files but access them in small random
1723 chunks, these algorithms may be suboptimal.
1726 greater than or equal to the record size of the database can result in
1727 significant performance gains.
1728 Use of this property for general purpose file systems is strongly discouraged,
1729 and may adversely affect performance.
1731 The size specified must be a power of two greater than or equal to 512 and less
1732 than or equal to 128 Kbytes.
1735 feature is enabled on the pool, the size may be up to 1 Mbyte.
1737 .Xr zpool-features 5
1738 for details on ZFS feature flags.
1740 Changing the file system's
1742 affects only files created afterward; existing files are unaffected.
1744 This property can also be referred to by its shortened column name,
1746 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1747 Controls what types of metadata are stored redundantly.
1748 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1749 the amount of user data lost is limited.
1750 This extra copy is in addition to any redundancy provided at the pool level
1751 .Pq e.g. by mirroring or RAID-Z ,
1752 and is in addition to an extra copy specified by the
1755 .Pq up to a total of 3 copies .
1756 For example if the pool is mirrored,
1757 .Sy copies Ns = Ns 2 ,
1759 .Sy redundant_metadata Ns = Ns Sy most ,
1760 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1765 ZFS stores an extra copy of all metadata.
1766 If a single on-disk block is corrupt, at worst a single block of user data
1775 ZFS stores an extra copy of most types of metadata.
1776 This can improve performance of random writes, because less metadata must be
1778 In practice, at worst about 100 blocks
1783 of user data can be lost if a single on-disk block is corrupt.
1784 The exact behavior of which metadata blocks are stored redundantly may change in
1787 The default value is
1789 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1790 Limits the amount of space a dataset can consume.
1791 This property enforces a hard limit on the amount of space used.
1792 This hard limit does not include space used by descendents, including file
1793 systems and snapshots.
1794 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1795 The minimum amount of space guaranteed to a dataset, not including its
1797 When the amount of space used is below this value, the dataset is treated as if
1798 it were taking up the amount of space specified by
1799 .Sy refreservation .
1802 reservation is accounted for in the parent datasets' space used, and counts
1803 against the parent datasets' quotas and reservations.
1807 is set, a snapshot is only allowed if there is enough free pool space outside of
1808 this reservation to accommodate the current number of
1810 bytes in the dataset.
1816 a volume is thick provisioned
1820 .Sy refreservation Ns = Ns Sy auto
1821 is only supported on volumes.
1825 .Sx Native Properties
1826 section for more information about sparse volumes.
1828 This property can also be referred to by its shortened column name,
1830 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1831 Controls the manner in which the access time is updated when
1833 is set. Turning this property on causes the access time to be updated relative
1834 to the modify or change time. Access time is only updated if the previous
1835 access time was earlier than the current modify or change time or if the
1836 existing access time hasn't been updated within the past 24 hours. The default
1843 are equivalent to the
1848 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1849 The minimum amount of space guaranteed to a dataset and its descendants.
1850 When the amount of space used is below this value, the dataset is treated as if
1851 it were taking up the amount of space specified by its reservation.
1852 Reservations are accounted for in the parent datasets' space used, and count
1853 against the parent datasets' quotas and reservations.
1855 This property can also be referred to by its shortened column name,
1857 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1858 Controls what is cached in the secondary cache
1860 If this property is set to
1862 then both user data and metadata is cached.
1863 If this property is set to
1865 then neither user data nor metadata is cached.
1866 If this property is set to
1868 then only metadata is cached.
1869 The default value is
1871 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1872 Controls whether the setuid bit is respected for the file system.
1873 The default value is
1879 are equivalent to the
1884 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1885 Controls whether the file system is shared by using
1886 .Sy Samba USERSHARES
1887 and what options are to be used. Otherwise, the file system is automatically
1888 shared and unshared with the
1892 commands. If the property is set to on, the
1894 command is invoked to create a
1897 Because SMB shares requires a resource name, a unique resource name is
1898 constructed from the dataset name. The constructed name is a copy of the
1899 dataset name except that the characters in the dataset name, which would be
1900 invalid in the resource name, are replaced with underscore (_) characters.
1901 Linux does not currently support additional options which might be available
1908 the file systems are unshared.
1910 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1911 stands for "full permissions", ie. read and write permissions) and no guest
1912 access (which means Samba must be able to authenticate a real user, system
1913 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1914 additional access control (disallow specific user specific access etc) must
1915 be done on the underlying file system.
1916 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1917 Controls whether the file system is shared via NFS, and what options are to be
1919 A file system with a
1925 command and entries in the
1928 Otherwise, the file system is automatically shared and unshared with the
1933 If the property is set to
1935 the dataset is shared using the default options:
1937 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1941 for the meaning of the default options. Otherwise, the
1943 command is invoked with options equivalent to the contents of this property.
1947 property is changed for a dataset, the dataset and any children inheriting the
1948 property are re-shared with the new options, only if the property was previously
1950 or if they were shared before the property was changed.
1951 If the new property is
1953 the file systems are unshared.
1954 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1955 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1961 ZFS will use pool log devices
1963 to handle the requests at low latency.
1968 ZFS will not use configured pool log devices.
1969 ZFS will instead optimize synchronous operations for global pool throughput and
1970 efficient use of resources.
1971 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1972 Controls whether the volume snapshot devices under
1973 .Em /dev/zvol/<pool>
1974 are hidden or visible. The default value is
1976 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1977 Controls whether the
1979 directory is hidden or visible in the root of the file system as discussed in
1983 The default value is
1985 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1986 Controls the behavior of synchronous requests
1987 .Pq e.g. fsync, O_DSYNC .
1991 specified behavior of ensuring all synchronous requests are written to stable
1992 storage and all devices are flushed to ensure data is not cached by device
1994 .Pq this is the default .
1996 causes every file system transaction to be written and flushed before its
1997 system call returns.
1998 This has a large performance penalty.
2000 disables synchronous requests.
2001 File system transactions are only committed to stable storage periodically.
2002 This option will give the highest performance.
2003 However, it is very dangerous as ZFS would be ignoring the synchronous
2004 transaction demands of applications such as databases or NFS.
2005 Administrators should only use this option when the risks are understood.
2006 .It Sy version Ns = Ns Em N Ns | Ns Sy current
2007 The on-disk version of this file system, which is independent of the pool
2009 This property can only be set to later supported versions.
2013 .It Sy volsize Ns = Ns Em size
2014 For volumes, specifies the logical size of the volume.
2015 By default, creating a volume establishes a reservation of equal size.
2016 For storage pools with a version number of 9 or higher, a
2021 are reflected in an equivalent change to the reservation
2027 can only be set to a multiple of
2031 The reservation is kept equal to the volume's logical size to prevent unexpected
2032 behavior for consumers.
2033 Without the reservation, the volume could run out of space, resulting in
2034 undefined behavior or data corruption, depending on how the volume is used.
2035 These effects can also occur when the volume size is changed while it is in use
2036 .Pq particularly when shrinking the size .
2037 Extreme care should be used when adjusting the volume size.
2039 Though not recommended, a
2042 .Qq thin provisioned
2044 can be created by specifying the
2047 .Nm zfs Cm create Fl V
2048 command, or by changing the value of the
2053 property on pool version 8 or earlier
2055 after the volume has been created.
2058 is a volume where the value of
2060 is less than the size of the volume plus the space required to store its
2062 Consequently, writes to a sparse volume can fail with
2064 when the pool is low on space.
2065 For a sparse volume, changes to
2067 are not reflected in the
2069 A volume that is not sparse is said to be
2070 .Qq thick provisioned .
2071 A sparse volume can become thick provisioned by setting
2075 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
2076 This property specifies how volumes should be exposed to the OS.
2079 exposes volumes as fully fledged block devices, providing maximal
2080 functionality. The value
2082 is just an alias for
2084 and is kept for compatibility.
2087 hides its partitions.
2088 Volumes with property set to
2090 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
2091 that can be suitable for backup purposes.
2094 means that volumes exposition is controlled by system-wide tunable
2101 are encoded as 1, 2 and 3 respectively.
2102 The default values is
2104 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
2105 Controls whether regular files should be scanned for viruses when a file is
2107 In addition to enabling this property, the virus scan service must also be
2108 enabled for virus scanning to occur.
2109 The default value is
2111 This property is not used on Linux.
2112 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
2113 Controls whether extended attributes are enabled for this file system. Two
2114 styles of extended attributes are supported either directory based or system
2117 The default value of
2119 enables directory based extended attributes. This style of extended attribute
2120 imposes no practical limit on either the size or number of attributes which
2121 can be set on a file. Although under Linux the
2125 system calls limit the maximum size to 64K. This is the most compatible
2126 style of extended attribute and is supported by all OpenZFS implementations.
2128 System attribute based xattrs can be enabled by setting the value to
2130 The key advantage of this type of xattr is improved performance. Storing
2131 extended attributes as system attributes significantly decreases the amount of
2132 disk IO required. Up to 64K of data may be stored per-file in the space
2133 reserved for system attributes. If there is not enough space available for
2134 an extended attribute then it will be automatically written as a directory
2135 based xattr. System attribute based extended attributes are not accessible
2136 on platforms which do not support the
2140 The use of system attribute based xattrs is strongly encouraged for users of
2141 SELinux or posix ACLs. Both of these features heavily rely of extended
2142 attributes and benefit significantly from the reduced access time.
2148 are equivalent to the
2153 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
2154 Controls whether the dataset is managed from a non-global zone. Zones are a
2155 Solaris feature and are not relevant on Linux. The default value is
2159 The following three properties cannot be changed after the file system is
2160 created, and therefore, should be set when the file system is created.
2161 If the properties are not set with the
2165 commands, these properties are inherited from the parent dataset.
2166 If the parent dataset lacks these properties due to having been created prior to
2167 these features being supported, the new file system will have the default values
2168 for these properties.
2171 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2172 .Sy insensitive Ns | Ns Sy mixed
2174 Indicates whether the file name matching algorithm used by the file system
2175 should be case-sensitive, case-insensitive, or allow a combination of both
2177 The default value for the
2185 file systems have case-sensitive file names.
2191 property indicates that the file system can support requests for both
2192 case-sensitive and case-insensitive matching behavior.
2193 Currently, case-insensitive matching behavior on a file system that supports
2194 mixed behavior is limited to the SMB server product.
2195 For more information about the
2197 value behavior, see the "ZFS Administration Guide".
2199 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2200 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2202 Indicates whether the file system should perform a
2204 normalization of file names whenever two file names are compared, and which
2205 normalization algorithm should be used.
2206 File names are always stored unmodified, names are normalized as part of any
2208 If this property is set to a legal value other than
2212 property was left unspecified, the
2214 property is automatically set to
2216 The default value of the
2220 This property cannot be changed after the file system is created.
2221 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2222 Indicates whether the file system should reject file names that include
2223 characters that are not present in the
2226 If this property is explicitly set to
2228 the normalization property must either not be explicitly set or be set to
2230 The default value for the
2234 This property cannot be changed after the file system is created.
2238 .Sy casesensitivity ,
2242 properties are also new permissions that can be assigned to non-privileged users
2243 by using the ZFS delegated administration feature.
2244 .Ss "Temporary Mount Point Properties"
2245 When a file system is mounted, either through
2247 for legacy mounts or the
2249 command for normal file systems, its mount options are set according to its
2251 The correlation between properties and mount options is as follows:
2253 PROPERTY MOUNT OPTION
2255 canmount auto/noauto
2259 relatime relatime/norelatime
2264 In addition, these options can be set on a per-mount basis using the
2266 option, without affecting the property that is stored on disk.
2267 The values specified on the command line override the values stored in the
2271 option is an alias for
2272 .Sy nodevices Ns \&, Ns Sy nosetuid .
2273 These properties are reported as
2278 If the properties are changed while the dataset is mounted, the new setting
2279 overrides any temporary settings.
2280 .Ss "User Properties"
2281 In addition to the standard native properties, ZFS supports arbitrary user
2283 User properties have no effect on ZFS behavior, but applications or
2284 administrators can use them to annotate datasets
2285 .Pq file systems, volumes, and snapshots .
2287 User property names must contain a colon
2289 character to distinguish them from native properties.
2290 They may contain lowercase letters, numbers, and the following punctuation
2299 The expected convention is that the property name is divided into two portions
2301 .Em module Ns \&: Ns Em property ,
2302 but this namespace is not enforced by ZFS.
2303 User property names can be at most 256 characters, and cannot begin with a dash
2306 When making programmatic use of user properties, it is strongly suggested to use
2311 component of property names to reduce the chance that two
2312 independently-developed packages use the same property name for different
2315 The values of user properties are arbitrary strings, are always inherited, and
2316 are never validated.
2317 All of the commands that operate on properties
2318 .Po Nm zfs Cm list ,
2323 can be used to manipulate both native properties and user properties.
2326 command to clear a user property.
2327 If the property is not defined in any parent dataset, it is removed entirely.
2328 Property values are limited to 8192 bytes.
2329 .Ss ZFS Volumes as Swap
2330 ZFS volumes may be used as swap devices. After creating the volume with the
2331 .Nm zfs Cm create Fl V
2332 command set up and enable the swap area using the
2336 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2337 configuration is not supported.
2341 feature allows for the creation of encrypted filesystems and volumes.
2343 will encrypt all user data including file and zvol data, file attributes,
2344 ACLs, permission bits, directory listings, FUID mappings, and userused /
2347 will not encrypt metadata related to the pool structure, including dataset
2348 names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
2349 is managed internally by the kernel module and changing the user's key does not
2350 require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
2351 renamed, and deleted without the encryption keys being loaded (see the
2353 subcommand for more info on key loading).
2355 Creating an encrypted dataset requires specifying the
2359 properties at creation time, along with an optional
2363 After entering an encryption key, the
2364 created dataset will become an encryption root. Any descendant datasets will
2365 inherit their encryption key from the encryption root by default, meaning that
2366 loading, unloading, or changing the key for the encryption root will implicitly
2367 do the same for all inheriting datasets. If this inheritance is not desired,
2370 when creating the child dataset or use
2371 .Nm zfs Cm change-key
2372 to break an existing relationship, creating a new encryption root on the child.
2373 Note that the child's
2375 may match that of the parent while still creating a new encryption root, and
2378 property alone does not create a new encryption root; this would simply use a
2379 different cipher suite with the same key as its encryption root. The one
2380 exception is that clones will always use their origin's encryption key.
2381 As a result of this exception, some encryption-related properties (namely
2387 do not inherit like other ZFS properties and instead use the value determined
2388 by their encryption root. Encryption root inheritance can be tracked via the
2393 Encryption changes the behavior of a few
2395 operations. Encryption is applied after compression so compression ratios are
2396 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2397 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2398 the encryption suite, which provides additional protection against maliciously
2399 altered data. Deduplication is still possible with encryption enabled but for
2400 security, datasets will only dedup against themselves, their snapshots, and
2403 There are a few limitations on encrypted datasets. Encrypted data cannot be
2406 feature. Encrypted datasets may not have
2407 .Sy copies Ns = Ns Em 3
2408 since the implementation stores some encryption metadata where the third copy
2409 would normally be. Since compression is applied before encryption datasets may
2410 be vulnerable to a CRIME-like attack if applications accessing the data allow
2411 for it. Deduplication with encryption will leak information about which blocks
2412 are equivalent in a dataset and will incur an extra CPU cost per block written.
2414 All subcommands that modify state are logged persistently to the pool in their
2418 Displays a help message.
2423 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2426 Creates a new ZFS file system.
2427 The file system is automatically mounted according to the
2429 property inherited from the parent.
2430 .Bl -tag -width "-o"
2431 .It Fl o Ar property Ns = Ns Ar value
2432 Sets the specified property as if the command
2433 .Nm zfs Cm set Ar property Ns = Ns Ar value
2434 was invoked at the same time the dataset was created.
2435 Any editable ZFS property can also be set at creation time.
2438 options can be specified.
2439 An error results if the same property is specified in multiple
2443 Creates all the non-existing parent datasets.
2444 Datasets created in this manner are automatically mounted according to the
2446 property inherited from their parent.
2447 Any property specified on the command line using the
2450 If the target filesystem already exists, the operation completes successfully.
2456 .Op Fl b Ar blocksize
2457 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2458 .Fl V Ar size Ar volume
2460 Creates a volume of the given size.
2461 The volume is exported as a block device in
2462 .Pa /dev/zvol/path ,
2465 is the name of the volume in the ZFS namespace.
2466 The size represents the logical size as exported by the device.
2467 By default, a reservation of equal size is created.
2470 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2471 has an integral number of blocks regardless of
2473 .Bl -tag -width "-b"
2474 .It Fl b Ar blocksize
2476 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2477 If this option is specified in conjunction with
2478 .Fl o Sy volblocksize ,
2479 the resulting behavior is undefined.
2480 .It Fl o Ar property Ns = Ns Ar value
2481 Sets the specified property as if the
2482 .Nm zfs Cm set Ar property Ns = Ns Ar value
2483 command was invoked at the same time the dataset was created.
2484 Any editable ZFS property can also be set at creation time.
2487 options can be specified.
2488 An error results if the same property is specified in multiple
2492 Creates all the non-existing parent datasets.
2493 Datasets created in this manner are automatically mounted according to the
2495 property inherited from their parent.
2496 Any property specified on the command line using the
2499 If the target filesystem already exists, the operation completes successfully.
2501 Creates a sparse volume with no reservation.
2505 .Sx Native Properties
2506 section for more information about sparse volumes.
2512 .Ar filesystem Ns | Ns Ar volume
2514 Destroys the given dataset.
2515 By default, the command unshares any file systems that are currently shared,
2516 unmounts any file systems that are currently mounted, and refuses to destroy a
2517 dataset that has active dependents
2518 .Pq children or clones .
2519 .Bl -tag -width "-R"
2521 Recursively destroy all dependents, including cloned file systems outside the
2524 Force an unmount of any file systems using the
2527 This option has no effect on non-file systems or unmounted file systems.
2532 No data will be deleted.
2533 This is useful in conjunction with the
2537 flags to determine what data would be deleted.
2539 Print machine-parsable verbose information about the deleted data.
2541 Recursively destroy all children.
2543 Print verbose information about the deleted data.
2546 Extreme care should be taken when applying either the
2550 options, as they can destroy large portions of a pool and cause unexpected
2551 behavior for mounted file systems in use.
2556 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2557 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2559 The given snapshots are destroyed immediately if and only if the
2563 option would have destroyed it.
2564 Such immediate destruction would occur, for example, if the snapshot had no
2565 clones and the user-initiated reference count were zero.
2567 If a snapshot does not qualify for immediate destruction, it is marked for
2569 In this state, it exists as a usable, visible snapshot until both of the
2570 preconditions listed above are met, at which point it is destroyed.
2572 An inclusive range of snapshots may be specified by separating the first and
2573 last snapshots with a percent sign.
2574 The first and/or last snapshots may be left blank, in which case the
2575 filesystem's oldest or newest snapshot will be implied.
2578 .Pq or ranges of snapshots
2579 of the same filesystem or volume may be specified in a comma-separated list of
2581 Only the snapshot's short name
2582 .Po the part after the
2585 should be specified when using a range or comma-separated list to identify
2587 .Bl -tag -width "-R"
2589 Recursively destroy all clones of these snapshots, including the clones,
2590 snapshots, and children.
2591 If this flag is specified, the
2593 flag will have no effect.
2595 Destroy immediately. If a snapshot cannot be destroyed now, mark it for
2596 deferred destruction.
2601 No data will be deleted.
2602 This is useful in conjunction with the
2606 flags to determine what data would be deleted.
2608 Print machine-parsable verbose information about the deleted data.
2611 .Pq or mark for deferred deletion
2612 all snapshots with this name in descendent file systems.
2614 Print verbose information about the deleted data.
2616 Extreme care should be taken when applying either the
2620 options, as they can destroy large portions of a pool and cause unexpected
2621 behavior for mounted file systems in use.
2626 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2628 The given bookmark is destroyed.
2633 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2634 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2636 Creates snapshots with the given names.
2637 All previous modifications by successful system calls to the file system are
2638 part of the snapshots.
2639 Snapshots are taken atomically, so that all snapshots correspond to the same
2642 can be used as an alias for
2643 .Nm zfs Cm snapshot.
2646 section for details.
2647 .Bl -tag -width "-o"
2648 .It Fl o Ar property Ns = Ns Ar value
2649 Sets the specified property; see
2653 Recursively create snapshots of all descendent datasets
2661 Roll back the given dataset to a previous snapshot.
2662 When a dataset is rolled back, all data that has changed since the snapshot is
2663 discarded, and the dataset reverts to the state at the time of the snapshot.
2664 By default, the command refuses to roll back to a snapshot other than the most
2666 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2673 options do not recursively destroy the child snapshots of a recursive snapshot.
2674 Only direct snapshots of the specified filesystem are destroyed by either of
2676 To completely roll back a recursive snapshot, you must rollback the individual
2678 .Bl -tag -width "-R"
2680 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2685 option to force an unmount of any clone file systems that are to be destroyed.
2687 Destroy any snapshots and bookmarks more recent than the one specified.
2693 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2694 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2696 Creates a clone of the given snapshot.
2699 section for details.
2700 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2701 as the same type as the original.
2702 .Bl -tag -width "-o"
2703 .It Fl o Ar property Ns = Ns Ar value
2704 Sets the specified property; see
2708 Creates all the non-existing parent datasets.
2709 Datasets created in this manner are automatically mounted according to the
2711 property inherited from their parent.
2712 If the target filesystem or volume already exists, the operation completes
2718 .Ar clone-filesystem
2720 Promotes a clone file system to no longer be dependent on its
2723 This makes it possible to destroy the file system that the clone was created
2725 The clone parent-child dependency relationship is reversed, so that the origin
2726 file system becomes a clone of the specified file system.
2728 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2729 now owned by the promoted clone.
2730 The space they use moves from the origin file system to the promoted clone, so
2731 enough space must be available to accommodate these snapshots.
2732 No new space is consumed by this operation, but the space accounting is
2734 The promoted clone must not have any conflicting snapshot names of its own.
2737 subcommand can be used to rename any conflicting snapshots.
2742 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2743 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2749 .Ar filesystem Ns | Ns Ar volume
2750 .Ar filesystem Ns | Ns Ar volume
2752 Renames the given dataset.
2753 The new target can be located anywhere in the ZFS hierarchy, with the exception
2755 Snapshots can only be renamed within the parent file system or volume.
2756 When renaming a snapshot, the parent file system of the snapshot does not need
2757 to be specified as part of the second argument.
2758 Renamed file systems can inherit new mount points, in which case they are
2759 unmounted and remounted at the new mount point.
2760 .Bl -tag -width "-a"
2762 Force unmount any filesystems that need to be unmounted in the process.
2764 Creates all the nonexistent parent datasets.
2765 Datasets created in this manner are automatically mounted according to the
2767 property inherited from their parent.
2773 .Ar snapshot Ar snapshot
2775 Recursively rename the snapshots of all descendent datasets.
2776 Snapshots are the only dataset that can be renamed recursively.
2780 .Op Fl r Ns | Ns Fl d Ar depth
2782 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2783 .Oo Fl s Ar property Oc Ns ...
2784 .Oo Fl S Ar property Oc Ns ...
2785 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2786 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2788 Lists the property information for the given datasets in tabular form.
2789 If specified, you can list property information by the absolute pathname or the
2791 By default, all file systems and volumes are displayed.
2792 Snapshots are displayed if the
2799 The following fields are displayed,
2800 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2802 .Bl -tag -width "-H"
2804 Used for scripting mode.
2805 Do not print headers and separate fields by a single tab instead of arbitrary
2807 .It Fl S Ar property
2810 option, but sorts by property in descending order.
2812 Recursively display any children of the dataset, limiting the recursion to
2818 will display only the dataset and its direct children.
2819 .It Fl o Ar property
2820 A comma-separated list of properties to display.
2821 The property must be:
2824 One of the properties described in the
2825 .Sx Native Properties
2832 to display the dataset name
2836 to display space usage properties on file systems and volumes.
2837 This is a shortcut for specifying
2838 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2839 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2840 .Sy filesystem Ns \&, Ns Sy volume
2844 Display numbers in parsable
2848 Recursively display any children of the dataset on the command line.
2849 .It Fl s Ar property
2850 A property for sorting the output by column in ascending order based on the
2851 value of the property.
2852 The property must be one of the properties described in the
2854 section, or the special value
2856 to sort by the dataset name.
2857 Multiple properties can be specified at one time using multiple
2862 options are evaluated from left to right in decreasing order of importance.
2863 The following is a list of sorting criteria:
2866 Numeric types sort in numeric order.
2868 String types sort in alphabetical order.
2870 Types inappropriate for a row sort that row to the literal bottom, regardless of
2871 the specified ordering.
2874 If no sorting options are specified the existing behavior of
2878 A comma-separated list of types to display, where
2887 For example, specifying
2889 displays only snapshots.
2894 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2895 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2897 Sets the property or list of properties to the given value(s) for each dataset.
2898 Only some properties can be edited.
2901 section for more information on what properties can be set and acceptable
2903 Numeric values can be specified as exact values, or in a human-readable form
2905 .Sy B , K , M , G , T , P , E , Z
2906 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2907 or zettabytes, respectively
2909 User properties can be set on snapshots.
2910 For more information, see the
2916 .Op Fl r Ns | Ns Fl d Ar depth
2918 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2919 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2920 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2921 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2922 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2924 Displays properties for the given datasets.
2925 If no datasets are specified, then the command displays properties for all
2926 datasets on the system.
2927 For each property, the following columns are displayed:
2930 property Property name
2931 value Property value
2932 source Property source. Can either be local, default,
2933 temporary, inherited, or none (-).
2936 All columns are displayed by default, though this can be controlled by using the
2939 This command takes a comma-separated list of properties as described in the
2940 .Sx Native Properties
2947 can be used to display all properties that apply to the given dataset's type
2948 .Pq filesystem, volume, snapshot, or bookmark .
2949 .Bl -tag -width "-H"
2951 Display output in a form more easily parsed by scripts.
2952 Any headers are omitted, and fields are explicitly separated by a single tab
2953 instead of an arbitrary amount of space.
2955 Recursively display any children of the dataset, limiting the recursion to
2959 will display only the dataset and its direct children.
2961 A comma-separated list of columns to display.
2962 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2963 is the default value.
2965 Display numbers in parsable
2969 Recursively display properties for any children.
2971 A comma-separated list of sources to display.
2972 Those properties coming from a source other than those in this list are ignored.
2973 Each source must be one of the following:
2980 The default value is all sources.
2982 A comma-separated list of types to display, where
2996 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2998 Clears the specified property, causing it to be inherited from an ancestor,
2999 restored to default if no ancestor has the property set, or with the
3001 option reverted to the received value if one exists.
3004 section for a listing of default values, and details on which properties can be
3006 .Bl -tag -width "-r"
3008 Recursively inherit the given property for all children.
3010 Revert the property to the received value if one exists; otherwise operate as
3013 option was not specified.
3019 Displays a list of file systems that are not the most recent version.
3025 Displays a list of currently supported file system versions.
3031 .Fl a | Ar filesystem
3033 Upgrades file systems to a new on-disk version.
3034 Once this is done, the file systems will no longer be accessible on systems
3035 running older versions of the software.
3037 streams generated from new snapshots of these file systems cannot be accessed on
3038 systems running older versions of the software.
3040 In general, the file system version is independent of the pool version.
3043 for information on the
3044 .Nm zpool Cm upgrade
3047 In some cases, the file system version and the pool version are interrelated and
3048 the pool version must be upgraded before the file system version can be
3050 .Bl -tag -width "-V"
3052 Upgrade to the specified
3056 flag is not specified, this command upgrades to the most recent version.
3058 option can only be used to increase the version number, and only up to the most
3059 recent version supported by this software.
3061 Upgrade all file systems on all imported pools.
3063 Upgrade the specified file system.
3065 Upgrade the specified file system and all descendent file systems.
3071 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3072 .Oo Fl s Ar field Oc Ns ...
3073 .Oo Fl S Ar field Oc Ns ...
3074 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3075 .Ar filesystem Ns | Ns Ar snapshot
3077 Displays space consumed by, and quotas on, each user in the specified filesystem
3079 This corresponds to the
3080 .Sy userused@ Ns Em user ,
3081 .Sy userobjused@ Ns Em user ,
3082 .Sy userquota@ Ns Em user,
3084 .Sy userobjquota@ Ns Em user
3086 .Bl -tag -width "-H"
3088 Do not print headers, use tab-delimited output.
3090 Sort by this field in reverse order.
3094 Translate SID to POSIX ID.
3095 The POSIX ID may be ephemeral if no mapping exists.
3096 Normal POSIX interfaces
3101 perform this translation, so the
3103 option allows the output from
3104 .Nm zfs Cm userspace
3105 to be compared directly with those utilities.
3108 may lead to confusion if some files were created by an SMB user before a
3109 SMB-to-POSIX name mapping was established.
3110 In such a case, some files will be owned by the SMB entity and some by the POSIX
3114 option will report that the POSIX entity has the total usage and quota for both.
3116 Print numeric ID instead of user/group name.
3117 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
3118 Display only the specified fields from the following set:
3123 The default is to display all fields.
3129 Sort output by this field.
3134 flags may be specified multiple times to sort first by one field, then by
3137 .Fl s Sy type Fl s Sy name .
3138 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
3139 Print only the specified types from the following set:
3146 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
3147 The default can be changed to include group types.
3153 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3154 .Oo Fl s Ar field Oc Ns ...
3155 .Oo Fl S Ar field Oc Ns ...
3156 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
3157 .Ar filesystem Ns | Ns Ar snapshot
3159 Displays space consumed by, and quotas on, each group in the specified
3160 filesystem or snapshot.
3161 This subcommand is identical to
3162 .Nm zfs Cm userspace ,
3163 except that the default types to display are
3164 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3169 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
3170 .Oo Fl s Ar field Oc Ns ...
3171 .Oo Fl S Ar field Oc Ns ...
3172 .Ar filesystem Ns | Ns Ar snapshot
3174 Displays space consumed by, and quotas on, each project in the specified
3175 filesystem or snapshot. This subcommand is identical to
3176 .Nm zfs Cm userspace ,
3177 except that the project identifier is numeral, not name. So need neither
3180 for SID to POSIX ID nor
3188 .Oo Fl d Ns | Ns Fl r Ns Oc
3189 .Ar file Ns | Ns Ar directory Ns ...
3191 List project identifier (ID) and inherit flag of file(s) or directories.
3192 .Bl -tag -width "-d"
3194 Show the directory project ID and inherit flag, not its childrens. It will
3195 overwrite the former specified
3199 Show on subdirectories recursively. It will overwrite the former specified
3208 .Ar file Ns | Ns Ar directory Ns ...
3210 Clear project inherit flag and/or ID on the file(s) or directories.
3211 .Bl -tag -width "-k"
3213 Keep the project ID unchanged. If not specified, the project ID will be reset
3216 Clear on subdirectories recursively.
3223 .Oo Fl d Ns | Ns Fl r Ns Oc
3225 .Ar file Ns | Ns Ar directory Ns ...
3227 Check project ID and inherit flag on the file(s) or directories, report the
3228 entries without project inherit flag or with different project IDs from the
3231 option) value or the target directory's project ID.
3232 .Bl -tag -width "-0"
3234 Print file name with a trailing NUL instead of newline (by default), like
3237 Check the directory project ID and inherit flag, not its childrens. It will
3238 overwrite the former specified
3242 Specify the referenced ID for comparing with the target file(s) or directories'
3243 project IDs. If not specified, the target (top) directory's project ID will be
3244 used as the referenced one.
3246 Check on subdirectories recursively. It will overwrite the former specified
3255 .Ar file Ns | Ns Ar directory Ns ...
3257 .Bl -tag -width "-p"
3258 Set project ID and/or inherit flag on the file(s) or directories.
3260 Set the file(s)' or directories' project ID with the given value.
3262 Set on subdirectories recursively.
3264 Set project inherit flag on the given file(s) or directories. It is usually used
3265 for setup tree quota on the directory target with
3267 option specified together. When setup tree quota, by default the directory's
3268 project ID will be set to all its descendants unless you specify the project
3277 Displays all ZFS file systems currently mounted.
3283 .Fl a | Ar filesystem
3285 Mounts ZFS file systems.
3286 .Bl -tag -width "-O"
3288 Perform an overlay mount.
3291 for more information.
3293 Mount all available ZFS file systems.
3294 Invoked automatically as part of the boot process.
3296 Mount the specified filesystem.
3298 An optional, comma-separated list of mount options to use temporarily for the
3299 duration of the mount.
3301 .Sx Temporary Mount Point Properties
3302 section for details.
3304 Load keys for encrypted filesystems as they are being mounted. This is
3305 equivalent to executing
3307 on each encryption root before mounting it. Note that if a filesystem has a
3311 this will cause the terminal to interactively block after asking for the key.
3313 Report mount progress.
3319 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3321 Unmounts currently mounted ZFS file systems.
3322 .Bl -tag -width "-a"
3324 Unmount all available ZFS file systems.
3325 Invoked automatically as part of the shutdown process.
3326 .It Ar filesystem Ns | Ns Ar mountpoint
3327 Unmount the specified filesystem.
3328 The command can also be given a path to a ZFS file system mount point on the
3331 Forcefully unmount the file system, even if it is currently in use.
3336 .Fl a | Ar filesystem
3338 Shares available ZFS file systems.
3339 .Bl -tag -width "-a"
3341 Share all available ZFS file systems.
3342 Invoked automatically as part of the boot process.
3344 Share the specified filesystem according to the
3349 File systems are shared when the
3358 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3360 Unshares currently shared ZFS file systems.
3361 .Bl -tag -width "-a"
3363 Unshare all available ZFS file systems.
3364 Invoked automatically as part of the shutdown process.
3365 .It Ar filesystem Ns | Ns Ar mountpoint
3366 Unshare the specified filesystem.
3367 The command can also be given a path to a ZFS file system shared on the system.
3372 .Ar snapshot bookmark
3374 Creates a bookmark of the given snapshot.
3375 Bookmarks mark the point in time when the snapshot was created, and can be used
3376 as the incremental source for a
3380 This feature must be enabled to be used.
3382 .Xr zpool-features 5
3383 for details on ZFS feature flags and the
3390 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3393 Creates a stream representation of the second
3395 which is written to standard output.
3396 The output can be redirected to a file or to a different system
3397 .Po for example, using
3400 By default, a full stream is generated.
3401 .Bl -tag -width "-D"
3403 Generate a deduplicated stream.
3404 Blocks which would have been sent multiple times in the send stream will only be
3406 The receiving system must also support this feature to receive a deduplicated
3408 This flag can be used regardless of the dataset's
3410 property, but performance will be much better if the filesystem uses a
3411 dedup-capable checksum
3415 .It Fl I Ar snapshot
3416 Generate a stream package that sends all intermediary snapshots from the first
3417 snapshot to the second snapshot.
3421 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3422 The incremental source may be specified as with the
3425 .It Fl L, -large-block
3426 Generate a stream which may contain blocks larger than 128KB.
3427 This flag has no effect if the
3429 pool feature is disabled, or if the
3431 property of this filesystem has never been set above 128KB.
3432 The receiving system must have the
3434 pool feature enabled as well.
3436 .Xr zpool-features 5
3437 for details on ZFS feature flags and the
3441 Print machine-parsable verbose information about the stream package generated.
3442 .It Fl R, -replicate
3443 Generate a replication stream package, which will replicate the specified
3444 file system, and all descendent file systems, up to the named snapshot.
3445 When received, all properties, snapshots, descendent file systems, and clones
3452 flags are used in conjunction with the
3454 flag, an incremental replication stream is generated.
3455 The current values of properties, and current snapshot and file system names are
3456 set when the stream is received.
3459 flag is specified when this stream is received, snapshots and file systems that
3460 do not exist on the sending side are destroyed.
3462 Generate a more compact stream by using
3464 records for blocks which are stored more compactly on disk by the
3467 This flag has no effect if the
3469 feature is disabled.
3470 The receiving system must have the
3475 feature is active on the sending system, then the receiving system must have
3476 that feature enabled as well. Datasets that are sent with this flag may not be
3477 received as an encrypted dataset, since encrypted datasets cannot use the
3481 .Xr zpool-features 5
3482 for details on ZFS feature flags and the
3486 Sends only received property values whether or not they are overridden by local
3487 settings, but only if the dataset has ever been received. Use this option when
3490 to restore received properties backed up on the sent dataset and to avoid
3491 sending local settings that may have nothing to do with the source dataset,
3492 but only with how the data is backed up.
3493 .It Fl c, -compressed
3494 Generate a more compact stream by using compressed WRITE records for blocks
3495 which are compressed on disk and in memory
3498 property for details
3502 feature is active on the sending system, then the receiving system must have
3503 that feature enabled as well.
3506 feature is enabled on the sending system but the
3508 option is not supplied in conjunction with
3510 then the data will be decompressed before sending so it can be split into
3511 smaller block sizes.
3513 For encrypted datasets, send data exactly as it exists on disk. This allows
3514 backups to be taken even if encryption keys are not currently loaded. The
3515 backup may then be received on an untrusted machine since that machine will
3516 not have the encryption keys to read the protected data or alter it without
3517 being detected. Upon being received, the dataset will have the same encryption
3518 keys as it did on the send side, although the
3520 property will be defaulted to
3522 if not otherwise provided. For unencrypted datasets, this flag will be
3525 Note that if you do not use this flag for sending encrypted datasets, data will
3526 be sent unencrypted and may be re-encrypted with a different encryption key on
3527 the receiving system, which will disable the ability to do a raw send to that
3528 system for incrementals.
3529 .It Fl i Ar snapshot
3530 Generate an incremental stream from the first
3532 .Pq the incremental source
3535 .Pq the incremental target .
3536 The incremental source can be specified as the last component of the snapshot
3540 character and following
3542 and it is assumed to be from the same file system as the incremental target.
3544 If the destination is a clone, the source may be the origin snapshot, which must
3547 .Em pool/fs@origin ,
3555 Do not generate any actual send data.
3556 This is useful in conjunction with the
3560 flags to determine what data will be sent.
3561 In this case, the verbose output will be written to standard output
3562 .Po contrast with a non-dry-run, where the stream is written to standard output
3563 and the verbose output goes to standard error
3566 Include the dataset's properties in the stream.
3567 This flag is implicit when
3570 The receiving system must also support this feature. Sends of encrypted datasets
3573 when using this flag.
3575 Print verbose information about the stream package generated.
3576 This information includes a per-second report of how much data has been sent.
3578 The format of the stream is committed.
3579 You will be able to receive your streams on future versions of ZFS.
3585 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3586 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3588 Generate a send stream, which may be of a filesystem, and may be incremental
3590 If the destination is a filesystem or volume, the pool must be read-only, or the
3591 filesystem must not be mounted.
3592 When the stream generated from a filesystem or volume is received, the default
3593 snapshot name will be
3595 .Bl -tag -width "-L"
3596 .It Fl L, -large-block
3597 Generate a stream which may contain blocks larger than 128KB.
3598 This flag has no effect if the
3600 pool feature is disabled, or if the
3602 property of this filesystem has never been set above 128KB.
3603 The receiving system must have the
3605 pool feature enabled as well.
3607 .Xr zpool-features 5
3608 for details on ZFS feature flags and the
3612 Print machine-parsable verbose information about the stream package generated.
3613 .It Fl c, -compressed
3614 Generate a more compact stream by using compressed WRITE records for blocks
3615 which are compressed on disk and in memory
3618 property for details
3622 feature is active on the sending system, then the receiving system must have
3623 that feature enabled as well.
3626 feature is enabled on the sending system but the
3628 option is not supplied in conjunction with
3630 then the data will be decompressed before sending so it can be split into
3631 smaller block sizes.
3633 For encrypted datasets, send data exactly as it exists on disk. This allows
3634 backups to be taken even if encryption keys are not currently loaded. The
3635 backup may then be received on an untrusted machine since that machine will
3636 not have the encryption keys to read the protected data or alter it without
3637 being detected. Upon being received, the dataset will have the same encryption
3638 keys as it did on the send side, although the
3640 property will be defaulted to
3642 if not otherwise provided. For unencrypted datasets, this flag will be
3645 Note that if you do not use this flag for sending encrypted datasets, data will
3646 be sent unencrypted and may be re-encrypted with a different encryption key on
3647 the receiving system, which will disable the ability to do a raw send to that
3648 system for incrementals.
3650 Generate a more compact stream by using
3652 records for blocks which are stored more compactly on disk by the
3655 This flag has no effect if the
3657 feature is disabled.
3658 The receiving system must have the
3663 feature is active on the sending system, then the receiving system must have
3664 that feature enabled as well. Datasets that are sent with this flag may not be
3665 received as an encrypted dataset, since encrypted datasets cannot use the
3669 .Xr zpool-features 5
3670 for details on ZFS feature flags and the
3673 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3674 Generate an incremental send stream.
3675 The incremental source must be an earlier snapshot in the destination's history.
3676 It will commonly be an earlier snapshot in the destination's file system, in
3677 which case it can be specified as the last component of the name
3682 character and following
3685 If the incremental target is a clone, the incremental source can be the origin
3686 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3692 Do not generate any actual send data.
3693 This is useful in conjunction with the
3697 flags to determine what data will be sent.
3698 In this case, the verbose output will be written to standard output
3699 .Po contrast with a non-dry-run, where the stream is written to standard output
3700 and the verbose output goes to standard error
3703 Print verbose information about the stream package generated.
3704 This information includes a per-second report of how much data has been sent.
3711 .Ar receive_resume_token
3713 Creates a send stream which resumes an interrupted receive.
3715 .Ar receive_resume_token
3716 is the value of this property on the filesystem or volume that was being
3718 See the documentation for
3725 .Op Fl o Sy origin Ns = Ns Ar snapshot
3726 .Op Fl o Ar property Ns = Ns Ar value
3727 .Op Fl x Ar property
3728 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3734 .Op Fl d Ns | Ns Fl e
3735 .Op Fl o Sy origin Ns = Ns Ar snapshot
3736 .Op Fl o Ar property Ns = Ns Ar value
3737 .Op Fl x Ar property
3740 Creates a snapshot whose contents are as specified in the stream provided on
3742 If a full stream is received, then a new file system is created as well.
3743 Streams are created using the
3745 subcommand, which by default creates a full stream.
3747 can be used as an alias for
3750 If an incremental stream is received, then the destination file system must
3751 already exist, and its most recent snapshot must match the incremental stream's
3755 the destination device link is destroyed and recreated, which means the
3757 cannot be accessed during the
3761 When a snapshot replication package stream that is generated by using the
3762 .Nm zfs Cm send Fl R
3763 command is received, any snapshots that do not exist on the sending location are
3764 destroyed by using the
3765 .Nm zfs Cm destroy Fl d
3769 .Fl o Em property Ns = Ns Ar value
3772 is specified, it applies to the effective value of the property throughout
3773 the entire subtree of replicated datasets. Effective property values will be
3778 ) on the topmost in the replicated subtree. In descendant datasets, if the
3779 property is set by the send stream, it will be overridden by forcing the
3780 property to be inherited from the top‐most file system. Received properties
3781 are retained in spite of being overridden and may be restored with
3782 .Nm zfs Cm inherit Fl S .
3784 .Fl o Sy origin Ns = Ns Em snapshot
3785 is a special case because, even if
3787 is a read-only property and cannot be set, it's allowed to receive the send
3788 stream as a clone of the given snapshot.
3790 Raw encrypted send streams (created with
3791 .Nm zfs Cm send Fl w
3792 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3793 recompressed by the receive process. Unencrypted streams can be received as
3794 encrypted datasets, either through inheritance or by specifying encryption
3799 The name of the snapshot
3800 .Pq and file system, if a full stream is received
3801 that this subcommand creates depends on the argument type and the use of the
3807 If the argument is a snapshot name, the specified
3810 If the argument is a file system or volume name, a snapshot with the same name
3811 as the sent snapshot is created within the specified
3819 options are specified, the provided target snapshot name is used exactly as
3826 options cause the file system name of the target snapshot to be determined by
3827 appending a portion of the sent snapshot's name to the specified target
3831 option is specified, all but the first element of the sent snapshot's file
3833 .Pq usually the pool name
3834 is used and any required intermediate file systems within the specified one are
3838 option is specified, then only the last element of the sent snapshot's file
3840 .Pq i.e. the name of the source file system itself
3841 is used as the target file system name.
3842 .Bl -tag -width "-F"
3844 Force a rollback of the file system to the most recent snapshot before
3845 performing the receive operation.
3846 If receiving an incremental replication stream
3847 .Po for example, one generated by
3848 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3850 destroy snapshots and file systems that do not exist on the sending side.
3852 Discard the first element of the sent snapshot's file system name, using the
3853 remaining elements to determine the name of the target file system for the new
3854 snapshot as described in the paragraph above.
3856 Discard all but the last element of the sent snapshot's file system name, using
3857 that element to determine the name of the target file system for the new
3858 snapshot as described in the paragraph above.
3860 Do not actually receive the stream.
3861 This can be useful in conjunction with the
3863 option to verify the name the receive operation would use.
3864 .It Fl o Sy origin Ns = Ns Ar snapshot
3865 Forces the stream to be received as a clone of the given snapshot.
3866 If the stream is a full send stream, this will create the filesystem
3867 described by the stream as a clone of the specified snapshot.
3868 Which snapshot was specified will not affect the success or failure of the
3869 receive, as long as the snapshot does exist.
3870 If the stream is an incremental send stream, all the normal verification will be
3872 .It Fl o Em property Ns = Ns Ar value
3873 Sets the specified property as if the command
3874 .Nm zfs Cm set Em property Ns = Ns Ar value
3875 was invoked immediately before the receive. When receiving a stream from
3876 .Nm zfs Cm send Fl R ,
3877 causes the property to be inherited by all descendant datasets, as through
3878 .Nm zfs Cm inherit Em property
3879 was run on any descendant datasets that have this property set on the
3882 Any editable property can be set at receive time. Set-once properties bound
3883 to the received data, such as
3886 .Sy casesensitivity ,
3887 cannot be set at receive time even when the datasets are newly created by
3888 .Nm zfs Cm receive .
3889 Additionally both settable properties
3893 cannot be set at receive time.
3897 option may be specified multiple times, for different properties. An error
3898 results if the same property is specified in multiple
3904 If the receive is interrupted, save the partially received state, rather
3906 Interruption may be due to premature termination of the stream
3907 .Po e.g. due to network failure or failure of the remote system
3908 if the stream is being read over a network connection
3910 a checksum error in the stream, termination of the
3912 process, or unclean shutdown of the system.
3914 The receive can be resumed with a stream generated by
3915 .Nm zfs Cm send Fl t Ar token ,
3919 .Sy receive_resume_token
3920 property of the filesystem or volume which is received into.
3922 To use this flag, the storage pool must have the
3923 .Sy extensible_dataset
3926 .Xr zpool-features 5
3927 for details on ZFS feature flags.
3929 File system that is associated with the received stream is not mounted.
3931 Print verbose information about the stream and the time required to perform the
3933 .It Fl x Em property
3934 Ensures that the effective value of the specified property after the
3935 receive is unaffected by the value of that property in the send stream (if any),
3936 as if the property had been excluded from the send stream.
3938 If the specified property is not present in the send stream, this option does
3941 If a received property needs to be overridden, the effective value will be
3942 set or inherited, depending on whether the property is inheritable or not.
3944 In the case of an incremental update,
3946 leaves any existing local setting or explicit inheritance unchanged.
3950 restrictions on set-once and special properties apply equally to
3957 .Ar filesystem Ns | Ns Ar volume
3959 Abort an interrupted
3960 .Nm zfs Cm receive Fl s ,
3961 deleting its saved partially received state.
3965 .Ar filesystem Ns | Ns Ar volume
3967 Displays permissions that have been delegated on the specified filesystem or
3969 See the other forms of
3971 for more information.
3973 Delegations are supported under Linux with the exception of
3981 These permissions cannot be delegated because the Linux
3983 command restricts modifications of the global namespace to the root user.
3988 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3989 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3990 .Ar setname Oc Ns ...
3991 .Ar filesystem Ns | Ns Ar volume
3996 .Fl e Ns | Ns Sy everyone
3997 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3998 .Ar setname Oc Ns ...
3999 .Ar filesystem Ns | Ns Ar volume
4001 Delegates ZFS administration permission for the file systems to non-privileged
4003 .Bl -tag -width "-d"
4005 Allow only for the descendent file systems.
4006 .It Fl e Ns | Ns Sy everyone
4007 Specifies that the permissions be delegated to everyone.
4008 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
4009 Explicitly specify that permissions are delegated to the group.
4013 only for the specified file system.
4014 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
4015 Explicitly specify that permissions are delegated to the user.
4016 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4017 Specifies to whom the permissions are delegated.
4018 Multiple entities can be specified as a comma-separated list.
4021 options are specified, then the argument is interpreted preferentially as the
4024 then as a user name, and lastly as a group name.
4025 To specify a user or group named
4032 To specify a group with the same name as a user, use the
4036 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4037 .Ar setname Oc Ns ...
4039 The permissions to delegate.
4040 Multiple permissions may be specified as a comma-separated list.
4041 Permission names are the same as ZFS subcommand and property names.
4042 See the property list below.
4043 Property set names, which begin with
4048 form below for details.
4053 options are specified, or both are, then the permissions are allowed for the
4054 file system or volume, and all of its descendents.
4056 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
4058 The following permissions are available:
4061 allow subcommand Must also have the permission that is
4063 clone subcommand Must also have the 'create' ability and
4064 'mount' ability in the origin file system
4065 create subcommand Must also have the 'mount' ability
4066 destroy subcommand Must also have the 'mount' ability
4067 diff subcommand Allows lookup of paths within a dataset
4068 given an object number, and the ability
4069 to create snapshots necessary to
4071 load-key subcommand Allows loading and unloading of encryption key
4072 (see 'zfs load-key' and 'zfs unload-key').
4073 change-key subcommand Allows changing an encryption key via
4075 mount subcommand Allows mount/umount of ZFS datasets
4076 promote subcommand Must also have the 'mount' and 'promote'
4077 ability in the origin file system
4078 receive subcommand Must also have the 'mount' and 'create'
4080 rename subcommand Must also have the 'mount' and 'create'
4081 ability in the new parent
4082 rollback subcommand Must also have the 'mount' ability
4084 share subcommand Allows sharing file systems over NFS
4086 snapshot subcommand Must also have the 'mount' ability
4088 groupquota other Allows accessing any groupquota@...
4090 groupused other Allows reading any groupused@... property
4091 userprop other Allows changing any user property
4092 userquota other Allows accessing any userquota@...
4094 userused other Allows reading any userused@... property
4095 projectobjquota other Allows accessing any projectobjquota@...
4097 projectquota other Allows accessing any projectquota@... property
4098 projectobjused other Allows reading any projectobjused@... property
4099 projectused other Allows reading any projectused@... property
4105 casesensitivity property
4107 compression property
4111 filesystem_limit property
4114 normalization property
4115 primarycache property
4120 refreservation property
4121 reservation property
4122 secondarycache property
4127 snapshot_limit property
4130 volblocksize property
4140 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4141 .Ar setname Oc Ns ...
4142 .Ar filesystem Ns | Ns Ar volume
4147 These permissions are granted
4149 to the creator of any newly-created descendent file system.
4153 .Fl s No @ Ns Ar setname
4154 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4155 .Ar setname Oc Ns ...
4156 .Ar filesystem Ns | Ns Ar volume
4158 Defines or adds permissions to a permission set.
4159 The set can be used by other
4161 commands for the specified file system and its descendents.
4162 Sets are evaluated dynamically, so changes to a set are immediately reflected.
4163 Permission sets follow the same naming restrictions as ZFS file systems, but the
4164 name must begin with
4166 and can be no more than 64 characters long.
4171 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
4172 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4173 .Ar setname Oc Ns ... Oc
4174 .Ar filesystem Ns | Ns Ar volume
4179 .Fl e Ns | Ns Sy everyone
4180 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4181 .Ar setname Oc Ns ... Oc
4182 .Ar filesystem Ns | Ns Ar volume
4188 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4189 .Ar setname Oc Ns ... Oc
4190 .Ar filesystem Ns | Ns Ar volume
4192 Removes permissions that were granted with the
4195 No permissions are explicitly denied, so other permissions granted are still in
4197 For example, if the permission is granted by an ancestor.
4198 If no permissions are specified, then all permissions for the specified
4210 only removes the permissions that were granted to everyone, not all permissions
4211 for every user and group.
4214 command for a description of the
4217 .Bl -tag -width "-r"
4219 Recursively remove the permissions from this file system and all descendents.
4225 .Fl s No @ Ns Ar setname
4226 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
4227 .Ar setname Oc Ns ... Oc
4228 .Ar filesystem Ns | Ns Ar volume
4230 Removes permissions from a permission set.
4231 If no permissions are specified, then all permissions are removed, thus removing
4237 .Ar tag Ar snapshot Ns ...
4239 Adds a single reference, named with the
4241 argument, to the specified snapshot or snapshots.
4242 Each snapshot has its own tag namespace, and tags must be unique within that
4245 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4249 .Bl -tag -width "-r"
4251 Specifies that a hold with the given tag is applied recursively to the snapshots
4252 of all descendent file systems.
4260 Lists all existing user references for the given snapshot or snapshots.
4261 .Bl -tag -width "-r"
4263 Lists the holds that are set on the named descendent snapshots, in addition to
4264 listing the holds on the named snapshot.
4270 .Ar tag Ar snapshot Ns ...
4272 Removes a single reference, named with the
4274 argument, from the specified snapshot or snapshots.
4275 The tag must already exist for each snapshot.
4276 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
4280 .Bl -tag -width "-r"
4282 Recursively releases a hold with the given tag on the snapshots of all
4283 descendent file systems.
4289 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4291 Display the difference between a snapshot of a given filesystem and another
4292 snapshot of that filesystem from a later time or the current contents of the
4294 The first column is a character indicating the type of change, the other columns
4295 indicate pathname, new pathname
4296 .Pq in case of rename ,
4297 change in link count, and optionally file type and/or change time.
4298 The types of change are:
4300 - The path has been removed
4301 + The path has been created
4302 M The path has been modified
4303 R The path has been renamed
4305 .Bl -tag -width "-F"
4307 Display an indication of the type of file, in a manner similar to the
4323 Give more parsable tab-separated output, without header lines and without
4326 Display the path's inode change time as the first column of output.
4333 .Op Fl m Ar memory_limit
4339 as a ZFS channel program on
4342 program interface allows ZFS administrative operations to be run
4343 programmatically via a Lua script.
4344 The entire script is executed atomically, with no other administrative
4345 operations taking effect concurrently.
4346 A library of ZFS calls is made available to channel program scripts.
4347 Channel programs may only be run with root privileges.
4349 For full documentation of the ZFS channel program interface, see the manual
4354 Display channel program output in JSON format. When this flag is specified and
4355 standard output is empty - channel program encountered an error. The details of
4356 such an error will be printed to standard error in plain text.
4358 Executes a read-only channel program, which runs faster.
4359 The program cannot change on-disk state by calling functions from
4360 the zfs.sync submodule.
4361 The program can be used to gather information such as properties and
4362 determining if changes would succeed (zfs.check.*).
4363 Without this flag, all pending changes must be synced to disk before
4364 a channel program can complete.
4366 Execution time limit, in milliseconds.
4367 If a channel program executes for longer than the provided timeout, it will
4368 be stopped and an error will be returned.
4369 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
4370 .It Fl m Ar memory-limit
4371 Memory limit, in bytes.
4372 If a channel program attempts to allocate more memory than the given limit,
4373 it will be stopped and an error returned.
4374 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4376 All remaining argument strings are passed directly to the channel program as
4380 for more information.
4386 .Op Fl L Ar keylocation
4387 .Fl a | Ar filesystem
4391 allowing it and all children that inherit the
4393 property to be accessed. The key will be expected in the format specified by the
4395 and location specified by the
4397 property. Note that if the
4401 the terminal will interactively wait for the key to be entered. Loading a key
4402 will not automatically mount the dataset. If that functionality is desired,
4403 .Nm zfs Cm mount Sy -l
4404 will ask for the key and mount the dataset. Once the key is loaded the
4406 property will become
4408 .Bl -tag -width "-r"
4410 Recursively loads the keys for the specified filesystem and all descendent
4413 Loads the keys for all encryption roots in all imported pools.
4417 load-key. This will cause zfs to simply check that the
4418 provided key is correct. This command may be run even if the key is already
4420 .It Fl L Ar keylocation
4425 property. This will not change the value of the property on the dataset. Note
4426 that if used with either
4431 may only be given as
4438 .Fl a | Ar filesystem
4440 Unloads a key from ZFS, removing the ability to access the dataset and all of
4441 its children that inherit the
4443 property. This requires that the dataset is not currently open or mounted. Once
4444 the key is unloaded the
4446 property will become
4448 .Bl -tag -width "-r"
4450 Recursively unloads the keys for the specified filesystem and all descendent
4453 Unloads the keys for all encryption roots in all imported pools.
4459 .Op Fl o Ar keylocation Ns = Ns Ar value
4460 .Op Fl o Ar keyformat Ns = Ns Ar value
4461 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4471 Allows a user to change the encryption key used to access a dataset. This
4472 command requires that the existing key for the dataset is already loaded into
4473 ZFS. This command may also be used to change the
4478 properties as needed. If the dataset was not previously an encryption root it
4479 will become one. Alternatively, the
4481 flag may be provided to cause an encryption root to inherit the parent's key
4483 .Bl -tag -width "-r"
4485 Ensures the key is loaded before attempting to change the key. This is
4486 effectively equivalent to
4487 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4488 .It Fl o Ar property Ns = Ns Ar value
4489 Allows the user to set encryption key properties (
4494 ) while changing the key. This is the only way to alter
4498 after the dataset has been created.
4500 Indicates that zfs should make
4502 inherit the key of its parent. Note that this command can only be run on an
4503 encryption root that has an encrypted parent.
4509 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4510 options were specified.
4513 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4514 The following commands create a file system named
4516 and a file system named
4520 is set for the parent file system, and is automatically inherited by the child
4523 # zfs create pool/home
4524 # zfs set mountpoint=/export/home pool/home
4525 # zfs create pool/home/bob
4527 .It Sy Example 2 No Creating a ZFS Snapshot
4528 The following command creates a snapshot named
4530 This snapshot is mounted on demand in the
4532 directory at the root of the
4536 # zfs snapshot pool/home/bob@yesterday
4538 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4539 The following command creates snapshots named
4543 and all of its descendent file systems.
4544 Each snapshot is mounted on demand in the
4546 directory at the root of its file system.
4547 The second command destroys the newly created snapshots.
4549 # zfs snapshot -r pool/home@yesterday
4550 # zfs destroy -r pool/home@yesterday
4552 .It Sy Example 4 No Disabling and Enabling File System Compression
4553 The following command disables the
4555 property for all file systems under
4557 The next command explicitly enables
4560 .Em pool/home/anne .
4562 # zfs set compression=off pool/home
4563 # zfs set compression=on pool/home/anne
4565 .It Sy Example 5 No Listing ZFS Datasets
4566 The following command lists all active file systems and volumes in the system.
4567 Snapshots are displayed if the
4575 for more information on pool properties.
4578 NAME USED AVAIL REFER MOUNTPOINT
4579 pool 450K 457G 18K /pool
4580 pool/home 315K 457G 21K /export/home
4581 pool/home/anne 18K 457G 18K /export/home/anne
4582 pool/home/bob 276K 457G 276K /export/home/bob
4584 .It Sy Example 6 No Setting a Quota on a ZFS File System
4585 The following command sets a quota of 50 Gbytes for
4588 # zfs set quota=50G pool/home/bob
4590 .It Sy Example 7 No Listing ZFS Properties
4591 The following command lists all properties for
4594 # zfs get all pool/home/bob
4595 NAME PROPERTY VALUE SOURCE
4596 pool/home/bob type filesystem -
4597 pool/home/bob creation Tue Jul 21 15:53 2009 -
4598 pool/home/bob used 21K -
4599 pool/home/bob available 20.0G -
4600 pool/home/bob referenced 21K -
4601 pool/home/bob compressratio 1.00x -
4602 pool/home/bob mounted yes -
4603 pool/home/bob quota 20G local
4604 pool/home/bob reservation none default
4605 pool/home/bob recordsize 128K default
4606 pool/home/bob mountpoint /pool/home/bob default
4607 pool/home/bob sharenfs off default
4608 pool/home/bob checksum on default
4609 pool/home/bob compression on local
4610 pool/home/bob atime on default
4611 pool/home/bob devices on default
4612 pool/home/bob exec on default
4613 pool/home/bob setuid on default
4614 pool/home/bob readonly off default
4615 pool/home/bob zoned off default
4616 pool/home/bob snapdir hidden default
4617 pool/home/bob acltype off default
4618 pool/home/bob aclinherit restricted default
4619 pool/home/bob canmount on default
4620 pool/home/bob xattr on default
4621 pool/home/bob copies 1 default
4622 pool/home/bob version 4 -
4623 pool/home/bob utf8only off -
4624 pool/home/bob normalization none -
4625 pool/home/bob casesensitivity sensitive -
4626 pool/home/bob vscan off default
4627 pool/home/bob nbmand off default
4628 pool/home/bob sharesmb off default
4629 pool/home/bob refquota none default
4630 pool/home/bob refreservation none default
4631 pool/home/bob primarycache all default
4632 pool/home/bob secondarycache all default
4633 pool/home/bob usedbysnapshots 0 -
4634 pool/home/bob usedbydataset 21K -
4635 pool/home/bob usedbychildren 0 -
4636 pool/home/bob usedbyrefreservation 0 -
4639 The following command gets a single property value.
4641 # zfs get -H -o value compression pool/home/bob
4644 The following command lists all properties with local settings for
4647 # zfs get -r -s local -o name,property,value all pool/home/bob
4649 pool/home/bob quota 20G
4650 pool/home/bob compression on
4652 .It Sy Example 8 No Rolling Back a ZFS File System
4653 The following command reverts the contents of
4655 to the snapshot named
4657 deleting all intermediate snapshots.
4659 # zfs rollback -r pool/home/anne@yesterday
4661 .It Sy Example 9 No Creating a ZFS Clone
4662 The following command creates a writable file system whose initial contents are
4664 .Em pool/home/bob@yesterday .
4666 # zfs clone pool/home/bob@yesterday pool/clone
4668 .It Sy Example 10 No Promoting a ZFS Clone
4669 The following commands illustrate how to test out changes to a file system, and
4670 then replace the original file system with the changed one, using clones, clone
4671 promotion, and renaming:
4673 # zfs create pool/project/production
4674 populate /pool/project/production with data
4675 # zfs snapshot pool/project/production@today
4676 # zfs clone pool/project/production@today pool/project/beta
4677 make changes to /pool/project/beta and test them
4678 # zfs promote pool/project/beta
4679 # zfs rename pool/project/production pool/project/legacy
4680 # zfs rename pool/project/beta pool/project/production
4681 once the legacy version is no longer needed, it can be destroyed
4682 # zfs destroy pool/project/legacy
4684 .It Sy Example 11 No Inheriting ZFS Properties
4685 The following command causes
4691 property from their parent.
4693 # zfs inherit checksum pool/home/bob pool/home/anne
4695 .It Sy Example 12 No Remotely Replicating ZFS Data
4696 The following commands send a full stream and then an incremental stream to a
4697 remote machine, restoring them into
4698 .Em poolB/received/fs@a
4700 .Em poolB/received/fs@b ,
4703 must contain the file system
4704 .Em poolB/received ,
4705 and must not initially contain
4706 .Em poolB/received/fs .
4708 # zfs send pool/fs@a | \e
4709 ssh host zfs receive poolB/received/fs@a
4710 # zfs send -i a pool/fs@b | \e
4711 ssh host zfs receive poolB/received/fs
4713 .It Sy Example 13 No Using the zfs receive -d Option
4714 The following command sends a full stream of
4715 .Em poolA/fsA/fsB@snap
4716 to a remote machine, receiving it into
4717 .Em poolB/received/fsA/fsB@snap .
4720 portion of the received snapshot's name is determined from the name of the sent
4723 must contain the file system
4724 .Em poolB/received .
4726 .Em poolB/received/fsA
4727 does not exist, it is created as an empty file system.
4729 # zfs send poolA/fsA/fsB@snap | \e
4730 ssh host zfs receive -d poolB/received
4732 .It Sy Example 14 No Setting User Properties
4733 The following example sets the user-defined
4734 .Sy com.example:department
4735 property for a dataset.
4737 # zfs set com.example:department=12345 tank/accounting
4739 .It Sy Example 15 No Performing a Rolling Snapshot
4740 The following example shows how to maintain a history of snapshots with a
4741 consistent naming scheme.
4742 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4743 renames the remaining snapshots, and then creates a new snapshot, as follows:
4745 # zfs destroy -r pool/users@7daysago
4746 # zfs rename -r pool/users@6daysago @7daysago
4747 # zfs rename -r pool/users@5daysago @6daysago
4748 # zfs rename -r pool/users@yesterday @5daysago
4749 # zfs rename -r pool/users@yesterday @4daysago
4750 # zfs rename -r pool/users@yesterday @3daysago
4751 # zfs rename -r pool/users@yesterday @2daysago
4752 # zfs rename -r pool/users@today @yesterday
4753 # zfs snapshot -r pool/users@today
4755 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4756 The following commands show how to set
4758 property options to enable
4762 addresses and to enable root access for system
4768 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4773 for host name resolution, specify the fully qualified hostname.
4774 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4775 The following example shows how to set permissions so that user
4777 can create, destroy, mount, and take snapshots on
4783 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4784 # zfs allow tank/cindys
4785 ---- Permissions on tank/cindys --------------------------------------
4786 Local+Descendent permissions:
4787 user cindys create,destroy,mount,snapshot
4792 mount point permission is set to 755 by default, user
4794 will be unable to mount file systems under
4796 Add an ACE similar to the following syntax to provide mount point access:
4798 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4800 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4801 The following example shows how to grant anyone in the group
4803 to create file systems in
4805 This syntax also allows staff members to destroy their own file systems, but not
4806 destroy anyone else's file system.
4811 # zfs allow staff create,mount tank/users
4812 # zfs allow -c destroy tank/users
4813 # zfs allow tank/users
4814 ---- Permissions on tank/users ---------------------------------------
4817 Local+Descendent permissions:
4818 group staff create,mount
4820 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4821 The following example shows how to define and grant a permission set on the
4828 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4829 # zfs allow staff @pset tank/users
4830 # zfs allow tank/users
4831 ---- Permissions on tank/users ---------------------------------------
4833 @pset create,destroy,mount,snapshot
4834 Local+Descendent permissions:
4837 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4838 The following example shows to grant the ability to set quotas and reservations
4846 # zfs allow cindys quota,reservation users/home
4847 # zfs allow users/home
4848 ---- Permissions on users/home ---------------------------------------
4849 Local+Descendent permissions:
4850 user cindys quota,reservation
4851 cindys% zfs set quota=10G users/home/marks
4852 cindys% zfs get quota users/home/marks
4853 NAME PROPERTY VALUE SOURCE
4854 users/home/marks quota 10G local
4856 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4857 The following example shows how to remove the snapshot permission from the
4866 # zfs unallow staff snapshot tank/users
4867 # zfs allow tank/users
4868 ---- Permissions on tank/users ---------------------------------------
4870 @pset create,destroy,mount,snapshot
4871 Local+Descendent permissions:
4874 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4875 The following example shows how to see what has changed between a prior
4876 snapshot of a ZFS dataset and its current state.
4879 option is used to indicate type information for the files affected.
4881 # zfs diff -F tank/test@before tank/test
4883 M F /tank/test/linked (+1)
4884 R F /tank/test/oldname -> /tank/test/newname
4885 - F /tank/test/deleted
4886 + F /tank/test/created
4887 M F /tank/test/modified
4889 .It Sy Example 23 No Creating a bookmark
4890 The following example create a bookmark to a snapshot. This bookmark
4891 can then be used instead of snapshot in send streams.
4893 # zfs bookmark rpool@snapshot rpool#bookmark
4895 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4896 The following example show how to share SMB filesystem through ZFS. Note that
4897 that a user and his/her password must be given.
4899 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4900 -o user=workgroup/turbo,password=obrut,uid=1000
4904 .Em /etc/samba/smb.conf
4905 configuration required:
4907 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4908 communicate with Samba. This is the default behavior for most Linux
4911 Samba must be able to authenticate a user. This can be done in a number of
4912 ways, depending on if using the system password file, LDAP or the Samba
4913 specific smbpasswd file. How to do this is outside the scope of this manual.
4916 man page for more information.
4919 .Sy USERSHARE section
4922 man page for all configuration options in case you need to modify any options
4923 to the share afterwards. Do note that any changes done with the
4925 command will be undone if the share is ever unshared (such as at a reboot etc).
4927 .Sh INTERFACE STABILITY
projects / zfs / blob