diff options
Diffstat (limited to 'man/man8/zfs.8')
| -rw-r--r-- | man/man8/zfs.8 | 4935 |
1 files changed, 134 insertions, 4801 deletions
diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index e391b9810..1f100ab9e 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -31,7 +31,7 @@ .\" Copyright 2019 Joyent, Inc. .\" .Dd June 30, 2019 -.Dt ZFS 8 SMM +.Dt ZFS 8 .Os Linux .Sh NAME .Nm zfs @@ -40,307 +40,10 @@ .Nm .Fl ?V .Nm -.Cm create -.Op Fl Pnpv -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem -.Nm -.Cm create -.Op Fl Pnpsv -.Op Fl b Ar blocksize -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Fl V Ar size Ar volume -.Nm -.Cm destroy -.Op Fl Rfnprv -.Ar filesystem Ns | Ns Ar volume -.Nm -.Cm destroy -.Op Fl Rdnprv -.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns -.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... -.Nm -.Cm destroy -.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark -.Nm -.Cm snapshot -.Op Fl r -.Oo Fl o Ar property Ns = Ns Ar 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 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 ... -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc 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 Oflv -.Op Fl o Ar options -.Fl a | Ar filesystem -.Nm -.Cm unmount -.Op Fl fu -.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 DLPcenpvw -.Oo Fl i Ar snapshot Ns | Ns Ar bookmark -.Oc -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot -.Nm -.Cm send -.Fl -redact Ar redaction_bookmark -.Op Fl DLPcenpv -.Op Fl i Ar snapshot Ns | Ns Ar bookmark -.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 redact -.Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... -.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 rH -.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 instruction-limit -.Op Fl m Ar memory-limit -.Ar pool script -.Op -- -.Ar arg1 No ... -.Nm -.Cm load-key -.Op Fl nr -.Op Fl L Ar keylocation -.Fl a | Ar filesystem -.Nm -.Cm unload-key -.Op Fl r -.Fl a | Ar filesystem -.Nm -.Cm change-key -.Op Fl l -.Op Fl o Ar keylocation Ns = Ns Ar value -.Op Fl o Ar keyformat Ns = Ns Ar value -.Op Fl o Ar pbkdf2iters Ns = Ns Ar value -.Ar filesystem -.Nm -.Cm change-key -.Fl i -.Op Fl l -.Ar filesystem -.Nm .Cm version +.Nm +.Cm <subcommand> +.Op Ar <args> .Sh DESCRIPTION The .Nm @@ -381,172 +84,16 @@ or .It Sy bookmark Much like a .Sy snapshot , -but without the hold on on-disk data. It can be used as the source of a send -(but not for a receive). It is specified as +but without the hold on on-disk data. +It can be used as the source of a send (but not for a receive). It is specified as .Ar filesystem Ns # Ns Ar name or .Ar volume Ns # Ns Ar name . .El -.Ss ZFS File System Hierarchy -A ZFS storage pool is a logical collection of devices that provide space for -datasets. -A storage pool is also the root of the ZFS file system hierarchy. -.Pp -The root of the pool can be accessed as a file system, such as mounting and -unmounting, taking snapshots, and setting properties. -The physical storage characteristics, however, are managed by the -.Xr zpool 8 -command. -.Pp -See -.Xr zpool 8 -for more information on creating and administering pools. -.Ss Snapshots -A snapshot is a read-only copy of a file system or volume. -Snapshots can be created extremely quickly, and initially consume no additional -space within the pool. -As data within the active dataset changes, the snapshot consumes more data than -would otherwise be shared with the active dataset. -.Pp -Snapshots can have arbitrary names. -Snapshots of volumes can be cloned or rolled back, visibility is determined -by the -.Sy snapdev -property of the parent volume. -.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 Bookmarks -A bookmark is like a snapshot, a read-only copy of a file system or volume. -Bookmarks can be created extremely quickly, compared to snapshots, and they -consume no additional space within the pool. Bookmarks can also have arbitrary -names, much like snapshots. -.Pp -Unlike snapshots, bookmarks can not be accessed through the filesystem in any -way. From a storage standpoint a bookmark just provides a way to reference -when a snapshot was created as a distinct object. Bookmarks are initially -tied to a snapshot, not the filesystem or volume, and they will survive if the -snapshot itself is destroyed. Since they are very light weight there's little -incentive to destroy them. -.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/fstab -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/fstab -.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/fstab -.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. Because pools must -be imported before a legacy mount can succeed, administrators should ensure -that legacy mounts are only attempted after the zpool import process -finishes at boot time. For example, on machines using systemd, the mount -option -.Pp -.Nm x-systemd.requires=zfs-import.target -.Pp -will ensure that the zfs-import completes before systemd attempts mounting -the filesystem. See systemd.mount(5) for details. -.Ss Deduplication -Deduplication is the process for removing redundant data at the block level, -reducing the total amount of data stored. If a file system has the -.Sy dedup -property enabled, duplicate data blocks are removed synchronously. The result -is that only unique data is stored and common components are shared among files. -.Pp -Deduplicating data is a very resource-intensive operation. It is generally -recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when -you enable deduplication. Calculating the exact requirement depends heavily -on the type of data stored in the pool. -.Pp -Enabling deduplication on an improperly-designed system can result in -performance issues (slow IO and administrative operations). It can potentially -lead to problems importing a pool due to memory exhaustion. Deduplication -can consume significant processing power (CPU) and memory as well as generate -additional disk IO. -.Pp -Before creating a pool with deduplication enabled, ensure that you have planned -your hardware requirements appropriately and implemented appropriate recovery -practices, such as regular backups. As an alternative to deduplication -consider using -.Sy compression=on , -as a less resource-intensive alternative. -.Ss Native Properties +For details see +.Xr zfsconcepts 8 . +.Ss Properties Properties are divided into two types, native properties and user-defined .Po or .Qq user @@ -556,1991 +103,20 @@ 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 . -The roles of origin and clone can be swapped by promoting the clone with the -.Nm zfs Cm promote -command. -.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 (see -.Nm zfs Cm load-key -and -.Nm zfs Cm unload-key -for details). -Clones will always share an -encryption key with their origin. See the -.Sx 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 keystatus -Indicates if an encryption key is currently loaded into ZFS. The possible -values are -.Sy none , -.Sy available , -and -.Sy unavailable . -See -.Nm zfs Cm load-key -and -.Nm zfs Cm unload-key . -.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 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 objsetid -A unique identifier for this dataset within the pool. Unlike the dataset's -.Sy guid -, the -.Sy objsetid -of a dataset is not transferred to other pools when the snapshot is copied -with a send/receive operation. -The -.Sy objsetid -can be reused (for a new dataset) after the dataset is deleted. -.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 redact_snaps -For bookmarks, this is the list of snapshot guids the bookmark contains a redaction -list for. -For snapshots, this is the list of snapshot guids the snapshot is redacted with -respect to. -.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 2 -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 -.Pp -Files created on Linux always have POSIX owners. -.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 . -When a file system is configured to use -.Sy xattr=sa -no additional internal objects are normally required. -.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 chattr Fl /+P -or -.Nm zfs project Fl s ) -when being created. The privileged user can set and change object's project -ID via -.Nm chattr Fl p -or -.Nm zfs project Fl s -anytime. Space is charged to the project of each file, as displayed by -.Nm lsattr Fl p -or -.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 . -When a filesystem is configured to use -.Sy xattr=sa -no additional internal objects are required. 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. -.Pp -The -.Sy aclinherit -property does not apply to POSIX ACLs. -.It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl -Controls whether ACLs are enabled and if so what type of ACL to use. -.Bl -tag -width "posixacl" -.It Sy off -default, when a file system has the -.Sy acltype -property set to off then ACLs are disabled. -.It Sy noacl -an alias for -.Sy off -.It Sy posixacl -indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are -not functional on other platforms. POSIX ACLs are stored as an extended -attribute and therefore will not overwrite any existing NFSv4 ACLs which -may be set. -.El -.Pp -To obtain the best performance when setting -.Sy posixacl -users are strongly encouraged to set the -.Sy xattr=sa -property. This will result in the POSIX ACL being stored more efficiently on -disk. But as a consequence, all new extended attributes will only be -accessible from OpenZFS implementations which support the -.Sy xattr=sa -property. See the -.Sy xattr -property for more details. -.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 values -.Sy on -and -.Sy off -are equivalent to the -.Sy atime -and -.Sy noatime -mount options. The default value is -.Sy on . -See also -.Sy relatime -below. -.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. -These pool features are not supported by GRUB and must not be used on the -pool if GRUB needs to access the pool (e.g. for /boot). -.Pp -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. -.Pp -When any setting except -.Sy off -is selected, compression will explicitly check for blocks consisting of only -zeroes (the NUL byte). When a zero-filled block is detected, it is stored as -a hole and not compressed using the indicated compression algorithm. -.Pp -Any block being compressed must be no larger than 7/8 of its original size -after compression, otherwise the compression will not be considered worthwhile -and the block saved uncompressed. Note that when the logical block is less than -8 times the disk sector size this effectively reduces the necessary compression -ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2 -or less of their original size. -.It Xo -.Sy context Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level -.Xc -This flag sets the SELinux context for all files in the file system under -a mount point for that file system. See -.Xr selinux 8 -for more information. -.It Xo -.Sy fscontext Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level -.Xc -This flag sets the SELinux context for the file system file system being -mounted. See -.Xr selinux 8 -for more information. -.It Xo -.Sy defcontext Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level -.Xc -This flag sets the SELinux default context for unlabeled files. See -.Xr selinux 8 -for more information. -.It Xo -.Sy rootcontext Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level -.Xc -This flag sets the SELinux context for the root inode of the file system. See -.Xr selinux 8 -for more information. -.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. -.Pp -Remember that ZFS will not import a pool with a missing top-level vdev. Do -.Sy NOT -create, for example a two-disk striped pool and set -.Sy copies=2 -on some datasets thinking you have setup redundancy for them. When a disk -fails you will not be able to import the pool and will have lost all of your -data. -.Pp -Encrypted datasets may not have -.Sy copies Ns = Ns Em 3 -since the implementation stores some encryption metadata where the third copy -would normally be. -.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 . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy dev -and -.Sy nodev -mount options. -.It Xo -.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns -.Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns -.Sy edonr,verify -.Xc -Configures deduplication for a dataset. The default value is -.Sy off . -The default deduplication checksum is -.Sy sha256 -(this may change in the future). When -.Sy dedup -is enabled, the checksum defined here overrides the -.Sy checksum -property. Setting the value to -.Sy verify -has the same effect as the setting -.Sy sha256,verify. -.Pp -If set to -.Sy verify , -ZFS will do a byte-to-byte comparison in case of two blocks having the same -signature to make sure the block contents are identical. Specifying -.Sy verify -is mandatory for the -.Sy edonr -algorithm. -.Pp -Unless necessary, deduplication should NOT be enabled on a system. See -.Sx Deduplication -above. -.It Xo -.Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns -.Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k -.Xc -Specifies a compatibility mode or literal value for the size of dnodes in the -file system. The default value is -.Sy legacy . -Setting this property to a value other than -.Sy legacy -requires the large_dnode pool feature to be enabled. -.Pp -Consider setting -.Sy dnodesize -to -.Sy auto -if the dataset uses the -.Sy xattr=sa -property setting and the workload makes heavy use of extended attributes. This -may be applicable to SELinux-enabled systems, Lustre servers, and Samba -servers, for example. Literal values are supported for cases where the optimal -size is known in advance and for performance testing. -.Pp -Leave -.Sy dnodesize -set to -.Sy legacy -if you need to receive a send stream of this dataset on a pool that doesn't -enable the large_dnode feature, or if you need to import this pool on a system -that doesn't support the large_dnode feature. -.Pp -This property can also be referred to by its shortened column name, -.Sy dnsize . -.It Xo -.Sy encryption Ns = Ns Sy off Ns | Ns Sy on 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 (block cipher, key length, and mode) used -for this dataset. Requires the -.Sy 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 -.Sy 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 when the dataset is encrypted. -.Pp -Raw keys and hex keys must be 32 bytes long (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 (see the -.Sy pbkdf2iters -property). Even though the -encryption suite cannot be changed after dataset creation, the keyformat can be -with -.Nm zfs Cm change-key . -.It Xo -.Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path> -.Xc -Controls where the user's encryption key will be loaded from by default for -commands such as -.Nm zfs Cm load-key -and -.Nm zfs Cm mount Cm -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 zfs Cm set -or -.Nm zfs 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 (see -.Nm zfs Cm load-key -for details). 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 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 -.Sy 350000 -and the minimum is -.Sy 100000 . -This property may be changed with -.Nm zfs Cm change-key . -.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 . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy exec -and -.Sy noexec -mount options. -.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 8 -for more details on the special allocation class. -.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy -Controls the mount point used for this file system. -See the -.Sx Mount Points -section for more information on how this property is used. -.Pp -When the -.Sy mountpoint -property is changed for a file system, the file system and any children that -inherit the mount point are unmounted. -If the new value is -.Sy legacy , -then they remain unmounted. -Otherwise, they are automatically remounted in the new location if the property -was previously -.Sy legacy -or -.Sy none , -or if they were mounted before the property was changed. -In addition, any shared file systems are unshared and shared in the new -location. -.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off -Controls whether the file system should be mounted with -.Sy nbmand -.Pq Non Blocking mandatory locks . -This is used for SMB clients. -Changes to this property only take effect when the file system is umounted and -remounted. -See -.Xr mount 8 -for more information on -.Sy nbmand -mounts. This property is not used on Linux. -.It Sy overlay Ns = Ns Sy off Ns | Ns Sy on -Allow mounting on a busy directory or a directory which already contains -files or directories. This is the default mount behavior for Linux file systems. -For consistency with OpenZFS on other platforms overlay mounts are -.Sy off -by default. Set to -.Sy on -to enable overlay mounts. -.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 -.Pp -Files created on Linux always have POSIX owners. -.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 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/changed. -.Pp -The root user, or a user who has been granted the -.Sy projectquota -privilege with -.Nm zfs allow , -can access all projects' quota. -.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 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 . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy ro -and -.Sy rw -mount options. -.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 relatime Ns = Ns Sy on Ns | Ns Sy off -Controls the manner in which the access time is updated when -.Sy atime=on -is set. Turning this property on causes the access time to be updated relative -to the modify or change time. Access time is only updated if the previous -access time was earlier than the current modify or change time or if the -existing access time hasn't been updated within the past 24 hours. The default -value is -.Sy off . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy relatime -and -.Sy norelatime -mount options. -.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 . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy suid -and -.Sy nosuid -mount options. -.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts -Controls whether the file system is shared by using -.Sy Samba USERSHARES -and what options are to be used. 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 on, the -.Xr net 8 -command is invoked to create a -.Sy USERSHARE . -.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 (_) characters. -Linux does not currently support additional options which might be available -on Solaris. -.Pp -If the -.Sy sharesmb -property is set to -.Sy off , -the file systems are unshared. -.Pp -The share is created with the ACL (Access Control List) "Everyone:F" ("F" -stands for "full permissions", ie. read and write permissions) and no guest -access (which means Samba must be able to authenticate a real user, system -passwd/shadow, LDAP or smbpasswd based) by default. This means that any -additional access control (disallow specific user specific access etc) must -be done on the underlying file system. -.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 with the -.Xr exportfs 8 -command and entries in the -.Em /etc/exports -file. -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 dataset is shared using the default options: -.Pp -.Em sec=sys,rw,crossmnt,no_subtree_check -.Pp -See -.Xr exports 5 -for the meaning of the default options. Otherwise, the -.Xr exportfs 8 -command is invoked with options equivalent to the contents of this property. -.Pp -When the -.Sy sharenfs -property is changed for a dataset, the dataset and any children inheriting the -property are re-shared with the new options, only if the property was previously -.Sy off , -or if they were shared before the property was changed. -If the new property is -.Sy off , -the file systems are unshared. -.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput -Provide a hint to ZFS about handling of synchronous requests in this dataset. -If -.Sy logbias -is set to -.Sy latency -.Pq the default , -ZFS will use pool log devices -.Pq if configured -to handle the requests at low latency. -If -.Sy logbias -is set to -.Sy throughput , -ZFS will not use configured pool log devices. -ZFS will instead optimize synchronous operations for global pool throughput and -efficient use of resources. -.It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible -Controls whether the volume snapshot devices under -.Em /dev/zvol/<pool> -are hidden or visible. The default value is -.Sy hidden . -.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 -.Tn 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 volmode Ns = Ns Cm default | full | geom | dev | none -This property specifies how volumes should be exposed to the OS. -Setting it to -.Sy full -exposes volumes as fully fledged block devices, providing maximal -functionality. The value -.Sy geom -is just an alias for -.Sy full -and is kept for compatibility. -Setting it to -.Sy dev -hides its partitions. -Volumes with property set to -.Sy none -are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc, -that can be suitable for backup purposes. -Value -.Sy default -means that volumes exposition is controlled by system-wide tunable -.Va zvol_volmode , -where -.Sy full , -.Sy dev -and -.Sy none -are encoded as 1, 2 and 3 respectively. -The default values is -.Sy full . -.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 . -This property is not used on Linux. -.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa -Controls whether extended attributes are enabled for this file system. Two -styles of extended attributes are supported either directory based or system -attribute based. -.Pp -The default value of -.Sy on -enables directory based extended attributes. This style of extended attribute -imposes no practical limit on either the size or number of attributes which -can be set on a file. Although under Linux the -.Xr getxattr 2 -and -.Xr setxattr 2 -system calls limit the maximum size to 64K. This is the most compatible -style of extended attribute and is supported by all OpenZFS implementations. -.Pp -System attribute based xattrs can be enabled by setting the value to -.Sy sa . -The key advantage of this type of xattr is improved performance. Storing -extended attributes as system attributes significantly decreases the amount of -disk IO required. Up to 64K of data may be stored per-file in the space -reserved for system attributes. If there is not enough space available for -an extended attribute then it will be automatically written as a directory -based xattr. System attribute based extended attributes are not accessible -on platforms which do not support the -.Sy xattr=sa -feature. -.Pp -The use of system attribute based xattrs is strongly encouraged for users of -SELinux or POSIX ACLs. Both of these features heavily rely of extended -attributes and benefit significantly from the reduced access time. -.Pp -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy xattr -and -.Sy noxattr -mount options. -.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off -Controls whether the dataset is managed from a non-global zone. Zones are a -Solaris feature and are not relevant on Linux. 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 -.Tn POSIX -file systems have case-sensitive file names. -.Pp -The -.Sy mixed -value for the -.Sy casesensitivity -property indicates that the file system can support requests for both -case-sensitive and case-insensitive matching behavior. -Currently, case-insensitive matching behavior on a file system that supports -mixed behavior is limited to the SMB server product. -For more information about the -.Sy mixed -value behavior, see the "ZFS Administration Guide". -.It Xo -.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns -.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD -.Xc -Indicates whether the file system should perform a -.Sy unicode -normalization of file names whenever two file names are compared, and which -normalization algorithm should be used. -File names are always stored unmodified, names are normalized as part of any -comparison process. -If this property is set to a legal value other than -.Sy none , -and the -.Sy utf8only -property was left unspecified, the -.Sy utf8only -property is automatically set to -.Sy on . -The default value of the -.Sy normalization -property is -.Sy none . -This property cannot be changed after the file system is created. -.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off -Indicates whether the file system should reject file names that include -characters that are not present in the -.Sy UTF-8 -character code set. -If this property is explicitly set to -.Sy off , -the normalization property must either not be explicitly set or be set to -.Sy none . -The default value for the -.Sy utf8only -property is -.Sy off . -This property cannot be changed after the file system is created. -.El -.Pp -The -.Sy casesensitivity , -.Sy normalization , -and -.Sy utf8only -properties are also new permissions that can be assigned to non-privileged users -by using the ZFS delegated administration feature. -.Ss "Temporary Mount Point Properties" -When a file system is mounted, either through -.Xr mount 8 -for legacy mounts or the -.Nm zfs Cm mount -command for normal file systems, its mount options are set according to its -properties. -The correlation between properties and mount options is as follows: -.Bd -literal - PROPERTY MOUNT OPTION - atime atime/noatime - canmount auto/noauto - devices dev/nodev - exec exec/noexec - readonly ro/rw - relatime relatime/norelatime - setuid suid/nosuid - 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 -ZFS volumes may be used as swap devices. After creating the volume with the -.Nm zfs Cm create Fl V -command set up and enable the swap area using the -.Xr mkswap 8 -and -.Xr swapon 8 -commands. Do not swap to a file on a ZFS file system. A ZFS swap file -configuration is not supported. +For more information about properties, see the +.Xr zfsprops 8 man page. .Ss Encryption Enabling the .Sy encryption -feature allows for the creation of encrypted filesystems and volumes. ZFS -will encrypt file and zvol data, file attributes, ACLs, permission bits, +feature allows for the creation of encrypted filesystems and volumes. +ZFS will encrypt file and zvol data, file attributes, ACLs, permission bits, directory listings, FUID mappings, and .Sy userused / .Sy groupused -data. ZFS will not encrypt metadata related to the pool structure, including -dataset and snapshot names, dataset hierarchy, properties, file size, file -holes, and deduplication tables (though the deduplicated data itself is -encrypted). -.Pp -Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) -does not require re-encrypting the entire dataset. Datasets can be scrubbed, -resilvered, renamed, and deleted without the encryption keys being loaded (see the -.Nm zfs Cm load-key -subcommand for more info on key loading). -.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 zfs 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 Em 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. -.Ss Redaction -ZFS has support for a limited version of data subsetting, in the form of -redaction. Using the -.Sy zfs redact -command, a -.Sy redaction bookmark -can be created that stores a list of blocks containing sensitive information. When -provided to -.Sy zfs -.Sy send , -this causes a -.Sy redacted send -to occur. Redacted sends omit the blocks containing sensitive information, -replacing them with REDACT records. When these send streams are received, a -.Sy redacted dataset -is created. A redacted dataset cannot be mounted by default, since it is -incomplete. It can be used to receive other send streams. In this way datasets -can be used for data backup and replication, with all the benefits that zfs send -and receive have to offer, while protecting sensitive information from being -stored on less-trusted machines or services. -.Pp -For the purposes of redaction, there are two steps to the process. A redact -step, and a send/receive step. First, a redaction bookmark is created. This is -done by providing the -.Sy zfs redact -command with a parent snapshot, a bookmark to be created, and a number of -redaction snapshots. These redaction snapshots must be descendants of the -parent snapshot, and they should modify data that is considered sensitive in -some way. Any blocks of data modified by all of the redaction snapshots will -be listed in the redaction bookmark, because it represents the truly sensitive -information. When it comes to the send step, the send process will not send -the blocks listed in the redaction bookmark, instead replacing them with -REDACT records. When received on the target system, this will create a -redacted dataset, missing the data that corresponds to the blocks in the -redaction bookmark on the sending system. The incremental send streams from -the original parent to the redaction snapshots can then also be received on -the target system, and this will produce a complete snapshot that can be used -normally. Incrementals from one snapshot on the parent filesystem and another -can also be done by sending from the redaction bookmark, rather than the -snapshots themselves. -.Pp -In order to make the purpose of the feature more clear, an example is -provided. Consider a zfs filesystem containing four files. These files -represent information for an online shopping service. One file contains a list -of usernames and passwords, another contains purchase histories, a third -contains click tracking data, and a fourth contains user preferences. The -owner of this data wants to make it available for their development teams to -test against, and their market research teams to do analysis on. The -development teams need information about user preferences and the click -tracking data, while the market research teams need information about purchase -histories and user preferences. Neither needs access to the usernames and -passwords. However, because all of this data is stored in one ZFS filesystem, -it must all be sent and received together. In addition, the owner of the data -wants to take advantage of features like compression, checksumming, and -snapshots, so they do want to continue to use ZFS to store and transmit their -data. Redaction can help them do so. First, they would make two clones of a -snapshot of the data on the source. In one clone, they create the setup they -want their market research team to see; they delete the usernames and -passwords file, and overwrite the click tracking data with dummy -information. In another, they create the setup they want the development teams -to see, by replacing the passwords with fake information and replacing the -purchase histories with randomly generated ones. They would then create a -redaction bookmark on the parent snapshot, using snapshots on the two clones -as redaction snapshots. The parent can then be sent, redacted, to the target -server where the research and development teams have access. Finally, -incremental sends from the parent snapshot to each of the clones can be send -to and received on the target server; these snapshots are identical to the -ones on the source, and are ready to be used, while the parent snapshot on the -target contains none of the username and password data present on the source, -because it was removed by the redacted send operation. +data. +For an overview of encryption see the +.Xr zfs-load-key 8 command manual. .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their original form. @@ -2549,2393 +125,147 @@ original form. Displays a help message. .It Xo .Nm -.Fl V, -version +.Fl V , -version .Xc An alias for the .Nm zfs Cm version subcommand. .It Xo .Nm -.Cm create -.Op Fl Pnpv -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem -.Xc -Creates a new ZFS file system. -The file system is automatically mounted according to the -.Sy mountpoint -property inherited from the parent. -.Bl -tag -width "-o" -.It Fl o Ar property Ns = Ns Ar value -Sets the specified property as if the command -.Nm zfs Cm set Ar property Ns = Ns Ar value -was invoked at the same time the dataset was created. -Any editable ZFS property can also be set at creation time. -Multiple -.Fl o -options can be specified. -An error results if the same property is specified in multiple -.Fl o -options. -.It Fl p -Creates all the non-existing parent datasets. -Datasets created in this manner are automatically mounted according to the -.Sy mountpoint -property inherited from their parent. -Any property specified on the command line using the -.Fl o -option is ignored. -If the target filesystem already exists, the operation completes successfully. -.It Fl n -Do a dry-run -.Pq Qq No-op -creation. -No datasets will be created. -This is useful in conjunction with the -.Fl v -or -.Fl P -flags to validate properties that are passed via -.Fl o -options and those implied by other options. -The actual dataset creation can still fail due to insufficient privileges or -available capacity. -.It Fl P -Print machine-parsable verbose information about the created dataset. -Each line of output contains a key and one or two values, all separated by tabs. -The -.Sy create_ancestors -and -.Sy create -keys have -.Em filesystem -as their only value. -The -.Sy create_ancestors -key only appears if the -.Fl p -option is used. -The -.Sy property -key has two values, a property name that property's value. -The -.Sy property -key may appear zero or more times, once for each property that will be set local -to -.Em filesystem -due to the use of the -.Fl o -option. -.It Fl v -Print verbose information about the created dataset. -.El -.It Xo -.Nm -.Cm create -.Op Fl ps -.Op Fl b Ar blocksize -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Fl V Ar size Ar volume +.Cm version .Xc -Creates a volume of the given size. -The volume is exported as a block device in -.Pa /dev/zvol/path , -where -.Em path -is the name of the volume in the ZFS namespace. -The size represents the logical size as exported by the device. -By default, a reservation of equal size is created. -.Pp -.Ar size -is automatically rounded up to the nearest 128 Kbytes to ensure that the volume -has an integral number of blocks regardless of -.Sy blocksize . -.Bl -tag -width "-b" -.It Fl b Ar blocksize -Equivalent to -.Fl o Sy volblocksize Ns = Ns Ar blocksize . -If this option is specified in conjunction with -.Fl o Sy volblocksize , -the resulting behavior is undefined. -.It Fl o Ar property Ns = Ns Ar value -Sets the specified property as if the -.Nm zfs Cm set Ar property Ns = Ns Ar value -command was invoked at the same time the dataset was created. -Any editable ZFS property can also be set at creation time. -Multiple -.Fl o -options can be specified. -An error results if the same property is specified in multiple -.Fl o -options. -.It Fl p -Creates all the non-existing parent datasets. -Datasets created in this manner are automatically mounted according to the -.Sy mountpoint -property inherited from their parent. -Any property specified on the command line using the -.Fl o -option is ignored. -If the target filesystem already exists, the operation completes successfully. -.It Fl s -Creates a sparse volume with no reservation. -See -.Sy volsize -in the -.Sx Native Properties -section for more information about sparse volumes. -.It Fl n -Do a dry-run -.Pq Qq No-op -creation. -No datasets will be created. -This is useful in conjunction with the -.Fl v -or -.Fl P -flags to validate properties that are passed via -.Fl o -options and those implied by other options. -The actual dataset creation can still fail due to insufficient privileges or -available capacity. -.It Fl P -Print machine-parsable verbose information about the created dataset. -Each line of output contains a key and one or two values, all separated by tabs. -The -.Sy create_ancestors -and -.Sy create -keys have -.Em volume -as their only value. -The -.Sy create_ancestors -key only appears if the -.Fl p -option is used. -The -.Sy property -key has two values, a property name that property's value. -The -.Sy property -key may appear zero or more times, once for each property that will be set local -to -.Em volume -due to the use of the -.Fl b -or -.Fl o -options, as well as -.Sy refreservation -if the volume is not sparse. -.It Fl v -Print verbose information about the created dataset. -.El -.It Xo +Displays the software version of the .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. +userland utility and the zfs kernel module. .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 -Destroy immediately. If a snapshot cannot be destroyed now, mark it for -deferred destruction. -.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. +.Ss Dataset Management +.Bl -tag -width "" +.It Xr zfs-list 8 +Lists the property information for the given datasets in tabular form. +.It Xr zfs-create 8 +Creates a new ZFS file system or volume. +.It Xr zfs-destroy 8 +Destroys the given dataset(s), snapshot(s), or bookmark. +.It Xr zfs-rename 8 +Renames the given dataset (filesystem or snapshot). +.It Xr zfs-upgrade 8 +Manage upgrading the on-disk version of filesystems. .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 Ar value Oc Ns ... -.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... -.Xc +.Ss Snapshots +.Bl -tag -width "" +.It Xr zfs-snapshot 8 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. -.Nm zfs Cm snap -can be used as an alias for -.Nm zfs Cm snapshot. -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 +.It Xr zfs-rollback 8 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 +.Xr zfs-hold 8 / +.Xr zfs-release 8 .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. +Add or remove a hold reference to the specified snapshot or snapshots. +If a hold exists on a snapshot, attempts to destroy that snapshot by using the +.Nm zfs Cm destroy +command return +.Er EBUSY . +.It Xr zfs-diff 8 +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. .El -.It Xo -.Nm -.Cm promote -.Ar clone-filesystem -.Xc +.Ss Clones +.Bl -tag -width "" +.It Xr zfs-clone 8 +Creates a clone of the given snapshot. +.It Xr zfs-promote 8 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 \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns . -.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 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 ... -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc 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 \fBlocal\fP, \fBdefault\fP, \fBinherited\fP, - \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP). -.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 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 , -.Sy received , -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 upgrade -.Xc -Displays a list of file systems that are not the most recent version. -.It Xo -.Nm -.Cm upgrade -.Fl v -.Xc -Displays a list of currently supported file system versions. -.It Xo -.Nm -.Cm upgrade -.Op Fl r -.Op Fl V Ar version -.Fl a | Ar filesystem -.Xc -Upgrades file systems to a new on-disk version. -Once this is done, the file systems will no longer be accessible on systems -running older versions of the software. -.Nm zfs Cm send -streams generated from new snapshots of these file systems cannot be accessed on -systems running older versions of the software. -.Pp -In general, the file system version is independent of the pool version. -See -.Xr zpool 8 -for information on the -.Nm zpool Cm upgrade -command. -.Pp -In some cases, the file system version and the pool version are interrelated and -the pool version must be upgraded before the file system version can be -upgraded. -.Bl -tag -width "-V" -.It Fl V Ar version -Upgrade to the specified -.Ar version . -If the -.Fl V -flag is not specified, this command upgrades to the most recent version. -This -option can only be used to increase the version number, and only up to the most -recent version supported by this software. -.It Fl a -Upgrade all file systems on all imported pools. -.It Ar filesystem -Upgrade the specified file system. -.It Fl r -Upgrade the specified file system and all descendent file systems. -.El -.It Xo -.Nm -.Cm userspace -.Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Ar filesystem Ns | Ns Ar snapshot -.Xc -Displays space consumed by, and quotas on, each user in the specified filesystem -or snapshot. -This corresponds to the -.Sy userused@ Ns Em user , -.Sy userobjused@ Ns Em user , -.Sy userquota@ Ns Em user, -and -.Sy userobjquota@ Ns Em user -properties. -.Bl -tag -width "-H" -.It Fl H -Do not print headers, use tab-delimited output. -.It Fl S Ar field -Sort by this field in reverse order. -See -.Fl s . -.It Fl i -Translate SID to POSIX ID. -The POSIX ID may be ephemeral if no mapping exists. -Normal POSIX interfaces -.Po for example, -.Xr stat 2 , -.Nm ls Fl l -.Pc -perform this translation, so the -.Fl i -option allows the output from -.Nm zfs Cm userspace -to be compared directly with those utilities. -However, -.Fl i -may lead to confusion if some files were created by an SMB user before a -SMB-to-POSIX name mapping was established. -In such a case, some files will be owned by the SMB entity and some by the POSIX -entity. -However, the -.Fl i -option will report that the POSIX entity has the total usage and quota for both. -.It Fl n -Print numeric ID instead of user/group name. -.It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... -Display only the specified fields from the following set: -.Sy type , -.Sy name , -.Sy used , -.Sy quota . -The default is to display all fields. -.It Fl p -Use exact -.Pq parsable -numeric output. -.It Fl s Ar field -Sort output by this field. -The -.Fl s -and -.Fl S -flags may be specified multiple times to sort first by one field, then by -another. -The default is -.Fl s Sy type Fl s Sy name . -.It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... -Print only the specified types from the following set: -.Sy all , -.Sy posixuser , -.Sy smbuser , -.Sy posixgroup , -.Sy smbgroup . -The default is -.Fl t Sy posixuser Ns \&, Ns Sy smbuser . -The default can be changed to include group types. -.El -.It Xo -.Nm -.Cm groupspace -.Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Ar filesystem Ns | Ns Ar snapshot -.Xc -Displays space consumed by, and quotas on, each group in the specified -filesystem or snapshot. -This subcommand is identical to -.Nm zfs Cm userspace , -except that the default types to display are -.Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . -.It Xo -.Nm -.Cm projectspace -.Op Fl Hp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Ar filesystem Ns | Ns Ar snapshot -.Xc -Displays space consumed by, and quotas on, each project in the specified -filesystem or snapshot. This subcommand is identical to -.Nm zfs Cm userspace , -except that the project identifier is numeral, not name. So need neither -the option -.Sy -i -for SID to POSIX ID nor -.Sy -n -for numeric ID, nor -.Sy -t -for types. -.It Xo -.Nm -.Cm project -.Oo Fl d Ns | Ns Fl r Ns Oc -.Ar file Ns | Ns Ar directory Ns ... -.Xc -List project identifier (ID) and inherit flag of file(s) 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 file(s) 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 file(s) 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 file(s) 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 -.Bl -tag -width "-p" -Set project ID and/or inherit flag on the file(s) or directories. -.It Fl p -Set the file(s)' 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 file(s) 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 Oflv -.Op Fl o Ar options -.Fl a | Ar filesystem -.Xc -Mount ZFS filesystem on a path described by its -.Sy mountpoint -property, if the path exists and is empty. If -.Sy mountpoint -is set to -.Em legacy , -the filesystem should be instead mounted using -.Xr mount 8 . -.Bl -tag -width "-O" -.It Fl O -Perform an overlay mount. Allows mounting in non-empty -.Sy mountpoint . -See -.Xr mount 8 -for more information. -.It Fl a -Mount all available ZFS file systems. -Invoked automatically as part of the boot process if configured. -.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 l -Load keys for encrypted filesystems as they are being mounted. This is -equivalent to executing -.Nm zfs 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 Fl v -Report mount progress. -.It Fl f -Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets). -.El -.It Xo -.Nm -.Cm unmount -.Op Fl fu -.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 Fl f -Forcefully unmount the file system, even if it is currently in use. -.It Fl u -Unload keys for any encryption roots unmounted by this command. -.El -.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 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 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 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 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 DLPRcenpvw -.Op Fl i Ar snapshot Ns | Ns Ar bookmark -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot -.Xc +.Ss Send & Receive +.Bl -tag -width "" +.It Xr zfs-send 8 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 P, -parsable -Print machine-parsable verbose information about the stream package generated. -.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 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 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 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 v, -verbose -Print verbose information about the stream package generated. -This information includes a per-second report of how much data has been sent. -.El -.It Xo -.Nm -.Cm send -.Fl -redact Ar redaction_bookmark -.Op Fl DLPcenpv -.br -.Op Fl i Ar snapshot Ns | Ns Ar bookmark -.Ar snapshot -.Xc -Generate a redacted send stream. -This send stream contains all blocks from the snapshot being sent that aren't -included in the redaction list contained in the bookmark specified by the -.Fl -redact -(or -.Fl -d -) flag. -The resulting send stream is said to be redacted with respect to the snapshots -the bookmark specified by the -.Fl -redact No flag was created with. -The bookmark must have been created by running -.Sy zfs redact -on the snapshot being sent. -.sp -This feature can be used to allow clones of a filesystem to be made available on -a remote system, in the case where their parent need not (or needs to not) be -usable. -For example, if a filesystem contains sensitive data, and it has clones where -that sensitive data has been secured or replaced with dummy data, redacted sends -can be used to replicate the secured data without replicating the original -sensitive data, while still sharing all possible blocks. -A snapshot that has been redacted with respect to a set of snapshots will -contain all blocks referenced by at least one snapshot in the set, but will -contain none of the blocks referenced by none of the snapshots in the set. -In other words, if all snapshots in the set have modified a given block in the -parent, that block will not be sent; but if one or more snapshots have not -modified a block in the parent, they will still reference the parent's block, so -that block will be sent. -Note that only user data will be redacted. -.sp -When the redacted send stream is received, we will generate a redacted -snapshot. -Due to the nature of redaction, a redacted dataset can only be used in the -following ways: -.sp -1. To receive, as a clone, an incremental send from the original snapshot to one -of the snapshots it was redacted with respect to. -In this case, the stream will produce a valid dataset when received because all -blocks that were redacted in the parent are guaranteed to be present in the -child's send stream. -This use case will produce a normal snapshot, which can be used just like other -snapshots. -.sp -2. To receive an incremental send from the original snapshot to something -redacted with respect to a subset of the set of snapshots the initial snapshot -was redacted with respect to. -In this case, each block that was redacted in the original is still redacted -(redacting with respect to additional snapshots causes less data to be redacted -(because the snapshots define what is permitted, and everything else is -redacted)). -This use case will produce a new redacted snapshot. -.sp -3. To receive an incremental send from a redaction bookmark of the original -snapshot that was created when redacting with respect to a subset of the set of -snapshots the initial snapshot was created with respect to -anything else. -A send stream from such a redaction bookmark will contain all of the blocks -necessary to fill in any redacted data, should it be needed, because the sending -system is aware of what blocks were originally redacted. -This will either produce a normal snapshot or a redacted one, depending on -whether the new send stream is redacted. -.sp -4. To receive an incremental send from a redacted version of the initial -snapshot that is redacted with respect to a subject of the set of snapshots the -initial snapshot was created with respect to. -A send stream from a compatible redacted dataset will contain all of the blocks -necessary to fill in any redacted data. -This will either produce a normal snapshot or a redacted one, depending on -whether the new send stream is redacted. -.sp -5. To receive a full send as a clone of the redacted snapshot. -Since the stream is a full send, it definitionally contains all the data needed -to create a new dataset. -This use case will either produce a normal snapshot or a redacted one, depending -on whether the full send stream was redacted. -.sp -These restrictions are detected and enforced by \fBzfs receive\fR; a -redacted send stream will contain the list of snapshots that the stream is -redacted with respect to. -These are stored with the redacted snapshot, and are used to detect and -correctly handle the cases above. Note that for technical reasons, raw sends -and redacted sends cannot be combined at this time. -.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 +.It Xr zfs-receive 8 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 +.Xr zfs-send 8 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 +.It Xr zfs-bookmark 8 +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 -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 through -.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 Ns ) -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 redact -.Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... -.Xc +.It Xr zfs-redact 8 Generate a new redaction bookmark. -In addition to the typical bookmark information, a redaction bookmark contains -the list of redacted blocks and the list of redaction snapshots specified. -The redacted blocks are blocks in the snapshot which are not referenced by any -of the redaction snapshots. -These blocks are found by iterating over the metadata in each redaction snapshot -to determine what has been changed since the target snapshot. -Redaction is designed to support redacted zfs sends; see the entry for -.Sy zfs send -for more information on the purpose of this operation. -If a redact operation fails partway through (due to an error or a system -failure), the redaction can be resumed by rerunning the same command. -.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. -.Pp -Delegations are supported under Linux with the exception of -.Sy mount , -.Sy unmount , -.Sy mountpoint , -.Sy canmount , -.Sy rename , -and -.Sy share . -These permissions cannot be delegated because the Linux -.Xr mount 8 -command restricts modifications of the global namespace to the root user. -.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. - Must also have the 'refreservation' ability to - create a non-sparse volume. -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 -acltype 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 rH -.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. -.It Fl H -Do not print headers, use tab-delimited output. +This feature can be used to allow clones of a filesystem to be made available on +a remote system, in the case where their parent need not (or needs to not) be +usable. .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. +.Ss Properties +.Bl -tag -width "" +.It Xr zfs-get 8 +Displays properties for the given datasets. +.It Xr zfs-set 8 +Sets the property or list of properties to the given value(s) for each dataset. +.It Xr zfs-inherit 8 +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. .El +.Ss Quotas +.Bl -tag -width "" .It Xo -.Nm -.Cm diff -.Op Fl FHt -.Ar snapshot Ar snapshot Ns | Ns Ar filesystem +.Xr zfs-userspace 8 / +.Xr zfs-groupspace 8 / +.Xr zfs-projectspace 8 .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. +Displays space consumed by, and quotas on, each user, group, or project +in the specified filesystem or snapshot. +.It Xr zfs-project 8 +List, set, or clear project ID and/or inherit flag on the file(s) or directories. .El -.It Xo -.Nm -.Cm program -.Op Fl jn -.Op Fl t Ar instruction-limit -.Op Fl m Ar memory-limit -.Ar pool script -.Op -- -.Ar arg1 No ... -.Xc -Executes -.Ar script -as a ZFS channel program on -.Ar pool . -The ZFS channel -program interface allows ZFS administrative operations to be run -programmatically via a Lua script. -The entire script is executed atomically, with no other administrative -operations taking effect concurrently. -A library of ZFS calls is made available to channel program scripts. -Channel programs may only be run with root privileges. -.sp -For full documentation of the ZFS channel program interface, see the manual -page for -.Xr zfs-program 8 . +.Ss Mountpoints .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 instruction-limit -Limit the number of Lua instructions to execute. -If a channel program executes more than the specified number of instructions, -it will be stopped and an error will be returned. -The default limit is 10 million instructions, and it can be set to a maximum of -100 million instructions. -.It Fl m Ar memory-limit -Memory limit, in bytes. -If a channel program attempts to allocate more memory than the given limit, -it will be stopped and an error returned. -The default memory limit is 10 MB, and can be set to a maximum of 100 MB. -.sp -All remaining argument strings are passed directly to the channel program as -arguments. -See -.Xr zfs-program 8 -for more information. -.El -.It Xo -.Nm -.Cm load-key -.Op Fl nr -.Op Fl L Ar keylocation -.Fl a | Ar filesystem -.Xc -Load the key for -.Ar filesystem , -allowing it and all children that inherit the -.Sy keylocation -property to be accessed. The key will be expected in the format specified by the -.Sy keyformat -and location specified by the -.Sy keylocation -property. Note that if the -.Sy keylocation -is set to -.Sy prompt -the terminal will interactively wait for the key to be entered. Loading a key -will not automatically mount the dataset. If that functionality is desired, -.Nm zfs Cm mount Sy -l -will ask for the key and mount the dataset. Once the key is loaded the -.Sy keystatus -property will become -.Sy available . -.Bl -tag -width "-r" -.It Fl r -Recursively loads the keys for the specified filesystem and all descendent -encryption roots. -.It Fl a -Loads the keys for all encryption roots in all imported pools. -.It Fl n -Do a dry-run -.Pq Qq No-op -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 L Ar keylocation -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 . +.It Xr zfs-mount 8 +Displays all ZFS file systems currently mounted, or mount ZFS filesystem +on a path described by its +.Sy mountpoint +property. +.It Xr zfs-unmount 8 +Unmounts currently mounted ZFS file systems. .El -.It Xo -.Nm -.Cm unload-key -.Op Fl r -.Fl a | Ar filesystem -.Xc -Unloads a key from ZFS, removing the ability to access the dataset and all of -its children that inherit the -.Sy keylocation -property. This requires that the dataset is not currently open or mounted. Once -the key is unloaded the -.Sy keystatus -property will become -.Sy unavailable . -.Bl -tag -width "-r" -.It Fl r -Recursively unloads the keys for the specified filesystem and all descendent -encryption roots. -.It Fl a -Unloads the keys for all encryption roots in all imported pools. +.Ss Shares +.Bl -tag -width "" +.It Xr zfs-share 8 +Shares available ZFS file systems. +.It Xr zfs-unshare 8 +Unshares currently shared ZFS file systems. .El -.It Xo -.Nm -.Cm change-key -.Op Fl l -.Op Fl o Ar keylocation Ns = Ns Ar value -.Op Fl o Ar keyformat Ns = Ns Ar value -.Op Fl o Ar pbkdf2iters Ns = Ns Ar value -.Ar filesystem -.Xc -.It Xo -.Nm -.Cm change-key -.Fl i -.Op Fl l -.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 , -.Sy 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 "-r" -.It Fl l -Ensures the key is loaded before attempting to change the key. This is -effectively equivalent to -.Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem -.It Fl o Ar property Ns = Ns Ar value -Allows the user to set encryption key properties ( -.Sy keyformat , -.Sy 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. -.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. +.Ss Delegated Administration +.Bl -tag -width "" +.It Xr zfs-allow 8 +Delegate permissions on the specified filesystem or volume. +.It Xr zfs-unallow 8 +Remove delegated permissions on the specified filesystem or volume. .El -.It Xo -.Nm -.Cm version -.Xc -Displays the software version of the -.Nm -userland utility and the zfs kernel module. +.Ss Encryption +.Bl -tag -width "" +.It Xr zfs-change-key 8 +Add or change an encryption key on the specified dataset. +.It Xr zfs-load-key 8 +Load the key for the specified encrypted dataset, enabling access. +.It Xr zfs-unload-key 8 +Unload a key for the specified dataset, removing the ability to access the dataset. +.El +.Ss Channel Programs +.Bl -tag -width "" +.It Xr zfs-program 8 +Execute ZFS administrative operations +programmatically via a Lua script-language channel program. .El .Sh EXIT STATUS The @@ -5321,14 +651,14 @@ R F /tank/test/oldname -> /tank/test/newname M F /tank/test/modified .Ed .It Sy Example 23 No Creating a bookmark -The following example create a bookmark to a snapshot. This bookmark -can then be used instead of snapshot in send streams. +The following example create a bookmark to a snapshot. +This bookmark can then be used instead of snapshot in send streams. .Bd -literal # zfs bookmark rpool@snapshot rpool#bookmark .Ed .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System -The following example show how to share SMB filesystem through ZFS. Note that -that a user and his/her password must be given. +The following example show how to share SMB filesystem through ZFS. +Note that that a user and his/her password must be given. .Bd -literal # smbmount //127.0.0.1/share_tmp /mnt/tmp \\ -o user=workgroup/turbo,password=obrut,uid=1000 @@ -5339,12 +669,13 @@ Minimal configuration required: .Pp Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to -communicate with Samba. This is the default behavior for most Linux -distributions. +communicate with Samba. +This is the default behavior for most Linux distributions. .Pp -Samba must be able to authenticate a user. This can be done in a number of -ways, depending on if using the system password file, LDAP or the Samba -specific smbpasswd file. How to do this is outside the scope of this manual. +Samba must be able to authenticate a user. +This can be done in a number of ways, depending on if using the system password file, LDAP or the Samba +specific smbpasswd file. +How to do this is outside the scope of this manual. Please refer to the .Xr smb.conf 5 man page for more information. @@ -5354,7 +685,8 @@ See the of the .Xr smb.conf 5 man page for all configuration options in case you need to modify any options -to the share afterwards. Do note that any changes done with the +to the share afterwards. +Do note that any changes done with the .Xr net 8 command will be undone if the share is ever unshared (such as at a reboot etc). .El @@ -5375,5 +707,6 @@ command will be undone if the share is ever unshared (such as at a reboot etc). .Xr mount 8 , .Xr net 8 , .Xr selinux 8 , -.Xr zfs-program 8 , +.Xr zfsconcepts 8 , +.Xr zfsprops 8 , .Xr zpool 8 |