diff options
Diffstat (limited to 'usr/src/man/man8/zfs.8')
| -rw-r--r-- | usr/src/man/man8/zfs.8 | 4855 |
1 files changed, 4855 insertions, 0 deletions
diff --git a/usr/src/man/man8/zfs.8 b/usr/src/man/man8/zfs.8 new file mode 100644 index 0000000000..dd357ee5ac --- /dev/null +++ b/usr/src/man/man8/zfs.8 @@ -0,0 +1,4855 @@ +.\" +.\" CDDL HEADER START +.\" +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.\" +.\" CDDL HEADER END +.\" +.\" +.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> +.\" Copyright (c) 2011, 2016 by Delphix. All rights reserved. +.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. +.\" Copyright (c) 2014 by Adam Stevko. All rights reserved. +.\" Copyright (c) 2014 Integros [integros.com] +.\" Copyright 2018 Nexenta Systems, Inc. +.\" Copyright 2019 Joyent, Inc. +.\" Copyright (c) 2018 Datto Inc. +.\" +.Dd Jul 22, 2019 +.Dt ZFS 8 +.Os +.Sh NAME +.Nm zfs +.Nd configures ZFS file systems +.Sh SYNOPSIS +.Nm +.Op Fl \&? +.Nm +.Cm create +.Op Fl Pnpv +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Ar filesystem +.Nm +.Cm create +.Op Fl Pnpsv +.Op Fl b Ar blocksize +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Fl V Ar size Ar volume +.Nm +.Cm destroy +.Op Fl Rfnprv +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm destroy +.Op Fl Rdnprv +.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns +.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... +.Nm +.Cm destroy +.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark +.Nm +.Cm snapshot +.Op Fl r +.Oo Fl o Ar property Ns = Ns value Oc Ns ... +.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... +.Nm +.Cm rollback +.Op Fl Rfr +.Ar snapshot +.Nm +.Cm clone +.Op Fl p +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Ar snapshot Ar filesystem Ns | Ns Ar volume +.Nm +.Cm promote +.Ar clone-filesystem +.Nm +.Cm rename +.Op Fl f +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Nm +.Cm rename +.Op Fl fp +.Ar filesystem Ns | Ns Ar volume +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm rename +.Fl r +.Ar snapshot Ar snapshot +.Nm +.Cm list +.Op Fl r Ns | Ns Fl d Ar depth +.Op Fl Hp +.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc +.Oo Fl s Ar property Oc Ns ... +.Oo Fl S Ar property Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... +.Nm +.Cm remap +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm set +.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Nm +.Cm get +.Op Fl r Ns | Ns Fl d Ar depth +.Op Fl Hp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... +.Nm +.Cm inherit +.Op Fl rS +.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Nm +.Cm upgrade +.Nm +.Cm upgrade +.Fl v +.Nm +.Cm upgrade +.Op Fl r +.Op Fl V Ar version +.Fl a | Ar filesystem +.Nm +.Cm userspace +.Op Fl Hinp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar snapshot +.Nm +.Cm groupspace +.Op Fl Hinp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar snapshot +.Nm +.Cm projectspace +.Op Fl Hp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Ar filesystem Ns | Ns Ar snapshot +.Nm +.Cm project +.Oo Fl d Ns | Ns Fl r Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Nm +.Cm project +.Fl C +.Oo Fl kr Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Nm +.Cm project +.Fl c +.Oo Fl 0 Ns Oc +.Oo Fl d Ns | Ns Fl r Ns Oc +.Op Fl p Ar id +.Ar file Ns | Ns Ar directory Ns ... +.Nm +.Cm project +.Op Fl p Ar id +.Oo Fl rs Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Nm +.Cm mount +.Nm +.Cm mount +.Op Fl Olv +.Op Fl o Ar options +.Fl a | Ar filesystem +.Nm +.Cm unmount +.Op Fl f +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Nm +.Cm share +.Fl a | Ar filesystem +.Nm +.Cm unshare +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Nm +.Cm bookmark +.Ar snapshot bookmark +.Nm +.Cm send +.Op Fl DLPRbcehnpvw +.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot +.Ar snapshot +.Nm +.Cm send +.Op Fl LPcenvw +.Op Fl i Ar snapshot Ns | Ns Ar bookmark +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Nm +.Cm send +.Op Fl Penv +.Fl t Ar receive_resume_token +.Nm +.Cm receive +.Op Fl Fhnsuv +.Op Fl o Sy origin Ns = Ns Ar snapshot +.Op Fl o Ar property Ns = Ns Ar value +.Op Fl x Ar property +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Nm +.Cm receive +.Op Fl Fhnsuv +.Op Fl d Ns | Ns Fl e +.Op Fl o Sy origin Ns = Ns Ar snapshot +.Op Fl o Ar property Ns = Ns Ar value +.Op Fl x Ar property +.Ar filesystem +.Nm +.Cm receive +.Fl A +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm allow +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm allow +.Op Fl dglu +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm allow +.Op Fl dl +.Fl e Ns | Ns Sy everyone +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm allow +.Fl c +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm allow +.Fl s No @ Ns Ar setname +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm unallow +.Op Fl dglru +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm unallow +.Op Fl dlr +.Fl e Ns | Ns Sy everyone +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm unallow +.Op Fl r +.Fl c +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm unallow +.Op Fl r +.Fl s @ Ns Ar setname +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Nm +.Cm hold +.Op Fl r +.Ar tag Ar snapshot Ns ... +.Nm +.Cm holds +.Op Fl r +.Ar snapshot Ns ... +.Nm +.Cm release +.Op Fl r +.Ar tag Ar snapshot Ns ... +.Nm +.Cm diff +.Op Fl FHt +.Ar snapshot Ar snapshot Ns | Ns Ar filesystem +.Nm +.Cm program +.Op Fl jn +.Op Fl t Ar timeout +.Op Fl m Ar memory_limit +.Ar pool script +.Op Ar arg1 No ... +.Nm +.Cm load-key +.Op Fl rn +.Op Fl L Ar keylocation +.Op Fl a Ns | Ns Ar filesystem +.Nm +.Cm unload-key +.Op Fl r +.Op Fl a Ns | Ns Ar filesystem +.Nm +.Cm change-key +.Op Fl l +.Op Fl o Sy keylocation Ns = Ns Ar value +.Op Fl o Sy keyformat Ns = Ns Ar value +.Op Fl o Sy pbkdf2iters Ns = Ns Ar value +.Ar filesystem +.Sh DESCRIPTION +The +.Nm +command configures ZFS datasets within a ZFS storage pool, as described in +.Xr zpool 8 . +A dataset is identified by a unique path within the ZFS namespace. +For example: +.Bd -literal +pool/{filesystem,volume,snapshot} +.Ed +.Pp +where the maximum length of a dataset name is +.Dv MAXNAMELEN +.Pq 256 bytes +and the maximum amount of nesting allowed in a path is 50 levels deep. +.Pp +A dataset can be one of the following: +.Bl -tag -width "file system" +.It Sy file system +A ZFS dataset of type +.Sy filesystem +can be mounted within the standard system namespace and behaves like other file +systems. +While ZFS file systems are designed to be POSIX compliant, known issues exist +that prevent compliance in some cases. +Applications that depend on standards conformance might fail due to non-standard +behavior when checking file system free space. +.It Sy volume +A logical volume exported as a raw or block device. +This type of dataset should only be used under special circumstances. +File systems are typically used in most environments. +.It Sy snapshot +A read-only version of a file system or volume at a given point in time. +It is specified as +.Ar filesystem Ns @ Ns Ar name +or +.Ar volume Ns @ Ns Ar name . +.El +.Ss ZFS File System Hierarchy +A ZFS storage pool is a logical collection of devices that provide space for +datasets. +A storage pool is also the root of the ZFS file system hierarchy. +.Pp +The root of the pool can be accessed as a file system, such as mounting and +unmounting, taking snapshots, and setting properties. +The physical storage characteristics, however, are managed by the +.Xr zpool 8 +command. +.Pp +See +.Xr zpool 8 +for more information on creating and administering pools. +.Ss Snapshots +A snapshot is a read-only copy of a file system or volume. +Snapshots can be created extremely quickly, and initially consume no additional +space within the pool. +As data within the active dataset changes, the snapshot consumes more data than +would otherwise be shared with the active dataset. +.Pp +Snapshots can have arbitrary names. +Snapshots of volumes can be cloned or rolled back, but cannot be accessed +independently. +.Pp +File system snapshots can be accessed under the +.Pa .zfs/snapshot +directory in the root of the file system. +Snapshots are automatically mounted on demand and may be unmounted at regular +intervals. +The visibility of the +.Pa .zfs +directory can be controlled by the +.Sy snapdir +property. +.Ss Clones +A clone is a writable volume or file system whose initial contents are the same +as another dataset. +As with snapshots, creating a clone is nearly instantaneous, and initially +consumes no additional space. +.Pp +Clones can only be created from a snapshot. +When a snapshot is cloned, it creates an implicit dependency between the parent +and child. +Even though the clone is created somewhere else in the dataset hierarchy, the +original snapshot cannot be destroyed as long as a clone exists. +The +.Sy origin +property exposes this dependency, and the +.Cm destroy +command lists any such dependencies, if they exist. +.Pp +The clone parent-child dependency relationship can be reversed by using the +.Cm promote +subcommand. +This causes the +.Qq origin +file system to become a clone of the specified file system, which makes it +possible to destroy the file system that the clone was created from. +.Ss "Mount Points" +Creating a ZFS file system is a simple operation, so the number of file systems +per system is likely to be numerous. +To cope with this, ZFS automatically manages mounting and unmounting file +systems without the need to edit the +.Pa /etc/vfstab +file. +All automatically managed file systems are mounted by ZFS at boot time. +.Pp +By default, file systems are mounted under +.Pa /path , +where +.Ar path +is the name of the file system in the ZFS namespace. +Directories are created and destroyed as needed. +.Pp +A file system can also have a mount point set in the +.Sy mountpoint +property. +This directory is created as needed, and ZFS automatically mounts the file +system when the +.Nm zfs Cm mount Fl a +command is invoked +.Po without editing +.Pa /etc/vfstab +.Pc . +The +.Sy mountpoint +property can be inherited, so if +.Em pool/home +has a mount point of +.Pa /export/stuff , +then +.Em pool/home/user +automatically inherits a mount point of +.Pa /export/stuff/user . +.Pp +A file system +.Sy mountpoint +property of +.Sy none +prevents the file system from being mounted. +.Pp +If needed, ZFS file systems can also be managed with traditional tools +.Po +.Nm mount , +.Nm umount , +.Pa /etc/vfstab +.Pc . +If a file system's mount point is set to +.Sy legacy , +ZFS makes no attempt to manage the file system, and the administrator is +responsible for mounting and unmounting the file system. +.Ss "Zones" +A ZFS file system can be added to a non-global zone by using the +.Nm zonecfg Cm add Sy fs +subcommand. +A ZFS file system that is added to a non-global zone must have its +.Sy mountpoint +property set to +.Sy legacy . +.Pp +The physical properties of an added file system are controlled by the global +administrator. +However, the zone administrator can create, modify, or destroy files within the +added file system, depending on how the file system is mounted. +.Pp +A dataset can also be delegated to a non-global zone by using the +.Nm zonecfg Cm add Sy dataset +subcommand. +You cannot delegate a dataset to one zone and the children of the same dataset +to another zone. +The zone administrator can change properties of the dataset or any of its +children. +However, the +.Sy quota , +.Sy filesystem_limit +and +.Sy snapshot_limit +properties of the delegated dataset can be modified only by the global +administrator. +.Pp +A ZFS volume can be added as a device to a non-global zone by using the +.Nm zonecfg Cm add Sy device +subcommand. +However, its physical properties can be modified only by the global +administrator. +.Pp +For more information about +.Nm zonecfg +syntax, see +.Xr zonecfg 8 . +.Pp +After a dataset is delegated to a non-global zone, the +.Sy zoned +property is automatically set. +A zoned file system cannot be mounted in the global zone, since the zone +administrator might have to set the mount point to an unacceptable value. +.Pp +The global administrator can forcibly clear the +.Sy zoned +property, though this should be done with extreme care. +The global administrator should verify that all the mount points are acceptable +before clearing the property. +.Ss Native Properties +Properties are divided into two types, native properties and user-defined +.Po or +.Qq user +.Pc +properties. +Native properties either export internal statistics or control ZFS behavior. +In addition, native properties are either editable or read-only. +User properties have no effect on ZFS behavior, but you can use them to annotate +datasets in a way that is meaningful in your environment. +For more information about user properties, see the +.Sx User Properties +section, below. +.Pp +Every dataset has a set of properties that export statistics about the dataset +as well as control various behaviors. +Properties are inherited from the parent unless overridden by the child. +Some properties apply only to certain types of datasets +.Pq file systems, volumes, or snapshots . +.Pp +The values of numeric properties can be specified using human-readable suffixes +.Po for example, +.Sy k , +.Sy KB , +.Sy M , +.Sy Gb , +and so forth, up to +.Sy Z +for zettabyte +.Pc . +The following are all valid +.Pq and equal +specifications: +.Li 1536M, 1.5g, 1.50GB . +.Pp +The values of non-numeric properties are case sensitive and must be lowercase, +except for +.Sy mountpoint , +.Sy sharenfs , +and +.Sy sharesmb . +.Pp +The following native properties consist of read-only statistics about the +dataset. +These properties can be neither set, nor inherited. +Native properties apply to all dataset types unless otherwise noted. +.Bl -tag -width "usedbyrefreservation" +.It Sy available +The amount of space available to the dataset and all its children, assuming that +there is no other activity in the pool. +Because space is shared within a pool, availability can be limited by any number +of factors, including physical pool size, quotas, reservations, or other +datasets within the pool. +.Pp +This property can also be referred to by its shortened column name, +.Sy avail . +.It Sy compressratio +For non-snapshots, the compression ratio achieved for the +.Sy used +space of this dataset, expressed as a multiplier. +The +.Sy used +property includes descendant datasets, and, for clones, does not include the +space shared with the origin snapshot. +For snapshots, the +.Sy compressratio +is the same as the +.Sy refcompressratio +property. +Compression can be turned on by running: +.Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . +The default value is +.Sy off . +.It Sy createtxg +The transaction group (txg) in which the dataset was created. +Bookmarks have the same +.Sy createtxg +as the snapshot they are initially tied to. +This property is suitable for ordering a list of snapshots, +e.g. for incremental send and receive. +.It Sy creation +The time this dataset was created. +.It Sy clones +For snapshots, this property is a comma-separated list of filesystems or volumes +which are clones of this snapshot. +The clones' +.Sy origin +property is this snapshot. +If the +.Sy clones +property is not empty, then this snapshot can not be destroyed +.Po even with the +.Fl r +or +.Fl f +options +.Pc . +.It Sy defer_destroy +This property is +.Sy on +if the snapshot has been marked for deferred destroy by using the +.Nm zfs Cm destroy Fl d +command. +Otherwise, the property is +.Sy off . +.It Sy encryptionroot +For encrypted datasets, indicates where the dataset is currently inheriting its +encryption key from. +Loading or unloading a key for the +.Sy encryptionroot +will implicitly load / unload the key for any inheriting datasets +.Po see +.Nm zfs Cm load-key +and +.Nm zfs Cm unload-key +.Pc . +Clones will always share an encryption key with their origin. +See the +.Sy Encryption +section for details. +.It Sy filesystem_count +The total number of filesystems and volumes that exist under this location in +the dataset tree. +This value is only available when a +.Sy filesystem_limit +has been set somewhere in the tree under which the dataset resides. +.It Sy guid +The 64 bit GUID of this dataset or bookmark which does not change over its +entire lifetime. +When a snapshot is sent to another pool, the received snapshot has the same +GUID. +Thus, the +.Sy guid +is suitable to identify a snapshot across pools. +.It Sy keystatus +Indicates if an encryption key is currently loaded into ZFS. +The possible values are +.Sy none , available , +and +.Sy unavailable . +See +.Nm Cm load-key +and +.Nm Cm unload-key . +.It Sy logicalreferenced +The amount of space that is +.Qq logically +accessible by this dataset. +See the +.Sy referenced +property. +The logical space ignores the effect of the +.Sy compression +and +.Sy copies +properties, giving a quantity closer to the amount of data that applications +see. +However, it does include space consumed by metadata. +.Pp +This property can also be referred to by its shortened column name, +.Sy lrefer . +.It Sy logicalused +The amount of space that is +.Qq logically +consumed by this dataset and all its descendents. +See the +.Sy used +property. +The logical space ignores the effect of the +.Sy compression +and +.Sy copies +properties, giving a quantity closer to the amount of data that applications +see. +However, it does include space consumed by metadata. +.Pp +This property can also be referred to by its shortened column name, +.Sy lused . +.It Sy mounted +For file systems, indicates whether the file system is currently mounted. +This property can be either +.Sy yes +or +.Sy no . +.It Sy origin +For cloned file systems or volumes, the snapshot from which the clone was +created. +See also the +.Sy clones +property. +.It Sy receive_resume_token +For filesystems or volumes which have saved partially-completed state from +.Sy zfs receive -s , +this opaque token can be provided to +.Sy zfs send -t +to resume and complete the +.Sy zfs receive . +.It Sy referenced +The amount of data that is accessible by this dataset, which may or may not be +shared with other datasets in the pool. +When a snapshot or clone is created, it initially references the same amount of +space as the file system or snapshot it was created from, since its contents are +identical. +.Pp +This property can also be referred to by its shortened column name, +.Sy refer . +.It Sy refcompressratio +The compression ratio achieved for the +.Sy referenced +space of this dataset, expressed as a multiplier. +See also the +.Sy compressratio +property. +.It Sy snapshot_count +The total number of snapshots that exist under this location in the dataset +tree. +This value is only available when a +.Sy snapshot_limit +has been set somewhere in the tree under which the dataset resides. +.It Sy type +The type of dataset: +.Sy filesystem , +.Sy volume , +or +.Sy snapshot . +.It Sy used +The amount of space consumed by this dataset and all its descendents. +This is the value that is checked against this dataset's quota and reservation. +The space used does not include this dataset's reservation, but does take into +account the reservations of any descendent datasets. +The amount of space that a dataset consumes from its parent, as well as the +amount of space that is freed if this dataset is recursively destroyed, is the +greater of its space used and its reservation. +.Pp +The used space of a snapshot +.Po see the +.Sx Snapshots +section +.Pc +is space that is referenced exclusively by this snapshot. +If this snapshot is destroyed, the amount of +.Sy used +space will be freed. +Space that is shared by multiple snapshots isn't accounted for in this metric. +When a snapshot is destroyed, space that was previously shared with this +snapshot can become unique to snapshots adjacent to it, thus changing the used +space of those snapshots. +The used space of the latest snapshot can also be affected by changes in the +file system. +Note that the +.Sy used +space of a snapshot is a subset of the +.Sy written +space of the snapshot. +.Pp +The amount of space used, available, or referenced does not take into account +pending changes. +Pending changes are generally accounted for within a few seconds. +Committing a change to a disk using +.Xr fsync 3C +or +.Dv O_SYNC +does not necessarily guarantee that the space usage information is updated +immediately. +.It Sy usedby* +The +.Sy usedby* +properties decompose the +.Sy used +properties into the various reasons that space is used. +Specifically, +.Sy used No = +.Sy usedbychildren No + +.Sy usedbydataset No + +.Sy usedbyrefreservation No + +.Sy usedbysnapshots . +These properties are only available for datasets created on +.Nm zpool +.Qo version 13 Qc +pools. +.It Sy usedbychildren +The amount of space used by children of this dataset, which would be freed if +all the dataset's children were destroyed. +.It Sy usedbydataset +The amount of space used by this dataset itself, which would be freed if the +dataset were destroyed +.Po after first removing any +.Sy refreservation +and destroying any necessary snapshots or descendents +.Pc . +.It Sy usedbyrefreservation +The amount of space used by a +.Sy refreservation +set on this dataset, which would be freed if the +.Sy refreservation +was removed. +.It Sy usedbysnapshots +The amount of space consumed by snapshots of this dataset. +In particular, it is the amount of space that would be freed if all of this +dataset's snapshots were destroyed. +Note that this is not simply the sum of the snapshots' +.Sy used +properties because space can be shared by multiple snapshots. +.It Sy userused Ns @ Ns Em user +The amount of space consumed by the specified user in this dataset. +Space is charged to the owner of each file, as displayed by +.Nm ls Fl l . +The amount of space charged is displayed by +.Nm du +and +.Nm ls Fl s . +See the +.Nm zfs Cm userspace +subcommand for more information. +.Pp +Unprivileged users can access only their own space usage. +The root user, or a user who has been granted the +.Sy userused +privilege with +.Nm zfs Cm allow , +can access everyone's usage. +.Pp +The +.Sy userused Ns @ Ns Em ... +properties are not displayed by +.Nm zfs Cm get Sy all . +The user's name must be appended after the @ symbol, using one of the following +forms: +.Bl -bullet -width "" +.It +.Em POSIX name +.Po for example, +.Sy joe +.Pc +.It +.Em POSIX numeric ID +.Po for example, +.Sy 789 +.Pc +.It +.Em SID name +.Po for example, +.Sy joe.smith@mydomain +.Pc +.It +.Em SID numeric ID +.Po for example, +.Sy S-1-123-456-789 +.Pc +.El +.It Sy userobjused Ns @ Ns Em user +The +.Sy userobjused +property is similar to +.Sy userused +but instead it counts the number of objects consumed by a user. +This property counts all objects allocated on behalf of the user, it may +differ from the results of system tools such as +.Nm df Fl i . +.Pp +When the property +.Sy xattr=on +is set on a file system additional objects will be created per-file to store +extended attributes. +These additional objects are reflected in the +.Sy userobjused +value and are counted against the user's +.Sy userobjquota . +.It Sy userrefs +This property is set to the number of user holds on this snapshot. +User holds are set by using the +.Nm zfs Cm hold +command. +.It Sy groupused Ns @ Ns Em group +The amount of space consumed by the specified group in this dataset. +Space is charged to the group of each file, as displayed by +.Nm ls Fl l . +See the +.Sy userused Ns @ Ns Em user +property for more information. +.Pp +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the +.Sy groupused +privilege with +.Nm zfs Cm allow , +can access all groups' usage. +.It Sy groupobjused Ns @ Ns Em group +The number of objects consumed by the specified group in this dataset. +Multiple objects may be charged to the group for each file when extended +attributes are in use. +See the +.Sy userobjused Ns @ Ns Em user +property for more information. +.Pp +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the +.Sy groupobjused +privilege with +.Nm zfs Cm allow , +can access all groups' usage. +.It Sy projectused Ns @ Ns Em project +The amount of space consumed by the specified project in this dataset. +Project is identified via the project identifier (ID) that is object-based +numeral attribute. +An object can inherit the project ID from its parent object (if the +parent has the flag of inherit project ID that can be set and changed via +.Nm zfs project Fl s ) +when being created. +The privileged user can set and change object's project +ID via +.Nm zfs project Fl s +anytime. +Space is charged to the project of each file, as displayed by +.Nm zfs project . +See the +.Sy userused Ns @ Ns Em user +property for more information. +.Pp +The root user, or a user who has been granted the +.Sy projectused +privilege with +.Nm zfs allow , +can access all projects' usage. +.It Sy projectobjused Ns @ Ns Em project +The +.Sy projectobjused +is similar to +.Sy projectused +but instead it counts the number of objects consumed by project. +When the property +.Sy xattr=on +is set on a fileset, ZFS will create additional objects per-file to store +extended attributes. +These additional objects are reflected in the +.Sy projectobjused +value and are counted against the project's +.Sy projectobjquota . +See the +.Sy userobjused Ns @ Ns Em user +property for more information. +.Pp +The root user, or a user who has been granted the +.Sy projectobjused +privilege with +.Nm zfs allow , +can access all projects' objects usage. +.It Sy volblocksize +For volumes, specifies the block size of the volume. +The +.Sy blocksize +cannot be changed once the volume has been written, so it should be set at +volume creation time. +The default +.Sy blocksize +for volumes is 8 Kbytes. +Any power of 2 from 512 bytes to 128 Kbytes is valid. +.Pp +This property can also be referred to by its shortened column name, +.Sy volblock . +.It Sy written +The amount of space +.Sy referenced +by this dataset, that was written since the previous snapshot +.Pq i.e. that is not referenced by the previous snapshot . +.It Sy written Ns @ Ns Em snapshot +The amount of +.Sy referenced +space written to this dataset since the specified snapshot. +This is the space that is referenced by this dataset but was not referenced by +the specified snapshot. +.Pp +The +.Em snapshot +may be specified as a short snapshot name +.Po just the part after the +.Sy @ +.Pc , +in which case it will be interpreted as a snapshot in the same filesystem as +this dataset. +The +.Em snapshot +may be a full snapshot name +.Po Em filesystem Ns @ Ns Em snapshot Pc , +which for clones may be a snapshot in the origin's filesystem +.Pq or the origin of the origin's filesystem, etc. +.El +.Pp +The following native properties can be used to change the behavior of a ZFS +dataset. +.Bl -tag -width "" +.It Xo +.Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns +.Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x +.Xc +Controls how ACEs are inherited when files and directories are created. +.Bl -tag -width "passthrough-x" +.It Sy discard +does not inherit any ACEs. +.It Sy noallow +only inherits inheritable ACEs that specify +.Qq deny +permissions. +.It Sy restricted +default, removes the +.Sy write_acl +and +.Sy write_owner +permissions when the ACE is inherited. +.It Sy passthrough +inherits all inheritable ACEs without any modifications. +.It Sy passthrough-x +same meaning as +.Sy passthrough , +except that the +.Sy owner@ , +.Sy group@ , +and +.Sy everyone@ +ACEs inherit the execute permission only if the file creation mode also requests +the execute bit. +.El +.Pp +When the property value is set to +.Sy passthrough , +files are created with a mode determined by the inheritable ACEs. +If no inheritable ACEs exist that affect the mode, then the mode is set in +accordance to the requested mode from the application. +.It Xo +.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns +.Sy passthrough Ns | Ns Sy restricted +.Xc +Controls how an ACL is modified during +.Xr chmod 2 +and how inherited ACEs are modified by the file creation mode. +.Bl -tag -width "passthrough" +.It Sy discard +default, deletes all ACEs except for those representing the mode of the file or +directory requested by +.Xr chmod 2 . +.It Sy groupmask +reduces permissions granted by all +.Sy ALLOW +entries found in the ACL such that they are no greater than the group +permissions specified by the mode. +.It Sy passthrough +indicates that no changes are made to the ACL other than creating or updating +the necessary ACEs to represent the new mode of the file or directory. +.It Sy restricted +causes the +.Xr chmod 2 +operation to return an error when used on any file or directory which has a +non-trivial ACL, with entries in addition to those that represent the mode. +.El +.Pp +.Xr chmod 2 +is required to change the set user ID, set group ID, or sticky bit on a file or +directory, as they do not have equivalent ACEs. +In order to use +.Xr chmod 2 +on a file or directory with a non-trivial ACL when +.Sy aclmode +is set to +.Sy restricted , +you must first remove all ACEs except for those that represent the current mode. +.It Sy atime Ns = Ns Sy on Ns | Ns Sy off +Controls whether the access time for files is updated when they are read. +Turning this property off avoids producing write traffic when reading files and +can result in significant performance gains, though it might confuse mailers +and other similar utilities. +The default value is +.Sy on . +.It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto +If this property is set to +.Sy off , +the file system cannot be mounted, and is ignored by +.Nm zfs Cm mount Fl a . +Setting this property to +.Sy off +is similar to setting the +.Sy mountpoint +property to +.Sy none , +except that the dataset still has a normal +.Sy mountpoint +property, which can be inherited. +Setting this property to +.Sy off +allows datasets to be used solely as a mechanism to inherit properties. +One example of setting +.Sy canmount Ns = Ns Sy off +is to have two datasets with the same +.Sy mountpoint , +so that the children of both datasets appear in the same directory, but might +have different inherited characteristics. +.Pp +When set to +.Sy noauto , +a dataset can only be mounted and unmounted explicitly. +The dataset is not mounted automatically when the dataset is created or +imported, nor is it mounted by the +.Nm zfs Cm mount Fl a +command or unmounted by the +.Nm zfs Cm unmount Fl a +command. +.Pp +This property is not inherited. +.It Xo +.Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns +.Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns +.Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr +.Xc +Controls the checksum used to verify data integrity. +The default value is +.Sy on , +which automatically selects an appropriate algorithm +.Po currently, +.Sy fletcher4 , +but this may change in future releases +.Pc . +The value +.Sy off +disables integrity checking on user data. +The value +.Sy noparity +not only disables integrity but also disables maintaining parity for user data. +This setting is used internally by a dump device residing on a RAID-Z pool and +should not be used by any other dataset. +Disabling checksums is +.Sy NOT +a recommended practice. +.Pp +The +.Sy sha512 , +.Sy skein , +and +.Sy edonr +checksum algorithms require enabling the appropriate features on the pool. +Please see +.Xr zpool-features 7 +for more information on these algorithms. +.Pp +Changing this property affects only newly-written data. +.It Xo +.Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns +.Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle +.Xc +Controls the compression algorithm used for this dataset. +.Pp +Setting compression to +.Sy on +indicates that the current default compression algorithm should be used. +The default balances compression and decompression speed, with compression ratio +and is expected to work well on a wide variety of workloads. +Unlike all other settings for this property, +.Sy on +does not select a fixed compression type. +As new compression algorithms are added to ZFS and enabled on a pool, the +default compression algorithm may change. +The current default compression algorithm is either +.Sy lzjb +or, if the +.Sy lz4_compress +feature is enabled, +.Sy lz4 . +.Pp +The +.Sy lz4 +compression algorithm is a high-performance replacement for the +.Sy lzjb +algorithm. +It features significantly faster compression and decompression, as well as a +moderately higher compression ratio than +.Sy lzjb , +but can only be used on pools with the +.Sy lz4_compress +feature set to +.Sy enabled . +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy lz4_compress +feature. +.Pp +The +.Sy lzjb +compression algorithm is optimized for performance while providing decent data +compression. +.Pp +The +.Sy gzip +compression algorithm uses the same compression as the +.Xr gzip 1 +command. +You can specify the +.Sy gzip +level by using the value +.Sy gzip- Ns Em N , +where +.Em N +is an integer from 1 +.Pq fastest +to 9 +.Pq best compression ratio . +Currently, +.Sy gzip +is equivalent to +.Sy gzip-6 +.Po which is also the default for +.Xr gzip 1 +.Pc . +.Pp +The +.Sy zle +compression algorithm compresses runs of zeros. +.Pp +This property can also be referred to by its shortened column name +.Sy compress . +Changing this property affects only newly-written data. +.It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 +Controls the number of copies of data stored for this dataset. +These copies are in addition to any redundancy provided by the pool, for +example, mirroring or RAID-Z. +The copies are stored on different disks, if possible. +The space used by multiple copies is charged to the associated file and dataset, +changing the +.Sy used +property and counting against quotas and reservations. +.Pp +Changing this property only affects newly-written data. +Therefore, set this property at file system creation time by using the +.Fl o Sy copies Ns = Ns Ar N +option. +.It Sy devices Ns = Ns Sy on Ns | Ns Sy off +Controls whether device nodes can be opened on this file system. +The default value is +.Sy on . +.It Xo +.Sy encryption Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy aes-128-ccm Ns | Ns +.Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns +.Sy aes-192-gcm Ns | Ns Sy aes-256-gcm +.Xc +Controls the encryption cipher suite +.Pq block cipher, key length, and mode +used for this dataset. +Requires the encryption feature to be enabled on the pool. +Requires a +.Sy keyformat +to be set at dataset creation time. +.Pp +Selecting +.Sy encryption Ns = Ns Sy on +when creating a dataset indicates that the default encryption suite will be +selected, which is currently +.Sy aes-256-ccm . +In order to provide consistent data protection, encryption must be specified at +dataset creation time and it cannot be changed afterwards. +.Pp +For more details and caveats about encryption see the +.Sx Encryption +section. +.It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase +Controls what format the user's encryption key will be provided as. +This property is only set for encrypted datasets which are encryption roots. +.Pp +Raw keys and hex keys must be 32 bytes long +.Pq regardless of the chosen encryption suite +and must be randomly generated. +A raw key can be generated with the following command: +.Bd -literal +# dd if=/dev/urandom of=/path/to/output/key bs=32 count=1 +.Ed +.Pp +Passphrases must be between 8 and 512 bytes long and will be processed through +PBKDF2 before being used +.Po see the +.Nm pbkdf2iters +property +.Pc . +Even though the encryption suite cannot be changed after dataset creation, the +keyformat can be with +.Nm Cm change-key . +.It Sy keylocation Ns = Ns Sy prompt Ns | Ns Ar file://<absolute file path> +Controls where the user's encryption key will be loaded from by default for +commands such as +.Nm Cm load-key +and +.Nm Cm mount Fl l . +This property is only set for encrypted datasets which are encryption roots. +If unspecified, the default is +.Sy prompt . +.Pp +Even though the encryption suite cannot be changed after dataset creation, the +keylocation can be with either +.Nm Cm set +or +.Nm Cm change-key . +If +.Sy prompt +is selected ZFS will ask for the key at the command prompt when +it is required to access the encrypted data +.Po see +.Nm Cm load-key +.Pc . +This setting will also allow the key to be passed in via STDIN, but users +should be careful not to place keys which should be kept secret on the +command line. +If a file URI is selected, the key will be loaded from the specified absolute +file path. +.It Sy exec Ns = Ns Sy on Ns | Ns Sy off +Controls whether processes can be executed from within this file system. +The default value is +.Sy on . +.It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none +Limits the number of filesystems and volumes that can exist under this point in +the dataset tree. +The limit is not enforced if the user is allowed to change the limit. +Setting a +.Sy filesystem_limit +to +.Sy on +a descendent of a filesystem that already has a +.Sy filesystem_limit +does not override the ancestor's +.Sy filesystem_limit , +but rather imposes an additional limit. +This feature must be enabled to be used +.Po see +.Xr zpool-features 7 +.Pc . +.It Sy special_small_blocks Ns = Ns Em size +This value represents the threshold block size for including small file +blocks into the special allocation class. +Blocks smaller than or equal to this value will be assigned to the special +allocation class while greater blocks will be assigned to the regular class. +Valid values are zero or a power of two from 512B up to 128K. +The default size is 0 which means no small file blocks will be allocated in +the special class. +.Pp +Before setting this property, a special class vdev must be added to the +pool. +See +.Xr zpool 8 +for more details on the special allocation class. +.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy +Controls the mount point used for this file system. +See the +.Sx Mount Points +section for more information on how this property is used. +.Pp +When the +.Sy mountpoint +property is changed for a file system, the file system and any children that +inherit the mount point are unmounted. +If the new value is +.Sy legacy , +then they remain unmounted. +Otherwise, they are automatically remounted in the new location if the property +was previously +.Sy legacy +or +.Sy none , +or if they were mounted before the property was changed. +In addition, any shared file systems are unshared and shared in the new +location. +.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off +Controls whether the file system should be mounted with +.Sy nbmand +.Pq Non Blocking mandatory locks . +This is used for SMB clients. +Changes to this property only take effect when the file system is umounted and +remounted. +See +.Xr mount 8 +for more information on +.Sy nbmand +mounts. +.It Sy pbkdf2iters Ns = Ns Ar iterations +Controls the number of PBKDF2 iterations that a +.Sy passphrase +encryption key should be run through when processing it into an encryption key. +This property is only defined when encryption is enabled and a keyformat of +.Sy passphrase +is selected. +The goal of PBKDF2 is to significantly increase the computational difficulty +needed to brute force a user's passphrase. +This is accomplished by forcing the attacker to run each passphrase through a +computationally expensive hashing function many times before they arrive at the +resulting key. +A user who actually knows the passphrase will only have to pay this cost once. +As CPUs become better at processing, this number should be raised to ensure that +a brute force attack is still not possible. +The current default is 350000 and the minimum is 100000. +This property may be changed with +.Nm Cm change-key . +.It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata +Controls what is cached in the primary cache +.Pq ARC . +If this property is set to +.Sy all , +then both user data and metadata is cached. +If this property is set to +.Sy none , +then neither user data nor metadata is cached. +If this property is set to +.Sy metadata , +then only metadata is cached. +The default value is +.Sy all . +.It Sy quota Ns = Ns Em size Ns | Ns Sy none +Limits the amount of space a dataset and its descendents can consume. +This property enforces a hard limit on the amount of space used. +This includes all space consumed by descendents, including file systems and +snapshots. +Setting a quota on a descendent of a dataset that already has a quota does not +override the ancestor's quota, but rather imposes an additional limit. +.Pp +Quotas cannot be set on volumes, as the +.Sy volsize +property acts as an implicit quota. +.It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none +Limits the number of snapshots that can be created on a dataset and its +descendents. +Setting a +.Sy snapshot_limit +on a descendent of a dataset that already has a +.Sy snapshot_limit +does not override the ancestor's +.Sy snapshot_limit , +but rather imposes an additional limit. +The limit is not enforced if the user is allowed to change the limit. +For example, this means that recursive snapshots taken from the global zone are +counted against each delegated dataset within a zone. +This feature must be enabled to be used +.Po see +.Xr zpool-features 7 +.Pc . +.It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none +Limits the amount of space consumed by the specified user. +User space consumption is identified by the +.Sy userspace@ Ns Em user +property. +.Pp +Enforcement of user quotas may be delayed by several seconds. +This delay means that a user might exceed their quota before the system notices +that they are over quota and begins to refuse additional writes with the +.Er EDQUOT +error message. +See the +.Nm zfs Cm userspace +subcommand for more information. +.Pp +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the +.Sy userquota +privilege with +.Nm zfs Cm allow , +can get and set everyone's quota. +.Pp +This property is not available on volumes, on file systems before version 4, or +on pools before version 15. +The +.Sy userquota@ Ns Em ... +properties are not displayed by +.Nm zfs Cm get Sy all . +The user's name must be appended after the +.Sy @ +symbol, using one of the following forms: +.Bl -bullet +.It +.Em POSIX name +.Po for example, +.Sy joe +.Pc +.It +.Em POSIX numeric ID +.Po for example, +.Sy 789 +.Pc +.It +.Em SID name +.Po for example, +.Sy joe.smith@mydomain +.Pc +.It +.Em SID numeric ID +.Po for example, +.Sy S-1-123-456-789 +.Pc +.El +.It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none +The +.Sy userobjquota +is similar to +.Sy userquota +but it limits the number of objects a user can create. +Please refer to +.Sy userobjused +for more information about how objects are counted. +.It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none +Limits the amount of space consumed by the specified group. +Group space consumption is identified by the +.Sy groupused@ Ns Em group +property. +.Pp +Unprivileged users can access only their own groups' space usage. +The root user, or a user who has been granted the +.Sy groupquota +privilege with +.Nm zfs Cm allow , +can get and set all groups' quotas. +.It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none +The +.Sy groupobjquota +is similar to +.Sy groupquota +but it limits the number of objects a group can consume. +Please refer to +.Sy userobjused +for more information about how objects are counted. +.It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none +Limits the amount of space consumed by the specified project. +Project space consumption is identified by the +.Sy projectused@ Ns Em project +property. +Please refer to +.Sy projectused +for more information about how project is identified and set or changed. +.Pp +The root user, or a user who has been granted the +.Sy projectquota +privilege with +.Nm zfs allow , +can access all projects' quotas. +.It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none +The +.Sy projectobjquota +is similar to +.Sy projectquota +but it limits the number of objects a project can consume. +Please refer to +.Sy userobjused +for more information about how objects are counted. +.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off +Controls whether this dataset can be modified. +The default value is +.Sy off . +.Pp +This property can also be referred to by its shortened column name, +.Sy rdonly . +.It Sy recordsize Ns = Ns Em size +Specifies a suggested block size for files in the file system. +This property is designed solely for use with database workloads that access +files in fixed-size records. +ZFS automatically tunes block sizes according to internal algorithms optimized +for typical access patterns. +.Pp +For databases that create very large files but access them in small random +chunks, these algorithms may be suboptimal. +Specifying a +.Sy recordsize +greater than or equal to the record size of the database can result in +significant performance gains. +Use of this property for general purpose file systems is strongly discouraged, +and may adversely affect performance. +.Pp +The size specified must be a power of two greater than or equal to 512 and less +than or equal to 128 Kbytes. +If the +.Sy large_blocks +feature is enabled on the pool, the size may be up to 1 Mbyte. +See +.Xr zpool-features 7 +for details on ZFS feature flags. +.Pp +Changing the file system's +.Sy recordsize +affects only files created afterward; existing files are unaffected. +.Pp +This property can also be referred to by its shortened column name, +.Sy recsize . +.It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most +Controls what types of metadata are stored redundantly. +ZFS stores an extra copy of metadata, so that if a single block is corrupted, +the amount of user data lost is limited. +This extra copy is in addition to any redundancy provided at the pool level +.Pq e.g. by mirroring or RAID-Z , +and is in addition to an extra copy specified by the +.Sy copies +property +.Pq up to a total of 3 copies . +For example if the pool is mirrored, +.Sy copies Ns = Ns 2 , +and +.Sy redundant_metadata Ns = Ns Sy most , +then ZFS stores 6 copies of most metadata, and 4 copies of data and some +metadata. +.Pp +When set to +.Sy all , +ZFS stores an extra copy of all metadata. +If a single on-disk block is corrupt, at worst a single block of user data +.Po which is +.Sy recordsize +bytes long +.Pc +can be lost. +.Pp +When set to +.Sy most , +ZFS stores an extra copy of most types of metadata. +This can improve performance of random writes, because less metadata must be +written. +In practice, at worst about 100 blocks +.Po of +.Sy recordsize +bytes each +.Pc +of user data can be lost if a single on-disk block is corrupt. +The exact behavior of which metadata blocks are stored redundantly may change in +future releases. +.Pp +The default value is +.Sy all . +.It Sy refquota Ns = Ns Em size Ns | Ns Sy none +Limits the amount of space a dataset can consume. +This property enforces a hard limit on the amount of space used. +This hard limit does not include space used by descendents, including file +systems and snapshots. +.It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto +The minimum amount of space guaranteed to a dataset, not including its +descendents. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by +.Sy refreservation . +The +.Sy refreservation +reservation is accounted for in the parent datasets' space used, and counts +against the parent datasets' quotas and reservations. +.Pp +If +.Sy refreservation +is set, a snapshot is only allowed if there is enough free pool space outside of +this reservation to accommodate the current number of +.Qq referenced +bytes in the dataset. +.Pp +If +.Sy refreservation +is set to +.Sy auto , +a volume is thick provisioned +.Po or +.Qq not sparse +.Pc . +.Sy refreservation Ns = Ns Sy auto +is only supported on volumes. +See +.Sy volsize +in the +.Sx Native Properties +section for more information about sparse volumes. +.Pp +This property can also be referred to by its shortened column name, +.Sy refreserv . +.It Sy reservation Ns = Ns Em size Ns | Ns Sy none +The minimum amount of space guaranteed to a dataset and its descendants. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by its reservation. +Reservations are accounted for in the parent datasets' space used, and count +against the parent datasets' quotas and reservations. +.Pp +This property can also be referred to by its shortened column name, +.Sy reserv . +.It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata +Controls what is cached in the secondary cache +.Pq L2ARC . +If this property is set to +.Sy all , +then both user data and metadata is cached. +If this property is set to +.Sy none , +then neither user data nor metadata is cached. +If this property is set to +.Sy metadata , +then only metadata is cached. +The default value is +.Sy all . +.It Sy setuid Ns = Ns Sy on Ns | Ns Sy off +Controls whether the setuid bit is respected for the file system. +The default value is +.Sy on . +.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts +Controls whether the file system is shared via SMB, and what options are to be +used. +A file system with the +.Sy sharesmb +property set to +.Sy off +is managed through traditional tools such as +.Xr sharemgr 8 . +Otherwise, the file system is automatically shared and unshared with the +.Nm zfs Cm share +and +.Nm zfs Cm unshare +commands. +If the property is set to +.Sy on , +the +.Xr sharemgr 8 +command is invoked with no options. +Otherwise, the +.Xr sharemgr 8 +command is invoked with options equivalent to the contents of this property. +.Pp +Because SMB shares requires a resource name, a unique resource name is +constructed from the dataset name. +The constructed name is a copy of the dataset name except that the characters in +the dataset name, which would be invalid in the resource name, are replaced with +underscore +.Pq Sy _ +characters. +A pseudo property +.Qq name +is also supported that allows you to replace the data set name with a specified +name. +The specified name is then used to replace the prefix dataset in the case of +inheritance. +For example, if the dataset +.Em data/home/john +is set to +.Sy name Ns = Ns Sy john , +then +.Em data/home/john +has a resource name of +.Sy john . +If a child dataset +.Em data/home/john/backups +is shared, it has a resource name of +.Sy john_backups . +.Pp +When SMB shares are created, the SMB share name appears as an entry in the +.Pa .zfs/shares +directory. +You can use the +.Nm ls +or +.Nm chmod +command to display the share-level ACLs on the entries in this directory. +.Pp +When the +.Sy sharesmb +property is changed for a dataset, the dataset and any children inheriting the +property are re-shared with the new options, only if the property was previously +set to +.Sy off , +or if they were shared before the property was changed. +If the new property is set to +.Sy off , +the file systems are unshared. +.It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts +Controls whether the file system is shared via NFS, and what options are to be +used. +A file system with a +.Sy sharenfs +property of +.Sy off +is managed through traditional tools such as +.Xr share 8 , +.Xr unshare 8 , +and +.Xr dfstab 5 . +Otherwise, the file system is automatically shared and unshared with the +.Nm zfs Cm share +and +.Nm zfs Cm unshare +commands. +If the property is set to +.Sy on , +.Xr share 8 +command is invoked with no options. +Otherwise, the +.Xr share 8 +command is invoked with options equivalent to the contents of this property. +.Pp +When the +.Sy sharenfs +property is changed for a dataset, the dataset and any children inheriting the +property are re-shared with the new options, only if the property was previously +.Sy off , +or if they were shared before the property was changed. +If the new property is +.Sy off , +the file systems are unshared. +.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput +Provide a hint to ZFS about handling of synchronous requests in this dataset. +If +.Sy logbias +is set to +.Sy latency +.Pq the default , +ZFS will use pool log devices +.Pq if configured +to handle the requests at low latency. +If +.Sy logbias +is set to +.Sy throughput , +ZFS will not use configured pool log devices. +ZFS will instead optimize synchronous operations for global pool throughput and +efficient use of resources. +.It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible +Controls whether the +.Pa .zfs +directory is hidden or visible in the root of the file system as discussed in +the +.Sx Snapshots +section. +The default value is +.Sy hidden . +.It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled +Controls the behavior of synchronous requests +.Pq e.g. fsync, O_DSYNC . +.Sy standard +is the +POSIX +specified behavior of ensuring all synchronous requests are written to stable +storage and all devices are flushed to ensure data is not cached by device +controllers +.Pq this is the default . +.Sy always +causes every file system transaction to be written and flushed before its +system call returns. +This has a large performance penalty. +.Sy disabled +disables synchronous requests. +File system transactions are only committed to stable storage periodically. +This option will give the highest performance. +However, it is very dangerous as ZFS would be ignoring the synchronous +transaction demands of applications such as databases or NFS. +Administrators should only use this option when the risks are understood. +.It Sy version Ns = Ns Em N Ns | Ns Sy current +The on-disk version of this file system, which is independent of the pool +version. +This property can only be set to later supported versions. +See the +.Nm zfs Cm upgrade +command. +.It Sy volsize Ns = Ns Em size +For volumes, specifies the logical size of the volume. +By default, creating a volume establishes a reservation of equal size. +For storage pools with a version number of 9 or higher, a +.Sy refreservation +is set instead. +Any changes to +.Sy volsize +are reflected in an equivalent change to the reservation +.Po or +.Sy refreservation +.Pc . +The +.Sy volsize +can only be set to a multiple of +.Sy volblocksize , +and cannot be zero. +.Pp +The reservation is kept equal to the volume's logical size to prevent unexpected +behavior for consumers. +Without the reservation, the volume could run out of space, resulting in +undefined behavior or data corruption, depending on how the volume is used. +These effects can also occur when the volume size is changed while it is in use +.Pq particularly when shrinking the size . +Extreme care should be used when adjusting the volume size. +.Pp +Though not recommended, a +.Qq sparse volume +.Po also known as +.Qq thin provisioned +.Pc +can be created by specifying the +.Fl s +option to the +.Nm zfs Cm create Fl V +command, or by changing the value of the +.Sy refreservation +property +.Po or +.Sy reservation +property on pool version 8 or earlier +.Pc +after the volume has been created. +A +.Qq sparse volume +is a volume where the value of +.Sy refreservation +is less than the size of the volume plus the space required to store its +metadata. +Consequently, writes to a sparse volume can fail with +.Er ENOSPC +when the pool is low on space. +For a sparse volume, changes to +.Sy volsize +are not reflected in the +.Sy refreservation . +A volume that is not sparse is said to be +.Qq thick provisioned . +A sparse volume can become thick provisioned by setting +.Sy refreservation +to +.Sy auto . +.It Sy vscan Ns = Ns Sy on Ns | Ns Sy off +Controls whether regular files should be scanned for viruses when a file is +opened and closed. +In addition to enabling this property, the virus scan service must also be +enabled for virus scanning to occur. +The default value is +.Sy off . +.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off +Controls whether extended attributes are enabled for this file system. +The default value is +.Sy on . +.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off +Controls whether the dataset is managed from a non-global zone. +See the +.Sx Zones +section for more information. +The default value is +.Sy off . +.El +.Pp +The following three properties cannot be changed after the file system is +created, and therefore, should be set when the file system is created. +If the properties are not set with the +.Nm zfs Cm create +or +.Nm zpool Cm create +commands, these properties are inherited from the parent dataset. +If the parent dataset lacks these properties due to having been created prior to +these features being supported, the new file system will have the default values +for these properties. +.Bl -tag -width "" +.It Xo +.Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns +.Sy insensitive Ns | Ns Sy mixed +.Xc +Indicates whether the file name matching algorithm used by the file system +should be case-sensitive, case-insensitive, or allow a combination of both +styles of matching. +The default value for the +.Sy casesensitivity +property is +.Sy sensitive . +Traditionally, +.Ux +and +POSIX +file systems have case-sensitive file names. +.Pp +The +.Sy mixed +value for the +.Sy casesensitivity +property indicates that the file system can support requests for both +case-sensitive and case-insensitive matching behavior. +Currently, case-insensitive matching behavior on a file system that supports +mixed behavior is limited to the SMB server product. +For more information about the +.Sy mixed +value behavior, see the "ZFS Administration Guide". +.It Xo +.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns +.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD +.Xc +Indicates whether the file system should perform a +.Sy unicode +normalization of file names whenever two file names are compared, and which +normalization algorithm should be used. +File names are always stored unmodified, names are normalized as part of any +comparison process. +If this property is set to a legal value other than +.Sy none , +and the +.Sy utf8only +property was left unspecified, the +.Sy utf8only +property is automatically set to +.Sy on . +The default value of the +.Sy normalization +property is +.Sy none . +This property cannot be changed after the file system is created. +.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off +Indicates whether the file system should reject file names that include +characters that are not present in the +.Sy UTF-8 +character code set. +If this property is explicitly set to +.Sy off , +the normalization property must either not be explicitly set or be set to +.Sy none . +The default value for the +.Sy utf8only +property is +.Sy off . +This property cannot be changed after the file system is created. +.El +.Pp +The +.Sy casesensitivity , +.Sy normalization , +and +.Sy utf8only +properties are also new permissions that can be assigned to non-privileged users +by using the ZFS delegated administration feature. +.Ss "Temporary Mount Point Properties" +When a file system is mounted, either through +.Xr mount 8 +for legacy mounts or the +.Nm zfs Cm mount +command for normal file systems, its mount options are set according to its +properties. +The correlation between properties and mount options is as follows: +.Bd -literal + PROPERTY MOUNT OPTION + devices devices/nodevices + exec exec/noexec + readonly ro/rw + setuid setuid/nosetuid + xattr xattr/noxattr +.Ed +.Pp +In addition, these options can be set on a per-mount basis using the +.Fl o +option, without affecting the property that is stored on disk. +The values specified on the command line override the values stored in the +dataset. +The +.Sy nosuid +option is an alias for +.Sy nodevices Ns \&, Ns Sy nosetuid . +These properties are reported as +.Qq temporary +by the +.Nm zfs Cm get +command. +If the properties are changed while the dataset is mounted, the new setting +overrides any temporary settings. +.Ss "User Properties" +In addition to the standard native properties, ZFS supports arbitrary user +properties. +User properties have no effect on ZFS behavior, but applications or +administrators can use them to annotate datasets +.Pq file systems, volumes, and snapshots . +.Pp +User property names must contain a colon +.Pq Qq Sy \&: +character to distinguish them from native properties. +They may contain lowercase letters, numbers, and the following punctuation +characters: colon +.Pq Qq Sy \&: , +dash +.Pq Qq Sy - , +period +.Pq Qq Sy \&. , +and underscore +.Pq Qq Sy _ . +The expected convention is that the property name is divided into two portions +such as +.Em module Ns \&: Ns Em property , +but this namespace is not enforced by ZFS. +User property names can be at most 256 characters, and cannot begin with a dash +.Pq Qq Sy - . +.Pp +When making programmatic use of user properties, it is strongly suggested to use +a reversed +.Sy DNS +domain name for the +.Em module +component of property names to reduce the chance that two +independently-developed packages use the same property name for different +purposes. +.Pp +The values of user properties are arbitrary strings, are always inherited, and +are never validated. +All of the commands that operate on properties +.Po Nm zfs Cm list , +.Nm zfs Cm get , +.Nm zfs Cm set , +and so forth +.Pc +can be used to manipulate both native properties and user properties. +Use the +.Nm zfs Cm inherit +command to clear a user property. +If the property is not defined in any parent dataset, it is removed entirely. +Property values are limited to 8192 bytes. +.Ss ZFS Volumes as Swap or Dump Devices +During an initial installation a swap device and dump device are created on ZFS +volumes in the ZFS root pool. +By default, the swap area size is based on 1/2 the size of physical memory up to +2 Gbytes. +The size of the dump device depends on the kernel's requirements at installation +time. +Separate ZFS volumes must be used for the swap area and dump devices. +Do not swap to a file on a ZFS file system. +A ZFS swap file configuration is not supported. +.Pp +If you need to change your swap area or dump device after the system is +installed or upgraded, use the +.Xr swap 8 +and +.Xr dumpadm 8 +commands. +.Ss "Encryption" +Enabling the +.Sy encryption +feature allows for the creation of encrypted filesystems and volumes. +ZFS will encrypt all user data including file and zvol data, file attributes, +ACLs, permission bits, directory listings, FUID mappings, and userused/groupused +data. +ZFS +will not encrypt metadata related to the pool structure, including dataset +names, dataset hierarchy, file size, file holes, and dedup tables. +Key rotation is managed internally by the ZFS kernel module and changing the +user's key does not require re-encrypting the entire dataset. +Datasets can be scrubbed, resilvered, renamed, and deleted without the +encryption keys being loaded +.Po see the +.Nm Cm load-key +subcommand for more info on key loading +.Pc . +.Pp +Creating an encrypted dataset requires specifying the +.Sy encryption +and +.Sy keyformat +properties at creation time, along with an optional +.Sy keylocation +and +.Sy pbkdf2iters . +After entering an encryption key, the created +dataset will become an encryption root. +Any descendant datasets will inherit their encryption key from the encryption +root by default, meaning that loading, unloading, or changing the key for the +encryption root will implicitly do the same for all inheriting datasets. +If this inheritance is not desired, simply supply a +.Sy keyformat +when creating the child dataset or use +.Nm Cm change-key +to break an existing relationship, creating a new encryption root on the child. +Note that the child's +.Sy keyformat +may match that of the parent while still creating a new encryption root, and +that changing the +.Sy encryption +property alone does not create a new encryption root; this would simply use a +different cipher suite with the same key as its encryption root. +The one exception is that clones will always use their origin's encryption key. +As a result of this exception, some encryption-related properties (namely +.Sy keystatus , +.Sy keyformat , +.Sy keylocation , +and +.Sy pbkdf2iters ) +do not inherit like other ZFS properties and instead use the value determined +by their encryption root. +Encryption root inheritance can be tracked via the read-only +.Sy encryptionroot +property. +.Pp +Encryption changes the behavior of a few ZFS operations. +Encryption is applied after compression so compression ratios are preserved. +Normally checksums in ZFS are 256 bits long, but for encrypted data the checksum +is 128 bits of the user-chosen checksum and 128 bits of MAC from the encryption +suite, which provides additional protection against maliciously altered data. +Deduplication is still possible with encryption enabled but for security, +datasets will only dedup against themselves, their snapshots, and their clones. +.Pp +There are a few limitations on encrypted datasets. +Encrypted data cannot be embedded via the +.Sy embedded_data +feature. +Encrypted datasets may not have +.Sy copies Ns = Ns Sy 3 +since the implementation stores some encryption metadata where the third copy +would normally be. +Since compression is applied before encryption datasets may be vulnerable to a +CRIME-like attack if applications accessing the data allow for it. +Deduplication with encryption will leak information about which blocks are +equivalent in a dataset and will incur an extra CPU cost per block written. +.Sh SUBCOMMANDS +All subcommands that modify state are logged persistently to the pool in their +original form. +.Bl -tag -width "" +.It Nm Fl \&? +Displays a help message. +.It Xo +.Nm +.Cm create +.Op Fl Pnpv +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Ar filesystem +.Xc +Creates a new ZFS file system. +The file system is automatically mounted according to the +.Sy mountpoint +property inherited from the parent. +.Bl -tag -width "-o" +.It Fl o Ar property Ns = Ns Ar value +Sets the specified property as if the command +.Nm zfs Cm set Ar property Ns = Ns Ar value +was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple +.Fl o +options can be specified. +An error results if the same property is specified in multiple +.Fl o +options. +.It Fl p +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the +.Sy mountpoint +property inherited from their parent. +Any property specified on the command line using the +.Fl o +option is ignored. +If the target filesystem already exists, the operation completes successfully. +.It Fl n +Do a dry-run +.Pq Qq No-op +creation. +No datasets will be created. +This is useful in conjunction with the +.Fl v +or +.Fl P +flags to validate properties that are passed via +.Fl o +options and those implied by other options. +The actual dataset creation can still fail due to insufficient privileges or +available capacity. +.It Fl P +Print machine-parsable verbose information about the created dataset. +Each line of output contains a key and one or two values, all separated by tabs. +The +.Sy create_ancestors +and +.Sy create +keys have +.Em filesystem +as their only value. +The +.Sy create_ancestors +key only appears if the +.Fl p +option is used. +The +.Sy property +key has two values, a property name and that property's value. +The +.Sy property +key may appear zero or more times, once for each property that will be set local +to +.Em filesystem +due to the use of the +.Fl o +option. +.It Fl v +Print verbose information about the created dataset. +.El +.It Xo +.Nm +.Cm create +.Op Fl ps +.Op Fl b Ar blocksize +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Fl V Ar size Ar volume +.Xc +Creates a volume of the given size. +The volume is exported as a block device in +.Pa /dev/zvol/{dsk,rdsk}/path , +where +.Em path +is the name of the volume in the ZFS namespace. +The size represents the logical size as exported by the device. +By default, a reservation of equal size is created. +.Pp +.Ar size +is automatically rounded up to the nearest 128 Kbytes to ensure that the volume +has an integral number of blocks regardless of +.Sy blocksize . +.Bl -tag -width "-b" +.It Fl b Ar blocksize +Equivalent to +.Fl o Sy volblocksize Ns = Ns Ar blocksize . +If this option is specified in conjunction with +.Fl o Sy volblocksize , +the resulting behavior is undefined. +.It Fl o Ar property Ns = Ns Ar value +Sets the specified property as if the +.Nm zfs Cm set Ar property Ns = Ns Ar value +command was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple +.Fl o +options can be specified. +An error results if the same property is specified in multiple +.Fl o +options. +.It Fl p +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the +.Sy mountpoint +property inherited from their parent. +Any property specified on the command line using the +.Fl o +option is ignored. +If the target filesystem already exists, the operation completes successfully. +.It Fl s +Creates a sparse volume with no reservation. +See +.Sy volsize +in the +.Sx Native Properties +section for more information about sparse volumes. +.It Fl n +Do a dry-run +.Pq Qq No-op +creation. +No datasets will be created. +This is useful in conjunction with the +.Fl v +or +.Fl P +flags to validate properties that are passed via +.Fl o +options and those implied by other options. +The actual dataset creation can still fail due to insufficient privileges or +available capacity. +.It Fl P +Print machine-parsable verbose information about the created dataset. +Each line of output contains a key and one or two values, all separated by tabs. +The +.Sy create_ancestors +and +.Sy create +keys have +.Em volume +as their only value. +The +.Sy create_ancestors +key only appears if the +.Fl p +option is used. +The +.Sy property +key has two values, a property name and that property's value. +The +.Sy property +key may appear zero or more times, once for each property that will be set local +to +.Em volume +due to the use of the +.Fl b +or +.Fl o +options, as well as +.Sy refreservation +if the volume is not sparse. +.It Fl v +Print verbose information about the created dataset. +.El +.It Xo +.Nm +.Cm destroy +.Op Fl Rfnprv +.Ar filesystem Ns | Ns Ar volume +.Xc +Destroys the given dataset. +By default, the command unshares any file systems that are currently shared, +unmounts any file systems that are currently mounted, and refuses to destroy a +dataset that has active dependents +.Pq children or clones . +.Bl -tag -width "-R" +.It Fl R +Recursively destroy all dependents, including cloned file systems outside the +target hierarchy. +.It Fl f +Force an unmount of any file systems using the +.Nm unmount Fl f +command. +This option has no effect on non-file systems or unmounted file systems. +.It Fl n +Do a dry-run +.Pq Qq No-op +deletion. +No data will be deleted. +This is useful in conjunction with the +.Fl v +or +.Fl p +flags to determine what data would be deleted. +.It Fl p +Print machine-parsable verbose information about the deleted data. +.It Fl r +Recursively destroy all children. +.It Fl v +Print verbose information about the deleted data. +.El +.Pp +Extreme care should be taken when applying either the +.Fl r +or the +.Fl R +options, as they can destroy large portions of a pool and cause unexpected +behavior for mounted file systems in use. +.It Xo +.Nm +.Cm destroy +.Op Fl Rdnprv +.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns +.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... +.Xc +The given snapshots are destroyed immediately if and only if the +.Nm zfs Cm destroy +command without the +.Fl d +option would have destroyed it. +Such immediate destruction would occur, for example, if the snapshot had no +clones and the user-initiated reference count were zero. +.Pp +If a snapshot does not qualify for immediate destruction, it is marked for +deferred deletion. +In this state, it exists as a usable, visible snapshot until both of the +preconditions listed above are met, at which point it is destroyed. +.Pp +An inclusive range of snapshots may be specified by separating the first and +last snapshots with a percent sign. +The first and/or last snapshots may be left blank, in which case the +filesystem's oldest or newest snapshot will be implied. +.Pp +Multiple snapshots +.Pq or ranges of snapshots +of the same filesystem or volume may be specified in a comma-separated list of +snapshots. +Only the snapshot's short name +.Po the part after the +.Sy @ +.Pc +should be specified when using a range or comma-separated list to identify +multiple snapshots. +.Bl -tag -width "-R" +.It Fl R +Recursively destroy all clones of these snapshots, including the clones, +snapshots, and children. +If this flag is specified, the +.Fl d +flag will have no effect. +.It Fl d +Defer snapshot deletion. +.It Fl n +Do a dry-run +.Pq Qq No-op +deletion. +No data will be deleted. +This is useful in conjunction with the +.Fl p +or +.Fl v +flags to determine what data would be deleted. +.It Fl p +Print machine-parsable verbose information about the deleted data. +.It Fl r +Destroy +.Pq or mark for deferred deletion +all snapshots with this name in descendent file systems. +.It Fl v +Print verbose information about the deleted data. +.Pp +Extreme care should be taken when applying either the +.Fl r +or the +.Fl R +options, as they can destroy large portions of a pool and cause unexpected +behavior for mounted file systems in use. +.El +.It Xo +.Nm +.Cm destroy +.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark +.Xc +The given bookmark is destroyed. +.It Xo +.Nm +.Cm snapshot +.Op Fl r +.Oo Fl o Ar property Ns = Ns value Oc Ns ... +.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... +.Xc +Creates snapshots with the given names. +All previous modifications by successful system calls to the file system are +part of the snapshots. +Snapshots are taken atomically, so that all snapshots correspond to the same +moment in time. +See the +.Sx Snapshots +section for details. +.Bl -tag -width "-o" +.It Fl o Ar property Ns = Ns Ar value +Sets the specified property; see +.Nm zfs Cm create +for details. +.It Fl r +Recursively create snapshots of all descendent datasets +.El +.It Xo +.Nm +.Cm rollback +.Op Fl Rfr +.Ar snapshot +.Xc +Roll back the given dataset to a previous snapshot. +When a dataset is rolled back, all data that has changed since the snapshot is +discarded, and the dataset reverts to the state at the time of the snapshot. +By default, the command refuses to roll back to a snapshot other than the most +recent one. +In order to do so, all intermediate snapshots and bookmarks must be destroyed by +specifying the +.Fl r +option. +.Pp +The +.Fl rR +options do not recursively destroy the child snapshots of a recursive snapshot. +Only direct snapshots of the specified filesystem are destroyed by either of +these options. +To completely roll back a recursive snapshot, you must rollback the individual +child snapshots. +.Bl -tag -width "-R" +.It Fl R +Destroy any more recent snapshots and bookmarks, as well as any clones of those +snapshots. +.It Fl f +Used with the +.Fl R +option to force an unmount of any clone file systems that are to be destroyed. +.It Fl r +Destroy any snapshots and bookmarks more recent than the one specified. +.El +.It Xo +.Nm +.Cm clone +.Op Fl p +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Ar snapshot Ar filesystem Ns | Ns Ar volume +.Xc +Creates a clone of the given snapshot. +See the +.Sx Clones +section for details. +The target dataset can be located anywhere in the ZFS hierarchy, and is created +as the same type as the original. +.Bl -tag -width "-o" +.It Fl o Ar property Ns = Ns Ar value +Sets the specified property; see +.Nm zfs Cm create +for details. +.It Fl p +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the +.Sy mountpoint +property inherited from their parent. +If the target filesystem or volume already exists, the operation completes +successfully. +.El +.It Xo +.Nm +.Cm promote +.Ar clone-filesystem +.Xc +Promotes a clone file system to no longer be dependent on its +.Qq origin +snapshot. +This makes it possible to destroy the file system that the clone was created +from. +The clone parent-child dependency relationship is reversed, so that the origin +file system becomes a clone of the specified file system. +.Pp +The snapshot that was cloned, and any snapshots previous to this snapshot, are +now owned by the promoted clone. +The space they use moves from the origin file system to the promoted clone, so +enough space must be available to accommodate these snapshots. +No new space is consumed by this operation, but the space accounting is +adjusted. +The promoted clone must not have any conflicting snapshot names of its own. +The +.Cm rename +subcommand can be used to rename any conflicting snapshots. +.It Xo +.Nm +.Cm rename +.Op Fl f +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Xc +.It Xo +.Nm +.Cm rename +.Op Fl fp +.Ar filesystem Ns | Ns Ar volume +.Ar filesystem Ns | Ns Ar volume +.Xc +Renames the given dataset. +The new target can be located anywhere in the ZFS hierarchy, with the exception +of snapshots. +Snapshots can only be renamed within the parent file system or volume. +When renaming a snapshot, the parent file system of the snapshot does not need +to be specified as part of the second argument. +Renamed file systems can inherit new mount points, in which case they are +unmounted and remounted at the new mount point. +.Bl -tag -width "-a" +.It Fl f +Force unmount any filesystems that need to be unmounted in the process. +.It Fl p +Creates all the nonexistent parent datasets. +Datasets created in this manner are automatically mounted according to the +.Sy mountpoint +property inherited from their parent. +.El +.It Xo +.Nm +.Cm rename +.Fl r +.Ar snapshot Ar snapshot +.Xc +Recursively rename the snapshots of all descendent datasets. +Snapshots are the only dataset that can be renamed recursively. +.It Xo +.Nm +.Cm list +.Op Fl r Ns | Ns Fl d Ar depth +.Op Fl Hp +.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc +.Oo Fl s Ar property Oc Ns ... +.Oo Fl S Ar property Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... +.Xc +Lists the property information for the given datasets in tabular form. +If specified, you can list property information by the absolute pathname or the +relative pathname. +By default, all file systems and volumes are displayed. +Snapshots are displayed if the +.Sy listsnaps +property is +.Sy on +.Po the default is +.Sy off +.Pc . +The following fields are displayed, +.Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns +.Sy mountpoint . +.Bl -tag -width "-H" +.It Fl H +Used for scripting mode. +Do not print headers and separate fields by a single tab instead of arbitrary +white space. +.It Fl S Ar property +Same as the +.Fl s +option, but sorts by property in descending order. +.It Fl d Ar depth +Recursively display any children of the dataset, limiting the recursion to +.Ar depth . +A +.Ar depth +of +.Sy 1 +will display only the dataset and its direct children. +.It Fl o Ar property +A comma-separated list of properties to display. +The property must be: +.Bl -bullet +.It +One of the properties described in the +.Sx Native Properties +section +.It +A user property +.It +The value +.Sy name +to display the dataset name +.It +The value +.Sy space +to display space usage properties on file systems and volumes. +This is a shortcut for specifying +.Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns +.Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t +.Sy filesystem Ns \&, Ns Sy volume +syntax. +.El +.It Fl p +Display numbers in parsable +.Pq exact +values. +.It Fl r +Recursively display any children of the dataset on the command line. +.It Fl s Ar property +A property for sorting the output by column in ascending order based on the +value of the property. +The property must be one of the properties described in the +.Sx Properties +section, or the special value +.Sy name +to sort by the dataset name. +Multiple properties can be specified at one time using multiple +.Fl s +property options. +Multiple +.Fl s +options are evaluated from left to right in decreasing order of importance. +The following is a list of sorting criteria: +.Bl -bullet +.It +Numeric types sort in numeric order. +.It +String types sort in alphabetical order. +.It +Types inappropriate for a row sort that row to the literal bottom, regardless of +the specified ordering. +.El +.Pp +If no sorting options are specified the existing behavior of +.Nm zfs Cm list +is preserved. +.It Fl t Ar type +A comma-separated list of types to display, where +.Ar type +is one of +.Sy filesystem , +.Sy snapshot , +.Sy volume , +.Sy bookmark , +or +.Sy all . +For example, specifying +.Fl t Sy snapshot +displays only snapshots. +.El +.It Xo +.Nm +.Cm set +.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Xc +Sets the property or list of properties to the given value(s) for each dataset. +Only some properties can be edited. +See the +.Sx Properties +section for more information on what properties can be set and acceptable +values. +Numeric values can be specified as exact values, or in a human-readable form +with a suffix of +.Sy B , K , M , G , T , P , E , Z +.Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, +or zettabytes, respectively +.Pc . +User properties can be set on snapshots. +For more information, see the +.Sx User Properties +section. +.It Xo +.Nm +.Cm get +.Op Fl r Ns | Ns Fl d Ar depth +.Op Fl Hp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... +.Xc +Displays properties for the given datasets. +If no datasets are specified, then the command displays properties for all +datasets on the system. +For each property, the following columns are displayed: +.Bd -literal + name Dataset name + property Property name + value Property value + source Property source. Can either be local, default, + temporary, inherited, or none (-). +.Ed +.Pp +All columns are displayed by default, though this can be controlled by using the +.Fl o +option. +This command takes a comma-separated list of properties as described in the +.Sx Native Properties +and +.Sx User Properties +sections. +.Pp +The special value +.Sy all +can be used to display all properties that apply to the given dataset's type +.Pq filesystem, volume, snapshot, or bookmark . +.Bl -tag -width "-H" +.It Fl H +Display output in a form more easily parsed by scripts. +Any headers are omitted, and fields are explicitly separated by a single tab +instead of an arbitrary amount of space. +.It Fl d Ar depth +Recursively display any children of the dataset, limiting the recursion to +.Ar depth . +A depth of +.Sy 1 +will display only the dataset and its direct children. +.It Fl o Ar field +A comma-separated list of columns to display. +.Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source +is the default value. +.It Fl p +Display numbers in parsable +.Pq exact +values. +.It Fl r +Recursively display properties for any children. +.It Fl s Ar source +A comma-separated list of sources to display. +Those properties coming from a source other than those in this list are ignored. +Each source must be one of the following: +.Sy local , +.Sy default , +.Sy inherited , +.Sy temporary , +and +.Sy none . +The default value is all sources. +.It Fl t Ar type +A comma-separated list of types to display, where +.Ar type +is one of +.Sy filesystem , +.Sy snapshot , +.Sy volume , +.Sy bookmark , +or +.Sy all . +.El +.It Xo +.Nm +.Cm inherit +.Op Fl rS +.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Xc +Clears the specified property, causing it to be inherited from an ancestor, +restored to default if no ancestor has the property set, or with the +.Fl S +option reverted to the received value if one exists. +See the +.Sx Properties +section for a listing of default values, and details on which properties can be +inherited. +.Bl -tag -width "-r" +.It Fl r +Recursively inherit the given property for all children. +.It Fl S +Revert the property to the received value if one exists; otherwise operate as +if the +.Fl S +option was not specified. +.El +.It Xo +.Nm +.Cm remap +.Ar filesystem Ns | Ns Ar volume +.Xc +Remap the indirect blocks in the given filesystem or volume so that they no +longer reference blocks on previously removed vdevs and we can eventually +shrink the size of the indirect mapping objects for the previously removed +vdevs. Note that remapping all blocks might not be possible and that +references from snapshots will still exist and cannot be remapped. +.It Xo +.Nm +.Cm upgrade +.Xc +Displays a list of file systems that are not the most recent version. +.It Xo +.Nm +.Cm upgrade +.Fl v +.Xc +Displays a list of currently supported file system versions. +.It Xo +.Nm +.Cm upgrade +.Op Fl r +.Op Fl V Ar version +.Fl a | Ar filesystem +.Xc +Upgrades file systems to a new on-disk version. +Once this is done, the file systems will no longer be accessible on systems +running older versions of the software. +.Nm zfs Cm send +streams generated from new snapshots of these file systems cannot be accessed on +systems running older versions of the software. +.Pp +In general, the file system version is independent of the pool version. +See +.Xr zpool 8 +for information on the +.Nm zpool Cm upgrade +command. +.Pp +In some cases, the file system version and the pool version are interrelated and +the pool version must be upgraded before the file system version can be +upgraded. +.Bl -tag -width "-V" +.It Fl V Ar version +Upgrade to the specified +.Ar version . +If the +.Fl V +flag is not specified, this command upgrades to the most recent version. +This +option can only be used to increase the version number, and only up to the most +recent version supported by this software. +.It Fl a +Upgrade all file systems on all imported pools. +.It Ar filesystem +Upgrade the specified file system. +.It Fl r +Upgrade the specified file system and all descendent file systems. +.El +.It Xo +.Nm +.Cm userspace +.Op Fl Hinp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar snapshot +.Xc +Displays space consumed by, and quotas on, each user in the specified filesystem +or snapshot. +This corresponds to the +.Sy userused@ Ns Em user , +.Sy userobjused@ Ns Em user , +.Sy userquota@ Ns Em user, +and +.Sy userobjquota@ Ns Em user +properties. +.Bl -tag -width "-H" +.It Fl H +Do not print headers, use tab-delimited output. +.It Fl S Ar field +Sort by this field in reverse order. +See +.Fl s . +.It Fl i +Translate SID to POSIX ID. +The POSIX ID may be ephemeral if no mapping exists. +Normal POSIX interfaces +.Po for example, +.Xr stat 2 , +.Nm ls Fl l +.Pc +perform this translation, so the +.Fl i +option allows the output from +.Nm zfs Cm userspace +to be compared directly with those utilities. +However, +.Fl i +may lead to confusion if some files were created by an SMB user before a +SMB-to-POSIX name mapping was established. +In such a case, some files will be owned by the SMB entity and some by the POSIX +entity. +However, the +.Fl i +option will report that the POSIX entity has the total usage and quota for both. +.It Fl n +Print numeric ID instead of user/group name. +.It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... +Display only the specified fields from the following set: +.Sy type , +.Sy name , +.Sy used , +.Sy quota . +The default is to display all fields. +.It Fl p +Use exact +.Pq parsable +numeric output. +.It Fl s Ar field +Sort output by this field. +The +.Fl s +and +.Fl S +flags may be specified multiple times to sort first by one field, then by +another. +The default is +.Fl s Sy type Fl s Sy name . +.It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... +Print only the specified types from the following set: +.Sy all , +.Sy posixuser , +.Sy smbuser , +.Sy posixgroup , +.Sy smbgroup . +The default is +.Fl t Sy posixuser Ns \&, Ns Sy smbuser . +The default can be changed to include group types. +.El +.It Xo +.Nm +.Cm groupspace +.Op Fl Hinp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar snapshot +.Xc +Displays space consumed by, and quotas on, each group in the specified +filesystem or snapshot. +This subcommand is identical to +.Nm zfs Cm userspace , +except that the default types to display are +.Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . +.It Xo +.Nm +.Cm projectspace +.Op Fl Hp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Ar filesystem Ns | Ns Ar snapshot +.Xc +Displays space consumed by, and quotas on, each project in the specified +filesystem or snapshot. +This subcommand is identical to +.Nm zfs Cm userspace , +except that the project identifier is numeral, not name. +So need neither the option +.Sy -i +for SID to POSIX ID nor +.Sy -n +for numeric ID, nor +.Sy -t +for types. +.It Xo +.Nm +.Cm project +.Oo Fl d Ns | Ns Fl r Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +List project identifier (ID) and inherit flag of files or directories. +.Bl -tag -width "-d" +.It Fl d +Show the directory project ID and inherit flag, not its children. +It will overwrite the former specified +.Fl r +option. +.It Fl r +Show on subdirectories recursively. +It will overwrite the former specified +.Fl d +option. +.El +.It Xo +.Nm +.Cm project +.Fl C +.Oo Fl kr Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +Clear project inherit flag and/or ID on the files or directories. +.Bl -tag -width "-k" +.It Fl k +Keep the project ID unchanged. +If not specified, the project ID will be reset as zero. +.It Fl r +Clear on subdirectories recursively. +.El +.It Xo +.Nm +.Cm project +.Fl c +.Oo Fl 0 Ns Oc +.Oo Fl d Ns | Ns Fl r Ns Oc +.Op Fl p Ar id +.Ar file Ns | Ns Ar directory Ns ... +.Xc +Check project ID and inherit flag on the files or directories, report the +entries without project inherit flag or with different project IDs from the +specified (via +.Fl p +option) value or the target directory's project ID. +.Bl -tag -width "-0" +.It Fl 0 +Print file name with a trailing NUL instead of newline (by default), like +"find -print0". +.It Fl d +Check the directory project ID and inherit flag, not its children. +It will overwrite the former specified +.Fl r +option. +.It Fl p +Specify the referenced ID for comparing with the target files or directories' +project IDs. +If not specified, the target (top) directory's project ID will be used as the +referenced one. +.It Fl r +Check on subdirectories recursively. +It will overwrite the former specified +.Fl d +option. +.El +.It Xo +.Nm +.Cm project +.Op Fl p Ar id +.Oo Fl rs Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +Set project ID and/or inherit flag on the files or directories. +.Bl -tag -width "-p" +.It Fl p +Set the files' or directories' project ID with the given value. +.It Fl r +Set on subdirectories recursively. +.It Fl s +Set project inherit flag on the given files or directories. +It is usually used for setup tree quota on the directory target with +.Fl r +option specified together. +When setup tree quota, by default the directory's project ID will be set to +all its descendants unless you specify the project ID via +.Fl p +option explicitly. +.El +.It Xo +.Nm +.Cm mount +.Xc +Displays all ZFS file systems currently mounted. +.It Xo +.Nm +.Cm mount +.Op Fl Olv +.Op Fl o Ar options +.Fl a | Ar filesystem +.Xc +Mounts ZFS file systems. +.Bl -tag -width "-O" +.It Fl O +Perform an overlay mount. +See +.Xr mount 8 +for more information. +.It Fl a +Mount all available ZFS file systems. +Invoked automatically as part of the boot process. +.It Fl l +Load keys for encrypted filesystems as they are being mounted. +This is equivalent to executing +.Nm Cm load-key +on each encryption root before mounting it. +Note that if a filesystem has a +.Sy keylocation +of +.Sy prompt +this will cause the terminal to interactively block after asking for the key. +.It Ar filesystem +Mount the specified filesystem. +.It Fl o Ar options +An optional, comma-separated list of mount options to use temporarily for the +duration of the mount. +See the +.Sx Temporary Mount Point Properties +section for details. +.It Fl v +Report mount progress. +.El +.It Xo +.Nm +.Cm unmount +.Op Fl f +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Xc +Unmounts currently mounted ZFS file systems. +.Bl -tag -width "-a" +.It Fl a +Unmount all available ZFS file systems. +Invoked automatically as part of the shutdown process. +.It Ar filesystem Ns | Ns Ar mountpoint +Unmount the specified filesystem. +The command can also be given a path to a ZFS file system mount point on the +system. +.It Fl f +Forcefully unmount the file system, even if it is currently in use. +.El +.It Xo +.Nm +.Cm share +.Fl a | Ar filesystem +.Xc +Shares available ZFS file systems. +.Bl -tag -width "-a" +.It Fl a +Share all available ZFS file systems. +Invoked automatically as part of the boot process. +.It Ar filesystem +Share the specified filesystem according to the +.Sy sharenfs +and +.Sy sharesmb +properties. +File systems are shared when the +.Sy sharenfs +or +.Sy sharesmb +property is set. +.El +.It Xo +.Nm +.Cm unshare +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Xc +Unshares currently shared ZFS file systems. +.Bl -tag -width "-a" +.It Fl a +Unshare all available ZFS file systems. +Invoked automatically as part of the shutdown process. +.It Ar filesystem Ns | Ns Ar mountpoint +Unshare the specified filesystem. +The command can also be given a path to a ZFS file system shared on the system. +.El +.It Xo +.Nm +.Cm bookmark +.Ar snapshot bookmark +.Xc +Creates a bookmark of the given snapshot. +Bookmarks mark the point in time when the snapshot was created, and can be used +as the incremental source for a +.Nm zfs Cm send +command. +.Pp +This feature must be enabled to be used. +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy bookmarks +feature. +.It Xo +.Nm +.Cm send +.Op Fl DLPRbcehnpvw +.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot +.Ar snapshot +.Xc +Creates a stream representation of the second +.Ar snapshot , +which is written to standard output. +The output can be redirected to a file or to a different system +.Po for example, using +.Xr ssh 1 +.Pc . +By default, a full stream is generated. +.Bl -tag -width "-D" +.It Fl D , -dedup +Generate a deduplicated stream. +Blocks which would have been sent multiple times in the send stream will only be +sent once. +The receiving system must also support this feature to receive a deduplicated +stream. +This flag can be used regardless of the dataset's +.Sy dedup +property, but performance will be much better if the filesystem uses a +dedup-capable checksum +.Po for example, +.Sy sha256 +.Pc . +.It Fl I Ar snapshot +Generate a stream package that sends all intermediary snapshots from the first +snapshot to the second snapshot. +For example, +.Fl I Em @a Em fs@d +is similar to +.Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . +The incremental source may be specified as with the +.Fl i +option. +.It Fl L , -large-block +Generate a stream which may contain blocks larger than 128KB. +This flag has no effect if the +.Sy large_blocks +pool feature is disabled, or if the +.Sy recordsize +property of this filesystem has never been set above 128KB. +The receiving system must have the +.Sy large_blocks +pool feature enabled as well. +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy large_blocks +feature. +.It Fl P , -parsable +Print machine-parsable verbose information about the stream package generated. +.It Fl R , -replicate +Generate a replication stream package, which will replicate the specified +file system, and all descendent file systems, up to the named snapshot. +When received, all properties, snapshots, descendent file systems, and clones +are preserved. +.Pp +If the +.Fl i +or +.Fl I +flags are used in conjunction with the +.Fl R +flag, an incremental replication stream is generated. +The current values of properties, and current snapshot and file system names are +set when the stream is received. +If the +.Fl F +flag is specified when this stream is received, snapshots and file systems that +do not exist on the sending side are destroyed. +If the +.Fl R +flag is used to send encrypted datasets, then +.Fl w +must also be specified. +.It Fl e , -embed +Generate a more compact stream by using +.Sy WRITE_EMBEDDED +records for blocks which are stored more compactly on disk by the +.Sy embedded_data +pool feature. +This flag has no effect if the +.Sy embedded_data +feature is disabled. +The receiving system must have the +.Sy embedded_data +feature enabled. +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +Datasets that are sent with this flag may not be received as an encrypted +dataset, since encrypted datasets cannot use the +.Sy embedded_data +feature. +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy embedded_data +feature. +.It Fl b, -backup +Sends only received property values whether or not they are overridden by local +settings, but only if the dataset has ever been received. +Use this option when you want +.Nm zfs Cm receive +to restore received properties backed up on the sent dataset and to avoid +sending local settings that may have nothing to do with the source dataset, +but only with how the data is backed up. +.It Fl c , -compressed +Generate a more compact stream by using compressed WRITE records for blocks +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L +option is not supplied in conjunction with +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. +.It Fl h, -holds +Generate a stream package that includes any snapshot holds (created with the +.Sy zfs hold +command), and indicating to +.Sy zfs receive +that the holds be applied to the dataset on the receiving system. +.It Fl i Ar snapshot +Generate an incremental stream from the first +.Ar snapshot +.Pq the incremental source +to the second +.Ar snapshot +.Pq the incremental target . +The incremental source can be specified as the last component of the snapshot +name +.Po the +.Sy @ +character and following +.Pc +and it is assumed to be from the same file system as the incremental target. +.Pp +If the destination is a clone, the source may be the origin snapshot, which must +be fully specified +.Po for example, +.Em pool/fs@origin , +not just +.Em @origin +.Pc . +.It Fl n , -dryrun +Do a dry-run +.Pq Qq No-op +send. +Do not generate any actual send data. +This is useful in conjunction with the +.Fl v +or +.Fl P +flags to determine what data will be sent. +In this case, the verbose output will be written to standard output +.Po contrast with a non-dry-run, where the stream is written to standard output +and the verbose output goes to standard error +.Pc . +.It Fl p , -props +Include the dataset's properties in the stream. +This flag is implicit when +.Fl R +is specified. +The receiving system must also support this feature. +Sends of encrypted datasets must use +.Fl w +when using this flag. +.It Fl w , -raw +For encrypted datasets, send data exactly as it exists on disk. +This allows backups to be taken even if encryption keys are not currently +loaded. +The backup may then be received on an untrusted machine since that machine will +not have the encryption keys to read the protected data or alter it without +being detected. +Upon being received, the dataset will have the same encryption keys as it did +on the send side, although the +.Sy keylocation +property will be defaulted to +.Sy prompt +if not otherwise provided. +For unencrypted datasets, this flag will be equivalent to +.Fl Lec . +Note that if you do not use this flag for sending encrypted datasets, +data will be sent unencrypted and may be re-encrypted with a different +encryption key on the receiving system, which will disable the ability +to do a raw send to that system for incrementals. +.It Fl v , -verbose +Print verbose information about the stream package generated. +This information includes a per-second report of how much data has been sent. +.Pp +The format of the stream is committed. +You will be able to receive your streams on future versions of ZFS . +.El +.It Xo +.Nm +.Cm send +.Op Fl Lcew +.Op Fl i Ar snapshot Ns | Ns Ar bookmark +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Xc +Generate a send stream, which may be of a filesystem, and may be incremental +from a bookmark. +If the destination is a filesystem or volume, the pool must be read-only, or the +filesystem must not be mounted. +When the stream generated from a filesystem or volume is received, the default +snapshot name will be +.Qq --head-- . +.Bl -tag -width "-L" +.It Fl L , -large-block +Generate a stream which may contain blocks larger than 128KB. +This flag has no effect if the +.Sy large_blocks +pool feature is disabled, or if the +.Sy recordsize +property of this filesystem has never been set above 128KB. +The receiving system must have the +.Sy large_blocks +pool feature enabled as well. +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy large_blocks +feature. +.It Fl c , -compressed +Generate a more compact stream by using compressed WRITE records for blocks +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L +option is not supplied in conjunction with +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. +.It Fl e , -embed +Generate a more compact stream by using +.Sy WRITE_EMBEDDED +records for blocks which are stored more compactly on disk by the +.Sy embedded_data +pool feature. +This flag has no effect if the +.Sy embedded_data +feature is disabled. +The receiving system must have the +.Sy embedded_data +feature enabled. +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +Datasets that are sent with this flag may not be received as an encrypted +dataset, since encrypted datasets cannot use the +.Sy embedded_data +feature. +See +.Xr zpool-features 7 +for details on ZFS feature flags and the +.Sy embedded_data +feature. +.It Fl i Ar snapshot Ns | Ns Ar bookmark +Generate an incremental send stream. +The incremental source must be an earlier snapshot in the destination's history. +It will commonly be an earlier snapshot in the destination's file system, in +which case it can be specified as the last component of the name +.Po the +.Sy # +or +.Sy @ +character and following +.Pc . +.Pp +If the incremental target is a clone, the incremental source can be the origin +snapshot, or an earlier snapshot in the origin's filesystem, or the origin's +origin, etc. +.It Fl w , -raw +For encrypted datasets, send data exactly as it exists on disk. +This allows backups to be taken even if encryption keys are not currently +loaded. +The backup may then be received on an untrusted machine since that machine will +not have the encryption keys to read the protected data or alter it without +being detected. +Upon being received, the dataset will have the same encryption keys as it did +on the send side, although the +.Sy keylocation +property will be defaulted to +.Sy prompt +if not otherwise provided. +For unencrypted datasets, this flag will be equivalent to +.Fl Lec . +Note that if you do not use this flag for sending encrypted datasets, +data will be sent unencrypted and may be re-encrypted with a different +encryption key on the receiving system, which will disable the ability +to do a raw send to that system for incrementals. +.El +.It Xo +.Nm +.Cm send +.Op Fl Penv +.Fl t +.Ar receive_resume_token +.Xc +Creates a send stream which resumes an interrupted receive. +The +.Ar receive_resume_token +is the value of this property on the filesystem or volume that was being +received into. +See the documentation for +.Sy zfs receive -s +for more details. +.It Xo +.Nm +.Cm receive +.Op Fl Fhnsuv +.Op Fl o Sy origin Ns = Ns Ar snapshot +.Op Fl o Ar property Ns = Ns Ar value +.Op Fl x Ar property +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Xc +.It Xo +.Nm +.Cm receive +.Op Fl Fhnsuv +.Op Fl d Ns | Ns Fl e +.Op Fl o Sy origin Ns = Ns Ar snapshot +.Op Fl o Ar property Ns = Ns Ar value +.Op Fl x Ar property +.Ar filesystem +.Xc +Creates a snapshot whose contents are as specified in the stream provided on +standard input. +If a full stream is received, then a new file system is created as well. +Streams are created using the +.Nm zfs Cm send +subcommand, which by default creates a full stream. +.Nm zfs Cm recv +can be used as an alias for +.Nm zfs Cm receive . +.Pp +If an incremental stream is received, then the destination file system must +already exist, and its most recent snapshot must match the incremental stream's +source. +For +.Sy zvols , +the destination device link is destroyed and recreated, which means the +.Sy zvol +cannot be accessed during the +.Cm receive +operation. +.Pp +When a snapshot replication package stream that is generated by using the +.Nm zfs Cm send Fl R +command is received, any snapshots that do not exist on the sending location are +destroyed by using the +.Nm zfs Cm destroy Fl d +command. +.Pp +If +.Fl o Em property Ns = Ns Ar value +or +.Fl x Em property +is specified, it applies to the effective value of the property throughout +the entire subtree of replicated datasets. +Effective property values will be +set ( +.Fl o +) or inherited ( +.Fl x +) on the topmost in the replicated subtree. +In descendant datasets, if the property is set by the send stream, it will be +overridden by forcing the property to be inherited from the top‐most file +system. +Received properties are retained in spite of being overridden and may be +restored with +.Nm zfs Cm inherit Fl S . +Specifying +.Fl o Sy origin Ns = Ns Em snapshot +is a special case because, even if +.Sy origin +is a read-only property and cannot be set, it's allowed to receive the send +stream as a clone of the given snapshot. +.Pp +Raw encrypted send streams (created with +.Nm zfs Cm send Fl w +) may only be received as is, and cannot be re-encrypted, decrypted, or +recompressed by the receive process. +Unencrypted streams can be received as encrypted datasets, either through +inheritance or by specifying encryption parameters with the +.Fl o +options. +Note that the +.Sy keylocation +property cannot be overridden to +.Sy prompt +during a receive. +This is because the receive process itself is already using +stdin for the send stream. +Instead, the property can be overridden after the receive completes. +.Pp +The added security provided by raw sends adds some restrictions to the send +and receive process. +ZFS will not allow a mix of raw receives and non-raw receives. +Specifically, any raw incremental receives that are attempted after +a non-raw receive will fail. +Non-raw receives do not have this restriction and, therefore, are always +possible. +Because of this, it is best practice to always use either raw sends for +their security benefits or non-raw sends for their flexibility when working +with encrypted datasets, but not a combination. +.Pp +The reason for this restriction stems from the inherent restrictions of the +AEAD ciphers that ZFS uses to encrypt data. +When using ZFS native encryption, each block of data is encrypted against +a randomly generated number known as the "initialization vector" (IV), +which is stored in the filesystem metadata. +This number is required by the encryption algorithms whenever the data is to +be decrypted. +Together, all of the IVs provided for all of the blocks in a given snapshot +are collectively called an "IV set". +When ZFS performs a raw send, the IV set is transferred from the source to +the destination in the send stream. +When ZFS performs a non-raw send, the data is decrypted by the source +system and re-encrypted by the destination system, creating a snapshot with +effectively the same data, but a different IV set. +In order for decryption to work after a raw send, ZFS must ensure that the +IV set used on both the source and destination side match. +When an incremental raw receive is performed on top of an existing snapshot, +ZFS will check to confirm that the "from" snapshot on both the source and +destination were using the same IV set, ensuring the new IV set is consistent. +.Pp +The name of the snapshot +.Pq and file system, if a full stream is received +that this subcommand creates depends on the argument type and the use of the +.Fl d +or +.Fl e +options. +.Pp +If the argument is a snapshot name, the specified +.Ar snapshot +is created. +If the argument is a file system or volume name, a snapshot with the same name +as the sent snapshot is created within the specified +.Ar filesystem +or +.Ar volume . +If neither of the +.Fl d +or +.Fl e +options are specified, the provided target snapshot name is used exactly as +provided. +.Pp +The +.Fl d +and +.Fl e +options cause the file system name of the target snapshot to be determined by +appending a portion of the sent snapshot's name to the specified target +.Ar filesystem . +If the +.Fl d +option is specified, all but the first element of the sent snapshot's file +system path +.Pq usually the pool name +is used and any required intermediate file systems within the specified one are +created. +If the +.Fl e +option is specified, then only the last element of the sent snapshot's file +system name +.Pq i.e. the name of the source file system itself +is used as the target file system name. +.Bl -tag -width "-F" +.It Fl F +Force a rollback of the file system to the most recent snapshot before +performing the receive operation. +If receiving an incremental replication stream +.Po for example, one generated by +.Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I +.Pc , +destroy snapshots and file systems that do not exist on the sending side. +.It Fl d +Discard the first element of the sent snapshot's file system name, using the +remaining elements to determine the name of the target file system for the new +snapshot as described in the paragraph above. +.It Fl e +Discard all but the last element of the sent snapshot's file system name, using +that element to determine the name of the target file system for the new +snapshot as described in the paragraph above. +.It Fl h +Skip the receive of holds. +There is no effect if holds are not sent. +.It Fl n +Do not actually receive the stream. +This can be useful in conjunction with the +.Fl v +option to verify the name the receive operation would use. +.It Fl o Sy origin Ns = Ns Ar snapshot +Forces the stream to be received as a clone of the given snapshot. +If the stream is a full send stream, this will create the filesystem +described by the stream as a clone of the specified snapshot. +Which snapshot was specified will not affect the success or failure of the +receive, as long as the snapshot does exist. +If the stream is an incremental send stream, all the normal verification will be +performed. +.It Fl o Em property Ns = Ns Ar value +Sets the specified property as if the command +.Nm zfs Cm set Em property Ns = Ns Ar value +was invoked immediately before the receive. +When receiving a stream from +.Nm zfs Cm send Fl R , +causes the property to be inherited by all descendant datasets, as though +.Nm zfs Cm inherit Em property +was run on any descendant datasets that have this property set on the +sending system. +.Pp +Any editable property can be set at receive time. +Set-once properties bound to the received data, such as +.Sy normalization +and +.Sy casesensitivity , +cannot be set at receive time even when the datasets are newly created by +.Nm zfs Cm receive . +Additionally both settable properties +.Sy version +and +.Sy volsize +cannot be set at receive time. +.Pp +The +.Fl o +option may be specified multiple times, for different properties. +An error results if the same property is specified in multiple +.Fl o +or +.Fl x +options. +.Pp +The +.Fl o +option may also be used to override encryption properties upon initial +receive. +This allows unencrypted streams to be received as encrypted datasets. +To cause the received dataset (or root dataset of a recursive stream) to be +received as an encryption root, specify encryption properties in the same +manner as is required for +.Nm +.Cm create . +For instance: +.Bd -literal +# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile +.Ed +.Pp +Note that +.Op Fl o Ar keylocation Ns = Ns Ar prompt +may not be specified here, since stdin is already being utilized for the send +stream. +Once the receive has completed, you can use +.Nm +.Cm set +to change this setting after the fact. +Similarly, you can receive a dataset as an encrypted child by specifying +.Op Fl x Ar encryption +to force the property to be inherited. +Overriding encryption properties (except for +.Sy keylocation ) +is not possible with raw send streams. +.It Fl s +If the receive is interrupted, save the partially received state, rather +than deleting it. +Interruption may be due to premature termination of the stream +.Po e.g. due to network failure or failure of the remote system +if the stream is being read over a network connection +.Pc , +a checksum error in the stream, termination of the +.Nm zfs Cm receive +process, or unclean shutdown of the system. +.Pp +The receive can be resumed with a stream generated by +.Nm zfs Cm send Fl t Ar token , +where the +.Ar token +is the value of the +.Sy receive_resume_token +property of the filesystem or volume which is received into. +.Pp +To use this flag, the storage pool must have the +.Sy extensible_dataset +feature enabled. +See +.Xr zpool-features 7 +for details on ZFS feature flags. +.It Fl u +File system that is associated with the received stream is not mounted. +.It Fl v +Print verbose information about the stream and the time required to perform the +receive operation. +.It Fl x Em property +Ensures that the effective value of the specified property after the +receive is unaffected by the value of that property in the send stream (if any), +as if the property had been excluded from the send stream. +.Pp +If the specified property is not present in the send stream, this option does +nothing. +.Pp +If a received property needs to be overridden, the effective value will be +set or inherited, depending on whether the property is inheritable or not. +.Pp +In the case of an incremental update, +.Fl x +leaves any existing local setting or explicit inheritance unchanged. +.Pp +All +.Fl o +restrictions (e.g. set-once) apply equally to +.Fl x . +.El +.It Xo +.Nm +.Cm receive +.Fl A +.Ar filesystem Ns | Ns Ar volume +.Xc +Abort an interrupted +.Nm zfs Cm receive Fl s , +deleting its saved partially received state. +.It Xo +.Nm +.Cm allow +.Ar filesystem Ns | Ns Ar volume +.Xc +Displays permissions that have been delegated on the specified filesystem or +volume. +See the other forms of +.Nm zfs Cm allow +for more information. +.It Xo +.Nm +.Cm allow +.Op Fl dglu +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Xc +.It Xo +.Nm +.Cm allow +.Op Fl dl +.Fl e Ns | Ns Sy everyone +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Xc +Delegates ZFS administration permission for the file systems to non-privileged +users. +.Bl -tag -width "-d" +.It Fl d +Allow only for the descendent file systems. +.It Fl e Ns | Ns Sy everyone +Specifies that the permissions be delegated to everyone. +.It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... +Explicitly specify that permissions are delegated to the group. +.It Fl l +Allow +.Qq locally +only for the specified file system. +.It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... +Explicitly specify that permissions are delegated to the user. +.It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +Specifies to whom the permissions are delegated. +Multiple entities can be specified as a comma-separated list. +If neither of the +.Fl gu +options are specified, then the argument is interpreted preferentially as the +keyword +.Sy everyone , +then as a user name, and lastly as a group name. +To specify a user or group named +.Qq everyone , +use the +.Fl g +or +.Fl u +options. +To specify a group with the same name as a user, use the +.Fl g +options. +.It Xo +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Xc +The permissions to delegate. +Multiple permissions may be specified as a comma-separated list. +Permission names are the same as ZFS subcommand and property names. +See the property list below. +Property set names, which begin with +.Sy @ , +may be specified. +See the +.Fl s +form below for details. +.El +.Pp +If neither of the +.Fl dl +options are specified, or both are, then the permissions are allowed for the +file system or volume, and all of its descendents. +.Pp +Permissions are generally the ability to use a ZFS subcommand or change a ZFS +property. +The following permissions are available: +.Bd -literal +NAME TYPE NOTES +allow subcommand Must also have the permission that is + being allowed +clone subcommand Must also have the 'create' ability and + 'mount' ability in the origin file system +create subcommand Must also have the 'mount' ability +destroy subcommand Must also have the 'mount' ability +diff subcommand Allows lookup of paths within a dataset + given an object number, and the ability + to create snapshots necessary to + 'zfs diff'. +load-key subcommand Allows loading and unloading of encryption key + (see 'zfs load-key' and 'zfs unload-key'). +change-key subcommand Allows changing an encryption key via + 'zfs change-key'. +mount subcommand Allows mount/umount of ZFS datasets +promote subcommand Must also have the 'mount' and 'promote' + ability in the origin file system +receive subcommand Must also have the 'mount' and 'create' + ability +rename subcommand Must also have the 'mount' and 'create' + ability in the new parent +rollback subcommand Must also have the 'mount' ability +send subcommand +share subcommand Allows sharing file systems over NFS + or SMB protocols +snapshot subcommand Must also have the 'mount' ability + +groupquota other Allows accessing any groupquota@... + property +groupused other Allows reading any groupused@... property +userprop other Allows changing any user property +userquota other Allows accessing any userquota@... + property +userused other Allows reading any userused@... property +projectobjquota other Allows accessing any projectobjquota@... + property +projectquota other Allows accessing any projectquota@... property +projectobjused other Allows reading any projectobjused@... property +projectused other Allows reading any projectused@... property + +aclinherit property +aclmode property +atime property +canmount property +casesensitivity property +checksum property +compression property +copies property +devices property +exec property +filesystem_limit property +mountpoint property +nbmand property +normalization property +primarycache property +quota property +readonly property +recordsize property +refquota property +refreservation property +reservation property +secondarycache property +setuid property +sharenfs property +sharesmb property +snapdir property +snapshot_limit property +utf8only property +version property +volblocksize property +volsize property +vscan property +xattr property +zoned property +.Ed +.It Xo +.Nm +.Cm allow +.Fl c +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Xc +Sets +.Qq create time +permissions. +These permissions are granted +.Pq locally +to the creator of any newly-created descendent file system. +.It Xo +.Nm +.Cm allow +.Fl s No @ Ns Ar setname +.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... +.Ar filesystem Ns | Ns Ar volume +.Xc +Defines or adds permissions to a permission set. +The set can be used by other +.Nm zfs Cm allow +commands for the specified file system and its descendents. +Sets are evaluated dynamically, so changes to a set are immediately reflected. +Permission sets follow the same naming restrictions as ZFS file systems, but the +name must begin with +.Sy @ , +and can be no more than 64 characters long. +.It Xo +.Nm +.Cm unallow +.Op Fl dglru +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Xc +.It Xo +.Nm +.Cm unallow +.Op Fl dlr +.Fl e Ns | Ns Sy everyone +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Xc +.It Xo +.Nm +.Cm unallow +.Op Fl r +.Fl c +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Xc +Removes permissions that were granted with the +.Nm zfs Cm allow +command. +No permissions are explicitly denied, so other permissions granted are still in +effect. +For example, if the permission is granted by an ancestor. +If no permissions are specified, then all permissions for the specified +.Ar user , +.Ar group , +or +.Sy everyone +are removed. +Specifying +.Sy everyone +.Po or using the +.Fl e +option +.Pc +only removes the permissions that were granted to everyone, not all permissions +for every user and group. +See the +.Nm zfs Cm allow +command for a description of the +.Fl ldugec +options. +.Bl -tag -width "-r" +.It Fl r +Recursively remove the permissions from this file system and all descendents. +.El +.It Xo +.Nm +.Cm unallow +.Op Fl r +.Fl s No @ Ns Ar setname +.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns +.Ar setname Oc Ns ... Oc +.Ar filesystem Ns | Ns Ar volume +.Xc +Removes permissions from a permission set. +If no permissions are specified, then all permissions are removed, thus removing +the set entirely. +.It Xo +.Nm +.Cm hold +.Op Fl r +.Ar tag Ar snapshot Ns ... +.Xc +Adds a single reference, named with the +.Ar tag +argument, to the specified snapshot or snapshots. +Each snapshot has its own tag namespace, and tags must be unique within that +space. +.Pp +If a hold exists on a snapshot, attempts to destroy that snapshot by using the +.Nm zfs Cm destroy +command return +.Er EBUSY . +.Bl -tag -width "-r" +.It Fl r +Specifies that a hold with the given tag is applied recursively to the snapshots +of all descendent file systems. +.El +.It Xo +.Nm +.Cm holds +.Op Fl r +.Ar snapshot Ns ... +.Xc +Lists all existing user references for the given snapshot or snapshots. +.Bl -tag -width "-r" +.It Fl r +Lists the holds that are set on the named descendent snapshots, in addition to +listing the holds on the named snapshot. +.El +.It Xo +.Nm +.Cm release +.Op Fl r +.Ar tag Ar snapshot Ns ... +.Xc +Removes a single reference, named with the +.Ar tag +argument, from the specified snapshot or snapshots. +The tag must already exist for each snapshot. +If a hold exists on a snapshot, attempts to destroy that snapshot by using the +.Nm zfs Cm destroy +command return +.Er EBUSY . +.Bl -tag -width "-r" +.It Fl r +Recursively releases a hold with the given tag on the snapshots of all +descendent file systems. +.El +.It Xo +.Nm +.Cm diff +.Op Fl FHt +.Ar snapshot Ar snapshot Ns | Ns Ar filesystem +.Xc +Display the difference between a snapshot of a given filesystem and another +snapshot of that filesystem from a later time or the current contents of the +filesystem. +The first column is a character indicating the type of change, the other columns +indicate pathname, new pathname +.Pq in case of rename , +change in link count, and optionally file type and/or change time. +The types of change are: +.Bd -literal +- The path has been removed ++ The path has been created +M The path has been modified +R The path has been renamed +.Ed +.Bl -tag -width "-F" +.It Fl F +Display an indication of the type of file, in a manner similar to the +.Fl +option of +.Xr ls 1 . +.Bd -literal +B Block device +C Character device +/ Directory +> Door +| Named pipe +@ Symbolic link +P Event port += Socket +F Regular file +.Ed +.It Fl H +Give more parsable tab-separated output, without header lines and without +arrows. +.It Fl t +Display the path's inode change time as the first column of output. +.El +.It Xo +.Nm +.Cm program +.Op Fl jn +.Op Fl t Ar timeout +.Op Fl m Ar memory_limit +.Ar pool script +.Op Ar arg1 No ... +.Xc +Executes +.Ar script +as a ZFS channel program on +.Ar pool . +The ZFS channel +program interface allows ZFS administrative operations to be run +programmatically via a Lua script. +The entire script is executed atomically, with no other administrative +operations taking effect concurrently. +A library of ZFS calls is made available to channel program scripts. +Channel programs may only be run with root privileges. +.sp +For full documentation of the ZFS channel program interface, see the manual +page for +.Xr zfs-program 8 . +.Bl -tag -width "" +.It Fl j +Display channel program output in JSON format. +When this flag is specified and standard output is empty - +channel program encountered an error. +The details of such an error will be printed to standard error in plain text. +.It Fl n +Executes a read-only channel program, which runs faster. +The program cannot change on-disk state by calling functions from +the zfs.sync submodule. +The program can be used to gather information such as properties and +determining if changes would succeed (zfs.check.*). +Without this flag, all pending changes must be synced to disk before +a channel program can complete. +.It Fl t Ar timeout +Execution time limit, in milliseconds. +If a channel program executes for longer than the provided timeout, it will +be stopped and an error will be returned. +The default timeout is 1000 ms, and can be set to a maximum of 10000 ms. +.It Fl m Ar memory-limit +Memory limit, in bytes. +If a channel program attempts to allocate more memory than the given limit, +it will be stopped and an error returned. +The default memory limit is 10 MB, and can be set to a maximum of 100 MB. +.sp +All remaining argument strings are passed directly to the channel program as +arguments. +See +.Xr zfs-program 8 +for more information. +.El +.It Xo +.Nm Cm load-key +.Op Fl nr +.Op Fl L Ar keylocation +.Fl a Ns | Ns filesystem +.Xc +Use +.Ar keylocation +instead of the +.Sy keylocation +property. +This will not change the value of the property on the dataset. +Note that if used with either +.Fl r +or +.Fl a +.Ar keylocation +may only be given as +.Sy prompt . +.Bl -tag -width Ds +.It Fl a +Loads the keys for all encryption roots in all imported pools. +.It Fl n +Do a dry-run +.Cm load-key . +This will cause zfs to simply check that the provided key is correct. +This command may be run even if the key is already loaded. +.It Fl r +Recursively loads the keys for the specified filesystem and all descendent +encryption roots. +.El +.It Xo +.Nm +.Cm unload-key +.Op Fl r +.Fl a Ns | Ns Ar filesystem +.Xc +Unloads a key from ZFS, removing the ability to access the dataset and all of +its children that inherit the +.Sy encryption +property. +This requires that the dataset is not currently open or mounted. +Once the key is unloaded the +.Sy keystatus +property will be set to +.Sy unavailable . +.Bl -tag -width Ds +.It Fl a +Unloads the keys for all encryption roots in all imported pools. +.It Fl r +Recursively unloads the keys for the specified filesystem and all descendent +encryption roots. +.El +.It Xo +.Nm +.Cm change-key +.Op Fl il +.Op Fl o Sy keylocation Ns = Ns Ar value +.Op Fl o Sy keyformat Ns = Ns Ar value +.Op Fl o Sy pbkdf2iters Ns = Ns Ar value +.Ar filesystem +.Xc +Allows a user to change the encryption key used to access a dataset. +This command requires that the existing key for the dataset is already loaded +into ZFS. +This command may also be used to change the +.Sy keylocation , keyformat , +and +.Sy pbkdf2iters +properties as needed. +If the dataset was not previously an encryption root it will become one. +Alternatively, the +.Fl i +flag may be provided to cause an encryption root to inherit the +parent's key instead. +.Bl -tag -width Ds +.It Fl i +Indicates that ZFS should make +.Ar filesystem +inherit the key of its parent. +Note that this command can only be run on an encryption root that has an +encrypted parent. +.It Fl l +Ensures the key is loaded before attempting to change the key. +This is effectively equivalent to +.Qq Nm Cm load-key Ar filesystem ; Nm Cm change-key Ar filesystem . +.It Fl o Sy property Ns = Ns Ar value +Allows the user to set encryption key properties +.Pq +.Sy keyformat , keylocation , +and +.Sy pbkdf2iters +while changing the key. +This is the only way to alter +.Sy keyformat +and +.Sy pbkdf2iters +after the dataset has been created. +.El +.El +.Sh EXIT STATUS +The +.Nm +utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line +options were specified. +.Sh EXAMPLES +.Bl -tag -width "" +.It Sy Example 1 No Creating a ZFS File System Hierarchy +The following commands create a file system named +.Em pool/home +and a file system named +.Em pool/home/bob . +The mount point +.Pa /export/home +is set for the parent file system, and is automatically inherited by the child +file system. +.Bd -literal +# zfs create pool/home +# zfs set mountpoint=/export/home pool/home +# zfs create pool/home/bob +.Ed +.It Sy Example 2 No Creating a ZFS Snapshot +The following command creates a snapshot named +.Sy yesterday . +This snapshot is mounted on demand in the +.Pa .zfs/snapshot +directory at the root of the +.Em pool/home/bob +file system. +.Bd -literal +# zfs snapshot pool/home/bob@yesterday +.Ed +.It Sy Example 3 No Creating and Destroying Multiple Snapshots +The following command creates snapshots named +.Sy yesterday +of +.Em pool/home +and all of its descendent file systems. +Each snapshot is mounted on demand in the +.Pa .zfs/snapshot +directory at the root of its file system. +The second command destroys the newly created snapshots. +.Bd -literal +# zfs snapshot -r pool/home@yesterday +# zfs destroy -r pool/home@yesterday +.Ed +.It Sy Example 4 No Disabling and Enabling File System Compression +The following command disables the +.Sy compression +property for all file systems under +.Em pool/home . +The next command explicitly enables +.Sy compression +for +.Em pool/home/anne . +.Bd -literal +# zfs set compression=off pool/home +# zfs set compression=on pool/home/anne +.Ed +.It Sy Example 5 No Listing ZFS Datasets +The following command lists all active file systems and volumes in the system. +Snapshots are displayed if the +.Sy listsnaps +property is +.Sy on . +The default is +.Sy off . +See +.Xr zpool 8 +for more information on pool properties. +.Bd -literal +# zfs list +NAME USED AVAIL REFER MOUNTPOINT +pool 450K 457G 18K /pool +pool/home 315K 457G 21K /export/home +pool/home/anne 18K 457G 18K /export/home/anne +pool/home/bob 276K 457G 276K /export/home/bob +.Ed +.It Sy Example 6 No Setting a Quota on a ZFS File System +The following command sets a quota of 50 Gbytes for +.Em pool/home/bob . +.Bd -literal +# zfs set quota=50G pool/home/bob +.Ed +.It Sy Example 7 No Listing ZFS Properties +The following command lists all properties for +.Em pool/home/bob . +.Bd -literal +# zfs get all pool/home/bob +NAME PROPERTY VALUE SOURCE +pool/home/bob type filesystem - +pool/home/bob creation Tue Jul 21 15:53 2009 - +pool/home/bob used 21K - +pool/home/bob available 20.0G - +pool/home/bob referenced 21K - +pool/home/bob compressratio 1.00x - +pool/home/bob mounted yes - +pool/home/bob quota 20G local +pool/home/bob reservation none default +pool/home/bob recordsize 128K default +pool/home/bob mountpoint /pool/home/bob default +pool/home/bob sharenfs off default +pool/home/bob checksum on default +pool/home/bob compression on local +pool/home/bob atime on default +pool/home/bob devices on default +pool/home/bob exec on default +pool/home/bob setuid on default +pool/home/bob readonly off default +pool/home/bob zoned off default +pool/home/bob snapdir hidden default +pool/home/bob aclmode discard default +pool/home/bob aclinherit restricted default +pool/home/bob canmount on default +pool/home/bob xattr on default +pool/home/bob copies 1 default +pool/home/bob version 4 - +pool/home/bob utf8only off - +pool/home/bob normalization none - +pool/home/bob casesensitivity sensitive - +pool/home/bob vscan off default +pool/home/bob nbmand off default +pool/home/bob sharesmb off default +pool/home/bob refquota none default +pool/home/bob refreservation none default +pool/home/bob primarycache all default +pool/home/bob secondarycache all default +pool/home/bob usedbysnapshots 0 - +pool/home/bob usedbydataset 21K - +pool/home/bob usedbychildren 0 - +pool/home/bob usedbyrefreservation 0 - +.Ed +.Pp +The following command gets a single property value. +.Bd -literal +# zfs get -H -o value compression pool/home/bob +on +.Ed +The following command lists all properties with local settings for +.Em pool/home/bob . +.Bd -literal +# zfs get -r -s local -o name,property,value all pool/home/bob +NAME PROPERTY VALUE +pool/home/bob quota 20G +pool/home/bob compression on +.Ed +.It Sy Example 8 No Rolling Back a ZFS File System +The following command reverts the contents of +.Em pool/home/anne +to the snapshot named +.Sy yesterday , +deleting all intermediate snapshots. +.Bd -literal +# zfs rollback -r pool/home/anne@yesterday +.Ed +.It Sy Example 9 No Creating a ZFS Clone +The following command creates a writable file system whose initial contents are +the same as +.Em pool/home/bob@yesterday . +.Bd -literal +# zfs clone pool/home/bob@yesterday pool/clone +.Ed +.It Sy Example 10 No Promoting a ZFS Clone +The following commands illustrate how to test out changes to a file system, and +then replace the original file system with the changed one, using clones, clone +promotion, and renaming: +.Bd -literal +# zfs create pool/project/production + populate /pool/project/production with data +# zfs snapshot pool/project/production@today +# zfs clone pool/project/production@today pool/project/beta + make changes to /pool/project/beta and test them +# zfs promote pool/project/beta +# zfs rename pool/project/production pool/project/legacy +# zfs rename pool/project/beta pool/project/production + once the legacy version is no longer needed, it can be destroyed +# zfs destroy pool/project/legacy +.Ed +.It Sy Example 11 No Inheriting ZFS Properties +The following command causes +.Em pool/home/bob +and +.Em pool/home/anne +to inherit the +.Sy checksum +property from their parent. +.Bd -literal +# zfs inherit checksum pool/home/bob pool/home/anne +.Ed +.It Sy Example 12 No Remotely Replicating ZFS Data +The following commands send a full stream and then an incremental stream to a +remote machine, restoring them into +.Em poolB/received/fs@a +and +.Em poolB/received/fs@b , +respectively. +.Em poolB +must contain the file system +.Em poolB/received , +and must not initially contain +.Em poolB/received/fs . +.Bd -literal +# zfs send pool/fs@a | \e + ssh host zfs receive poolB/received/fs@a +# zfs send -i a pool/fs@b | \e + ssh host zfs receive poolB/received/fs +.Ed +.It Sy Example 13 No Using the zfs receive -d Option +The following command sends a full stream of +.Em poolA/fsA/fsB@snap +to a remote machine, receiving it into +.Em poolB/received/fsA/fsB@snap . +The +.Em fsA/fsB@snap +portion of the received snapshot's name is determined from the name of the sent +snapshot. +.Em poolB +must contain the file system +.Em poolB/received . +If +.Em poolB/received/fsA +does not exist, it is created as an empty file system. +.Bd -literal +# zfs send poolA/fsA/fsB@snap | \e + ssh host zfs receive -d poolB/received +.Ed +.It Sy Example 14 No Setting User Properties +The following example sets the user-defined +.Sy com.example:department +property for a dataset. +.Bd -literal +# zfs set com.example:department=12345 tank/accounting +.Ed +.It Sy Example 15 No Performing a Rolling Snapshot +The following example shows how to maintain a history of snapshots with a +consistent naming scheme. +To keep a week's worth of snapshots, the user destroys the oldest snapshot, +renames the remaining snapshots, and then creates a new snapshot, as follows: +.Bd -literal +# zfs destroy -r pool/users@7daysago +# zfs rename -r pool/users@6daysago @7daysago +# zfs rename -r pool/users@5daysago @6daysago +# zfs rename -r pool/users@4daysago @5daysago +# zfs rename -r pool/users@3daysago @4daysago +# zfs rename -r pool/users@2daysago @3daysago +# zfs rename -r pool/users@yesterday @2daysago +# zfs rename -r pool/users@today @yesterday +# zfs snapshot -r pool/users@today +.Ed +.It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System +The following commands show how to set +.Sy sharenfs +property options to enable +.Sy rw +access for a set of +.Sy IP +addresses and to enable root access for system +.Sy neo +on the +.Em tank/home +file system. +.Bd -literal +# zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home +.Ed +.Pp +If you are using +.Sy DNS +for host name resolution, specify the fully qualified hostname. +.It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset +The following example shows how to set permissions so that user +.Sy cindys +can create, destroy, mount, and take snapshots on +.Em tank/cindys . +The permissions on +.Em tank/cindys +are also displayed. +.Bd -literal +# zfs allow cindys create,destroy,mount,snapshot tank/cindys +# zfs allow tank/cindys +---- Permissions on tank/cindys -------------------------------------- +Local+Descendent permissions: + user cindys create,destroy,mount,snapshot +.Ed +.Pp +Because the +.Em tank/cindys +mount point permission is set to 755 by default, user +.Sy cindys +will be unable to mount file systems under +.Em tank/cindys . +Add an ACE similar to the following syntax to provide mount point access: +.Bd -literal +# chmod A+user:cindys:add_subdirectory:allow /tank/cindys +.Ed +.It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset +The following example shows how to grant anyone in the group +.Sy staff +to create file systems in +.Em tank/users . +This syntax also allows staff members to destroy their own file systems, but not +destroy anyone else's file system. +The permissions on +.Em tank/users +are also displayed. +.Bd -literal +# zfs allow staff create,mount tank/users +# zfs allow -c destroy tank/users +# zfs allow tank/users +---- Permissions on tank/users --------------------------------------- +Permission sets: + destroy +Local+Descendent permissions: + group staff create,mount +.Ed +.It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset +The following example shows how to define and grant a permission set on the +.Em tank/users +file system. +The permissions on +.Em tank/users +are also displayed. +.Bd -literal +# zfs allow -s @pset create,destroy,snapshot,mount tank/users +# zfs allow staff @pset tank/users +# zfs allow tank/users +---- Permissions on tank/users --------------------------------------- +Permission sets: + @pset create,destroy,mount,snapshot +Local+Descendent permissions: + group staff @pset +.Ed +.It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset +The following example shows to grant the ability to set quotas and reservations +on the +.Em users/home +file system. +The permissions on +.Em users/home +are also displayed. +.Bd -literal +# zfs allow cindys quota,reservation users/home +# zfs allow users/home +---- Permissions on users/home --------------------------------------- +Local+Descendent permissions: + user cindys quota,reservation +cindys% zfs set quota=10G users/home/marks +cindys% zfs get quota users/home/marks +NAME PROPERTY VALUE SOURCE +users/home/marks quota 10G local +.Ed +.It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset +The following example shows how to remove the snapshot permission from the +.Sy staff +group on the +.Em tank/users +file system. +The permissions on +.Em tank/users +are also displayed. +.Bd -literal +# zfs unallow staff snapshot tank/users +# zfs allow tank/users +---- Permissions on tank/users --------------------------------------- +Permission sets: + @pset create,destroy,mount,snapshot +Local+Descendent permissions: + group staff @pset +.Ed +.It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset +The following example shows how to see what has changed between a prior +snapshot of a ZFS dataset and its current state. +The +.Fl F +option is used to indicate type information for the files affected. +.Bd -literal +# zfs diff -F tank/test@before tank/test +M / /tank/test/ +M F /tank/test/linked (+1) +R F /tank/test/oldname -> /tank/test/newname +- F /tank/test/deleted ++ F /tank/test/created +M F /tank/test/modified +.Ed +.El +.Sh INTERFACE STABILITY +.Sy Committed . +.Sh SEE ALSO +.Xr gzip 1 , +.Xr ssh 1 , +.Xr chmod 2 , +.Xr stat 2 , +.Xr write 2 , +.Xr fsync 3C , +.Xr dfstab 5 , +.Xr acl 7 , +.Xr attributes 7 , +.Xr mount 8 , +.Xr share 8 , +.Xr sharemgr 8 , +.Xr unshare 8 , +.Xr zfs-program 8 , +.Xr zonecfg 8 , +.Xr zpool 8 |