4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
22 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
23 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
24 .\" Copyright (c) 2011, 2017 by Delphix. All rights reserved.
25 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
26 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
27 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
28 .\" Copyright (c) 2014 Integros [integros.com]
29 .\" Copyright 2016 Richard Laager. All rights reserved.
30 .\" Copyright 2017 Nexenta Systems, Inc.
37 .Nd configures ZFS file systems
44 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
50 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
51 .Fl V Ar size Ar volume
55 .Ar filesystem Ns | Ns Ar volume
59 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
60 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
63 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
67 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
68 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
76 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
77 .Ar snapshot Ar filesystem Ns | Ns Ar volume
84 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
89 .Ar filesystem Ns | Ns Ar volume
90 .Ar filesystem Ns | Ns Ar volume
94 .Ar snapshot Ar snapshot
97 .Op Fl r Ns | Ns Fl d Ar depth
99 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
100 .Oo Fl s Ar property Oc Ns ...
101 .Oo Fl S Ar property Oc Ns ...
102 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
103 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
106 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
107 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
110 .Op Fl r Ns | Ns Fl d Ar depth
112 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
113 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
114 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
115 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
116 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
120 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
130 .Fl a | Ar filesystem
134 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
135 .Oo Fl s Ar field Oc Ns ...
136 .Oo Fl S Ar field Oc Ns ...
137 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
138 .Ar filesystem Ns | Ns Ar snapshot
142 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
143 .Oo Fl s Ar field Oc Ns ...
144 .Oo Fl S Ar field Oc Ns ...
145 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
146 .Ar filesystem Ns | Ns Ar snapshot
153 .Fl a | Ar filesystem
157 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
160 .Fl a | Ar filesystem
163 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
166 .Ar snapshot bookmark
170 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
175 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
176 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
180 .Fl t Ar receive_resume_token
184 .Op Fl o Sy origin Ns = Ns Ar snapshot
185 .Op Fl o Ar property Ns = Ns Ar value
187 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
191 .Op Fl d Ns | Ns Fl e
192 .Op Fl o Sy origin Ns = Ns Ar snapshot
193 .Op Fl o Ar property Ns = Ns Ar value
199 .Ar filesystem Ns | Ns Ar volume
202 .Ar filesystem Ns | Ns Ar volume
206 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
207 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
208 .Ar setname Oc Ns ...
209 .Ar filesystem Ns | Ns Ar volume
213 .Fl e Ns | Ns Sy everyone
214 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
215 .Ar setname Oc Ns ...
216 .Ar filesystem Ns | Ns Ar volume
220 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
221 .Ar setname Oc Ns ...
222 .Ar filesystem Ns | Ns Ar volume
225 .Fl s No @ Ns Ar setname
226 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
227 .Ar setname Oc Ns ...
228 .Ar filesystem Ns | Ns Ar volume
232 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
233 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
234 .Ar setname Oc Ns ... Oc
235 .Ar filesystem Ns | Ns Ar volume
239 .Fl e Ns | Ns Sy everyone
240 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
241 .Ar setname Oc Ns ... Oc
242 .Ar filesystem Ns | Ns Ar volume
247 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
248 .Ar setname Oc Ns ... Oc
249 .Ar filesystem Ns | Ns Ar volume
253 .Fl s @ Ns Ar setname
254 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
255 .Ar setname Oc Ns ... Oc
256 .Ar filesystem Ns | Ns Ar volume
260 .Ar tag Ar snapshot Ns ...
268 .Ar tag Ar snapshot Ns ...
272 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
277 .Op Fl m Ar memory_limit
283 .Op Fl L Ar keylocation
284 .Fl a | Ar filesystem
288 .Fl a | Ar filesystem
292 .Op Fl o Ar keylocation Ns = Ns Ar value
293 .Op Fl o Ar keyformat Ns = Ns Ar value
294 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
304 command configures ZFS datasets within a ZFS storage pool, as described in
306 A dataset is identified by a unique path within the ZFS namespace.
309 pool/{filesystem,volume,snapshot}
312 where the maximum length of a dataset name is
316 A dataset can be one of the following:
317 .Bl -tag -width "file system"
319 A ZFS dataset of type
321 can be mounted within the standard system namespace and behaves like other file
323 While ZFS file systems are designed to be POSIX compliant, known issues exist
324 that prevent compliance in some cases.
325 Applications that depend on standards conformance might fail due to non-standard
326 behavior when checking file system free space.
328 A logical volume exported as a raw or block device.
329 This type of dataset should only be used under special circumstances.
330 File systems are typically used in most environments.
332 A read-only version of a file system or volume at a given point in time.
334 .Ar filesystem Ns @ Ns Ar name
336 .Ar volume Ns @ Ns Ar name .
340 but without the hold on on-disk data. It can be used as the source of a send
341 (but not for a receive). It is specified as
342 .Ar filesystem Ns # Ns Ar name
344 .Ar volume Ns # Ns Ar name .
346 .Ss ZFS File System Hierarchy
347 A ZFS storage pool is a logical collection of devices that provide space for
349 A storage pool is also the root of the ZFS file system hierarchy.
351 The root of the pool can be accessed as a file system, such as mounting and
352 unmounting, taking snapshots, and setting properties.
353 The physical storage characteristics, however, are managed by the
359 for more information on creating and administering pools.
361 A snapshot is a read-only copy of a file system or volume.
362 Snapshots can be created extremely quickly, and initially consume no additional
363 space within the pool.
364 As data within the active dataset changes, the snapshot consumes more data than
365 would otherwise be shared with the active dataset.
367 Snapshots can have arbitrary names.
368 Snapshots of volumes can be cloned or rolled back, visibility is determined
371 property of the parent volume.
373 File system snapshots can be accessed under the
375 directory in the root of the file system.
376 Snapshots are automatically mounted on demand and may be unmounted at regular
378 The visibility of the
380 directory can be controlled by the
384 A bookmark is like a snapshot, a read-only copy of a file system or volume.
385 Bookmarks can be created extremely quickly, compared to snapshots, and they
386 consume no additional space within the pool. Bookmarks can also have arbitrary
387 names, much like snapshots.
389 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
390 way. From a storage standpoint a bookmark just provides a way to reference
391 when a snapshot was created as a distinct object. Bookmarks are initially
392 tied to a snapshot, not the filesystem or volume, and they will survive if the
393 snapshot itself is destroyed. Since they are very light weight there's little
394 incentive to destroy them.
396 A clone is a writable volume or file system whose initial contents are the same
398 As with snapshots, creating a clone is nearly instantaneous, and initially
399 consumes no additional space.
401 Clones can only be created from a snapshot.
402 When a snapshot is cloned, it creates an implicit dependency between the parent
404 Even though the clone is created somewhere else in the dataset hierarchy, the
405 original snapshot cannot be destroyed as long as a clone exists.
408 property exposes this dependency, and the
410 command lists any such dependencies, if they exist.
412 The clone parent-child dependency relationship can be reversed by using the
417 file system to become a clone of the specified file system, which makes it
418 possible to destroy the file system that the clone was created from.
420 Creating a ZFS file system is a simple operation, so the number of file systems
421 per system is likely to be numerous.
422 To cope with this, ZFS automatically manages mounting and unmounting file
423 systems without the need to edit the
426 All automatically managed file systems are mounted by ZFS at boot time.
428 By default, file systems are mounted under
432 is the name of the file system in the ZFS namespace.
433 Directories are created and destroyed as needed.
435 A file system can also have a mount point set in the
438 This directory is created as needed, and ZFS automatically mounts the file
440 .Nm zfs Cm mount Fl a
447 property can be inherited, so if
453 automatically inherits a mount point of
454 .Pa /export/stuff/user .
460 prevents the file system from being mounted.
462 If needed, ZFS file systems can also be managed with traditional tools
468 If a file system's mount point is set to
470 ZFS makes no attempt to manage the file system, and the administrator is
471 responsible for mounting and unmounting the file system. Because pools must
472 be imported before a legacy mount can succeed, administrators should ensure
473 that legacy mounts are only attempted after the zpool import process
474 finishes at boot time. For example, on machines using systemd, the mount
477 .Nm x-systemd.requires=zfs-import.target
479 will ensure that the zfs-import completes before systemd attempts mounting
480 the filesystem. See systemd.mount(5) for details.
482 Deduplication is the process for removing redundant data at the block level,
483 reducing the total amount of data stored. If a file system has the
485 property enabled, duplicate data blocks are removed synchronously. The result
486 is that only unique data is stored and common components are shared among files.
488 Deduplicating data is a very resource-intensive operation. It is generally
489 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
490 you enable deduplication. Calculating the exact requirement depends heavily
491 on the type of data stored in the pool.
493 Enabling deduplication on an improperly-designed system can result in
494 performance issues (slow IO and administrative operations). It can potentially
495 lead to problems importing a pool due to memory exhaustion. Deduplication
496 can consume significant processing power (CPU) and memory as well as generate
499 Before creating a pool with deduplication enabled, ensure that you have planned
500 your hardware requirements appropriately and implemented appropriate recovery
501 practices, such as regular backups. As an alternative to deduplication
504 as a less resource-intensive alternative.
505 .Ss Native Properties
506 Properties are divided into two types, native properties and user-defined
511 Native properties either export internal statistics or control ZFS behavior.
512 In addition, native properties are either editable or read-only.
513 User properties have no effect on ZFS behavior, but you can use them to annotate
514 datasets in a way that is meaningful in your environment.
515 For more information about user properties, see the
519 Every dataset has a set of properties that export statistics about the dataset
520 as well as control various behaviors.
521 Properties are inherited from the parent unless overridden by the child.
522 Some properties apply only to certain types of datasets
523 .Pq file systems, volumes, or snapshots .
525 The values of numeric properties can be specified using human-readable suffixes
535 The following are all valid
538 .Li 1536M, 1.5g, 1.50GB .
540 The values of non-numeric properties are case sensitive and must be lowercase,
547 The following native properties consist of read-only statistics about the
549 These properties can be neither set, nor inherited.
550 Native properties apply to all dataset types unless otherwise noted.
551 .Bl -tag -width "usedbyrefreservation"
553 The amount of space available to the dataset and all its children, assuming that
554 there is no other activity in the pool.
555 Because space is shared within a pool, availability can be limited by any number
556 of factors, including physical pool size, quotas, reservations, or other
557 datasets within the pool.
559 This property can also be referred to by its shortened column name,
562 For non-snapshots, the compression ratio achieved for the
564 space of this dataset, expressed as a multiplier.
567 property includes descendant datasets, and, for clones, does not include the
568 space shared with the origin snapshot.
574 Compression can be turned on by running:
575 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
579 The transaction group (txg) in which the dataset was created. Bookmarks have
582 as the snapshot they are initially tied to. This property is suitable for
583 ordering a list of snapshots, e.g. for incremental send and receive.
585 The time this dataset was created.
587 For snapshots, this property is a comma-separated list of filesystems or volumes
588 which are clones of this snapshot.
591 property is this snapshot.
594 property is not empty, then this snapshot can not be destroyed
601 The roles of origin and clone can be swapped by promoting the clone with the
607 if the snapshot has been marked for deferred destroy by using the
608 .Nm zfs Cm destroy Fl d
610 Otherwise, the property is
612 .It Sy encryptionroot
613 For encrypted datasets, indicates where the dataset is currently inheriting its
614 encryption key from. Loading or unloading a key for the
616 will implicitly load / unload the key for any inheriting datasets (see
619 .Nm zfs Cm unload-key
621 Clones will always share an
622 encryption key with their origin. See the
625 .It Sy filesystem_count
626 The total number of filesystems and volumes that exist under this location in
628 This value is only available when a
630 has been set somewhere in the tree under which the dataset resides.
632 Indicates if an encryption key is currently loaded into ZFS. The possible
641 .Nm zfs Cm unload-key .
643 The 64 bit GUID of this dataset or bookmark which does not change over its
644 entire lifetime. When a snapshot is sent to another pool, the received
645 snapshot has the same GUID. Thus, the
647 is suitable to identify a snapshot across pools.
648 .It Sy logicalreferenced
649 The amount of space that is
651 accessible by this dataset.
655 The logical space ignores the effect of the
659 properties, giving a quantity closer to the amount of data that applications
661 However, it does include space consumed by metadata.
663 This property can also be referred to by its shortened column name,
666 The amount of space that is
668 consumed by this dataset and all its descendents.
672 The logical space ignores the effect of the
676 properties, giving a quantity closer to the amount of data that applications
678 However, it does include space consumed by metadata.
680 This property can also be referred to by its shortened column name,
683 For file systems, indicates whether the file system is currently mounted.
684 This property can be either
689 For cloned file systems or volumes, the snapshot from which the clone was
694 .It Sy receive_resume_token
695 For filesystems or volumes which have saved partially-completed state from
697 this opaque token can be provided to
699 to resume and complete the
702 The amount of data that is accessible by this dataset, which may or may not be
703 shared with other datasets in the pool.
704 When a snapshot or clone is created, it initially references the same amount of
705 space as the file system or snapshot it was created from, since its contents are
708 This property can also be referred to by its shortened column name,
710 .It Sy refcompressratio
711 The compression ratio achieved for the
713 space of this dataset, expressed as a multiplier.
717 .It Sy snapshot_count
718 The total number of snapshots that exist under this location in the dataset
720 This value is only available when a
722 has been set somewhere in the tree under which the dataset resides.
730 The amount of space consumed by this dataset and all its descendents.
731 This is the value that is checked against this dataset's quota and reservation.
732 The space used does not include this dataset's reservation, but does take into
733 account the reservations of any descendent datasets.
734 The amount of space that a dataset consumes from its parent, as well as the
735 amount of space that is freed if this dataset is recursively destroyed, is the
736 greater of its space used and its reservation.
738 The used space of a snapshot
743 is space that is referenced exclusively by this snapshot.
744 If this snapshot is destroyed, the amount of
747 Space that is shared by multiple snapshots isn't accounted for in this metric.
748 When a snapshot is destroyed, space that was previously shared with this
749 snapshot can become unique to snapshots adjacent to it, thus changing the used
750 space of those snapshots.
751 The used space of the latest snapshot can also be affected by changes in the
755 space of a snapshot is a subset of the
757 space of the snapshot.
759 The amount of space used, available, or referenced does not take into account
761 Pending changes are generally accounted for within a few seconds.
762 Committing a change to a disk using
766 does not necessarily guarantee that the space usage information is updated
771 properties decompose the
773 properties into the various reasons that space is used.
776 .Sy usedbychildren No +
777 .Sy usedbydataset No +
778 .Sy usedbyrefreservation No +
779 .Sy usedbysnapshots .
780 These properties are only available for datasets created on
784 .It Sy usedbychildren
785 The amount of space used by children of this dataset, which would be freed if
786 all the dataset's children were destroyed.
788 The amount of space used by this dataset itself, which would be freed if the
789 dataset were destroyed
790 .Po after first removing any
792 and destroying any necessary snapshots or descendents
794 .It Sy usedbyrefreservation
795 The amount of space used by a
797 set on this dataset, which would be freed if the
800 .It Sy usedbysnapshots
801 The amount of space consumed by snapshots of this dataset.
802 In particular, it is the amount of space that would be freed if all of this
803 dataset's snapshots were destroyed.
804 Note that this is not simply the sum of the snapshots'
806 properties because space can be shared by multiple snapshots.
807 .It Sy userused Ns @ Ns Em user
808 The amount of space consumed by the specified user in this dataset.
809 Space is charged to the owner of each file, as displayed by
811 The amount of space charged is displayed by
817 subcommand for more information.
819 Unprivileged users can access only their own space usage.
820 The root user, or a user who has been granted the
824 can access everyone's usage.
827 .Sy userused Ns @ Ns Em ...
828 properties are not displayed by
829 .Nm zfs Cm get Sy all .
830 The user's name must be appended after the @ symbol, using one of the following
832 .Bl -bullet -width ""
846 .Sy joe.smith@mydomain
855 Files created on Linux always have POSIX owners.
856 .It Sy userobjused Ns @ Ns Em user
859 property is similar to
861 but instead it counts the number of objects consumed by a user. This property
862 counts all objects allocated on behalf of the user, it may differ from the
863 results of system tools such as
868 is set on a file system additional objects will be created per-file to store
869 extended attributes. These additional objects are reflected in the
871 value and are counted against the user's
873 When a file system is configured to use
875 no additional internal objects are normally required.
877 This property is set to the number of user holds on this snapshot.
878 User holds are set by using the
881 .It Sy groupused Ns @ Ns Em group
882 The amount of space consumed by the specified group in this dataset.
883 Space is charged to the group of each file, as displayed by
886 .Sy userused Ns @ Ns Em user
887 property for more information.
889 Unprivileged users can only access their own groups' space usage.
890 The root user, or a user who has been granted the
894 can access all groups' usage.
895 .It Sy groupobjused Ns @ Ns Em group
896 The number of objects consumed by the specified group in this dataset.
897 Multiple objects may be charged to the group for each file when extended
898 attributes are in use. See the
899 .Sy userobjused Ns @ Ns Em user
900 property for more information.
902 Unprivileged users can only access their own groups' space usage.
903 The root user, or a user who has been granted the
907 can access all groups' usage.
909 For volumes, specifies the block size of the volume.
912 cannot be changed once the volume has been written, so it should be set at
913 volume creation time.
916 for volumes is 8 Kbytes.
917 Any power of 2 from 512 bytes to 128 Kbytes is valid.
919 This property can also be referred to by its shortened column name,
924 by this dataset, that was written since the previous snapshot
925 .Pq i.e. that is not referenced by the previous snapshot .
926 .It Sy written Ns @ Ns Em snapshot
929 space written to this dataset since the specified snapshot.
930 This is the space that is referenced by this dataset but was not referenced by
931 the specified snapshot.
935 may be specified as a short snapshot name
936 .Po just the part after the
939 in which case it will be interpreted as a snapshot in the same filesystem as
943 may be a full snapshot name
944 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
945 which for clones may be a snapshot in the origin's filesystem
946 .Pq or the origin of the origin's filesystem, etc.
949 The following native properties can be used to change the behavior of a ZFS
953 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
954 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
956 Controls how ACEs are inherited when files and directories are created.
957 .Bl -tag -width "passthrough-x"
959 does not inherit any ACEs.
961 only inherits inheritable ACEs that specify
969 permissions when the ACE is inherited.
971 inherits all inheritable ACEs without any modifications.
980 ACEs inherit the execute permission only if the file creation mode also requests
984 When the property value is set to
986 files are created with a mode determined by the inheritable ACEs.
987 If no inheritable ACEs exist that affect the mode, then the mode is set in
988 accordance to the requested mode from the application.
992 property does not apply to posix ACLs.
993 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
994 Controls whether ACLs are enabled and if so what type of ACL to use.
995 .Bl -tag -width "posixacl"
997 default, when a file system has the
999 property set to off then ACLs are disabled.
1004 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
1005 not functional on other platforms. Posix ACLs are stored as an extended
1006 attribute and therefore will not overwrite any existing NFSv4 ACLs which
1010 To obtain the best performance when setting
1012 users are strongly encouraged to set the
1014 property. This will result in the posix ACL being stored more efficiently on
1015 disk. But as a consequence of this all new extended attributes will only be
1016 accessible from OpenZFS implementations which support the
1020 property for more details.
1021 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
1022 Controls whether the access time for files is updated when they are read.
1023 Turning this property off avoids producing write traffic when reading files and
1024 can result in significant performance gains, though it might confuse mailers
1025 and other similar utilities. The values
1029 are equivalent to the
1033 mount options. The default value is
1038 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
1039 If this property is set to
1041 the file system cannot be mounted, and is ignored by
1042 .Nm zfs Cm mount Fl a .
1043 Setting this property to
1045 is similar to setting the
1049 except that the dataset still has a normal
1051 property, which can be inherited.
1052 Setting this property to
1054 allows datasets to be used solely as a mechanism to inherit properties.
1055 One example of setting
1056 .Sy canmount Ns = Ns Sy off
1057 is to have two datasets with the same
1059 so that the children of both datasets appear in the same directory, but might
1060 have different inherited characteristics.
1064 a dataset can only be mounted and unmounted explicitly.
1065 The dataset is not mounted automatically when the dataset is created or
1066 imported, nor is it mounted by the
1067 .Nm zfs Cm mount Fl a
1068 command or unmounted by the
1069 .Nm zfs Cm unmount Fl a
1072 This property is not inherited.
1074 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1075 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1076 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1078 Controls the checksum used to verify data integrity.
1079 The default value is
1081 which automatically selects an appropriate algorithm
1084 but this may change in future releases
1088 disables integrity checking on user data.
1091 not only disables integrity but also disables maintaining parity for user data.
1092 This setting is used internally by a dump device residing on a RAID-Z pool and
1093 should not be used by any other dataset.
1094 Disabling checksums is
1096 a recommended practice.
1103 checksum algorithms require enabling the appropriate features on the pool.
1105 .Xr zpool-features 5
1106 for more information on these algorithms.
1108 Changing this property affects only newly-written data.
1110 Salted checksum algorithms
1111 .Pq Cm edonr , skein
1112 are currently not supported for any filesystem on the boot pools.
1114 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1115 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1117 Controls the compression algorithm used for this dataset.
1119 Setting compression to
1121 indicates that the current default compression algorithm should be used.
1122 The default balances compression and decompression speed, with compression ratio
1123 and is expected to work well on a wide variety of workloads.
1124 Unlike all other settings for this property,
1126 does not select a fixed compression type.
1127 As new compression algorithms are added to ZFS and enabled on a pool, the
1128 default compression algorithm may change.
1129 The current default compression algorithm is either
1138 compression algorithm is a high-performance replacement for the
1141 It features significantly faster compression and decompression, as well as a
1142 moderately higher compression ratio than
1144 but can only be used on pools with the
1149 .Xr zpool-features 5
1150 for details on ZFS feature flags and the
1156 compression algorithm is optimized for performance while providing decent data
1161 compression algorithm uses the same compression as the
1166 level by using the value
1170 is an integer from 1
1173 .Pq best compression ratio .
1178 .Po which is also the default for
1184 compression algorithm compresses runs of zeros.
1186 This property can also be referred to by its shortened column name
1188 Changing this property affects only newly-written data.
1190 .Sy context Ns = Ns Sy none Ns | Ns
1191 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1193 This flag sets the SELinux context for all files in the file system under
1194 a mount point for that file system. See
1196 for more information.
1198 .Sy fscontext Ns = Ns Sy none Ns | Ns
1199 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1201 This flag sets the SELinux context for the file system file system being
1204 for more information.
1206 .Sy defcontext Ns = Ns Sy none Ns | Ns
1207 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1209 This flag sets the SELinux default context for unlabeled files. See
1211 for more information.
1213 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1214 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1216 This flag sets the SELinux context for the root inode of the file system. See
1218 for more information.
1219 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1220 Controls the number of copies of data stored for this dataset.
1221 These copies are in addition to any redundancy provided by the pool, for
1222 example, mirroring or RAID-Z.
1223 The copies are stored on different disks, if possible.
1224 The space used by multiple copies is charged to the associated file and dataset,
1227 property and counting against quotas and reservations.
1229 Changing this property only affects newly-written data.
1230 Therefore, set this property at file system creation time by using the
1231 .Fl o Sy copies Ns = Ns Ar N
1234 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1236 create, for example a two-disk striped pool and set
1238 on some datasets thinking you have setup redundancy for them. When a disk
1239 fails you will not be able to import the pool and will have lost all of your
1241 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1242 Controls whether device nodes can be opened on this file system.
1243 The default value is
1249 are equivalent to the
1255 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1256 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1258 Specifies a compatibility mode or literal value for the size of dnodes in the
1259 file system. The default value is
1261 Setting this property to a value other than
1263 requires the large_dnode pool feature to be enabled.
1269 if the dataset uses the
1271 property setting and the workload makes heavy use of extended attributes. This
1272 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1273 servers, for example. Literal values are supported for cases where the optimal
1274 size is known in advance and for performance testing.
1280 if you need to receive a send stream of this dataset on a pool that doesn't
1281 enable the large_dnode feature, or if you need to import this pool on a system
1282 that doesn't support the large_dnode feature.
1284 This property can also be referred to by its shortened column name,
1287 .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
1288 .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
1289 .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
1291 Controls the encryption cipher suite (block cipher, key length, and mode) used
1292 for this dataset. Requires the
1294 feature to be enabled on the pool.
1297 to be set at dataset creation time.
1300 .Sy encryption Ns = Ns Sy on
1301 when creating a dataset indicates that the default encryption suite will be
1302 selected, which is currently
1304 In order to provide consistent data protection, encryption must be specified at
1305 dataset creation time and it cannot be changed afterwards.
1307 For more details and caveats about encryption see the
1310 .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
1311 Controls what format the user's encryption key will be provided as. This
1312 property is only set when the dataset is encrypted.
1314 Raw keys and hex keys must be 32 bytes long (regardless of the chosen
1315 encryption suite) and must be randomly generated. A raw key can be generated
1316 with the following command:
1318 # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
1321 Passphrases must be between 8 and 512 bytes long and will be processed through
1322 PBKDF2 before being used (see the
1324 property). Even though the
1325 encryption suite cannot be changed after dataset creation, the keyformat can be
1327 .Nm zfs Cm change-key .
1329 .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
1331 Controls where the user's encryption key will be loaded from by default for
1335 .Nm zfs Cm mount Cm -l . This property is
1336 only set for encrypted datasets which are encryption roots. If unspecified, the
1340 Even though the encryption suite cannot be changed after dataset creation, the
1341 keylocation can be with either
1344 .Nm zfs Cm change-key .
1347 is selected ZFS will ask for the key at the command prompt when it is required
1348 to access the encrypted data (see
1350 for details). This setting will also allow the key to be passed in via STDIN,
1351 but users should be careful not to place keys which should be kept secret on
1352 the command line. If a file URI is selected, the key will be loaded from the
1353 specified absolute file path.
1354 .It Sy pbkdf2iters Ns = Ns Ar iterations
1355 Controls the number of PBKDF2 iterations that a
1357 encryption key should be run through when processing it into an encryption key.
1358 This property is only defined when encryption is enabled and a keyformat of
1360 is selected. The goal of PBKDF2 is to significantly increase the
1361 computational difficulty needed to brute force a user's passphrase. This is
1362 accomplished by forcing the attacker to run each passphrase through a
1363 computationally expensive hashing function many times before they arrive at the
1364 resulting key. A user who actually knows the passphrase will only have to pay
1365 this cost once. As CPUs become better at processing, this number should be
1366 raised to ensure that a brute force attack is still not possible. The current
1371 This property may be changed with
1372 .Nm zfs Cm change-key .
1373 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1374 Controls whether processes can be executed from within this file system.
1375 The default value is
1381 are equivalent to the
1386 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1387 Limits the number of filesystems and volumes that can exist under this point in
1389 The limit is not enforced if the user is allowed to change the limit.
1391 .Sy filesystem_limit
1394 a descendent of a filesystem that already has a
1395 .Sy filesystem_limit
1396 does not override the ancestor's
1397 .Sy filesystem_limit ,
1398 but rather imposes an additional limit.
1399 This feature must be enabled to be used
1401 .Xr zpool-features 5
1403 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1404 Controls the mount point used for this file system.
1407 section for more information on how this property is used.
1411 property is changed for a file system, the file system and any children that
1412 inherit the mount point are unmounted.
1415 then they remain unmounted.
1416 Otherwise, they are automatically remounted in the new location if the property
1421 or if they were mounted before the property was changed.
1422 In addition, any shared file systems are unshared and shared in the new
1424 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1425 Controls whether the file system should be mounted with
1427 .Pq Non Blocking mandatory locks .
1428 This is used for SMB clients.
1429 Changes to this property only take effect when the file system is umounted and
1433 for more information on
1435 mounts. This property is not used on Linux.
1436 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1437 Allow mounting on a busy directory or a directory which already contains
1438 files or directories. This is the default mount behavior for Linux file systems.
1439 For consistency with OpenZFS on other platforms overlay mounts are
1443 to enable overlay mounts.
1444 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1445 Controls what is cached in the primary cache
1447 If this property is set to
1449 then both user data and metadata is cached.
1450 If this property is set to
1452 then neither user data nor metadata is cached.
1453 If this property is set to
1455 then only metadata is cached.
1456 The default value is
1458 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1459 Limits the amount of space a dataset and its descendents can consume.
1460 This property enforces a hard limit on the amount of space used.
1461 This includes all space consumed by descendents, including file systems and
1463 Setting a quota on a descendent of a dataset that already has a quota does not
1464 override the ancestor's quota, but rather imposes an additional limit.
1466 Quotas cannot be set on volumes, as the
1468 property acts as an implicit quota.
1469 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1470 Limits the number of snapshots that can be created on a dataset and its
1474 on a descendent of a dataset that already has a
1476 does not override the ancestor's
1477 .Sy snapshot_limit ,
1478 but rather imposes an additional limit.
1479 The limit is not enforced if the user is allowed to change the limit.
1480 For example, this means that recursive snapshots taken from the global zone are
1481 counted against each delegated dataset within a zone.
1482 This feature must be enabled to be used
1484 .Xr zpool-features 5
1486 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1487 Limits the amount of space consumed by the specified user.
1488 User space consumption is identified by the
1489 .Sy userspace@ Ns Em user
1492 Enforcement of user quotas may be delayed by several seconds.
1493 This delay means that a user might exceed their quota before the system notices
1494 that they are over quota and begins to refuse additional writes with the
1498 .Nm zfs Cm userspace
1499 subcommand for more information.
1501 Unprivileged users can only access their own groups' space usage.
1502 The root user, or a user who has been granted the
1506 can get and set everyone's quota.
1508 This property is not available on volumes, on file systems before version 4, or
1509 on pools before version 15.
1511 .Sy userquota@ Ns Em ...
1512 properties are not displayed by
1513 .Nm zfs Cm get Sy all .
1514 The user's name must be appended after the
1516 symbol, using one of the following forms:
1524 .Em POSIX numeric ID
1531 .Sy joe.smith@mydomain
1540 Files created on Linux always have POSIX owners.
1541 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1546 but it limits the number of objects a user can create. Please refer to
1548 for more information about how objects are counted.
1549 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1550 Limits the amount of space consumed by the specified group.
1551 Group space consumption is identified by the
1552 .Sy groupused@ Ns Em group
1555 Unprivileged users can access only their own groups' space usage.
1556 The root user, or a user who has been granted the
1560 can get and set all groups' quotas.
1561 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1566 but it limits number of objects a group can consume. Please refer to
1568 for more information about how objects are counted.
1569 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1570 Controls whether this dataset can be modified.
1571 The default value is
1577 are equivalent to the
1583 This property can also be referred to by its shortened column name,
1585 .It Sy recordsize Ns = Ns Em size
1586 Specifies a suggested block size for files in the file system.
1587 This property is designed solely for use with database workloads that access
1588 files in fixed-size records.
1589 ZFS automatically tunes block sizes according to internal algorithms optimized
1590 for typical access patterns.
1592 For databases that create very large files but access them in small random
1593 chunks, these algorithms may be suboptimal.
1596 greater than or equal to the record size of the database can result in
1597 significant performance gains.
1598 Use of this property for general purpose file systems is strongly discouraged,
1599 and may adversely affect performance.
1601 The size specified must be a power of two greater than or equal to 512 and less
1602 than or equal to 128 Kbytes.
1605 feature is enabled on the pool, the size may be up to 1 Mbyte.
1607 .Xr zpool-features 5
1608 for details on ZFS feature flags.
1610 Changing the file system's
1612 affects only files created afterward; existing files are unaffected.
1614 This property can also be referred to by its shortened column name,
1616 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1617 Controls what types of metadata are stored redundantly.
1618 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1619 the amount of user data lost is limited.
1620 This extra copy is in addition to any redundancy provided at the pool level
1621 .Pq e.g. by mirroring or RAID-Z ,
1622 and is in addition to an extra copy specified by the
1625 .Pq up to a total of 3 copies .
1626 For example if the pool is mirrored,
1627 .Sy copies Ns = Ns 2 ,
1629 .Sy redundant_metadata Ns = Ns Sy most ,
1630 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1635 ZFS stores an extra copy of all metadata.
1636 If a single on-disk block is corrupt, at worst a single block of user data
1645 ZFS stores an extra copy of most types of metadata.
1646 This can improve performance of random writes, because less metadata must be
1648 In practice, at worst about 100 blocks
1653 of user data can be lost if a single on-disk block is corrupt.
1654 The exact behavior of which metadata blocks are stored redundantly may change in
1657 The default value is
1659 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1660 Limits the amount of space a dataset can consume.
1661 This property enforces a hard limit on the amount of space used.
1662 This hard limit does not include space used by descendents, including file
1663 systems and snapshots.
1664 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1665 The minimum amount of space guaranteed to a dataset, not including its
1667 When the amount of space used is below this value, the dataset is treated as if
1668 it were taking up the amount of space specified by
1669 .Sy refreservation .
1672 reservation is accounted for in the parent datasets' space used, and counts
1673 against the parent datasets' quotas and reservations.
1677 is set, a snapshot is only allowed if there is enough free pool space outside of
1678 this reservation to accommodate the current number of
1680 bytes in the dataset.
1682 This property can also be referred to by its shortened column name,
1684 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1685 Controls the manner in which the access time is updated when
1687 is set. Turning this property on causes the access time to be updated relative
1688 to the modify or change time. Access time is only updated if the previous
1689 access time was earlier than the current modify or change time or if the
1690 existing access time hasn't been updated within the past 24 hours. The default
1697 are equivalent to the
1702 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1703 The minimum amount of space guaranteed to a dataset and its descendants.
1704 When the amount of space used is below this value, the dataset is treated as if
1705 it were taking up the amount of space specified by its reservation.
1706 Reservations are accounted for in the parent datasets' space used, and count
1707 against the parent datasets' quotas and reservations.
1709 This property can also be referred to by its shortened column name,
1711 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1712 Controls what is cached in the secondary cache
1714 If this property is set to
1716 then both user data and metadata is cached.
1717 If this property is set to
1719 then neither user data nor metadata is cached.
1720 If this property is set to
1722 then only metadata is cached.
1723 The default value is
1725 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1726 Controls whether the setuid bit is respected for the file system.
1727 The default value is
1733 are equivalent to the
1738 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1739 Controls whether the file system is shared by using
1740 .Sy Samba USERSHARES
1741 and what options are to be used. Otherwise, the file system is automatically
1742 shared and unshared with the
1746 commands. If the property is set to on, the
1748 command is invoked to create a
1751 Because SMB shares requires a resource name, a unique resource name is
1752 constructed from the dataset name. The constructed name is a copy of the
1753 dataset name except that the characters in the dataset name, which would be
1754 invalid in the resource name, are replaced with underscore (_) characters.
1755 Linux does not currently support additional options which might be available
1762 the file systems are unshared.
1764 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1765 stands for "full permissions", ie. read and write permissions) and no guest
1766 access (which means Samba must be able to authenticate a real user, system
1767 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1768 additional access control (disallow specific user specific access etc) must
1769 be done on the underlying file system.
1770 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1771 Controls whether the file system is shared via NFS, and what options are to be
1773 A file system with a
1779 command and entries in the
1782 Otherwise, the file system is automatically shared and unshared with the
1787 If the property is set to
1789 the dataset is shared using the default options:
1791 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1795 for the meaning of the default options. Otherwise, the
1797 command is invoked with options equivalent to the contents of this property.
1801 property is changed for a dataset, the dataset and any children inheriting the
1802 property are re-shared with the new options, only if the property was previously
1804 or if they were shared before the property was changed.
1805 If the new property is
1807 the file systems are unshared.
1808 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1809 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1815 ZFS will use pool log devices
1817 to handle the requests at low latency.
1822 ZFS will not use configured pool log devices.
1823 ZFS will instead optimize synchronous operations for global pool throughput and
1824 efficient use of resources.
1825 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1826 Controls whether the volume snapshot devices under
1827 .Em /dev/zvol/<pool>
1828 are hidden or visible. The default value is
1830 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1831 Controls whether the
1833 directory is hidden or visible in the root of the file system as discussed in
1837 The default value is
1839 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1840 Controls the behavior of synchronous requests
1841 .Pq e.g. fsync, O_DSYNC .
1845 specified behavior of ensuring all synchronous requests are written to stable
1846 storage and all devices are flushed to ensure data is not cached by device
1848 .Pq this is the default .
1850 causes every file system transaction to be written and flushed before its
1851 system call returns.
1852 This has a large performance penalty.
1854 disables synchronous requests.
1855 File system transactions are only committed to stable storage periodically.
1856 This option will give the highest performance.
1857 However, it is very dangerous as ZFS would be ignoring the synchronous
1858 transaction demands of applications such as databases or NFS.
1859 Administrators should only use this option when the risks are understood.
1860 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1861 The on-disk version of this file system, which is independent of the pool
1863 This property can only be set to later supported versions.
1867 .It Sy volsize Ns = Ns Em size
1868 For volumes, specifies the logical size of the volume.
1869 By default, creating a volume establishes a reservation of equal size.
1870 For storage pools with a version number of 9 or higher, a
1875 are reflected in an equivalent change to the reservation
1881 can only be set to a multiple of
1885 The reservation is kept equal to the volume's logical size to prevent unexpected
1886 behavior for consumers.
1887 Without the reservation, the volume could run out of space, resulting in
1888 undefined behavior or data corruption, depending on how the volume is used.
1889 These effects can also occur when the volume size is changed while it is in use
1890 .Pq particularly when shrinking the size .
1891 Extreme care should be used when adjusting the volume size.
1893 Though not recommended, a
1896 .Qq thin provisioning
1898 can be created by specifying the
1901 .Nm zfs Cm create Fl V
1902 command, or by changing the reservation after the volume has been created.
1905 is a volume where the reservation is less then the volume size.
1906 Consequently, writes to a sparse volume can fail with
1908 when the pool is low on space.
1909 For a sparse volume, changes to
1911 are not reflected in the reservation.
1912 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1913 This property specifies how volumes should be exposed to the OS.
1916 exposes volumes as fully fledged block devices, providing maximal
1917 functionality. The value
1919 is just an alias for
1921 and is kept for compatibility.
1924 hides its partitions.
1925 Volumes with property set to
1927 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
1928 that can be suitable for backup purposes.
1931 means that volumes exposition is controlled by system-wide tunable
1938 are encoded as 1, 2 and 3 respectively.
1939 The default values is
1941 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1942 Controls whether regular files should be scanned for viruses when a file is
1944 In addition to enabling this property, the virus scan service must also be
1945 enabled for virus scanning to occur.
1946 The default value is
1948 This property is not used on Linux.
1949 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1950 Controls whether extended attributes are enabled for this file system. Two
1951 styles of extended attributes are supported either directory based or system
1954 The default value of
1956 enables directory based extended attributes. This style of extended attribute
1957 imposes no practical limit on either the size or number of attributes which
1958 can be set on a file. Although under Linux the
1962 system calls limit the maximum size to 64K. This is the most compatible
1963 style of extended attribute and is supported by all OpenZFS implementations.
1965 System attribute based xattrs can be enabled by setting the value to
1967 The key advantage of this type of xattr is improved performance. Storing
1968 extended attributes as system attributes significantly decreases the amount of
1969 disk IO required. Up to 64K of data may be stored per-file in the space
1970 reserved for system attributes. If there is not enough space available for
1971 an extended attribute then it will be automatically written as a directory
1972 based xattr. System attribute based extended attributes are not accessible
1973 on platforms which do not support the
1977 The use of system attribute based xattrs is strongly encouraged for users of
1978 SELinux or posix ACLs. Both of these features heavily rely of extended
1979 attributes and benefit significantly from the reduced access time.
1985 are equivalent to the
1990 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1991 Controls whether the dataset is managed from a non-global zone. Zones are a
1992 Solaris feature and are not relevant on Linux. The default value is
1996 The following three properties cannot be changed after the file system is
1997 created, and therefore, should be set when the file system is created.
1998 If the properties are not set with the
2002 commands, these properties are inherited from the parent dataset.
2003 If the parent dataset lacks these properties due to having been created prior to
2004 these features being supported, the new file system will have the default values
2005 for these properties.
2008 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
2009 .Sy insensitive Ns | Ns Sy mixed
2011 Indicates whether the file name matching algorithm used by the file system
2012 should be case-sensitive, case-insensitive, or allow a combination of both
2014 The default value for the
2022 file systems have case-sensitive file names.
2028 property indicates that the file system can support requests for both
2029 case-sensitive and case-insensitive matching behavior.
2030 Currently, case-insensitive matching behavior on a file system that supports
2031 mixed behavior is limited to the SMB server product.
2032 For more information about the
2034 value behavior, see the "ZFS Administration Guide".
2036 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
2037 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
2039 Indicates whether the file system should perform a
2041 normalization of file names whenever two file names are compared, and which
2042 normalization algorithm should be used.
2043 File names are always stored unmodified, names are normalized as part of any
2045 If this property is set to a legal value other than
2049 property was left unspecified, the
2051 property is automatically set to
2053 The default value of the
2057 This property cannot be changed after the file system is created.
2058 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
2059 Indicates whether the file system should reject file names that include
2060 characters that are not present in the
2063 If this property is explicitly set to
2065 the normalization property must either not be explicitly set or be set to
2067 The default value for the
2071 This property cannot be changed after the file system is created.
2075 .Sy casesensitivity ,
2079 properties are also new permissions that can be assigned to non-privileged users
2080 by using the ZFS delegated administration feature.
2081 .Ss "Temporary Mount Point Properties"
2082 When a file system is mounted, either through
2084 for legacy mounts or the
2086 command for normal file systems, its mount options are set according to its
2088 The correlation between properties and mount options is as follows:
2090 PROPERTY MOUNT OPTION
2092 canmount auto/noauto
2096 relatime relatime/norelatime
2101 In addition, these options can be set on a per-mount basis using the
2103 option, without affecting the property that is stored on disk.
2104 The values specified on the command line override the values stored in the
2108 option is an alias for
2109 .Sy nodevices Ns \&, Ns Sy nosetuid .
2110 These properties are reported as
2115 If the properties are changed while the dataset is mounted, the new setting
2116 overrides any temporary settings.
2117 .Ss "User Properties"
2118 In addition to the standard native properties, ZFS supports arbitrary user
2120 User properties have no effect on ZFS behavior, but applications or
2121 administrators can use them to annotate datasets
2122 .Pq file systems, volumes, and snapshots .
2124 User property names must contain a colon
2126 character to distinguish them from native properties.
2127 They may contain lowercase letters, numbers, and the following punctuation
2136 The expected convention is that the property name is divided into two portions
2138 .Em module Ns \&: Ns Em property ,
2139 but this namespace is not enforced by ZFS.
2140 User property names can be at most 256 characters, and cannot begin with a dash
2143 When making programmatic use of user properties, it is strongly suggested to use
2148 component of property names to reduce the chance that two
2149 independently-developed packages use the same property name for different
2152 The values of user properties are arbitrary strings, are always inherited, and
2153 are never validated.
2154 All of the commands that operate on properties
2155 .Po Nm zfs Cm list ,
2160 can be used to manipulate both native properties and user properties.
2163 command to clear a user property.
2164 If the property is not defined in any parent dataset, it is removed entirely.
2165 Property values are limited to 8192 bytes.
2166 .Ss ZFS Volumes as Swap
2167 ZFS volumes may be used as swap devices. After creating the volume with the
2168 .Nm zfs Cm create Fl V
2169 command set up and enable the swap area using the
2173 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2174 configuration is not supported.
2178 feature allows for the creation of encrypted filesystems and volumes.
2180 will encrypt all user data including file and zvol data, file attributes,
2181 ACLs, permission bits, directory listings, FUID mappings, and userused /
2184 will not encrypt metadata related to the pool structure, including dataset
2185 names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
2186 is managed internally by the kernel module and changing the user's key does not
2187 require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
2188 renamed, and deleted without the encryption keys being loaded (see the
2190 subcommand for more info on key loading).
2192 Creating an encrypted dataset requires specifying the
2196 properties at creation time, along with an optional
2200 After entering an encryption key, the
2201 created dataset will become an encryption root. Any descendant datasets will
2202 inherit their encryption key from the encryption root by default, meaning that
2203 loading, unloading, or changing the key for the encryption root will implicitly
2204 do the same for all inheriting datasets. If this inheritance is not desired,
2207 when creating the child dataset or use
2208 .Nm zfs Cm change-key
2209 to break an existing relationship, creating a new encryption root on the child.
2210 Note that the child's
2212 may match that of the parent while still creating a new encryption root, and
2215 property alone does not create a new encryption root; this would simply use a
2216 different cipher suite with the same key as its encryption root. The one
2217 exception is that clones will always use their origin's encryption key.
2218 As a result of this exception, some encryption-related properties (namely
2224 do not inherit like other ZFS properties and instead use the value determined
2225 by their encryption root. Encryption root inheritance can be tracked via the
2230 Encryption changes the behavior of a few
2232 operations. Encryption is applied after compression so compression ratios are
2233 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
2234 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from
2235 the encryption suite, which provides additional protection against maliciously
2236 altered data. Deduplication is still possible with encryption enabled but for
2237 security, datasets will only dedup against themselves, their snapshots, and
2240 There are a few limitations on encrypted datasets. Encrypted data cannot be
2243 feature. Encrypted datasets may not have
2244 .Sy copies Ns = Ns Em 3
2245 since the implementation stores some encryption metadata where the third copy
2246 would normally be. Since compression is applied before encryption datasets may
2247 be vulnerable to a CRIME-like attack if applications accessing the data allow
2248 for it. Deduplication with encryption will leak information about which blocks
2249 are equivalent in a dataset and will incur an extra CPU cost per block written.
2251 All subcommands that modify state are logged persistently to the pool in their
2255 Displays a help message.
2260 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2263 Creates a new ZFS file system.
2264 The file system is automatically mounted according to the
2266 property inherited from the parent.
2267 .Bl -tag -width "-o"
2268 .It Fl o Ar property Ns = Ns Ar value
2269 Sets the specified property as if the command
2270 .Nm zfs Cm set Ar property Ns = Ns Ar value
2271 was invoked at the same time the dataset was created.
2272 Any editable ZFS property can also be set at creation time.
2275 options can be specified.
2276 An error results if the same property is specified in multiple
2280 Creates all the non-existing parent datasets.
2281 Datasets created in this manner are automatically mounted according to the
2283 property inherited from their parent.
2284 Any property specified on the command line using the
2287 If the target filesystem already exists, the operation completes successfully.
2293 .Op Fl b Ar blocksize
2294 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2295 .Fl V Ar size Ar volume
2297 Creates a volume of the given size.
2298 The volume is exported as a block device in
2299 .Pa /dev/zvol/path ,
2302 is the name of the volume in the ZFS namespace.
2303 The size represents the logical size as exported by the device.
2304 By default, a reservation of equal size is created.
2307 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2308 has an integral number of blocks regardless of
2310 .Bl -tag -width "-b"
2311 .It Fl b Ar blocksize
2313 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2314 If this option is specified in conjunction with
2315 .Fl o Sy volblocksize ,
2316 the resulting behavior is undefined.
2317 .It Fl o Ar property Ns = Ns Ar value
2318 Sets the specified property as if the
2319 .Nm zfs Cm set Ar property Ns = Ns Ar value
2320 command was invoked at the same time the dataset was created.
2321 Any editable ZFS property can also be set at creation time.
2324 options can be specified.
2325 An error results if the same property is specified in multiple
2329 Creates all the non-existing parent datasets.
2330 Datasets created in this manner are automatically mounted according to the
2332 property inherited from their parent.
2333 Any property specified on the command line using the
2336 If the target filesystem already exists, the operation completes successfully.
2338 Creates a sparse volume with no reservation.
2342 .Sx Native Properties
2343 section for more information about sparse volumes.
2349 .Ar filesystem Ns | Ns Ar volume
2351 Destroys the given dataset.
2352 By default, the command unshares any file systems that are currently shared,
2353 unmounts any file systems that are currently mounted, and refuses to destroy a
2354 dataset that has active dependents
2355 .Pq children or clones .
2356 .Bl -tag -width "-R"
2358 Recursively destroy all dependents, including cloned file systems outside the
2361 Force an unmount of any file systems using the
2364 This option has no effect on non-file systems or unmounted file systems.
2369 No data will be deleted.
2370 This is useful in conjunction with the
2374 flags to determine what data would be deleted.
2376 Print machine-parsable verbose information about the deleted data.
2378 Recursively destroy all children.
2380 Print verbose information about the deleted data.
2383 Extreme care should be taken when applying either the
2387 options, as they can destroy large portions of a pool and cause unexpected
2388 behavior for mounted file systems in use.
2393 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2394 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2396 The given snapshots are destroyed immediately if and only if the
2400 option would have destroyed it.
2401 Such immediate destruction would occur, for example, if the snapshot had no
2402 clones and the user-initiated reference count were zero.
2404 If a snapshot does not qualify for immediate destruction, it is marked for
2406 In this state, it exists as a usable, visible snapshot until both of the
2407 preconditions listed above are met, at which point it is destroyed.
2409 An inclusive range of snapshots may be specified by separating the first and
2410 last snapshots with a percent sign.
2411 The first and/or last snapshots may be left blank, in which case the
2412 filesystem's oldest or newest snapshot will be implied.
2415 .Pq or ranges of snapshots
2416 of the same filesystem or volume may be specified in a comma-separated list of
2418 Only the snapshot's short name
2419 .Po the part after the
2422 should be specified when using a range or comma-separated list to identify
2424 .Bl -tag -width "-R"
2426 Recursively destroy all clones of these snapshots, including the clones,
2427 snapshots, and children.
2428 If this flag is specified, the
2430 flag will have no effect.
2432 Defer snapshot deletion.
2437 No data will be deleted.
2438 This is useful in conjunction with the
2442 flags to determine what data would be deleted.
2444 Print machine-parsable verbose information about the deleted data.
2447 .Pq or mark for deferred deletion
2448 all snapshots with this name in descendent file systems.
2450 Print verbose information about the deleted data.
2452 Extreme care should be taken when applying either the
2456 options, as they can destroy large portions of a pool and cause unexpected
2457 behavior for mounted file systems in use.
2462 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2464 The given bookmark is destroyed.
2469 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2470 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2472 Creates snapshots with the given names.
2473 All previous modifications by successful system calls to the file system are
2474 part of the snapshots.
2475 Snapshots are taken atomically, so that all snapshots correspond to the same
2478 can be used as an alias for
2479 .Nm zfs Cm snapshot.
2482 section for details.
2483 .Bl -tag -width "-o"
2484 .It Fl o Ar property Ns = Ns Ar value
2485 Sets the specified property; see
2489 Recursively create snapshots of all descendent datasets
2497 Roll back the given dataset to a previous snapshot.
2498 When a dataset is rolled back, all data that has changed since the snapshot is
2499 discarded, and the dataset reverts to the state at the time of the snapshot.
2500 By default, the command refuses to roll back to a snapshot other than the most
2502 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2509 options do not recursively destroy the child snapshots of a recursive snapshot.
2510 Only direct snapshots of the specified filesystem are destroyed by either of
2512 To completely roll back a recursive snapshot, you must rollback the individual
2514 .Bl -tag -width "-R"
2516 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2521 option to force an unmount of any clone file systems that are to be destroyed.
2523 Destroy any snapshots and bookmarks more recent than the one specified.
2529 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2530 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2532 Creates a clone of the given snapshot.
2535 section for details.
2536 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2537 as the same type as the original.
2538 .Bl -tag -width "-o"
2539 .It Fl o Ar property Ns = Ns Ar value
2540 Sets the specified property; see
2544 Creates all the non-existing parent datasets.
2545 Datasets created in this manner are automatically mounted according to the
2547 property inherited from their parent.
2548 If the target filesystem or volume already exists, the operation completes
2554 .Ar clone-filesystem
2556 Promotes a clone file system to no longer be dependent on its
2559 This makes it possible to destroy the file system that the clone was created
2561 The clone parent-child dependency relationship is reversed, so that the origin
2562 file system becomes a clone of the specified file system.
2564 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2565 now owned by the promoted clone.
2566 The space they use moves from the origin file system to the promoted clone, so
2567 enough space must be available to accommodate these snapshots.
2568 No new space is consumed by this operation, but the space accounting is
2570 The promoted clone must not have any conflicting snapshot names of its own.
2573 subcommand can be used to rename any conflicting snapshots.
2578 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2579 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2585 .Ar filesystem Ns | Ns Ar volume
2586 .Ar filesystem Ns | Ns Ar volume
2588 Renames the given dataset.
2589 The new target can be located anywhere in the ZFS hierarchy, with the exception
2591 Snapshots can only be renamed within the parent file system or volume.
2592 When renaming a snapshot, the parent file system of the snapshot does not need
2593 to be specified as part of the second argument.
2594 Renamed file systems can inherit new mount points, in which case they are
2595 unmounted and remounted at the new mount point.
2596 .Bl -tag -width "-a"
2598 Force unmount any filesystems that need to be unmounted in the process.
2600 Creates all the nonexistent parent datasets.
2601 Datasets created in this manner are automatically mounted according to the
2603 property inherited from their parent.
2609 .Ar snapshot Ar snapshot
2611 Recursively rename the snapshots of all descendent datasets.
2612 Snapshots are the only dataset that can be renamed recursively.
2616 .Op Fl r Ns | Ns Fl d Ar depth
2618 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2619 .Oo Fl s Ar property Oc Ns ...
2620 .Oo Fl S Ar property Oc Ns ...
2621 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2622 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2624 Lists the property information for the given datasets in tabular form.
2625 If specified, you can list property information by the absolute pathname or the
2627 By default, all file systems and volumes are displayed.
2628 Snapshots are displayed if the
2635 The following fields are displayed,
2636 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2638 .Bl -tag -width "-H"
2640 Used for scripting mode.
2641 Do not print headers and separate fields by a single tab instead of arbitrary
2643 .It Fl S Ar property
2646 option, but sorts by property in descending order.
2648 Recursively display any children of the dataset, limiting the recursion to
2654 will display only the dataset and its direct children.
2655 .It Fl o Ar property
2656 A comma-separated list of properties to display.
2657 The property must be:
2660 One of the properties described in the
2661 .Sx Native Properties
2668 to display the dataset name
2672 to display space usage properties on file systems and volumes.
2673 This is a shortcut for specifying
2674 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2675 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2676 .Sy filesystem Ns \&, Ns Sy volume
2680 Display numbers in parsable
2684 Recursively display any children of the dataset on the command line.
2685 .It Fl s Ar property
2686 A property for sorting the output by column in ascending order based on the
2687 value of the property.
2688 The property must be one of the properties described in the
2690 section, or the special value
2692 to sort by the dataset name.
2693 Multiple properties can be specified at one time using multiple
2698 options are evaluated from left to right in decreasing order of importance.
2699 The following is a list of sorting criteria:
2702 Numeric types sort in numeric order.
2704 String types sort in alphabetical order.
2706 Types inappropriate for a row sort that row to the literal bottom, regardless of
2707 the specified ordering.
2710 If no sorting options are specified the existing behavior of
2714 A comma-separated list of types to display, where
2723 For example, specifying
2725 displays only snapshots.
2730 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2731 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2733 Sets the property or list of properties to the given value(s) for each dataset.
2734 Only some properties can be edited.
2737 section for more information on what properties can be set and acceptable
2739 Numeric values can be specified as exact values, or in a human-readable form
2741 .Sy B , K , M , G , T , P , E , Z
2742 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2743 or zettabytes, respectively
2745 User properties can be set on snapshots.
2746 For more information, see the
2752 .Op Fl r Ns | Ns Fl d Ar depth
2754 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2755 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2756 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2757 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2758 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2760 Displays properties for the given datasets.
2761 If no datasets are specified, then the command displays properties for all
2762 datasets on the system.
2763 For each property, the following columns are displayed:
2766 property Property name
2767 value Property value
2768 source Property source. Can either be local, default,
2769 temporary, inherited, or none (-).
2772 All columns are displayed by default, though this can be controlled by using the
2775 This command takes a comma-separated list of properties as described in the
2776 .Sx Native Properties
2783 can be used to display all properties that apply to the given dataset's type
2784 .Pq filesystem, volume, snapshot, or bookmark .
2785 .Bl -tag -width "-H"
2787 Display output in a form more easily parsed by scripts.
2788 Any headers are omitted, and fields are explicitly separated by a single tab
2789 instead of an arbitrary amount of space.
2791 Recursively display any children of the dataset, limiting the recursion to
2795 will display only the dataset and its direct children.
2797 A comma-separated list of columns to display.
2798 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2799 is the default value.
2801 Display numbers in parsable
2805 Recursively display properties for any children.
2807 A comma-separated list of sources to display.
2808 Those properties coming from a source other than those in this list are ignored.
2809 Each source must be one of the following:
2816 The default value is all sources.
2818 A comma-separated list of types to display, where
2832 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2834 Clears the specified property, causing it to be inherited from an ancestor,
2835 restored to default if no ancestor has the property set, or with the
2837 option reverted to the received value if one exists.
2840 section for a listing of default values, and details on which properties can be
2842 .Bl -tag -width "-r"
2844 Recursively inherit the given property for all children.
2846 Revert the property to the received value if one exists; otherwise operate as
2849 option was not specified.
2855 Displays a list of file systems that are not the most recent version.
2861 Displays a list of currently supported file system versions.
2867 .Fl a | Ar filesystem
2869 Upgrades file systems to a new on-disk version.
2870 Once this is done, the file systems will no longer be accessible on systems
2871 running older versions of the software.
2873 streams generated from new snapshots of these file systems cannot be accessed on
2874 systems running older versions of the software.
2876 In general, the file system version is independent of the pool version.
2879 for information on the
2880 .Nm zpool Cm upgrade
2883 In some cases, the file system version and the pool version are interrelated and
2884 the pool version must be upgraded before the file system version can be
2886 .Bl -tag -width "-V"
2888 Upgrade to the specified
2892 flag is not specified, this command upgrades to the most recent version.
2894 option can only be used to increase the version number, and only up to the most
2895 recent version supported by this software.
2897 Upgrade all file systems on all imported pools.
2899 Upgrade the specified file system.
2901 Upgrade the specified file system and all descendent file systems.
2907 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2908 .Oo Fl s Ar field Oc Ns ...
2909 .Oo Fl S Ar field Oc Ns ...
2910 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2911 .Ar filesystem Ns | Ns Ar snapshot
2913 Displays space consumed by, and quotas on, each user in the specified filesystem
2915 This corresponds to the
2916 .Sy userused@ Ns Em user ,
2917 .Sy userobjused@ Ns Em user ,
2918 .Sy userquota@ Ns Em user,
2920 .Sy userobjquota@ Ns Em user
2922 .Bl -tag -width "-H"
2924 Do not print headers, use tab-delimited output.
2926 Sort by this field in reverse order.
2930 Translate SID to POSIX ID.
2931 The POSIX ID may be ephemeral if no mapping exists.
2932 Normal POSIX interfaces
2937 perform this translation, so the
2939 option allows the output from
2940 .Nm zfs Cm userspace
2941 to be compared directly with those utilities.
2944 may lead to confusion if some files were created by an SMB user before a
2945 SMB-to-POSIX name mapping was established.
2946 In such a case, some files will be owned by the SMB entity and some by the POSIX
2950 option will report that the POSIX entity has the total usage and quota for both.
2952 Print numeric ID instead of user/group name.
2953 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2954 Display only the specified fields from the following set:
2959 The default is to display all fields.
2965 Sort output by this field.
2970 flags may be specified multiple times to sort first by one field, then by
2973 .Fl s Sy type Fl s Sy name .
2974 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2975 Print only the specified types from the following set:
2982 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
2983 The default can be changed to include group types.
2989 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2990 .Oo Fl s Ar field Oc Ns ...
2991 .Oo Fl S Ar field Oc Ns ...
2992 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2993 .Ar filesystem Ns | Ns Ar snapshot
2995 Displays space consumed by, and quotas on, each group in the specified
2996 filesystem or snapshot.
2997 This subcommand is identical to
2998 .Nm zfs Cm userspace ,
2999 except that the default types to display are
3000 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
3005 Displays all ZFS file systems currently mounted.
3011 .Fl a | Ar filesystem
3013 Mounts ZFS file systems.
3014 .Bl -tag -width "-O"
3016 Perform an overlay mount.
3019 for more information.
3021 Mount all available ZFS file systems.
3022 Invoked automatically as part of the boot process.
3024 Mount the specified filesystem.
3026 An optional, comma-separated list of mount options to use temporarily for the
3027 duration of the mount.
3029 .Sx Temporary Mount Point Properties
3030 section for details.
3032 Load keys for encrypted filesystems as they are being mounted. This is
3033 equivalent to executing
3035 on each encryption root before mounting it. Note that if a filesystem has a
3039 this will cause the terminal to interactively block after asking for the key.
3041 Report mount progress.
3047 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3049 Unmounts currently mounted ZFS file systems.
3050 .Bl -tag -width "-a"
3052 Unmount all available ZFS file systems.
3053 Invoked automatically as part of the shutdown process.
3054 .It Ar filesystem Ns | Ns Ar mountpoint
3055 Unmount the specified filesystem.
3056 The command can also be given a path to a ZFS file system mount point on the
3059 Forcefully unmount the file system, even if it is currently in use.
3064 .Fl a | Ar filesystem
3066 Shares available ZFS file systems.
3067 .Bl -tag -width "-a"
3069 Share all available ZFS file systems.
3070 Invoked automatically as part of the boot process.
3072 Share the specified filesystem according to the
3077 File systems are shared when the
3086 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
3088 Unshares currently shared ZFS file systems.
3089 .Bl -tag -width "-a"
3091 Unshare all available ZFS file systems.
3092 Invoked automatically as part of the shutdown process.
3093 .It Ar filesystem Ns | Ns Ar mountpoint
3094 Unshare the specified filesystem.
3095 The command can also be given a path to a ZFS file system shared on the system.
3100 .Ar snapshot bookmark
3102 Creates a bookmark of the given snapshot.
3103 Bookmarks mark the point in time when the snapshot was created, and can be used
3104 as the incremental source for a
3108 This feature must be enabled to be used.
3110 .Xr zpool-features 5
3111 for details on ZFS feature flags and the
3118 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
3121 Creates a stream representation of the second
3123 which is written to standard output.
3124 The output can be redirected to a file or to a different system
3125 .Po for example, using
3128 By default, a full stream is generated.
3129 .Bl -tag -width "-D"
3131 Generate a deduplicated stream.
3132 Blocks which would have been sent multiple times in the send stream will only be
3134 The receiving system must also support this feature to receive a deduplicated
3136 This flag can be used regardless of the dataset's
3138 property, but performance will be much better if the filesystem uses a
3139 dedup-capable checksum
3143 .It Fl I Ar snapshot
3144 Generate a stream package that sends all intermediary snapshots from the first
3145 snapshot to the second snapshot.
3149 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
3150 The incremental source may be specified as with the
3153 .It Fl L, -large-block
3154 Generate a stream which may contain blocks larger than 128KB.
3155 This flag has no effect if the
3157 pool feature is disabled, or if the
3159 property of this filesystem has never been set above 128KB.
3160 The receiving system must have the
3162 pool feature enabled as well.
3164 .Xr zpool-features 5
3165 for details on ZFS feature flags and the
3169 Print machine-parsable verbose information about the stream package generated.
3170 .It Fl R, -replicate
3171 Generate a replication stream package, which will replicate the specified
3172 file system, and all descendent file systems, up to the named snapshot.
3173 When received, all properties, snapshots, descendent file systems, and clones
3180 flags are used in conjunction with the
3182 flag, an incremental replication stream is generated.
3183 The current values of properties, and current snapshot and file system names are
3184 set when the stream is received.
3187 flag is specified when this stream is received, snapshots and file systems that
3188 do not exist on the sending side are destroyed.
3190 Generate a more compact stream by using
3192 records for blocks which are stored more compactly on disk by the
3195 This flag has no effect if the
3197 feature is disabled.
3198 The receiving system must have the
3203 feature is active on the sending system, then the receiving system must have
3204 that feature enabled as well. Datasets that are sent with this flag may not be
3205 received as an encrypted dataset, since encrypted datasets cannot use the
3209 .Xr zpool-features 5
3210 for details on ZFS feature flags and the
3213 .It Fl c, -compressed
3214 Generate a more compact stream by using compressed WRITE records for blocks
3215 which are compressed on disk and in memory
3218 property for details
3222 feature is active on the sending system, then the receiving system must have
3223 that feature enabled as well.
3226 feature is enabled on the sending system but the
3228 option is not supplied in conjunction with
3230 then the data will be decompressed before sending so it can be split into
3231 smaller block sizes.
3233 For encrypted datasets, send data exactly as it exists on disk. This allows
3234 backups to be taken even if encryption keys are not currently loaded. The
3235 backup may then be received on an untrusted machine since that machine will
3236 not have the encryption keys to read the protected data or alter it without
3237 being detected. Upon being received, the dataset will have the same encryption
3238 keys as it did on the send side, although the
3240 property will be defaulted to
3242 if not otherwise provided. For unencrypted datasets, this flag will be
3245 Note that if you do not use this flag for sending encrypted datasets, data will
3246 be sent unencrypted and may be re-encrypted with a different encryption key on
3247 the receiving system, which will disable the ability to do a raw send to that
3248 system for incrementals.
3249 .It Fl i Ar snapshot
3250 Generate an incremental stream from the first
3252 .Pq the incremental source
3255 .Pq the incremental target .
3256 The incremental source can be specified as the last component of the snapshot
3260 character and following
3262 and it is assumed to be from the same file system as the incremental target.
3264 If the destination is a clone, the source may be the origin snapshot, which must
3267 .Em pool/fs@origin ,
3275 Do not generate any actual send data.
3276 This is useful in conjunction with the
3280 flags to determine what data will be sent.
3281 In this case, the verbose output will be written to standard output
3282 .Po contrast with a non-dry-run, where the stream is written to standard output
3283 and the verbose output goes to standard error
3286 Include the dataset's properties in the stream.
3287 This flag is implicit when
3290 The receiving system must also support this feature. Sends of encrypted datasets
3293 when using this flag.
3295 Print verbose information about the stream package generated.
3296 This information includes a per-second report of how much data has been sent.
3298 The format of the stream is committed.
3299 You will be able to receive your streams on future versions of ZFS.
3305 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3306 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3308 Generate a send stream, which may be of a filesystem, and may be incremental
3310 If the destination is a filesystem or volume, the pool must be read-only, or the
3311 filesystem must not be mounted.
3312 When the stream generated from a filesystem or volume is received, the default
3313 snapshot name will be
3315 .Bl -tag -width "-L"
3316 .It Fl L, -large-block
3317 Generate a stream which may contain blocks larger than 128KB.
3318 This flag has no effect if the
3320 pool feature is disabled, or if the
3322 property of this filesystem has never been set above 128KB.
3323 The receiving system must have the
3325 pool feature enabled as well.
3327 .Xr zpool-features 5
3328 for details on ZFS feature flags and the
3332 Print machine-parsable verbose information about the stream package generated.
3333 .It Fl c, -compressed
3334 Generate a more compact stream by using compressed WRITE records for blocks
3335 which are compressed on disk and in memory
3338 property for details
3342 feature is active on the sending system, then the receiving system must have
3343 that feature enabled as well.
3346 feature is enabled on the sending system but the
3348 option is not supplied in conjunction with
3350 then the data will be decompressed before sending so it can be split into
3351 smaller block sizes.
3353 For encrypted datasets, send data exactly as it exists on disk. This allows
3354 backups to be taken even if encryption keys are not currently loaded. The
3355 backup may then be received on an untrusted machine since that machine will
3356 not have the encryption keys to read the protected data or alter it without
3357 being detected. Upon being received, the dataset will have the same encryption
3358 keys as it did on the send side, although the
3360 property will be defaulted to
3362 if not otherwise provided. For unencrypted datasets, this flag will be
3365 Note that if you do not use this flag for sending encrypted datasets, data will
3366 be sent unencrypted and may be re-encrypted with a different encryption key on
3367 the receiving system, which will disable the ability to do a raw send to that
3368 system for incrementals.
3370 Generate a more compact stream by using
3372 records for blocks which are stored more compactly on disk by the
3375 This flag has no effect if the
3377 feature is disabled.
3378 The receiving system must have the
3383 feature is active on the sending system, then the receiving system must have
3384 that feature enabled as well. Datasets that are sent with this flag may not be
3385 received as an encrypted dataset, since encrypted datasets cannot use the
3389 .Xr zpool-features 5
3390 for details on ZFS feature flags and the
3393 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3394 Generate an incremental send stream.
3395 The incremental source must be an earlier snapshot in the destination's history.
3396 It will commonly be an earlier snapshot in the destination's file system, in
3397 which case it can be specified as the last component of the name
3402 character and following
3405 If the incremental target is a clone, the incremental source can be the origin
3406 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3412 Do not generate any actual send data.
3413 This is useful in conjunction with the
3417 flags to determine what data will be sent.
3418 In this case, the verbose output will be written to standard output
3419 .Po contrast with a non-dry-run, where the stream is written to standard output
3420 and the verbose output goes to standard error
3423 Print verbose information about the stream package generated.
3424 This information includes a per-second report of how much data has been sent.
3431 .Ar receive_resume_token
3433 Creates a send stream which resumes an interrupted receive.
3435 .Ar receive_resume_token
3436 is the value of this property on the filesystem or volume that was being
3438 See the documentation for
3445 .Op Fl o Sy origin Ns = Ns Ar snapshot
3446 .Op Fl o Ar property Ns = Ns Ar value
3447 .Op Fl x Ar property
3448 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3454 .Op Fl d Ns | Ns Fl e
3455 .Op Fl o Sy origin Ns = Ns Ar snapshot
3456 .Op Fl o Ar property Ns = Ns Ar value
3457 .Op Fl x Ar property
3460 Creates a snapshot whose contents are as specified in the stream provided on
3462 If a full stream is received, then a new file system is created as well.
3463 Streams are created using the
3465 subcommand, which by default creates a full stream.
3467 can be used as an alias for
3470 If an incremental stream is received, then the destination file system must
3471 already exist, and its most recent snapshot must match the incremental stream's
3475 the destination device link is destroyed and recreated, which means the
3477 cannot be accessed during the
3481 When a snapshot replication package stream that is generated by using the
3482 .Nm zfs Cm send Fl R
3483 command is received, any snapshots that do not exist on the sending location are
3484 destroyed by using the
3485 .Nm zfs Cm destroy Fl d
3489 .Fl o Em property Ns = Ns Ar value
3492 is specified, it applies to the effective value of the property throughout
3493 the entire subtree of replicated datasets. Effective property values will be
3498 ) on the topmost in the replicated subtree. In descendant datasets, if the
3499 property is set by the send stream, it will be overridden by forcing the
3500 property to be inherited from the top‐most file system. Received properties
3501 are retained in spite of being overridden and may be restored with
3502 .Nm zfs Cm inherit Fl S .
3504 .Fl o Sy origin Ns = Ns Em snapshot
3505 is a special case because, even if
3507 is a read-only property and cannot be set, it's allowed to receive the send
3508 stream as a clone of the given snapshot.
3510 Raw encrypted send streams (created with
3511 .Nm zfs Cm send Fl w
3512 ) may only be received as is, and cannot be re-encrypted, decrypted, or
3513 recompressed by the receive process. Unencrypted streams can be received as
3514 encrypted datasets, either through inheritance or by specifying encryption
3519 The name of the snapshot
3520 .Pq and file system, if a full stream is received
3521 that this subcommand creates depends on the argument type and the use of the
3527 If the argument is a snapshot name, the specified
3530 If the argument is a file system or volume name, a snapshot with the same name
3531 as the sent snapshot is created within the specified
3539 options are specified, the provided target snapshot name is used exactly as
3546 options cause the file system name of the target snapshot to be determined by
3547 appending a portion of the sent snapshot's name to the specified target
3551 option is specified, all but the first element of the sent snapshot's file
3553 .Pq usually the pool name
3554 is used and any required intermediate file systems within the specified one are
3558 option is specified, then only the last element of the sent snapshot's file
3560 .Pq i.e. the name of the source file system itself
3561 is used as the target file system name.
3562 .Bl -tag -width "-F"
3564 Force a rollback of the file system to the most recent snapshot before
3565 performing the receive operation.
3566 If receiving an incremental replication stream
3567 .Po for example, one generated by
3568 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3570 destroy snapshots and file systems that do not exist on the sending side.
3572 Discard the first element of the sent snapshot's file system name, using the
3573 remaining elements to determine the name of the target file system for the new
3574 snapshot as described in the paragraph above.
3576 Discard all but the last element of the sent snapshot's file system name, using
3577 that element to determine the name of the target file system for the new
3578 snapshot as described in the paragraph above.
3580 Do not actually receive the stream.
3581 This can be useful in conjunction with the
3583 option to verify the name the receive operation would use.
3584 .It Fl o Sy origin Ns = Ns Ar snapshot
3585 Forces the stream to be received as a clone of the given snapshot.
3586 If the stream is a full send stream, this will create the filesystem
3587 described by the stream as a clone of the specified snapshot.
3588 Which snapshot was specified will not affect the success or failure of the
3589 receive, as long as the snapshot does exist.
3590 If the stream is an incremental send stream, all the normal verification will be
3592 .It Fl o Em property Ns = Ns Ar value
3593 Sets the specified property as if the command
3594 .Nm zfs Cm set Em property Ns = Ns Ar value
3595 was invoked immediately before the receive. When receiving a stream from
3596 .Nm zfs Cm send Fl R ,
3597 causes the property to be inherited by all descendant datasets, as through
3598 .Nm zfs Cm inherit Em property
3599 was run on any descendant datasets that have this property set on the
3602 Any editable property can be set at receive time. Set-once properties bound
3603 to the received data, such as
3606 .Sy casesensitivity ,
3607 cannot be set at receive time even when the datasets are newly created by
3608 .Nm zfs Cm receive .
3609 Additionally both settable properties
3613 cannot be set at receive time.
3617 option may be specified multiple times, for different properties. An error
3618 results if the same property is specified in multiple
3624 If the receive is interrupted, save the partially received state, rather
3626 Interruption may be due to premature termination of the stream
3627 .Po e.g. due to network failure or failure of the remote system
3628 if the stream is being read over a network connection
3630 a checksum error in the stream, termination of the
3632 process, or unclean shutdown of the system.
3634 The receive can be resumed with a stream generated by
3635 .Nm zfs Cm send Fl t Ar token ,
3639 .Sy receive_resume_token
3640 property of the filesystem or volume which is received into.
3642 To use this flag, the storage pool must have the
3643 .Sy extensible_dataset
3646 .Xr zpool-features 5
3647 for details on ZFS feature flags.
3649 File system that is associated with the received stream is not mounted.
3651 Print verbose information about the stream and the time required to perform the
3653 .It Fl x Em property
3654 Ensures that the effective value of the specified property after the
3655 receive is unaffected by the value of that property in the send stream (if any),
3656 as if the property had been excluded from the send stream.
3658 If the specified property is not present in the send stream, this option does
3661 If a received property needs to be overridden, the effective value will be
3662 set or inherited, depending on whether the property is inheritable or not.
3664 In the case of an incremental update,
3666 leaves any existing local setting or explicit inheritance unchanged.
3670 restrictions on set-once and special properties apply equally to
3677 .Ar filesystem Ns | Ns Ar volume
3679 Abort an interrupted
3680 .Nm zfs Cm receive Fl s ,
3681 deleting its saved partially received state.
3685 .Ar filesystem Ns | Ns Ar volume
3687 Displays permissions that have been delegated on the specified filesystem or
3689 See the other forms of
3691 for more information.
3693 Delegations are supported under Linux with the exception of
3701 These permissions cannot be delegated because the Linux
3703 command restricts modifications of the global namespace to the root user.
3708 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3709 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3710 .Ar setname Oc Ns ...
3711 .Ar filesystem Ns | Ns Ar volume
3716 .Fl e Ns | Ns Sy everyone
3717 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3718 .Ar setname Oc Ns ...
3719 .Ar filesystem Ns | Ns Ar volume
3721 Delegates ZFS administration permission for the file systems to non-privileged
3723 .Bl -tag -width "-d"
3725 Allow only for the descendent file systems.
3726 .It Fl e Ns | Ns Sy everyone
3727 Specifies that the permissions be delegated to everyone.
3728 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3729 Explicitly specify that permissions are delegated to the group.
3733 only for the specified file system.
3734 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3735 Explicitly specify that permissions are delegated to the user.
3736 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3737 Specifies to whom the permissions are delegated.
3738 Multiple entities can be specified as a comma-separated list.
3741 options are specified, then the argument is interpreted preferentially as the
3744 then as a user name, and lastly as a group name.
3745 To specify a user or group named
3752 To specify a group with the same name as a user, use the
3756 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3757 .Ar setname Oc Ns ...
3759 The permissions to delegate.
3760 Multiple permissions may be specified as a comma-separated list.
3761 Permission names are the same as ZFS subcommand and property names.
3762 See the property list below.
3763 Property set names, which begin with
3768 form below for details.
3773 options are specified, or both are, then the permissions are allowed for the
3774 file system or volume, and all of its descendents.
3776 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3778 The following permissions are available:
3781 allow subcommand Must also have the permission that is
3783 clone subcommand Must also have the 'create' ability and
3784 'mount' ability in the origin file system
3785 create subcommand Must also have the 'mount' ability
3786 destroy subcommand Must also have the 'mount' ability
3787 diff subcommand Allows lookup of paths within a dataset
3788 given an object number, and the ability
3789 to create snapshots necessary to
3791 load-key subcommand Allows loading and unloading of encryption key
3792 (see 'zfs load-key' and 'zfs unload-key').
3793 change-key subcommand Allows changing an encryption key via
3795 mount subcommand Allows mount/umount of ZFS datasets
3796 promote subcommand Must also have the 'mount' and 'promote'
3797 ability in the origin file system
3798 receive subcommand Must also have the 'mount' and 'create'
3800 rename subcommand Must also have the 'mount' and 'create'
3801 ability in the new parent
3802 rollback subcommand Must also have the 'mount' ability
3804 share subcommand Allows sharing file systems over NFS
3806 snapshot subcommand Must also have the 'mount' ability
3808 groupquota other Allows accessing any groupquota@...
3810 groupused other Allows reading any groupused@... property
3811 userprop other Allows changing any user property
3812 userquota other Allows accessing any userquota@...
3814 userused other Allows reading any userused@... property
3820 casesensitivity property
3822 compression property
3826 filesystem_limit property
3829 normalization property
3830 primarycache property
3835 refreservation property
3836 reservation property
3837 secondarycache property
3842 snapshot_limit property
3845 volblocksize property
3855 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3856 .Ar setname Oc Ns ...
3857 .Ar filesystem Ns | Ns Ar volume
3862 These permissions are granted
3864 to the creator of any newly-created descendent file system.
3868 .Fl s No @ Ns Ar setname
3869 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3870 .Ar setname Oc Ns ...
3871 .Ar filesystem Ns | Ns Ar volume
3873 Defines or adds permissions to a permission set.
3874 The set can be used by other
3876 commands for the specified file system and its descendents.
3877 Sets are evaluated dynamically, so changes to a set are immediately reflected.
3878 Permission sets follow the same naming restrictions as ZFS file systems, but the
3879 name must begin with
3881 and can be no more than 64 characters long.
3886 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3887 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3888 .Ar setname Oc Ns ... Oc
3889 .Ar filesystem Ns | Ns Ar volume
3894 .Fl e Ns | Ns Sy everyone
3895 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3896 .Ar setname Oc Ns ... Oc
3897 .Ar filesystem Ns | Ns Ar volume
3903 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3904 .Ar setname Oc Ns ... Oc
3905 .Ar filesystem Ns | Ns Ar volume
3907 Removes permissions that were granted with the
3910 No permissions are explicitly denied, so other permissions granted are still in
3912 For example, if the permission is granted by an ancestor.
3913 If no permissions are specified, then all permissions for the specified
3925 only removes the permissions that were granted to everyone, not all permissions
3926 for every user and group.
3929 command for a description of the
3932 .Bl -tag -width "-r"
3934 Recursively remove the permissions from this file system and all descendents.
3940 .Fl s No @ Ns Ar setname
3941 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3942 .Ar setname Oc Ns ... Oc
3943 .Ar filesystem Ns | Ns Ar volume
3945 Removes permissions from a permission set.
3946 If no permissions are specified, then all permissions are removed, thus removing
3952 .Ar tag Ar snapshot Ns ...
3954 Adds a single reference, named with the
3956 argument, to the specified snapshot or snapshots.
3957 Each snapshot has its own tag namespace, and tags must be unique within that
3960 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3964 .Bl -tag -width "-r"
3966 Specifies that a hold with the given tag is applied recursively to the snapshots
3967 of all descendent file systems.
3975 Lists all existing user references for the given snapshot or snapshots.
3976 .Bl -tag -width "-r"
3978 Lists the holds that are set on the named descendent snapshots, in addition to
3979 listing the holds on the named snapshot.
3985 .Ar tag Ar snapshot Ns ...
3987 Removes a single reference, named with the
3989 argument, from the specified snapshot or snapshots.
3990 The tag must already exist for each snapshot.
3991 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3995 .Bl -tag -width "-r"
3997 Recursively releases a hold with the given tag on the snapshots of all
3998 descendent file systems.
4004 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
4006 Display the difference between a snapshot of a given filesystem and another
4007 snapshot of that filesystem from a later time or the current contents of the
4009 The first column is a character indicating the type of change, the other columns
4010 indicate pathname, new pathname
4011 .Pq in case of rename ,
4012 change in link count, and optionally file type and/or change time.
4013 The types of change are:
4015 - The path has been removed
4016 + The path has been created
4017 M The path has been modified
4018 R The path has been renamed
4020 .Bl -tag -width "-F"
4022 Display an indication of the type of file, in a manner similar to the
4038 Give more parsable tab-separated output, without header lines and without
4041 Display the path's inode change time as the first column of output.
4048 .Op Fl m Ar memory_limit
4054 as a ZFS channel program on
4057 program interface allows ZFS administrative operations to be run
4058 programmatically via a Lua script.
4059 The entire script is executed atomically, with no other administrative
4060 operations taking effect concurrently.
4061 A library of ZFS calls is made available to channel program scripts.
4062 Channel programs may only be run with root privileges.
4064 For full documentation of the ZFS channel program interface, see the manual
4069 Executes a read-only channel program, which runs faster.
4070 The program cannot change on-disk state by calling functions from
4071 the zfs.sync submodule.
4072 The program can be used to gather information such as properties and
4073 determining if changes would succeed (zfs.check.*).
4074 Without this flag, all pending changes must be synced to disk before
4075 a channel program can complete.
4077 Execution time limit, in milliseconds.
4078 If a channel program executes for longer than the provided timeout, it will
4079 be stopped and an error will be returned.
4080 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
4081 .It Fl m Ar memory-limit
4082 Memory limit, in bytes.
4083 If a channel program attempts to allocate more memory than the given limit,
4084 it will be stopped and an error returned.
4085 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
4087 All remaining argument strings are passed directly to the channel program as
4091 for more information.
4097 .Op Fl L Ar keylocation
4098 .Fl a | Ar filesystem
4102 allowing it and all children that inherit the
4104 property to be accessed. The key will be expected in the format specified by the
4106 and location specified by the
4108 property. Note that if the
4112 the terminal will interactively wait for the key to be entered. Loading a key
4113 will not automatically mount the dataset. If that functionality is desired,
4114 .Nm zfs Cm mount Sy -l
4115 will ask for the key and mount the dataset. Once the key is loaded the
4117 property will become
4119 .Bl -tag -width "-r"
4121 Recursively loads the keys for the specified filesystem and all descendent
4124 Loads the keys for all encryption roots in all imported pools.
4128 load-key. This will cause zfs to simply check that the
4129 provided key is correct. This command may be run even if the key is already
4131 .It Fl L Ar keylocation
4136 property. This will not change the value of the property on the dataset. Note
4137 that if used with either
4142 may only be given as
4149 .Fl a | Ar filesystem
4151 Unloads a key from ZFS, removing the ability to access the dataset and all of
4152 its children that inherit the
4154 property. This requires that the dataset is not currently open or mounted. Once
4155 the key is unloaded the
4157 property will become
4159 .Bl -tag -width "-r"
4161 Recursively unloads the keys for the specified filesystem and all descendent
4164 Unloads the keys for all encryption roots in all imported pools.
4170 .Op Fl o Ar keylocation Ns = Ns Ar value
4171 .Op Fl o Ar keyformat Ns = Ns Ar value
4172 .Op Fl o Ar pbkdf2iters Ns = Ns Ar value
4182 Allows a user to change the encryption key used to access a dataset. This
4183 command requires that the existing key for the dataset is already loaded into
4184 ZFS. This command may also be used to change the
4189 properties as needed. If the dataset was not previously an encryption root it
4190 will become one. Alternatively, the
4192 flag may be provided to cause an encryption root to inherit the parent's key
4194 .Bl -tag -width "-r"
4196 Ensures the key is loaded before attempting to change the key. This is
4197 effectively equivalent to
4198 .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem
4199 .It Fl o Ar property Ns = Ns Ar value
4200 Allows the user to set encryption key properties (
4205 ) while changing the key. This is the only way to alter
4209 after the dataset has been created.
4211 Indicates that zfs should make
4213 inherit the key of its parent. Note that this command can only be run on an
4214 encryption root that has an encrypted parent.
4220 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
4221 options were specified.
4224 .It Sy Example 1 No Creating a ZFS File System Hierarchy
4225 The following commands create a file system named
4227 and a file system named
4231 is set for the parent file system, and is automatically inherited by the child
4234 # zfs create pool/home
4235 # zfs set mountpoint=/export/home pool/home
4236 # zfs create pool/home/bob
4238 .It Sy Example 2 No Creating a ZFS Snapshot
4239 The following command creates a snapshot named
4241 This snapshot is mounted on demand in the
4243 directory at the root of the
4247 # zfs snapshot pool/home/bob@yesterday
4249 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
4250 The following command creates snapshots named
4254 and all of its descendent file systems.
4255 Each snapshot is mounted on demand in the
4257 directory at the root of its file system.
4258 The second command destroys the newly created snapshots.
4260 # zfs snapshot -r pool/home@yesterday
4261 # zfs destroy -r pool/home@yesterday
4263 .It Sy Example 4 No Disabling and Enabling File System Compression
4264 The following command disables the
4266 property for all file systems under
4268 The next command explicitly enables
4271 .Em pool/home/anne .
4273 # zfs set compression=off pool/home
4274 # zfs set compression=on pool/home/anne
4276 .It Sy Example 5 No Listing ZFS Datasets
4277 The following command lists all active file systems and volumes in the system.
4278 Snapshots are displayed if the
4286 for more information on pool properties.
4289 NAME USED AVAIL REFER MOUNTPOINT
4290 pool 450K 457G 18K /pool
4291 pool/home 315K 457G 21K /export/home
4292 pool/home/anne 18K 457G 18K /export/home/anne
4293 pool/home/bob 276K 457G 276K /export/home/bob
4295 .It Sy Example 6 No Setting a Quota on a ZFS File System
4296 The following command sets a quota of 50 Gbytes for
4299 # zfs set quota=50G pool/home/bob
4301 .It Sy Example 7 No Listing ZFS Properties
4302 The following command lists all properties for
4305 # zfs get all pool/home/bob
4306 NAME PROPERTY VALUE SOURCE
4307 pool/home/bob type filesystem -
4308 pool/home/bob creation Tue Jul 21 15:53 2009 -
4309 pool/home/bob used 21K -
4310 pool/home/bob available 20.0G -
4311 pool/home/bob referenced 21K -
4312 pool/home/bob compressratio 1.00x -
4313 pool/home/bob mounted yes -
4314 pool/home/bob quota 20G local
4315 pool/home/bob reservation none default
4316 pool/home/bob recordsize 128K default
4317 pool/home/bob mountpoint /pool/home/bob default
4318 pool/home/bob sharenfs off default
4319 pool/home/bob checksum on default
4320 pool/home/bob compression on local
4321 pool/home/bob atime on default
4322 pool/home/bob devices on default
4323 pool/home/bob exec on default
4324 pool/home/bob setuid on default
4325 pool/home/bob readonly off default
4326 pool/home/bob zoned off default
4327 pool/home/bob snapdir hidden default
4328 pool/home/bob acltype off default
4329 pool/home/bob aclinherit restricted default
4330 pool/home/bob canmount on default
4331 pool/home/bob xattr on default
4332 pool/home/bob copies 1 default
4333 pool/home/bob version 4 -
4334 pool/home/bob utf8only off -
4335 pool/home/bob normalization none -
4336 pool/home/bob casesensitivity sensitive -
4337 pool/home/bob vscan off default
4338 pool/home/bob nbmand off default
4339 pool/home/bob sharesmb off default
4340 pool/home/bob refquota none default
4341 pool/home/bob refreservation none default
4342 pool/home/bob primarycache all default
4343 pool/home/bob secondarycache all default
4344 pool/home/bob usedbysnapshots 0 -
4345 pool/home/bob usedbydataset 21K -
4346 pool/home/bob usedbychildren 0 -
4347 pool/home/bob usedbyrefreservation 0 -
4350 The following command gets a single property value.
4352 # zfs get -H -o value compression pool/home/bob
4355 The following command lists all properties with local settings for
4358 # zfs get -r -s local -o name,property,value all pool/home/bob
4360 pool/home/bob quota 20G
4361 pool/home/bob compression on
4363 .It Sy Example 8 No Rolling Back a ZFS File System
4364 The following command reverts the contents of
4366 to the snapshot named
4368 deleting all intermediate snapshots.
4370 # zfs rollback -r pool/home/anne@yesterday
4372 .It Sy Example 9 No Creating a ZFS Clone
4373 The following command creates a writable file system whose initial contents are
4375 .Em pool/home/bob@yesterday .
4377 # zfs clone pool/home/bob@yesterday pool/clone
4379 .It Sy Example 10 No Promoting a ZFS Clone
4380 The following commands illustrate how to test out changes to a file system, and
4381 then replace the original file system with the changed one, using clones, clone
4382 promotion, and renaming:
4384 # zfs create pool/project/production
4385 populate /pool/project/production with data
4386 # zfs snapshot pool/project/production@today
4387 # zfs clone pool/project/production@today pool/project/beta
4388 make changes to /pool/project/beta and test them
4389 # zfs promote pool/project/beta
4390 # zfs rename pool/project/production pool/project/legacy
4391 # zfs rename pool/project/beta pool/project/production
4392 once the legacy version is no longer needed, it can be destroyed
4393 # zfs destroy pool/project/legacy
4395 .It Sy Example 11 No Inheriting ZFS Properties
4396 The following command causes
4402 property from their parent.
4404 # zfs inherit checksum pool/home/bob pool/home/anne
4406 .It Sy Example 12 No Remotely Replicating ZFS Data
4407 The following commands send a full stream and then an incremental stream to a
4408 remote machine, restoring them into
4409 .Em poolB/received/fs@a
4411 .Em poolB/received/fs@b ,
4414 must contain the file system
4415 .Em poolB/received ,
4416 and must not initially contain
4417 .Em poolB/received/fs .
4419 # zfs send pool/fs@a | \e
4420 ssh host zfs receive poolB/received/fs@a
4421 # zfs send -i a pool/fs@b | \e
4422 ssh host zfs receive poolB/received/fs
4424 .It Sy Example 13 No Using the zfs receive -d Option
4425 The following command sends a full stream of
4426 .Em poolA/fsA/fsB@snap
4427 to a remote machine, receiving it into
4428 .Em poolB/received/fsA/fsB@snap .
4431 portion of the received snapshot's name is determined from the name of the sent
4434 must contain the file system
4435 .Em poolB/received .
4437 .Em poolB/received/fsA
4438 does not exist, it is created as an empty file system.
4440 # zfs send poolA/fsA/fsB@snap | \e
4441 ssh host zfs receive -d poolB/received
4443 .It Sy Example 14 No Setting User Properties
4444 The following example sets the user-defined
4445 .Sy com.example:department
4446 property for a dataset.
4448 # zfs set com.example:department=12345 tank/accounting
4450 .It Sy Example 15 No Performing a Rolling Snapshot
4451 The following example shows how to maintain a history of snapshots with a
4452 consistent naming scheme.
4453 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
4454 renames the remaining snapshots, and then creates a new snapshot, as follows:
4456 # zfs destroy -r pool/users@7daysago
4457 # zfs rename -r pool/users@6daysago @7daysago
4458 # zfs rename -r pool/users@5daysago @6daysago
4459 # zfs rename -r pool/users@yesterday @5daysago
4460 # zfs rename -r pool/users@yesterday @4daysago
4461 # zfs rename -r pool/users@yesterday @3daysago
4462 # zfs rename -r pool/users@yesterday @2daysago
4463 # zfs rename -r pool/users@today @yesterday
4464 # zfs snapshot -r pool/users@today
4466 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
4467 The following commands show how to set
4469 property options to enable
4473 addresses and to enable root access for system
4479 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4484 for host name resolution, specify the fully qualified hostname.
4485 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4486 The following example shows how to set permissions so that user
4488 can create, destroy, mount, and take snapshots on
4494 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4495 # zfs allow tank/cindys
4496 ---- Permissions on tank/cindys --------------------------------------
4497 Local+Descendent permissions:
4498 user cindys create,destroy,mount,snapshot
4503 mount point permission is set to 755 by default, user
4505 will be unable to mount file systems under
4507 Add an ACE similar to the following syntax to provide mount point access:
4509 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4511 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4512 The following example shows how to grant anyone in the group
4514 to create file systems in
4516 This syntax also allows staff members to destroy their own file systems, but not
4517 destroy anyone else's file system.
4522 # zfs allow staff create,mount tank/users
4523 # zfs allow -c destroy tank/users
4524 # zfs allow tank/users
4525 ---- Permissions on tank/users ---------------------------------------
4528 Local+Descendent permissions:
4529 group staff create,mount
4531 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4532 The following example shows how to define and grant a permission set on the
4539 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4540 # zfs allow staff @pset tank/users
4541 # zfs allow tank/users
4542 ---- Permissions on tank/users ---------------------------------------
4544 @pset create,destroy,mount,snapshot
4545 Local+Descendent permissions:
4548 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4549 The following example shows to grant the ability to set quotas and reservations
4557 # zfs allow cindys quota,reservation users/home
4558 # zfs allow users/home
4559 ---- Permissions on users/home ---------------------------------------
4560 Local+Descendent permissions:
4561 user cindys quota,reservation
4562 cindys% zfs set quota=10G users/home/marks
4563 cindys% zfs get quota users/home/marks
4564 NAME PROPERTY VALUE SOURCE
4565 users/home/marks quota 10G local
4567 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4568 The following example shows how to remove the snapshot permission from the
4577 # zfs unallow staff snapshot tank/users
4578 # zfs allow tank/users
4579 ---- Permissions on tank/users ---------------------------------------
4581 @pset create,destroy,mount,snapshot
4582 Local+Descendent permissions:
4585 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4586 The following example shows how to see what has changed between a prior
4587 snapshot of a ZFS dataset and its current state.
4590 option is used to indicate type information for the files affected.
4592 # zfs diff -F tank/test@before tank/test
4594 M F /tank/test/linked (+1)
4595 R F /tank/test/oldname -> /tank/test/newname
4596 - F /tank/test/deleted
4597 + F /tank/test/created
4598 M F /tank/test/modified
4600 .It Sy Example 23 No Creating a bookmark
4601 The following example create a bookmark to a snapshot. This bookmark
4602 can then be used instead of snapshot in send streams.
4604 # zfs bookmark rpool@snapshot rpool#bookmark
4606 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4607 The following example show how to share SMB filesystem through ZFS. Note that
4608 that a user and his/her password must be given.
4610 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4611 -o user=workgroup/turbo,password=obrut,uid=1000
4615 .Em /etc/samba/smb.conf
4616 configuration required:
4618 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4619 communicate with Samba. This is the default behavior for most Linux
4622 Samba must be able to authenticate a user. This can be done in a number of
4623 ways, depending on if using the system password file, LDAP or the Samba
4624 specific smbpasswd file. How to do this is outside the scope of this manual.
4627 man page for more information.
4630 .Sy USERSHARE section
4633 man page for all configuration options in case you need to modify any options
4634 to the share afterwards. Do note that any changes done with the
4636 command will be undone if the share is ever unshared (such as at a reboot etc).
4638 .Sh INTERFACE STABILITY
projects / zfs / blob