.\"
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
-.\" Copyright (c) 2011, 2016 by Delphix. All rights reserved.
+.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
.\" Copyright (c) 2014 Integros [integros.com]
-.\" Copyright 2016 Richard Laager. All rights reserved.
-.\" Copyright 2017 Nexenta Systems, Inc.
+.\" Copyright 2019 Richard Laager. All rights reserved.
+.\" Copyright 2018 Nexenta Systems, Inc.
+.\" Copyright 2019 Joyent, Inc.
.\"
-.Dd June 28, 2017
+.Dd June 30, 2019
.Dt ZFS 8 SMM
.Os Linux
.Sh NAME
.Nd configures ZFS file systems
.Sh SYNOPSIS
.Nm
-.Fl ?
+.Fl ?V
.Nm
.Cm create
-.Op Fl p
+.Op Fl Pnpv
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Ar filesystem
.Nm
.Cm create
-.Op Fl ps
+.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 snapshot
.Op Fl r
-.Oo Fl o Ar property Ns = Ns value Oc Ns ...
+.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
.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
-.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
+.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ...
.Nm
.Cm inherit
.Op Fl rS
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar snapshot
.Nm
+.Cm projectspace
+.Op Fl Hp
+.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
+.Oo Fl s Ar field Oc Ns ...
+.Oo Fl S Ar field Oc Ns ...
+.Ar filesystem Ns | Ns Ar snapshot
+.Nm
+.Cm project
+.Oo Fl d Ns | Ns Fl r Ns Oc
+.Ar file Ns | Ns Ar directory Ns ...
+.Nm
+.Cm project
+.Fl C
+.Oo Fl kr Ns Oc
+.Ar file Ns | Ns Ar directory Ns ...
+.Nm
+.Cm project
+.Fl c
+.Oo Fl 0 Ns Oc
+.Oo Fl d Ns | Ns Fl r Ns Oc
+.Op Fl p Ar id
+.Ar file Ns | Ns Ar directory Ns ...
+.Nm
+.Cm project
+.Op Fl p Ar id
+.Oo Fl rs Ns Oc
+.Ar file Ns | Ns Ar directory Ns ...
+.Nm
.Cm mount
.Nm
.Cm mount
-.Op Fl Olv
+.Op Fl Oflv
.Op Fl o Ar options
.Fl a | Ar filesystem
.Nm
.Cm unmount
-.Op Fl f
+.Op Fl fu
.Fl a | Ar filesystem Ns | Ns Ar mountpoint
.Nm
.Cm share
.Ar snapshot bookmark
.Nm
.Cm send
-.Op Fl DLPRcenpvw
+.Op Fl DLPRbcehnpvw
.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
.Ar snapshot
.Nm
.Cm send
-.Op Fl LPcenvw
-.Op Fl i Ar snapshot Ns | Ns Ar bookmark
+.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 Fnsuv
+.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 Fnsuv
+.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
.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
.Ar tag Ar snapshot Ns ...
.Nm
.Cm holds
-.Op Fl r
+.Op Fl rH
.Ar snapshot Ns ...
.Nm
.Cm release
.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 i
.Op Fl l
.Ar filesystem
+.Nm
+.Cm version
.Sh DESCRIPTION
The
.Nm
.Pp
where the maximum length of a dataset name is
.Dv MAXNAMELEN
-.Pq 256 bytes .
+.Pq 256 bytes
+and the maximum amount of nesting allowed in a path is 50 levels deep.
.Pp
A dataset can be one of the following:
.Bl -tag -width "file system"
behavior when checking file system free space.
.It Sy volume
A logical volume exported as a raw or block device.
-This type of dataset should only be used under special circumstances.
+This type of dataset should only be used when a block device is required.
File systems are typically used in most environments.
.It Sy snapshot
A read-only version of a file system or volume at a given point in time.
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.
+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 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.
.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.
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
.Pp
The
.Sy aclinherit
-property does not apply to posix ACLs.
+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"
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
+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
.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 of this all new extended attributes will only be
+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
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.
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
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 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
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
+.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
.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
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
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
+.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
.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
.Sy on ,
the dataset is shared using the default options:
.Pp
-.Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash
+.Em sec=sys,rw,crossmnt,no_subtree_check
.Pp
See
.Xr exports 5
Though not recommended, a
.Qq sparse volume
.Po also known as
-.Qq thin provisioning
+.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 reservation after the volume has been created.
+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 reservation is less then the volume size.
+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 reservation.
+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
hides its partitions.
Volumes with property set to
.Sy none
-are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc,
+are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
that can be suitable for backup purposes.
Value
.Sy default
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
+SELinux or POSIX ACLs. Both of these features heavily rely of extended
attributes and benefit significantly from the reduced access time.
.Pp
The values
.Ss Encryption
Enabling the
.Sy encryption
-feature allows for the creation of encrypted filesystems and volumes.
-.Nm
-will encrypt all user data including file and zvol data, file attributes,
-ACLs, permission bits, directory listings, FUID mappings, and userused /
-groupused data.
-.Nm
-will not encrypt metadata related to the pool structure, including dataset
-names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
-is managed internally by the kernel module and changing the user's key does not
-require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
-renamed, and deleted without the encryption keys being loaded (see the
+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
and
.Sy keyformat
properties at creation time, along with an optional
-.Sy
-keylocation
+.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, meaning that loading,
-unloading, or changing the key for the encryption root will implicitly do the
-same for all inheriting datasets. If this inheritence is not desired, simply
-supply a new
-.Sy encryption
-and
+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 the relationship. The one exception is that clones will always use
-their origin's encryption key. Encryption root inheritence can be tracked via
-the read-only
+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
-.Nm
+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
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.
.Sh SUBCOMMANDS
All subcommands that modify state are logged persistently to the pool in their
original form.
Displays a help message.
.It Xo
.Nm
+.Fl V, -version
+.Xc
+An alias for the
+.Nm zfs Cm version
+subcommand.
+.It Xo
+.Nm
.Cm create
-.Op Fl p
+.Op Fl Pnpv
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Ar filesystem
.Xc
.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
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
.Nm
.Fl d
flag will have no effect.
.It Fl d
-Defer snapshot deletion.
+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
.Nm
.Cm snapshot
.Op Fl r
-.Oo Fl o Ar property Ns = Ns value Oc Ns ...
+.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
Creates snapshots with the given names.
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.
.Po the default is
.Sy off
.Pc .
-The following fields are displayed,
-.Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
-.Sy mountpoint .
+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.
value of the property.
The property must be one of the properties described in the
.Sx Properties
-section, or the special value
+section or the value
.Sy name
to sort by the dataset name.
Multiple properties can be specified at one time using multiple
.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
-.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
+.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
name Dataset name
property Property name
value Property value
- source Property source. Can either be local, default,
- temporary, inherited, or none (-).
+ 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
.Sx User Properties
sections.
.Pp
-The special value
+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 .
.Sy default ,
.Sy inherited ,
.Sy temporary ,
+.Sy received ,
and
.Sy none .
The default value is all sources.
.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 Olv
+.Op Fl Oflv
.Op Fl o Ar options
.Fl a | Ar filesystem
.Xc
-Mounts ZFS file systems.
+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.
+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.
+Invoked automatically as part of the boot process if configured.
.It Ar filesystem
Mount the specified filesystem.
.It Fl o Ar options
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 f
+.Op Fl fu
.Fl a | Ar filesystem Ns | Ns Ar mountpoint
.Xc
Unmounts currently mounted ZFS file systems.
.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 Fl f
-Forcefully unmount the file system, even if it is currently in use.
-.El
.It Xo
.Nm
.Cm share
.It Xo
.Nm
.Cm send
-.Op Fl DLPRcenpvw
+.Op Fl DLPRbcehnpvw
.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
.Ar snapshot
.Xc
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.
+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
If the
.Sy lz4_compress
feature is active on the sending system, then the receiving system must have
-that feature enabled as well.
+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
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
This flag is implicit when
.Fl R
is specified.
-The receiving system must also support this feature.
+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.
.It Xo
.Nm
.Cm send
-.Op Fl LPcenvw
+.Op Fl DLPRcenpvw
.Op Fl i Ar snapshot Ns | Ns Ar bookmark
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
.Xc
If the
.Sy lz4_compress
feature is active on the sending system, then the receiving system must have
-that feature enabled as well. Note that streams generated using this flag are
-unable to be received into an encrypted dataset.
+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
.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
.It Xo
.Nm
.Cm receive
-.Op Fl Fnsuv
+.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
.It Xo
.Nm
.Cm receive
-.Op Fl Fnsuv
+.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
command.
.Pp
If
-.Sy Fl o Em property=value
+.Fl o Em property Ns = Ns Ar value
or
-.Sy Fl x Em property
+.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 (
are retained in spite of being overridden and may be restored with
.Nm zfs Cm inherit Fl S .
Specifying
-.Sy Fl o Em origin=snapshot
+.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
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
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=value
+.It Fl o Em property Ns = Ns Ar value
Sets the specified property as if the command
-.Nm zfs Cm set Em property=value
+.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
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.
.Pp
All
.Fl o
-restrictions on set-once and special properties apply equally to
+restrictions (e.g. set-once) apply equally to
.Fl x .
.El
.It Xo
deleting its saved partially received state.
.It Xo
.Nm
+.Cm redact
+.Ar snapshot redaction_bookmark
+.Ar redaction_snapshot Ns ...
+.Xc
+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
.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
-.br
+.Xc
+.It Xo
.Nm
.Cm allow
.Op Fl dl
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
+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
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
.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
-.br
+.Xc
+.It Xo
.Nm
.Cm unallow
.Op Fl dlr
.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
-.br
+.Xc
+.It Xo
.Nm
.Cm unallow
.Op Fl r
.It Xo
.Nm
.Cm holds
-.Op Fl r
+.Op Fl rH
.Ar snapshot Ns ...
.Xc
Lists all existing user references for the given snapshot or snapshots.
.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.
.El
.It Xo
.Nm
.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 .
+.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
inherit the key of its parent. Note that this command can only be run on an
encryption root that has an encrypted parent.
.El
+.It Xo
+.Nm
+.Cm version
+.Xc
+Displays the software version of the
+.Nm
+userland utility and the zfs kernel module.
.El
.Sh EXIT STATUS
The
# zfs destroy -r pool/users@7daysago
# zfs rename -r pool/users@6daysago @7daysago
# zfs rename -r pool/users@5daysago @6daysago
-# zfs rename -r pool/users@yesterday @5daysago
-# zfs rename -r pool/users@yesterday @4daysago
-# zfs rename -r pool/users@yesterday @3daysago
+# zfs rename -r pool/users@4daysago @5daysago
+# zfs rename -r pool/users@3daysago @4daysago
+# zfs rename -r pool/users@2daysago @3daysago
# zfs rename -r pool/users@yesterday @2daysago
# zfs rename -r pool/users@today @yesterday
# zfs snapshot -r pool/users@today
.Sh INTERFACE STABILITY
.Sy Committed .
.Sh SEE ALSO
+.Xr attr 1 ,
.Xr gzip 1 ,
.Xr ssh 1 ,
-.Xr mount 8 ,
-.Xr zpool 8 ,
-.Xr selinux 8 ,
.Xr chmod 2 ,
+.Xr fsync 2 ,
.Xr stat 2 ,
.Xr write 2 ,
-.Xr fsync 2 ,
-.Xr attr 1 ,
.Xr acl 5 ,
+.Xr attributes 5 ,
.Xr exports 5 ,
.Xr exportfs 8 ,
+.Xr mount 8 ,
.Xr net 8 ,
-.Xr attributes 5
+.Xr selinux 8 ,
+.Xr zfs-program 8 ,
+.Xr zpool 8