diff options
Diffstat (limited to 'usr/src/man/man1m/zfs.1m')
| -rw-r--r-- | usr/src/man/man1m/zfs.1m | 4767 |
1 files changed, 0 insertions, 4767 deletions
diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m deleted file mode 100644 index 6cf069550e..0000000000 --- a/usr/src/man/man1m/zfs.1m +++ /dev/null @@ -1,4767 +0,0 @@ -.\" -.\" 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 February 26, 2019 -.Dt ZFS 1M -.Os -.Sh NAME -.Nm zfs -.Nd configures ZFS file systems -.Sh SYNOPSIS -.Nm -.Op Fl \&? -.Nm -.Cm create -.Op Fl p -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem -.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 -.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 1M . -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 1M -command. -.Pp -See -.Xr zpool 1M -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 1M . -.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 5 -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 5 -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 5 -.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 1M -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 1M -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 5 -.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 5 -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 1M . -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 1M -command is invoked with no options. -Otherwise, the -.Xr sharemgr 1M -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 1M , -.Xr unshare 1M , -and -.Xr dfstab 4 . -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 1M -command is invoked with no options. -Otherwise, the -.Xr share 1M -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 1M -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 1M -and -.Xr dumpadm 1M -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 p -.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. -.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. -.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 1M -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 1M -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 5 -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 5 -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 5 -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 5 -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 5 -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 5 -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 1M . -.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 1M -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 1M -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 mount 1M , -.Xr share 1M , -.Xr sharemgr 1M , -.Xr unshare 1M , -.Xr zfs-program 1M , -.Xr zonecfg 1M , -.Xr zpool 1M , -.Xr chmod 2 , -.Xr stat 2 , -.Xr write 2 , -.Xr fsync 3C , -.Xr dfstab 4 , -.Xr acl 5 , -.Xr attributes 5 |