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, 2016 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 Nexenta Systems, Inc.
30 .\" Copyright 2016 Richard Laager. All rights reserved.
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 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
276 command configures ZFS datasets within a ZFS storage pool, as described in
278 A dataset is identified by a unique path within the ZFS namespace.
281 pool/{filesystem,volume,snapshot}
284 where the maximum length of a dataset name is
288 A dataset can be one of the following:
289 .Bl -tag -width "file system"
291 A ZFS dataset of type
293 can be mounted within the standard system namespace and behaves like other file
295 While ZFS file systems are designed to be POSIX compliant, known issues exist
296 that prevent compliance in some cases.
297 Applications that depend on standards conformance might fail due to non-standard
298 behavior when checking file system free space.
300 A logical volume exported as a raw or block device.
301 This type of dataset should only be used under special circumstances.
302 File systems are typically used in most environments.
304 A read-only version of a file system or volume at a given point in time.
306 .Ar filesystem Ns @ Ns Ar name
308 .Ar volume Ns @ Ns Ar name .
312 but without the hold on on-disk data. It can be used as the source of a send
313 (but not for a receive). It is specified as
314 .Ar filesystem Ns # Ns Ar name
316 .Ar volume Ns # Ns Ar name .
318 .Ss ZFS File System Hierarchy
319 A ZFS storage pool is a logical collection of devices that provide space for
321 A storage pool is also the root of the ZFS file system hierarchy.
323 The root of the pool can be accessed as a file system, such as mounting and
324 unmounting, taking snapshots, and setting properties.
325 The physical storage characteristics, however, are managed by the
331 for more information on creating and administering pools.
333 A snapshot is a read-only copy of a file system or volume.
334 Snapshots can be created extremely quickly, and initially consume no additional
335 space within the pool.
336 As data within the active dataset changes, the snapshot consumes more data than
337 would otherwise be shared with the active dataset.
339 Snapshots can have arbitrary names.
340 Snapshots of volumes can be cloned or rolled back, visibility is determined
343 property of the parent volume.
345 File system snapshots can be accessed under the
347 directory in the root of the file system.
348 Snapshots are automatically mounted on demand and may be unmounted at regular
350 The visibility of the
352 directory can be controlled by the
356 A bookmark is like a snapshot, a read-only copy of a file system or volume.
357 Bookmarks can be created extremely quickly, compared to snapshots, and they
358 consume no additional space within the pool. Bookmarks can also have arbitrary
359 names, much like snapshots.
361 Unlike snapshots, bookmarks can not be accessed through the filesystem in any
362 way. From a storage standpoint a bookmark just provides a way to reference
363 when a snapshot was created as a distinct object. Bookmarks are initially
364 tied to a snapshot, not the filesystem or volume, and they will survive if the
365 snapshot itself is destroyed. Since they are very light weight there's little
366 incentive to destroy them.
368 A clone is a writable volume or file system whose initial contents are the same
370 As with snapshots, creating a clone is nearly instantaneous, and initially
371 consumes no additional space.
373 Clones can only be created from a snapshot.
374 When a snapshot is cloned, it creates an implicit dependency between the parent
376 Even though the clone is created somewhere else in the dataset hierarchy, the
377 original snapshot cannot be destroyed as long as a clone exists.
380 property exposes this dependency, and the
382 command lists any such dependencies, if they exist.
384 The clone parent-child dependency relationship can be reversed by using the
389 file system to become a clone of the specified file system, which makes it
390 possible to destroy the file system that the clone was created from.
392 Creating a ZFS file system is a simple operation, so the number of file systems
393 per system is likely to be numerous.
394 To cope with this, ZFS automatically manages mounting and unmounting file
395 systems without the need to edit the
398 All automatically managed file systems are mounted by ZFS at boot time.
400 By default, file systems are mounted under
404 is the name of the file system in the ZFS namespace.
405 Directories are created and destroyed as needed.
407 A file system can also have a mount point set in the
410 This directory is created as needed, and ZFS automatically mounts the file
412 .Nm zfs Cm mount Fl a
419 property can be inherited, so if
425 automatically inherits a mount point of
426 .Pa /export/stuff/user .
432 prevents the file system from being mounted.
434 If needed, ZFS file systems can also be managed with traditional tools
440 If a file system's mount point is set to
442 ZFS makes no attempt to manage the file system, and the administrator is
443 responsible for mounting and unmounting the file system. Because pools must
444 be imported before a legacy mount can succeed, administrators should ensure
445 that legacy mounts are only attempted after the zpool import process
446 finishes at boot time. For example, on machines using systemd, the mount
449 .Nm x-systemd.requires=zfs-import.target
451 will ensure that the zfs-import completes before systemd attempts mounting
452 the filesystem. See systemd.mount(5) for details.
454 Deduplication is the process for removing redundant data at the block level,
455 reducing the total amount of data stored. If a file system has the
457 property enabled, duplicate data blocks are removed synchronously. The result
458 is that only unique data is stored and common components are shared among files.
460 Deduplicating data is a very resource-intensive operation. It is generally
461 recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when
462 you enable deduplication. Calculating the exact requirement depends heavily
463 on the type of data stored in the pool.
465 Enabling deduplication on an improperly-designed system can result in
466 performance issues (slow IO and administrative operations). It can potentially
467 lead to problems importing a pool due to memory exhaustion. Deduplication
468 can consume significant processing power (CPU) and memory as well as generate
471 Before creating a pool with deduplication enabled, ensure that you have planned
472 your hardware requirements appropriately and implemented appropriate recovery
473 practices, such as regular backups. As an alternative to deduplication
475 .Sy compression=lz4 ,
476 as a less resource-intensive alternative.
477 .Ss Native Properties
478 Properties are divided into two types, native properties and user-defined
483 Native properties either export internal statistics or control ZFS behavior.
484 In addition, native properties are either editable or read-only.
485 User properties have no effect on ZFS behavior, but you can use them to annotate
486 datasets in a way that is meaningful in your environment.
487 For more information about user properties, see the
491 Every dataset has a set of properties that export statistics about the dataset
492 as well as control various behaviors.
493 Properties are inherited from the parent unless overridden by the child.
494 Some properties apply only to certain types of datasets
495 .Pq file systems, volumes, or snapshots .
497 The values of numeric properties can be specified using human-readable suffixes
507 The following are all valid
510 .Li 1536M, 1.5g, 1.50GB .
512 The values of non-numeric properties are case sensitive and must be lowercase,
519 The following native properties consist of read-only statistics about the
521 These properties can be neither set, nor inherited.
522 Native properties apply to all dataset types unless otherwise noted.
523 .Bl -tag -width "usedbyrefreservation"
525 The amount of space available to the dataset and all its children, assuming that
526 there is no other activity in the pool.
527 Because space is shared within a pool, availability can be limited by any number
528 of factors, including physical pool size, quotas, reservations, or other
529 datasets within the pool.
531 This property can also be referred to by its shortened column name,
534 For non-snapshots, the compression ratio achieved for the
536 space of this dataset, expressed as a multiplier.
539 property includes descendant datasets, and, for clones, does not include the
540 space shared with the origin snapshot.
546 Compression can be turned on by running:
547 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
551 The transaction group (txg) in which the dataset was created. Bookmarks have
554 as the snapshot they are initially tied to. This property is suitable for
555 ordering a list of snapshots, e.g. for incremental send and receive.
557 The time this dataset was created.
559 For snapshots, this property is a comma-separated list of filesystems or volumes
560 which are clones of this snapshot.
563 property is this snapshot.
566 property is not empty, then this snapshot can not be destroyed
573 The roles of origin and clone can be swapped by promoting the clone with the
579 if the snapshot has been marked for deferred destroy by using the
580 .Nm zfs Cm destroy Fl d
582 Otherwise, the property is
584 .It Sy filesystem_count
585 The total number of filesystems and volumes that exist under this location in
587 This value is only available when a
589 has been set somewhere in the tree under which the dataset resides.
591 The 64 bit GUID of this dataset or bookmark which does not change over its
592 entire lifetime. When a snapshot is sent to another pool, the received
593 snapshot has the same GUID. Thus, the
595 is suitable to identify a snapshot across pools.
596 .It Sy logicalreferenced
597 The amount of space that is
599 accessible by this dataset.
603 The logical space ignores the effect of the
607 properties, giving a quantity closer to the amount of data that applications
609 However, it does include space consumed by metadata.
611 This property can also be referred to by its shortened column name,
614 The amount of space that is
616 consumed by this dataset and all its descendents.
620 The logical space ignores the effect of the
624 properties, giving a quantity closer to the amount of data that applications
626 However, it does include space consumed by metadata.
628 This property can also be referred to by its shortened column name,
631 For file systems, indicates whether the file system is currently mounted.
632 This property can be either
637 For cloned file systems or volumes, the snapshot from which the clone was
642 .It Sy receive_resume_token
643 For filesystems or volumes which have saved partially-completed state from
645 this opaque token can be provided to
647 to resume and complete the
650 The amount of data that is accessible by this dataset, which may or may not be
651 shared with other datasets in the pool.
652 When a snapshot or clone is created, it initially references the same amount of
653 space as the file system or snapshot it was created from, since its contents are
656 This property can also be referred to by its shortened column name,
658 .It Sy refcompressratio
659 The compression ratio achieved for the
661 space of this dataset, expressed as a multiplier.
665 .It Sy snapshot_count
666 The total number of snapshots that exist under this location in the dataset
668 This value is only available when a
670 has been set somewhere in the tree under which the dataset resides.
678 The amount of space consumed by this dataset and all its descendents.
679 This is the value that is checked against this dataset's quota and reservation.
680 The space used does not include this dataset's reservation, but does take into
681 account the reservations of any descendent datasets.
682 The amount of space that a dataset consumes from its parent, as well as the
683 amount of space that is freed if this dataset is recursively destroyed, is the
684 greater of its space used and its reservation.
686 The used space of a snapshot
691 is space that is referenced exclusively by this snapshot.
692 If this snapshot is destroyed, the amount of
695 Space that is shared by multiple snapshots isn't accounted for in this metric.
696 When a snapshot is destroyed, space that was previously shared with this
697 snapshot can become unique to snapshots adjacent to it, thus changing the used
698 space of those snapshots.
699 The used space of the latest snapshot can also be affected by changes in the
703 space of a snapshot is a subset of the
705 space of the snapshot.
707 The amount of space used, available, or referenced does not take into account
709 Pending changes are generally accounted for within a few seconds.
710 Committing a change to a disk using
714 does not necessarily guarantee that the space usage information is updated
719 properties decompose the
721 properties into the various reasons that space is used.
724 .Sy usedbychildren No +
725 .Sy usedbydataset No +
726 .Sy usedbyrefreservation No +
727 .Sy usedbysnapshots .
728 These properties are only available for datasets created on
732 .It Sy usedbychildren
733 The amount of space used by children of this dataset, which would be freed if
734 all the dataset's children were destroyed.
736 The amount of space used by this dataset itself, which would be freed if the
737 dataset were destroyed
738 .Po after first removing any
740 and destroying any necessary snapshots or descendents
742 .It Sy usedbyrefreservation
743 The amount of space used by a
745 set on this dataset, which would be freed if the
748 .It Sy usedbysnapshots
749 The amount of space consumed by snapshots of this dataset.
750 In particular, it is the amount of space that would be freed if all of this
751 dataset's snapshots were destroyed.
752 Note that this is not simply the sum of the snapshots'
754 properties because space can be shared by multiple snapshots.
755 .It Sy userused Ns @ Ns Em user
756 The amount of space consumed by the specified user in this dataset.
757 Space is charged to the owner of each file, as displayed by
759 The amount of space charged is displayed by
765 subcommand for more information.
767 Unprivileged users can access only their own space usage.
768 The root user, or a user who has been granted the
772 can access everyone's usage.
775 .Sy userused Ns @ Ns Em ...
776 properties are not displayed by
777 .Nm zfs Cm get Sy all .
778 The user's name must be appended after the @ symbol, using one of the following
780 .Bl -bullet -width ""
794 .Sy joe.smith@mydomain
803 Files created on Linux always have POSIX owners.
804 .It Sy userobjused Ns @ Ns Em user
807 property is similar to
809 but instead it counts the number of objects consumed by a user. This property
810 counts all objects allocated on behalf of the user, it may differ from the
811 results of system tools such as
816 is set on a file system additional objects will be created per-file to store
817 extended attributes. These additional objects are reflected in the
819 value and are counted against the user's
821 When a file system is configured to use
823 no additional internal objects are normally required.
825 This property is set to the number of user holds on this snapshot.
826 User holds are set by using the
829 .It Sy groupused Ns @ Ns Em group
830 The amount of space consumed by the specified group in this dataset.
831 Space is charged to the group of each file, as displayed by
834 .Sy userused Ns @ Ns Em user
835 property for more information.
837 Unprivileged users can only access their own groups' space usage.
838 The root user, or a user who has been granted the
842 can access all groups' usage.
843 .It Sy groupobjused Ns @ Ns Em group
844 The number of objects consumed by the specified group in this dataset.
845 Multiple objects may be charged to the group for each file when extended
846 attributes are in use. See the
847 .Sy userobjused Ns @ Ns Em user
848 property for more information.
850 Unprivileged users can only access their own groups' space usage.
851 The root user, or a user who has been granted the
855 can access all groups' usage.
857 For volumes, specifies the block size of the volume.
860 cannot be changed once the volume has been written, so it should be set at
861 volume creation time.
864 for volumes is 8 Kbytes.
865 Any power of 2 from 512 bytes to 128 Kbytes is valid.
867 This property can also be referred to by its shortened column name,
872 by this dataset, that was written since the previous snapshot
873 .Pq i.e. that is not referenced by the previous snapshot .
874 .It Sy written Ns @ Ns Em snapshot
877 space written to this dataset since the specified snapshot.
878 This is the space that is referenced by this dataset but was not referenced by
879 the specified snapshot.
883 may be specified as a short snapshot name
884 .Po just the part after the
887 in which case it will be interpreted as a snapshot in the same filesystem as
891 may be a full snapshot name
892 .Po Em filesystem Ns @ Ns Em snapshot Pc ,
893 which for clones may be a snapshot in the origin's filesystem
894 .Pq or the origin of the origin's filesystem, etc.
897 The following native properties can be used to change the behavior of a ZFS
901 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
902 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
904 Controls how ACEs are inherited when files and directories are created.
905 .Bl -tag -width "passthrough-x"
907 does not inherit any ACEs.
909 only inherits inheritable ACEs that specify
917 permissions when the ACE is inherited.
919 inherits all inheritable ACEs without any modifications.
928 ACEs inherit the execute permission only if the file creation mode also requests
932 When the property value is set to
934 files are created with a mode determined by the inheritable ACEs.
935 If no inheritable ACEs exist that affect the mode, then the mode is set in
936 accordance to the requested mode from the application.
940 property does not apply to posix ACLs.
941 .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl
942 Controls whether ACLs are enabled and if so what type of ACL to use.
943 .Bl -tag -width "posixacl"
945 default, when a file system has the
947 property set to off then ACLs are disabled.
952 indicates posix ACLs should be used. Posix ACLs are specific to Linux and are
953 not functional on other platforms. Posix ACLs are stored as an extended
954 attribute and therefore will not overwrite any existing NFSv4 ACLs which
958 To obtain the best performance when setting
960 users are strongly encouraged to set the
962 property. This will result in the posix ACL being stored more efficiently on
963 disk. But as a consequence of this all new extended attributes will only be
964 accessible from OpenZFS implementations which support the
968 property for more details.
969 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
970 Controls whether the access time for files is updated when they are read.
971 Turning this property off avoids producing write traffic when reading files and
972 can result in significant performance gains, though it might confuse mailers
973 and other similar utilities. The values
977 are equivalent to the
981 mount options. The default value is
986 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
987 If this property is set to
989 the file system cannot be mounted, and is ignored by
990 .Nm zfs Cm mount Fl a .
991 Setting this property to
993 is similar to setting the
997 except that the dataset still has a normal
999 property, which can be inherited.
1000 Setting this property to
1002 allows datasets to be used solely as a mechanism to inherit properties.
1003 One example of setting
1004 .Sy canmount Ns = Ns Sy off
1005 is to have two datasets with the same
1007 so that the children of both datasets appear in the same directory, but might
1008 have different inherited characteristics.
1012 a dataset can only be mounted and unmounted explicitly.
1013 The dataset is not mounted automatically when the dataset is created or
1014 imported, nor is it mounted by the
1015 .Nm zfs Cm mount Fl a
1016 command or unmounted by the
1017 .Nm zfs Cm unmount Fl a
1020 This property is not inherited.
1022 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
1023 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
1024 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
1026 Controls the checksum used to verify data integrity.
1027 The default value is
1029 which automatically selects an appropriate algorithm
1032 but this may change in future releases
1036 disables integrity checking on user data.
1039 not only disables integrity but also disables maintaining parity for user data.
1040 This setting is used internally by a dump device residing on a RAID-Z pool and
1041 should not be used by any other dataset.
1042 Disabling checksums is
1044 a recommended practice.
1051 checksum algorithms require enabling the appropriate features on the pool.
1052 These algorithms are not supported by GRUB and should not be set on the
1054 filesystem when using GRUB to boot the system.
1056 .Xr zpool-features 5
1057 for more information on these algorithms.
1059 Changing this property affects only newly-written data.
1061 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1062 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1064 Controls the compression algorithm used for this dataset.
1066 Setting compression to
1068 indicates that the current default compression algorithm should be used.
1069 The default balances compression and decompression speed, with compression ratio
1070 and is expected to work well on a wide variety of workloads.
1071 Unlike all other settings for this property,
1073 does not select a fixed compression type.
1074 As new compression algorithms are added to ZFS and enabled on a pool, the
1075 default compression algorithm may change.
1076 The current default compression algorithm is either
1085 compression algorithm is a high-performance replacement for the
1088 It features significantly faster compression and decompression, as well as a
1089 moderately higher compression ratio than
1091 but can only be used on pools with the
1096 .Xr zpool-features 5
1097 for details on ZFS feature flags and the
1103 compression algorithm is optimized for performance while providing decent data
1108 compression algorithm uses the same compression as the
1113 level by using the value
1117 is an integer from 1
1120 .Pq best compression ratio .
1125 .Po which is also the default for
1131 compression algorithm compresses runs of zeros.
1133 This property can also be referred to by its shortened column name
1135 Changing this property affects only newly-written data.
1137 .Sy context Ns = Ns Sy none Ns | Ns
1138 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1140 This flag sets the SELinux context for all files in the file system under
1141 a mount point for that file system. See
1143 for more information.
1145 .Sy fscontext Ns = Ns Sy none Ns | Ns
1146 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1148 This flag sets the SELinux context for the file system file system being
1151 for more information.
1153 .Sy defcontext Ns = Ns Sy none Ns | Ns
1154 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1156 This flag sets the SELinux default context for unlabeled files. See
1158 for more information.
1160 .Sy rootcontext Ns = Ns Sy none Ns | Ns
1161 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
1163 This flag sets the SELinux context for the root inode of the file system. See
1165 for more information.
1166 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1167 Controls the number of copies of data stored for this dataset.
1168 These copies are in addition to any redundancy provided by the pool, for
1169 example, mirroring or RAID-Z.
1170 The copies are stored on different disks, if possible.
1171 The space used by multiple copies is charged to the associated file and dataset,
1174 property and counting against quotas and reservations.
1176 Changing this property only affects newly-written data.
1177 Therefore, set this property at file system creation time by using the
1178 .Fl o Sy copies Ns = Ns Ar N
1181 Remember that ZFS will not import a pool with a missing top-level vdev. Do
1183 create, for example a two-disk striped pool and set
1185 on some datasets thinking you have setup redundancy for them. When a disk
1186 fails you will not be able to import the pool and will have lost all of your
1188 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1189 Controls whether device nodes can be opened on this file system.
1190 The default value is
1196 are equivalent to the
1202 .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
1203 .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
1205 Specifies a compatibility mode or literal value for the size of dnodes in the
1206 file system. The default value is
1208 Setting this property to a value other than
1210 requires the large_dnode pool feature to be enabled.
1216 if the dataset uses the
1218 property setting and the workload makes heavy use of extended attributes. This
1219 may be applicable to SELinux-enabled systems, Lustre servers, and Samba
1220 servers, for example. Literal values are supported for cases where the optimal
1221 size is known in advance and for performance testing.
1227 if you need to receive a send stream of this dataset on a pool that doesn't
1228 enable the large_dnode feature, or if you need to import this pool on a system
1229 that doesn't support the large_dnode feature.
1231 This property can also be referred to by its shortened column name,
1233 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1234 Controls whether processes can be executed from within this file system.
1235 The default value is
1241 are equivalent to the
1246 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1247 Limits the number of filesystems and volumes that can exist under this point in
1249 The limit is not enforced if the user is allowed to change the limit.
1251 .Sy filesystem_limit
1254 a descendent of a filesystem that already has a
1255 .Sy filesystem_limit
1256 does not override the ancestor's
1257 .Sy filesystem_limit ,
1258 but rather imposes an additional limit.
1259 This feature must be enabled to be used
1261 .Xr zpool-features 5
1263 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1264 Controls the mount point used for this file system.
1267 section for more information on how this property is used.
1271 property is changed for a file system, the file system and any children that
1272 inherit the mount point are unmounted.
1275 then they remain unmounted.
1276 Otherwise, they are automatically remounted in the new location if the property
1281 or if they were mounted before the property was changed.
1282 In addition, any shared file systems are unshared and shared in the new
1284 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1285 Controls whether the file system should be mounted with
1287 .Pq Non Blocking mandatory locks .
1288 This is used for SMB clients.
1289 Changes to this property only take effect when the file system is umounted and
1293 for more information on
1295 mounts. This property is not used on Linux.
1296 .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on
1297 Allow mounting on a busy directory or a directory which already contains
1298 files or directories. This is the default mount behavior for Linux file systems.
1299 For consistency with OpenZFS on other platforms overlay mounts are
1303 to enable overlay mounts.
1304 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1305 Controls what is cached in the primary cache
1307 If this property is set to
1309 then both user data and metadata is cached.
1310 If this property is set to
1312 then neither user data nor metadata is cached.
1313 If this property is set to
1315 then only metadata is cached.
1316 The default value is
1318 .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1319 Limits the amount of space a dataset and its descendents can consume.
1320 This property enforces a hard limit on the amount of space used.
1321 This includes all space consumed by descendents, including file systems and
1323 Setting a quota on a descendent of a dataset that already has a quota does not
1324 override the ancestor's quota, but rather imposes an additional limit.
1326 Quotas cannot be set on volumes, as the
1328 property acts as an implicit quota.
1329 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1330 Limits the number of snapshots that can be created on a dataset and its
1334 on a descendent of a dataset that already has a
1336 does not override the ancestor's
1337 .Sy snapshot_limit ,
1338 but rather imposes an additional limit.
1339 The limit is not enforced if the user is allowed to change the limit.
1340 For example, this means that recursive snapshots taken from the global zone are
1341 counted against each delegated dataset within a zone.
1342 This feature must be enabled to be used
1344 .Xr zpool-features 5
1346 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1347 Limits the amount of space consumed by the specified user.
1348 User space consumption is identified by the
1349 .Sy userspace@ Ns Em user
1352 Enforcement of user quotas may be delayed by several seconds.
1353 This delay means that a user might exceed their quota before the system notices
1354 that they are over quota and begins to refuse additional writes with the
1358 .Nm zfs Cm userspace
1359 subcommand for more information.
1361 Unprivileged users can only access their own groups' space usage.
1362 The root user, or a user who has been granted the
1366 can get and set everyone's quota.
1368 This property is not available on volumes, on file systems before version 4, or
1369 on pools before version 15.
1371 .Sy userquota@ Ns Em ...
1372 properties are not displayed by
1373 .Nm zfs Cm get Sy all .
1374 The user's name must be appended after the
1376 symbol, using one of the following forms:
1384 .Em POSIX numeric ID
1391 .Sy joe.smith@mydomain
1400 Files created on Linux always have POSIX owners.
1401 .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1406 but it limits the number of objects a user can create. Please refer to
1408 for more information about how objects are counted.
1409 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1410 Limits the amount of space consumed by the specified group.
1411 Group space consumption is identified by the
1412 .Sy groupused@ Ns Em group
1415 Unprivileged users can access only their own groups' space usage.
1416 The root user, or a user who has been granted the
1420 can get and set all groups' quotas.
1421 .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1426 but it limits number of objects a group can consume. Please refer to
1428 for more information about how objects are counted.
1429 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1430 Controls whether this dataset can be modified.
1431 The default value is
1437 are equivalent to the
1443 This property can also be referred to by its shortened column name,
1445 .It Sy recordsize Ns = Ns Em size
1446 Specifies a suggested block size for files in the file system.
1447 This property is designed solely for use with database workloads that access
1448 files in fixed-size records.
1449 ZFS automatically tunes block sizes according to internal algorithms optimized
1450 for typical access patterns.
1452 For databases that create very large files but access them in small random
1453 chunks, these algorithms may be suboptimal.
1456 greater than or equal to the record size of the database can result in
1457 significant performance gains.
1458 Use of this property for general purpose file systems is strongly discouraged,
1459 and may adversely affect performance.
1461 The size specified must be a power of two greater than or equal to 512 and less
1462 than or equal to 128 Kbytes.
1465 feature is enabled on the pool, the size may be up to 1 Mbyte.
1467 .Xr zpool-features 5
1468 for details on ZFS feature flags.
1470 Changing the file system's
1472 affects only files created afterward; existing files are unaffected.
1474 This property can also be referred to by its shortened column name,
1476 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1477 Controls what types of metadata are stored redundantly.
1478 ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1479 the amount of user data lost is limited.
1480 This extra copy is in addition to any redundancy provided at the pool level
1481 .Pq e.g. by mirroring or RAID-Z ,
1482 and is in addition to an extra copy specified by the
1485 .Pq up to a total of 3 copies .
1486 For example if the pool is mirrored,
1487 .Sy copies Ns = Ns 2 ,
1489 .Sy redundant_metadata Ns = Ns Sy most ,
1490 then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1495 ZFS stores an extra copy of all metadata.
1496 If a single on-disk block is corrupt, at worst a single block of user data
1505 ZFS stores an extra copy of most types of metadata.
1506 This can improve performance of random writes, because less metadata must be
1508 In practice, at worst about 100 blocks
1513 of user data can be lost if a single on-disk block is corrupt.
1514 The exact behavior of which metadata blocks are stored redundantly may change in
1517 The default value is
1519 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1520 Limits the amount of space a dataset can consume.
1521 This property enforces a hard limit on the amount of space used.
1522 This hard limit does not include space used by descendents, including file
1523 systems and snapshots.
1524 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1525 The minimum amount of space guaranteed to a dataset, not including its
1527 When the amount of space used is below this value, the dataset is treated as if
1528 it were taking up the amount of space specified by
1529 .Sy refreservation .
1532 reservation is accounted for in the parent datasets' space used, and counts
1533 against the parent datasets' quotas and reservations.
1537 is set, a snapshot is only allowed if there is enough free pool space outside of
1538 this reservation to accommodate the current number of
1540 bytes in the dataset.
1542 This property can also be referred to by its shortened column name,
1544 .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
1545 Controls the manner in which the access time is updated when
1547 is set. Turning this property on causes the access time to be updated relative
1548 to the modify or change time. Access time is only updated if the previous
1549 access time was earlier than the current modify or change time or if the
1550 existing access time hasn't been updated within the past 24 hours. The default
1557 are equivalent to the
1562 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1563 The minimum amount of space guaranteed to a dataset and its descendants.
1564 When the amount of space used is below this value, the dataset is treated as if
1565 it were taking up the amount of space specified by its reservation.
1566 Reservations are accounted for in the parent datasets' space used, and count
1567 against the parent datasets' quotas and reservations.
1569 This property can also be referred to by its shortened column name,
1571 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1572 Controls what is cached in the secondary cache
1574 If this property is set to
1576 then both user data and metadata is cached.
1577 If this property is set to
1579 then neither user data nor metadata is cached.
1580 If this property is set to
1582 then only metadata is cached.
1583 The default value is
1585 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1586 Controls whether the setuid bit is respected for the file system.
1587 The default value is
1593 are equivalent to the
1598 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1599 Controls whether the file system is shared by using
1600 .Sy Samba USERSHARES
1601 and what options are to be used. Otherwise, the file system is automatically
1602 shared and unshared with the
1606 commands. If the property is set to on, the
1608 command is invoked to create a
1611 Because SMB shares requires a resource name, a unique resource name is
1612 constructed from the dataset name. The constructed name is a copy of the
1613 dataset name except that the characters in the dataset name, which would be
1614 invalid in the resource name, are replaced with underscore (_) characters.
1615 Linux does not currently support additional options which might be available
1622 the file systems are unshared.
1624 The share is created with the ACL (Access Control List) "Everyone:F" ("F"
1625 stands for "full permissions", ie. read and write permissions) and no guest
1626 access (which means Samba must be able to authenticate a real user, system
1627 passwd/shadow, LDAP or smbpasswd based) by default. This means that any
1628 additional access control (disallow specific user specific access etc) must
1629 be done on the underlying file system.
1630 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1631 Controls whether the file system is shared via NFS, and what options are to be
1633 A file system with a
1639 command and entries in the
1642 Otherwise, the file system is automatically shared and unshared with the
1647 If the property is set to
1649 the dataset is shared using the default options:
1651 .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
1655 for the meaning of the default options. Otherwise, the
1657 command is invoked with options equivalent to the contents of this property.
1661 property is changed for a dataset, the dataset and any children inheriting the
1662 property are re-shared with the new options, only if the property was previously
1664 or if they were shared before the property was changed.
1665 If the new property is
1667 the file systems are unshared.
1668 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1669 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1675 ZFS will use pool log devices
1677 to handle the requests at low latency.
1682 ZFS will not use configured pool log devices.
1683 ZFS will instead optimize synchronous operations for global pool throughput and
1684 efficient use of resources.
1685 .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
1686 Controls whether the volume snapshot devices under
1687 .Em /dev/zvol/<pool>
1688 are hidden or visible. The default value is
1690 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1691 Controls whether the
1693 directory is hidden or visible in the root of the file system as discussed in
1697 The default value is
1699 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1700 Controls the behavior of synchronous requests
1701 .Pq e.g. fsync, O_DSYNC .
1705 specified behavior of ensuring all synchronous requests are written to stable
1706 storage and all devices are flushed to ensure data is not cached by device
1708 .Pq this is the default .
1710 causes every file system transaction to be written and flushed before its
1711 system call returns.
1712 This has a large performance penalty.
1714 disables synchronous requests.
1715 File system transactions are only committed to stable storage periodically.
1716 This option will give the highest performance.
1717 However, it is very dangerous as ZFS would be ignoring the synchronous
1718 transaction demands of applications such as databases or NFS.
1719 Administrators should only use this option when the risks are understood.
1720 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1721 The on-disk version of this file system, which is independent of the pool
1723 This property can only be set to later supported versions.
1727 .It Sy volsize Ns = Ns Em size
1728 For volumes, specifies the logical size of the volume.
1729 By default, creating a volume establishes a reservation of equal size.
1730 For storage pools with a version number of 9 or higher, a
1735 are reflected in an equivalent change to the reservation
1741 can only be set to a multiple of
1745 The reservation is kept equal to the volume's logical size to prevent unexpected
1746 behavior for consumers.
1747 Without the reservation, the volume could run out of space, resulting in
1748 undefined behavior or data corruption, depending on how the volume is used.
1749 These effects can also occur when the volume size is changed while it is in use
1750 .Pq particularly when shrinking the size .
1751 Extreme care should be used when adjusting the volume size.
1753 Though not recommended, a
1756 .Qq thin provisioning
1758 can be created by specifying the
1761 .Nm zfs Cm create Fl V
1762 command, or by changing the reservation after the volume has been created.
1765 is a volume where the reservation is less then the volume size.
1766 Consequently, writes to a sparse volume can fail with
1768 when the pool is low on space.
1769 For a sparse volume, changes to
1771 are not reflected in the reservation.
1772 .It Sy volmode Ns = Ns Cm default | full | geom | dev | none
1773 This property specifies how volumes should be exposed to the OS.
1776 exposes volumes as fully fledged block devices, providing maximal
1777 functionality. The value
1779 is just an alias for
1781 and is kept for compatibility.
1784 hides its partitions.
1785 Volumes with property set to
1787 are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
1788 that can be suitable for backup purposes.
1791 means that volumes exposition is controlled by system-wide tunable
1798 are encoded as 1, 2 and 3 respectively.
1799 The default values is
1801 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1802 Controls whether regular files should be scanned for viruses when a file is
1804 In addition to enabling this property, the virus scan service must also be
1805 enabled for virus scanning to occur.
1806 The default value is
1808 This property is not used on Linux.
1809 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
1810 Controls whether extended attributes are enabled for this file system. Two
1811 styles of extended attributes are supported either directory based or system
1814 The default value of
1816 enables directory based extended attributes. This style of extended attribute
1817 imposes no practical limit on either the size or number of attributes which
1818 can be set on a file. Although under Linux the
1822 system calls limit the maximum size to 64K. This is the most compatible
1823 style of extended attribute and is supported by all OpenZFS implementations.
1825 System attribute based xattrs can be enabled by setting the value to
1827 The key advantage of this type of xattr is improved performance. Storing
1828 extended attributes as system attributes significantly decreases the amount of
1829 disk IO required. Up to 64K of data may be stored per-file in the space
1830 reserved for system attributes. If there is not enough space available for
1831 an extended attribute then it will be automatically written as a directory
1832 based xattr. System attribute based extended attributes are not accessible
1833 on platforms which do not support the
1837 The use of system attribute based xattrs is strongly encouraged for users of
1838 SELinux or posix ACLs. Both of these features heavily rely of extended
1839 attributes and benefit significantly from the reduced access time.
1845 are equivalent to the
1850 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1851 Controls whether the dataset is managed from a non-global zone. Zones are a
1852 Solaris feature and are not relevant on Linux. The default value is
1856 The following three properties cannot be changed after the file system is
1857 created, and therefore, should be set when the file system is created.
1858 If the properties are not set with the
1862 commands, these properties are inherited from the parent dataset.
1863 If the parent dataset lacks these properties due to having been created prior to
1864 these features being supported, the new file system will have the default values
1865 for these properties.
1868 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1869 .Sy insensitive Ns | Ns Sy mixed
1871 Indicates whether the file name matching algorithm used by the file system
1872 should be case-sensitive, case-insensitive, or allow a combination of both
1874 The default value for the
1882 file systems have case-sensitive file names.
1888 property indicates that the file system can support requests for both
1889 case-sensitive and case-insensitive matching behavior.
1890 Currently, case-insensitive matching behavior on a file system that supports
1891 mixed behavior is limited to the SMB server product.
1892 For more information about the
1894 value behavior, see the "ZFS Administration Guide".
1896 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1897 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1899 Indicates whether the file system should perform a
1901 normalization of file names whenever two file names are compared, and which
1902 normalization algorithm should be used.
1903 File names are always stored unmodified, names are normalized as part of any
1905 If this property is set to a legal value other than
1909 property was left unspecified, the
1911 property is automatically set to
1913 The default value of the
1917 This property cannot be changed after the file system is created.
1918 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1919 Indicates whether the file system should reject file names that include
1920 characters that are not present in the
1923 If this property is explicitly set to
1925 the normalization property must either not be explicitly set or be set to
1927 The default value for the
1931 This property cannot be changed after the file system is created.
1935 .Sy casesensitivity ,
1939 properties are also new permissions that can be assigned to non-privileged users
1940 by using the ZFS delegated administration feature.
1941 .Ss "Temporary Mount Point Properties"
1942 When a file system is mounted, either through
1944 for legacy mounts or the
1946 command for normal file systems, its mount options are set according to its
1948 The correlation between properties and mount options is as follows:
1950 PROPERTY MOUNT OPTION
1952 canmount auto/noauto
1956 relatime relatime/norelatime
1961 In addition, these options can be set on a per-mount basis using the
1963 option, without affecting the property that is stored on disk.
1964 The values specified on the command line override the values stored in the
1968 option is an alias for
1969 .Sy nodevices Ns , Ns Sy nosetuid .
1970 These properties are reported as
1975 If the properties are changed while the dataset is mounted, the new setting
1976 overrides any temporary settings.
1977 .Ss "User Properties"
1978 In addition to the standard native properties, ZFS supports arbitrary user
1980 User properties have no effect on ZFS behavior, but applications or
1981 administrators can use them to annotate datasets
1982 .Pq file systems, volumes, and snapshots .
1984 User property names must contain a colon
1986 character to distinguish them from native properties.
1987 They may contain lowercase letters, numbers, and the following punctuation
1996 The expected convention is that the property name is divided into two portions
1998 .Em module Ns : Ns Em property ,
1999 but this namespace is not enforced by ZFS.
2000 User property names can be at most 256 characters, and cannot begin with a dash
2003 When making programmatic use of user properties, it is strongly suggested to use
2008 component of property names to reduce the chance that two
2009 independently-developed packages use the same property name for different
2012 The values of user properties are arbitrary strings, are always inherited, and
2013 are never validated.
2014 All of the commands that operate on properties
2015 .Po Nm zfs Cm list ,
2020 can be used to manipulate both native properties and user properties.
2023 command to clear a user property.
2024 If the property is not defined in any parent dataset, it is removed entirely.
2025 Property values are limited to 8192 bytes.
2026 .Ss ZFS Volumes as Swap
2027 ZFS volumes may be used as swap devices. After creating the volume with the
2028 .Nm zfs Cm create Fl V
2029 command set up and enable the swap area using the
2033 commands. Do not swap to a file on a ZFS file system. A ZFS swap file
2034 configuration is not supported.
2036 All subcommands that modify state are logged persistently to the pool in their
2040 Displays a help message.
2045 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2048 Creates a new ZFS file system.
2049 The file system is automatically mounted according to the
2051 property inherited from the parent.
2052 .Bl -tag -width "-o"
2053 .It Fl o Ar property Ns = Ns Ar value
2054 Sets the specified property as if the command
2055 .Nm zfs Cm set Ar property Ns = Ns Ar value
2056 was invoked at the same time the dataset was created.
2057 Any editable ZFS property can also be set at creation time.
2060 options can be specified.
2061 An error results if the same property is specified in multiple
2065 Creates all the non-existing parent datasets.
2066 Datasets created in this manner are automatically mounted according to the
2068 property inherited from their parent.
2069 Any property specified on the command line using the
2072 If the target filesystem already exists, the operation completes successfully.
2078 .Op Fl b Ar blocksize
2079 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2080 .Fl V Ar size Ar volume
2082 Creates a volume of the given size.
2083 The volume is exported as a block device in
2084 .Pa /dev/zvol/path ,
2087 is the name of the volume in the ZFS namespace.
2088 The size represents the logical size as exported by the device.
2089 By default, a reservation of equal size is created.
2092 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
2093 has an integral number of blocks regardless of
2095 .Bl -tag -width "-b"
2096 .It Fl b Ar blocksize
2098 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
2099 If this option is specified in conjunction with
2100 .Fl o Sy volblocksize ,
2101 the resulting behavior is undefined.
2102 .It Fl o Ar property Ns = Ns Ar value
2103 Sets the specified property as if the
2104 .Nm zfs Cm set Ar property Ns = Ns Ar value
2105 command was invoked at the same time the dataset was created.
2106 Any editable ZFS property can also be set at creation time.
2109 options can be specified.
2110 An error results if the same property is specified in multiple
2114 Creates all the non-existing parent datasets.
2115 Datasets created in this manner are automatically mounted according to the
2117 property inherited from their parent.
2118 Any property specified on the command line using the
2121 If the target filesystem already exists, the operation completes successfully.
2123 Creates a sparse volume with no reservation.
2127 .Sx Native Properties
2128 section for more information about sparse volumes.
2134 .Ar filesystem Ns | Ns Ar volume
2136 Destroys the given dataset.
2137 By default, the command unshares any file systems that are currently shared,
2138 unmounts any file systems that are currently mounted, and refuses to destroy a
2139 dataset that has active dependents
2140 .Pq children or clones .
2141 .Bl -tag -width "-R"
2143 Recursively destroy all dependents, including cloned file systems outside the
2146 Force an unmount of any file systems using the
2149 This option has no effect on non-file systems or unmounted file systems.
2154 No data will be deleted.
2155 This is useful in conjunction with the
2159 flags to determine what data would be deleted.
2161 Print machine-parsable verbose information about the deleted data.
2163 Recursively destroy all children.
2165 Print verbose information about the deleted data.
2168 Extreme care should be taken when applying either the
2172 options, as they can destroy large portions of a pool and cause unexpected
2173 behavior for mounted file systems in use.
2178 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
2179 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
2181 The given snapshots are destroyed immediately if and only if the
2185 option would have destroyed it.
2186 Such immediate destruction would occur, for example, if the snapshot had no
2187 clones and the user-initiated reference count were zero.
2189 If a snapshot does not qualify for immediate destruction, it is marked for
2191 In this state, it exists as a usable, visible snapshot until both of the
2192 preconditions listed above are met, at which point it is destroyed.
2194 An inclusive range of snapshots may be specified by separating the first and
2195 last snapshots with a percent sign.
2196 The first and/or last snapshots may be left blank, in which case the
2197 filesystem's oldest or newest snapshot will be implied.
2200 .Pq or ranges of snapshots
2201 of the same filesystem or volume may be specified in a comma-separated list of
2203 Only the snapshot's short name
2204 .Po the part after the
2207 should be specified when using a range or comma-separated list to identify
2209 .Bl -tag -width "-R"
2211 Recursively destroy all clones of these snapshots, including the clones,
2212 snapshots, and children.
2213 If this flag is specified, the
2215 flag will have no effect.
2217 Defer snapshot deletion.
2222 No data will be deleted.
2223 This is useful in conjunction with the
2227 flags to determine what data would be deleted.
2229 Print machine-parsable verbose information about the deleted data.
2232 .Pq or mark for deferred deletion
2233 all snapshots with this name in descendent file systems.
2235 Print verbose information about the deleted data.
2237 Extreme care should be taken when applying either the
2241 options, as they can destroy large portions of a pool and cause unexpected
2242 behavior for mounted file systems in use.
2247 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2249 The given bookmark is destroyed.
2254 .Oo Fl o Ar property Ns = Ns value Oc Ns ...
2255 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2257 Creates snapshots with the given names.
2258 All previous modifications by successful system calls to the file system are
2259 part of the snapshots.
2260 Snapshots are taken atomically, so that all snapshots correspond to the same
2264 section for details.
2265 .Bl -tag -width "-o"
2266 .It Fl o Ar property Ns = Ns Ar value
2267 Sets the specified property; see
2271 Recursively create snapshots of all descendent datasets
2279 Roll back the given dataset to a previous snapshot.
2280 When a dataset is rolled back, all data that has changed since the snapshot is
2281 discarded, and the dataset reverts to the state at the time of the snapshot.
2282 By default, the command refuses to roll back to a snapshot other than the most
2284 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2291 options do not recursively destroy the child snapshots of a recursive snapshot.
2292 Only direct snapshots of the specified filesystem are destroyed by either of
2294 To completely roll back a recursive snapshot, you must rollback the individual
2296 .Bl -tag -width "-R"
2298 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2303 option to force an unmount of any clone file systems that are to be destroyed.
2305 Destroy any snapshots and bookmarks more recent than the one specified.
2311 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2312 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2314 Creates a clone of the given snapshot.
2317 section for details.
2318 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2319 as the same type as the original.
2320 .Bl -tag -width "-o"
2321 .It Fl o Ar property Ns = Ns Ar value
2322 Sets the specified property; see
2326 Creates all the non-existing parent datasets.
2327 Datasets created in this manner are automatically mounted according to the
2329 property inherited from their parent.
2330 If the target filesystem or volume already exists, the operation completes
2336 .Ar clone-filesystem
2338 Promotes a clone file system to no longer be dependent on its
2341 This makes it possible to destroy the file system that the clone was created
2343 The clone parent-child dependency relationship is reversed, so that the origin
2344 file system becomes a clone of the specified file system.
2346 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2347 now owned by the promoted clone.
2348 The space they use moves from the origin file system to the promoted clone, so
2349 enough space must be available to accommodate these snapshots.
2350 No new space is consumed by this operation, but the space accounting is
2352 The promoted clone must not have any conflicting snapshot names of its own.
2355 subcommand can be used to rename any conflicting snapshots.
2360 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2361 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2367 .Ar filesystem Ns | Ns Ar volume
2368 .Ar filesystem Ns | Ns Ar volume
2370 Renames the given dataset.
2371 The new target can be located anywhere in the ZFS hierarchy, with the exception
2373 Snapshots can only be renamed within the parent file system or volume.
2374 When renaming a snapshot, the parent file system of the snapshot does not need
2375 to be specified as part of the second argument.
2376 Renamed file systems can inherit new mount points, in which case they are
2377 unmounted and remounted at the new mount point.
2378 .Bl -tag -width "-a"
2380 Force unmount any filesystems that need to be unmounted in the process.
2382 Creates all the nonexistent parent datasets.
2383 Datasets created in this manner are automatically mounted according to the
2385 property inherited from their parent.
2391 .Ar snapshot Ar snapshot
2393 Recursively rename the snapshots of all descendent datasets.
2394 Snapshots are the only dataset that can be renamed recursively.
2398 .Op Fl r Ns | Ns Fl d Ar depth
2400 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2401 .Oo Fl s Ar property Oc Ns ...
2402 .Oo Fl S Ar property Oc Ns ...
2403 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2404 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2406 Lists the property information for the given datasets in tabular form.
2407 If specified, you can list property information by the absolute pathname or the
2409 By default, all file systems and volumes are displayed.
2410 Snapshots are displayed if the
2417 The following fields are displayed,
2418 .Sy name Ns , Ns Sy used Ns , Ns Sy available Ns , Ns Sy referenced Ns , Ns
2420 .Bl -tag -width "-H"
2422 Used for scripting mode.
2423 Do not print headers and separate fields by a single tab instead of arbitrary
2425 .It Fl S Ar property
2428 option, but sorts by property in descending order.
2430 Recursively display any children of the dataset, limiting the recursion to
2436 will display only the dataset and its direct children.
2437 .It Fl o Ar property
2438 A comma-separated list of properties to display.
2439 The property must be:
2442 One of the properties described in the
2443 .Sx Native Properties
2450 to display the dataset name
2454 to display space usage properties on file systems and volumes.
2455 This is a shortcut for specifying
2456 .Fl o Sy name Ns , Ns Sy avail Ns , Ns Sy used Ns , Ns Sy usedsnap Ns , Ns
2457 .Sy usedds Ns , Ns Sy usedrefreserv Ns , Ns Sy usedchild Fl t
2458 .Sy filesystem Ns , Ns Sy volume
2462 Display numbers in parsable
2466 Recursively display any children of the dataset on the command line.
2467 .It Fl s Ar property
2468 A property for sorting the output by column in ascending order based on the
2469 value of the property.
2470 The property must be one of the properties described in the
2472 section, or the special value
2474 to sort by the dataset name.
2475 Multiple properties can be specified at one time using multiple
2480 options are evaluated from left to right in decreasing order of importance.
2481 The following is a list of sorting criteria:
2484 Numeric types sort in numeric order.
2486 String types sort in alphabetical order.
2488 Types inappropriate for a row sort that row to the literal bottom, regardless of
2489 the specified ordering.
2492 If no sorting options are specified the existing behavior of
2496 A comma-separated list of types to display, where
2505 For example, specifying
2507 displays only snapshots.
2512 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2513 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2515 Sets the property or list of properties to the given value(s) for each dataset.
2516 Only some properties can be edited.
2519 section for more information on what properties can be set and acceptable
2521 Numeric values can be specified as exact values, or in a human-readable form
2523 .Sy B , K , M , G , T , P , E , Z
2524 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2525 or zettabytes, respectively
2527 User properties can be set on snapshots.
2528 For more information, see the
2534 .Op Fl r Ns | Ns Fl d Ar depth
2536 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2537 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2538 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2539 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2540 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2542 Displays properties for the given datasets.
2543 If no datasets are specified, then the command displays properties for all
2544 datasets on the system.
2545 For each property, the following columns are displayed:
2548 property Property name
2549 value Property value
2550 source Property source. Can either be local, default,
2551 temporary, inherited, or none (-).
2554 All columns are displayed by default, though this can be controlled by using the
2557 This command takes a comma-separated list of properties as described in the
2558 .Sx Native Properties
2565 can be used to display all properties that apply to the given dataset's type
2566 .Pq filesystem, volume, snapshot, or bookmark .
2567 .Bl -tag -width "-H"
2569 Display output in a form more easily parsed by scripts.
2570 Any headers are omitted, and fields are explicitly separated by a single tab
2571 instead of an arbitrary amount of space.
2573 Recursively display any children of the dataset, limiting the recursion to
2577 will display only the dataset and its direct children.
2579 A comma-separated list of columns to display.
2580 .Sy name Ns , Ns Sy property Ns , Ns Sy value Ns , Ns Sy source
2581 is the default value.
2583 Display numbers in parsable
2587 Recursively display properties for any children.
2589 A comma-separated list of sources to display.
2590 Those properties coming from a source other than those in this list are ignored.
2591 Each source must be one of the following:
2598 The default value is all sources.
2600 A comma-separated list of types to display, where
2614 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2616 Clears the specified property, causing it to be inherited from an ancestor,
2617 restored to default if no ancestor has the property set, or with the
2619 option reverted to the received value if one exists.
2622 section for a listing of default values, and details on which properties can be
2624 .Bl -tag -width "-r"
2626 Recursively inherit the given property for all children.
2628 Revert the property to the received value if one exists; otherwise operate as
2631 option was not specified.
2637 Displays a list of file systems that are not the most recent version.
2643 Displays a list of currently supported file system versions.
2649 .Fl a | Ar filesystem
2651 Upgrades file systems to a new on-disk version.
2652 Once this is done, the file systems will no longer be accessible on systems
2653 running older versions of the software.
2655 streams generated from new snapshots of these file systems cannot be accessed on
2656 systems running older versions of the software.
2658 In general, the file system version is independent of the pool version.
2661 for information on the
2662 .Nm zpool Cm upgrade
2665 In some cases, the file system version and the pool version are interrelated and
2666 the pool version must be upgraded before the file system version can be
2668 .Bl -tag -width "-V"
2670 Upgrade to the specified
2674 flag is not specified, this command upgrades to the most recent version.
2676 option can only be used to increase the version number, and only up to the most
2677 recent version supported by this software.
2679 Upgrade all file systems on all imported pools.
2681 Upgrade the specified file system.
2683 Upgrade the specified file system and all descendent file systems.
2689 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2690 .Oo Fl s Ar field Oc Ns ...
2691 .Oo Fl S Ar field Oc Ns ...
2692 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2693 .Ar filesystem Ns | Ns Ar snapshot
2695 Displays space consumed by, and quotas on, each user in the specified filesystem
2697 This corresponds to the
2698 .Sy userused@ Ns Em user ,
2699 .Sy userobjused@ Ns Em user ,
2700 .Sy userquota@ Ns Em user,
2702 .Sy userobjquota@ Ns Em user
2704 .Bl -tag -width "-H"
2706 Do not print headers, use tab-delimited output.
2708 Sort by this field in reverse order.
2712 Translate SID to POSIX ID.
2713 The POSIX ID may be ephemeral if no mapping exists.
2714 Normal POSIX interfaces
2719 perform this translation, so the
2721 option allows the output from
2722 .Nm zfs Cm userspace
2723 to be compared directly with those utilities.
2726 may lead to confusion if some files were created by an SMB user before a
2727 SMB-to-POSIX name mapping was established.
2728 In such a case, some files will be owned by the SMB entity and some by the POSIX
2732 option will report that the POSIX entity has the total usage and quota for both.
2734 Print numeric ID instead of user/group name.
2735 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2736 Display only the specified fields from the following set:
2741 The default is to display all fields.
2747 Sort output by this field.
2752 flags may be specified multiple times to sort first by one field, then by
2755 .Fl s Sy type Fl s Sy name .
2756 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2757 Print only the specified types from the following set:
2764 .Fl t Sy posixuser Ns , Ns Sy smbuser .
2765 The default can be changed to include group types.
2771 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2772 .Oo Fl s Ar field Oc Ns ...
2773 .Oo Fl S Ar field Oc Ns ...
2774 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2775 .Ar filesystem Ns | Ns Ar snapshot
2777 Displays space consumed by, and quotas on, each group in the specified
2778 filesystem or snapshot.
2779 This subcommand is identical to
2780 .Nm zfs Cm userspace ,
2781 except that the default types to display are
2782 .Fl t Sy posixgroup Ns , Ns Sy smbgroup .
2787 Displays all ZFS file systems currently mounted.
2793 .Fl a | Ar filesystem
2795 Mounts ZFS file systems.
2796 .Bl -tag -width "-O"
2798 Perform an overlay mount.
2801 for more information.
2803 Mount all available ZFS file systems.
2804 Invoked automatically as part of the boot process.
2806 Mount the specified filesystem.
2808 An optional, comma-separated list of mount options to use temporarily for the
2809 duration of the mount.
2811 .Sx Temporary Mount Point Properties
2812 section for details.
2814 Report mount progress.
2820 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2822 Unmounts currently mounted ZFS file systems.
2823 .Bl -tag -width "-a"
2825 Unmount all available ZFS file systems.
2826 Invoked automatically as part of the shutdown process.
2827 .It Ar filesystem Ns | Ns Ar mountpoint
2828 Unmount the specified filesystem.
2829 The command can also be given a path to a ZFS file system mount point on the
2832 Forcefully unmount the file system, even if it is currently in use.
2837 .Fl a | Ar filesystem
2839 Shares available ZFS file systems.
2840 .Bl -tag -width "-a"
2842 Share all available ZFS file systems.
2843 Invoked automatically as part of the boot process.
2845 Share the specified filesystem according to the
2850 File systems are shared when the
2859 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2861 Unshares currently shared ZFS file systems.
2862 .Bl -tag -width "-a"
2864 Unshare all available ZFS file systems.
2865 Invoked automatically as part of the shutdown process.
2866 .It Ar filesystem Ns | Ns Ar mountpoint
2867 Unshare the specified filesystem.
2868 The command can also be given a path to a ZFS file system shared on the system.
2873 .Ar snapshot bookmark
2875 Creates a bookmark of the given snapshot.
2876 Bookmarks mark the point in time when the snapshot was created, and can be used
2877 as the incremental source for a
2881 This feature must be enabled to be used.
2883 .Xr zpool-features 5
2884 for details on ZFS feature flags and the
2891 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2894 Creates a stream representation of the second
2896 which is written to standard output.
2897 The output can be redirected to a file or to a different system
2898 .Po for example, using
2901 By default, a full stream is generated.
2902 .Bl -tag -width "-D"
2904 Generate a deduplicated stream.
2905 Blocks which would have been sent multiple times in the send stream will only be
2907 The receiving system must also support this feature to receive a deduplicated
2909 This flag can be used regardless of the dataset's
2911 property, but performance will be much better if the filesystem uses a
2912 dedup-capable checksum
2916 .It Fl I Ar snapshot
2917 Generate a stream package that sends all intermediary snapshots from the first
2918 snapshot to the second snapshot.
2922 .Fl i Em @a Em fs@b Ns ; Fl i Em @b Em fs@c Ns ; Fl i Em @c Em fs@d .
2923 The incremental source may be specified as with the
2926 .It Fl L, -large-block
2927 Generate a stream which may contain blocks larger than 128KB.
2928 This flag has no effect if the
2930 pool feature is disabled, or if the
2932 property of this filesystem has never been set above 128KB.
2933 The receiving system must have the
2935 pool feature enabled as well.
2937 .Xr zpool-features 5
2938 for details on ZFS feature flags and the
2942 Print machine-parsable verbose information about the stream package generated.
2943 .It Fl R, -replicate
2944 Generate a replication stream package, which will replicate the specified
2945 file system, and all descendent file systems, up to the named snapshot.
2946 When received, all properties, snapshots, descendent file systems, and clones
2953 flags are used in conjunction with the
2955 flag, an incremental replication stream is generated.
2956 The current values of properties, and current snapshot and file system names are
2957 set when the stream is received.
2960 flag is specified when this stream is received, snapshots and file systems that
2961 do not exist on the sending side are destroyed.
2963 Generate a more compact stream by using
2965 records for blocks which are stored more compactly on disk by the
2968 This flag has no effect if the
2970 feature is disabled.
2971 The receiving system must have the
2976 feature is active on the sending system, then the receiving system must have
2977 that feature enabled as well.
2979 .Xr zpool-features 5
2980 for details on ZFS feature flags and the
2983 .It Fl c, -compressed
2984 Generate a more compact stream by using compressed WRITE records for blocks
2985 which are compressed on disk and in memory
2988 property for details
2992 feature is active on the sending system, then the receiving system must have
2993 that feature enabled as well.
2996 feature is enabled on the sending system but the
2998 option is not supplied in conjunction with
3000 then the data will be decompressed before sending so it can be split into
3001 smaller block sizes.
3002 .It Fl i Ar snapshot
3003 Generate an incremental stream from the first
3005 .Pq the incremental source
3008 .Pq the incremental target .
3009 The incremental source can be specified as the last component of the snapshot
3013 character and following
3015 and it is assumed to be from the same file system as the incremental target.
3017 If the destination is a clone, the source may be the origin snapshot, which must
3020 .Em pool/fs@origin ,
3028 Do not generate any actual send data.
3029 This is useful in conjunction with the
3033 flags to determine what data will be sent.
3034 In this case, the verbose output will be written to standard output
3035 .Po contrast with a non-dry-run, where the stream is written to standard output
3036 and the verbose output goes to standard error
3039 Include the dataset's properties in the stream.
3040 This flag is implicit when
3043 The receiving system must also support this feature.
3045 Print verbose information about the stream package generated.
3046 This information includes a per-second report of how much data has been sent.
3048 The format of the stream is committed.
3049 You will be able to receive your streams on future versions of ZFS .
3055 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
3056 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3058 Generate a send stream, which may be of a filesystem, and may be incremental
3060 If the destination is a filesystem or volume, the pool must be read-only, or the
3061 filesystem must not be mounted.
3062 When the stream generated from a filesystem or volume is received, the default
3063 snapshot name will be
3065 .Bl -tag -width "-L"
3066 .It Fl L, -large-block
3067 Generate a stream which may contain blocks larger than 128KB.
3068 This flag has no effect if the
3070 pool feature is disabled, or if the
3072 property of this filesystem has never been set above 128KB.
3073 The receiving system must have the
3075 pool feature enabled as well.
3077 .Xr zpool-features 5
3078 for details on ZFS feature flags and the
3081 .It Fl c, -compressed
3082 Generate a more compact stream by using compressed WRITE records for blocks
3083 which are compressed on disk and in memory
3086 property for details
3090 feature is active on the sending system, then the receiving system must have
3091 that feature enabled as well.
3094 feature is enabled on the sending system but the
3096 option is not supplied in conjunction with
3098 then the data will be decompressed before sending so it can be split into
3099 smaller block sizes.
3101 Generate a more compact stream by using
3103 records for blocks which are stored more compactly on disk by the
3106 This flag has no effect if the
3108 feature is disabled.
3109 The receiving system must have the
3114 feature is active on the sending system, then the receiving system must have
3115 that feature enabled as well.
3117 .Xr zpool-features 5
3118 for details on ZFS feature flags and the
3121 .It Fl i Ar snapshot Ns | Ns Ar bookmark
3122 Generate an incremental send stream.
3123 The incremental source must be an earlier snapshot in the destination's history.
3124 It will commonly be an earlier snapshot in the destination's file system, in
3125 which case it can be specified as the last component of the name
3130 character and following
3133 If the incremental target is a clone, the incremental source can be the origin
3134 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
3142 .Ar receive_resume_token
3144 Creates a send stream which resumes an interrupted receive.
3146 .Ar receive_resume_token
3147 is the value of this property on the filesystem or volume that was being
3149 See the documentation for
3156 .Op Fl o Sy origin Ns = Ns Ar snapshot
3157 .Op Fl o Ar property Ns = Ns Ar value
3158 .Op Fl x Ar property
3159 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
3165 .Op Fl d Ns | Ns Fl e
3166 .Op Fl o Sy origin Ns = Ns Ar snapshot
3167 .Op Fl o Ar property Ns = Ns Ar value
3168 .Op Fl x Ar property
3171 Creates a snapshot whose contents are as specified in the stream provided on
3173 If a full stream is received, then a new file system is created as well.
3174 Streams are created using the
3176 subcommand, which by default creates a full stream.
3178 can be used as an alias for
3181 If an incremental stream is received, then the destination file system must
3182 already exist, and its most recent snapshot must match the incremental stream's
3186 the destination device link is destroyed and recreated, which means the
3188 cannot be accessed during the
3192 When a snapshot replication package stream that is generated by using the
3193 .Nm zfs Cm send Fl R
3194 command is received, any snapshots that do not exist on the sending location are
3195 destroyed by using the
3196 .Nm zfs Cm destroy Fl d
3200 .Sy Fl o Em property=value
3202 .Sy Fl x Em property
3203 is specified, it applies to the effective value of the property throughout
3204 the entire subtree of replicated datasets. Effective property values will be
3209 ) on the topmost in the replicated subtree. In descendant datasets, if the
3210 property is set by the send stream, it will be overridden by forcing the
3211 property to be inherited from the top‐most file system. Received properties
3212 are retained in spite of being overridden and may be restored with
3213 .Nm zfs Cm inherit Fl S .
3215 .Sy Fl o Em origin=snapshot
3216 is a special case because, even if
3218 is a read-only property and cannot be set, it's allowed to receive the send
3219 stream as a clone of the given snapshot.
3221 The name of the snapshot
3222 .Pq and file system, if a full stream is received
3223 that this subcommand creates depends on the argument type and the use of the
3229 If the argument is a snapshot name, the specified
3232 If the argument is a file system or volume name, a snapshot with the same name
3233 as the sent snapshot is created within the specified
3241 options are specified, the provided target snapshot name is used exactly as
3248 options cause the file system name of the target snapshot to be determined by
3249 appending a portion of the sent snapshot's name to the specified target
3253 option is specified, all but the first element of the sent snapshot's file
3255 .Pq usually the pool name
3256 is used and any required intermediate file systems within the specified one are
3260 option is specified, then only the last element of the sent snapshot's file
3262 .Pq i.e. the name of the source file system itself
3263 is used as the target file system name.
3264 .Bl -tag -width "-F"
3266 Force a rollback of the file system to the most recent snapshot before
3267 performing the receive operation.
3268 If receiving an incremental replication stream
3269 .Po for example, one generated by
3270 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3272 destroy snapshots and file systems that do not exist on the sending side.
3274 Discard the first element of the sent snapshot's file system name, using the
3275 remaining elements to determine the name of the target file system for the new
3276 snapshot as described in the paragraph above.
3278 Discard all but the last element of the sent snapshot's file system name, using
3279 that element to determine the name of the target file system for the new
3280 snapshot as described in the paragraph above.
3282 Do not actually receive the stream.
3283 This can be useful in conjunction with the
3285 option to verify the name the receive operation would use.
3286 .It Fl o Sy origin Ns = Ns Ar snapshot
3287 Forces the stream to be received as a clone of the given snapshot.
3288 If the stream is a full send stream, this will create the filesystem
3289 described by the stream as a clone of the specified snapshot.
3290 Which snapshot was specified will not affect the success or failure of the
3291 receive, as long as the snapshot does exist.
3292 If the stream is an incremental send stream, all the normal verification will be
3294 .It Fl o Em property=value
3295 Sets the specified property as if the command
3296 .Nm zfs Cm set Em property=value
3297 was invoked immediately before the receive. When receiving a stream from
3298 .Nm zfs Cm send Fl R ,
3299 causes the property to be inherited by all descendant datasets, as through
3300 .Nm zfs Cm inherit Em property
3301 was run on any descendant datasets that have this property set on the
3304 Any editable property can be set at receive time. Set-once properties bound
3305 to the received data, such as
3308 .Sy casesensitivity ,
3309 cannot be set at receive time even when the datasets are newly created by
3310 .Nm zfs Cm receive .
3311 Additionally both settable properties
3315 cannot be set at receive time.
3319 option may be specified multiple times, for different properties. An error
3320 results if the same property is specified in multiple
3326 If the receive is interrupted, save the partially received state, rather
3328 Interruption may be due to premature termination of the stream
3329 .Po e.g. due to network failure or failure of the remote system
3330 if the stream is being read over a network connection
3332 a checksum error in the stream, termination of the
3334 process, or unclean shutdown of the system.
3336 The receive can be resumed with a stream generated by
3337 .Nm zfs Cm send Fl t Ar token ,
3341 .Sy receive_resume_token
3342 property of the filesystem or volume which is received into.
3344 To use this flag, the storage pool must have the
3345 .Sy extensible_dataset
3348 .Xr zpool-features 5
3349 for details on ZFS feature flags.
3351 File system that is associated with the received stream is not mounted.
3353 Print verbose information about the stream and the time required to perform the
3355 .It Fl x Em property
3356 Ensures that the effective value of the specified property after the
3357 receive is unaffected by the value of that property in the send stream (if any),
3358 as if the property had been excluded from the send stream.
3360 If the specified property is not present in the send stream, this option does
3363 If a received property needs to be overridden, the effective value will be
3364 set or inherited, depending on whether the property is inheritable or not.
3366 In the case of an incremental update,
3368 leaves any existing local setting or explicit inheritance unchanged.
3372 restrictions on set-once and special properties apply equally to
3379 .Ar filesystem Ns | Ns Ar volume
3381 Abort an interrupted
3382 .Nm zfs Cm receive Fl s ,
3383 deleting its saved partially received state.
3387 .Ar filesystem Ns | Ns Ar volume
3389 Displays permissions that have been delegated on the specified filesystem or
3391 See the other forms of
3393 for more information.
3395 Delegations are supported under Linux with the exception of
3403 These permissions cannot be delegated because the Linux
3405 command restricts modifications of the global namespace to the root user.
3410 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3411 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3412 .Ar setname Oc Ns ...
3413 .Ar filesystem Ns | Ns Ar volume
3418 .Fl e Ns | Ns Sy everyone
3419 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3420 .Ar setname Oc Ns ...
3421 .Ar filesystem Ns | Ns Ar volume
3423 Delegates ZFS administration permission for the file systems to non-privileged
3425 .Bl -tag -width "-d"
3427 Allow only for the descendent file systems.
3428 .It Fl e Ns | Ns Sy everyone
3429 Specifies that the permissions be delegated to everyone.
3430 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3431 Explicitly specify that permissions are delegated to the group.
3435 only for the specified file system.
3436 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3437 Explicitly specify that permissions are delegated to the user.
3438 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3439 Specifies to whom the permissions are delegated.
3440 Multiple entities can be specified as a comma-separated list.
3443 options are specified, then the argument is interpreted preferentially as the
3446 then as a user name, and lastly as a group name.
3447 To specify a user or group named
3454 To specify a group with the same name as a user, use the
3458 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3459 .Ar setname Oc Ns ...
3461 The permissions to delegate.
3462 Multiple permissions may be specified as a comma-separated list.
3463 Permission names are the same as ZFS subcommand and property names.
3464 See the property list below.
3465 Property set names, which begin with
3470 form below for details.
3475 options are specified, or both are, then the permissions are allowed for the
3476 file system or volume, and all of its descendents.
3478 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3480 The following permissions are available:
3483 allow subcommand Must also have the permission that is
3485 clone subcommand Must also have the 'create' ability and
3486 'mount' ability in the origin file system
3487 create subcommand Must also have the 'mount' ability
3488 destroy subcommand Must also have the 'mount' ability
3489 diff subcommand Allows lookup of paths within a dataset
3490 given an object number, and the ability
3491 to create snapshots necessary to
3493 mount subcommand Allows mount/umount of ZFS datasets
3494 promote subcommand Must also have the 'mount' and 'promote'
3495 ability in the origin file system
3496 receive subcommand Must also have the 'mount' and 'create'
3498 rename subcommand Must also have the 'mount' and 'create'
3499 ability in the new parent
3500 rollback subcommand Must also have the 'mount' ability
3502 share subcommand Allows sharing file systems over NFS
3504 snapshot subcommand Must also have the 'mount' ability
3506 groupquota other Allows accessing any groupquota@...
3508 groupused other Allows reading any groupused@... property
3509 userprop other Allows changing any user property
3510 userquota other Allows accessing any userquota@...
3512 userused other Allows reading any userused@... property
3518 casesensitivity property
3520 compression property
3524 filesystem_limit property
3527 normalization property
3528 primarycache property
3533 refreservation property
3534 reservation property
3535 secondarycache property
3540 snapshot_limit property
3543 volblocksize property
3553 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3554 .Ar setname Oc Ns ...
3555 .Ar filesystem Ns | Ns Ar volume
3560 These permissions are granted
3562 to the creator of any newly-created descendent file system.
3566 .Fl s No @ Ns Ar setname
3567 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3568 .Ar setname Oc Ns ...
3569 .Ar filesystem Ns | Ns Ar volume
3571 Defines or adds permissions to a permission set.
3572 The set can be used by other
3574 commands for the specified file system and its descendents.
3575 Sets are evaluated dynamically, so changes to a set are immediately reflected.
3576 Permission sets follow the same naming restrictions as ZFS file systems, but the
3577 name must begin with
3579 and can be no more than 64 characters long.
3584 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3585 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3586 .Ar setname Oc Ns ... Oc
3587 .Ar filesystem Ns | Ns Ar volume
3592 .Fl e Ns | Ns Sy everyone
3593 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3594 .Ar setname Oc Ns ... Oc
3595 .Ar filesystem Ns | Ns Ar volume
3601 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3602 .Ar setname Oc Ns ... Oc
3603 .Ar filesystem Ns | Ns Ar volume
3605 Removes permissions that were granted with the
3608 No permissions are explicitly denied, so other permissions granted are still in
3610 For example, if the permission is granted by an ancestor.
3611 If no permissions are specified, then all permissions for the specified
3623 only removes the permissions that were granted to everyone, not all permissions
3624 for every user and group.
3627 command for a description of the
3630 .Bl -tag -width "-r"
3632 Recursively remove the permissions from this file system and all descendents.
3638 .Fl s No @ Ns Ar setname
3639 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3640 .Ar setname Oc Ns ... Oc
3641 .Ar filesystem Ns | Ns Ar volume
3643 Removes permissions from a permission set.
3644 If no permissions are specified, then all permissions are removed, thus removing
3650 .Ar tag Ar snapshot Ns ...
3652 Adds a single reference, named with the
3654 argument, to the specified snapshot or snapshots.
3655 Each snapshot has its own tag namespace, and tags must be unique within that
3658 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3662 .Bl -tag -width "-r"
3664 Specifies that a hold with the given tag is applied recursively to the snapshots
3665 of all descendent file systems.
3673 Lists all existing user references for the given snapshot or snapshots.
3674 .Bl -tag -width "-r"
3676 Lists the holds that are set on the named descendent snapshots, in addition to
3677 listing the holds on the named snapshot.
3683 .Ar tag Ar snapshot Ns ...
3685 Removes a single reference, named with the
3687 argument, from the specified snapshot or snapshots.
3688 The tag must already exist for each snapshot.
3689 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3693 .Bl -tag -width "-r"
3695 Recursively releases a hold with the given tag on the snapshots of all
3696 descendent file systems.
3702 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3704 Display the difference between a snapshot of a given filesystem and another
3705 snapshot of that filesystem from a later time or the current contents of the
3707 The first column is a character indicating the type of change, the other columns
3708 indicate pathname, new pathname
3709 .Pq in case of rename ,
3710 change in link count, and optionally file type and/or change time.
3711 The types of change are:
3713 - The path has been removed
3714 + The path has been created
3715 M The path has been modified
3716 R The path has been renamed
3718 .Bl -tag -width "-F"
3720 Display an indication of the type of file, in a manner similar to the
3736 Give more parsable tab-separated output, without header lines and without
3739 Display the path's inode change time as the first column of output.
3745 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3746 options were specified.
3749 .It Sy Example 1 No Creating a ZFS File System Hierarchy
3750 The following commands create a file system named
3752 and a file system named
3756 is set for the parent file system, and is automatically inherited by the child
3759 # zfs create pool/home
3760 # zfs set mountpoint=/export/home pool/home
3761 # zfs create pool/home/bob
3763 .It Sy Example 2 No Creating a ZFS Snapshot
3764 The following command creates a snapshot named
3766 This snapshot is mounted on demand in the
3768 directory at the root of the
3772 # zfs snapshot pool/home/bob@yesterday
3774 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3775 The following command creates snapshots named
3779 and all of its descendent file systems.
3780 Each snapshot is mounted on demand in the
3782 directory at the root of its file system.
3783 The second command destroys the newly created snapshots.
3785 # zfs snapshot -r pool/home@yesterday
3786 # zfs destroy -r pool/home@yesterday
3788 .It Sy Example 4 No Disabling and Enabling File System Compression
3789 The following command disables the
3791 property for all file systems under
3793 The next command explicitly enables
3796 .Em pool/home/anne .
3798 # zfs set compression=off pool/home
3799 # zfs set compression=on pool/home/anne
3801 .It Sy Example 5 No Listing ZFS Datasets
3802 The following command lists all active file systems and volumes in the system.
3803 Snapshots are displayed if the
3811 for more information on pool properties.
3814 NAME USED AVAIL REFER MOUNTPOINT
3815 pool 450K 457G 18K /pool
3816 pool/home 315K 457G 21K /export/home
3817 pool/home/anne 18K 457G 18K /export/home/anne
3818 pool/home/bob 276K 457G 276K /export/home/bob
3820 .It Sy Example 6 No Setting a Quota on a ZFS File System
3821 The following command sets a quota of 50 Gbytes for
3824 # zfs set quota=50G pool/home/bob
3826 .It Sy Example 7 No Listing ZFS Properties
3827 The following command lists all properties for
3830 # zfs get all pool/home/bob
3831 NAME PROPERTY VALUE SOURCE
3832 pool/home/bob type filesystem -
3833 pool/home/bob creation Tue Jul 21 15:53 2009 -
3834 pool/home/bob used 21K -
3835 pool/home/bob available 20.0G -
3836 pool/home/bob referenced 21K -
3837 pool/home/bob compressratio 1.00x -
3838 pool/home/bob mounted yes -
3839 pool/home/bob quota 20G local
3840 pool/home/bob reservation none default
3841 pool/home/bob recordsize 128K default
3842 pool/home/bob mountpoint /pool/home/bob default
3843 pool/home/bob sharenfs off default
3844 pool/home/bob checksum on default
3845 pool/home/bob compression on local
3846 pool/home/bob atime on default
3847 pool/home/bob devices on default
3848 pool/home/bob exec on default
3849 pool/home/bob setuid on default
3850 pool/home/bob readonly off default
3851 pool/home/bob zoned off default
3852 pool/home/bob snapdir hidden default
3853 pool/home/bob acltype off default
3854 pool/home/bob aclinherit restricted default
3855 pool/home/bob canmount on default
3856 pool/home/bob xattr on default
3857 pool/home/bob copies 1 default
3858 pool/home/bob version 4 -
3859 pool/home/bob utf8only off -
3860 pool/home/bob normalization none -
3861 pool/home/bob casesensitivity sensitive -
3862 pool/home/bob vscan off default
3863 pool/home/bob nbmand off default
3864 pool/home/bob sharesmb off default
3865 pool/home/bob refquota none default
3866 pool/home/bob refreservation none default
3867 pool/home/bob primarycache all default
3868 pool/home/bob secondarycache all default
3869 pool/home/bob usedbysnapshots 0 -
3870 pool/home/bob usedbydataset 21K -
3871 pool/home/bob usedbychildren 0 -
3872 pool/home/bob usedbyrefreservation 0 -
3875 The following command gets a single property value.
3877 # zfs get -H -o value compression pool/home/bob
3880 The following command lists all properties with local settings for
3883 # zfs get -r -s local -o name,property,value all pool/home/bob
3885 pool/home/bob quota 20G
3886 pool/home/bob compression on
3888 .It Sy Example 8 No Rolling Back a ZFS File System
3889 The following command reverts the contents of
3891 to the snapshot named
3893 deleting all intermediate snapshots.
3895 # zfs rollback -r pool/home/anne@yesterday
3897 .It Sy Example 9 No Creating a ZFS Clone
3898 The following command creates a writable file system whose initial contents are
3900 .Em pool/home/bob@yesterday .
3902 # zfs clone pool/home/bob@yesterday pool/clone
3904 .It Sy Example 10 No Promoting a ZFS Clone
3905 The following commands illustrate how to test out changes to a file system, and
3906 then replace the original file system with the changed one, using clones, clone
3907 promotion, and renaming:
3909 # zfs create pool/project/production
3910 populate /pool/project/production with data
3911 # zfs snapshot pool/project/production@today
3912 # zfs clone pool/project/production@today pool/project/beta
3913 make changes to /pool/project/beta and test them
3914 # zfs promote pool/project/beta
3915 # zfs rename pool/project/production pool/project/legacy
3916 # zfs rename pool/project/beta pool/project/production
3917 once the legacy version is no longer needed, it can be destroyed
3918 # zfs destroy pool/project/legacy
3920 .It Sy Example 11 No Inheriting ZFS Properties
3921 The following command causes
3927 property from their parent.
3929 # zfs inherit checksum pool/home/bob pool/home/anne
3931 .It Sy Example 12 No Remotely Replicating ZFS Data
3932 The following commands send a full stream and then an incremental stream to a
3933 remote machine, restoring them into
3934 .Em poolB/received/fs@a
3936 .Em poolB/received/fs@b ,
3939 must contain the file system
3940 .Em poolB/received ,
3941 and must not initially contain
3942 .Em poolB/received/fs .
3944 # zfs send pool/fs@a | \e
3945 ssh host zfs receive poolB/received/fs@a
3946 # zfs send -i a pool/fs@b | \e
3947 ssh host zfs receive poolB/received/fs
3949 .It Sy Example 13 No Using the zfs receive -d Option
3950 The following command sends a full stream of
3951 .Em poolA/fsA/fsB@snap
3952 to a remote machine, receiving it into
3953 .Em poolB/received/fsA/fsB@snap .
3956 portion of the received snapshot's name is determined from the name of the sent
3959 must contain the file system
3960 .Em poolB/received .
3962 .Em poolB/received/fsA
3963 does not exist, it is created as an empty file system.
3965 # zfs send poolA/fsA/fsB@snap | \e
3966 ssh host zfs receive -d poolB/received
3968 .It Sy Example 14 No Setting User Properties
3969 The following example sets the user-defined
3970 .Sy com.example:department
3971 property for a dataset.
3973 # zfs set com.example:department=12345 tank/accounting
3975 .It Sy Example 15 No Performing a Rolling Snapshot
3976 The following example shows how to maintain a history of snapshots with a
3977 consistent naming scheme.
3978 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
3979 renames the remaining snapshots, and then creates a new snapshot, as follows:
3981 # zfs destroy -r pool/users@7daysago
3982 # zfs rename -r pool/users@6daysago @7daysago
3983 # zfs rename -r pool/users@5daysago @6daysago
3984 # zfs rename -r pool/users@yesterday @5daysago
3985 # zfs rename -r pool/users@yesterday @4daysago
3986 # zfs rename -r pool/users@yesterday @3daysago
3987 # zfs rename -r pool/users@yesterday @2daysago
3988 # zfs rename -r pool/users@today @yesterday
3989 # zfs snapshot -r pool/users@today
3991 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3992 The following commands show how to set
3994 property options to enable
3998 addresses and to enable root access for system
4004 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
4009 for host name resolution, specify the fully qualified hostname.
4010 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
4011 The following example shows how to set permissions so that user
4013 can create, destroy, mount, and take snapshots on
4019 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
4020 # zfs allow tank/cindys
4021 ---- Permissions on tank/cindys --------------------------------------
4022 Local+Descendent permissions:
4023 user cindys create,destroy,mount,snapshot
4028 mount point permission is set to 755 by default, user
4030 will be unable to mount file systems under
4032 Add an ACE similar to the following syntax to provide mount point access:
4034 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
4036 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
4037 The following example shows how to grant anyone in the group
4039 to create file systems in
4041 This syntax also allows staff members to destroy their own file systems, but not
4042 destroy anyone else's file system.
4047 # zfs allow staff create,mount tank/users
4048 # zfs allow -c destroy tank/users
4049 # zfs allow tank/users
4050 ---- Permissions on tank/users ---------------------------------------
4053 Local+Descendent permissions:
4054 group staff create,mount
4056 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
4057 The following example shows how to define and grant a permission set on the
4064 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
4065 # zfs allow staff @pset tank/users
4066 # zfs allow tank/users
4067 ---- Permissions on tank/users ---------------------------------------
4069 @pset create,destroy,mount,snapshot
4070 Local+Descendent permissions:
4073 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
4074 The following example shows to grant the ability to set quotas and reservations
4082 # zfs allow cindys quota,reservation users/home
4083 # zfs allow users/home
4084 ---- Permissions on users/home ---------------------------------------
4085 Local+Descendent permissions:
4086 user cindys quota,reservation
4087 cindys% zfs set quota=10G users/home/marks
4088 cindys% zfs get quota users/home/marks
4089 NAME PROPERTY VALUE SOURCE
4090 users/home/marks quota 10G local
4092 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
4093 The following example shows how to remove the snapshot permission from the
4102 # zfs unallow staff snapshot tank/users
4103 # zfs allow tank/users
4104 ---- Permissions on tank/users ---------------------------------------
4106 @pset create,destroy,mount,snapshot
4107 Local+Descendent permissions:
4110 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
4111 The following example shows how to see what has changed between a prior
4112 snapshot of a ZFS dataset and its current state.
4115 option is used to indicate type information for the files affected.
4117 # zfs diff -F tank/test@before tank/test
4119 M F /tank/test/linked (+1)
4120 R F /tank/test/oldname -> /tank/test/newname
4121 - F /tank/test/deleted
4122 + F /tank/test/created
4123 M F /tank/test/modified
4125 .It Sy Example 23 No Creating a bookmark
4126 The following example create a bookmark to a snapshot. This bookmark
4127 can then be used instead of snapshot in send streams.
4129 # zfs bookmark rpool@snapshot rpool#bookmark
4131 .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System
4132 The following example show how to share SMB filesystem through ZFS. Note that
4133 that a user and his/her password must be given.
4135 # smbmount //127.0.0.1/share_tmp /mnt/tmp \\
4136 -o user=workgroup/turbo,password=obrut,uid=1000
4140 .Em /etc/samba/smb.conf
4141 configuration required:
4143 Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to
4144 communicate with Samba. This is the default behavior for most Linux
4147 Samba must be able to authenticate a user. This can be done in a number of
4148 ways, depending on if using the system password file, LDAP or the Samba
4149 specific smbpasswd file. How to do this is outside the scope of this manual.
4152 man page for more information.
4155 .Sy USERSHARE section
4158 man page for all configuration options in case you need to modify any options
4159 to the share afterwards. Do note that any changes done with the
4161 command will be undone if the share is ever unshared (such as at a reboot etc).
4163 .Sh INTERFACE STABILITY
projects / mirror_zfs-debian.git / blob