.\"
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
-.\" Copyright (c) 2011, 2017 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 2018 Joyent, Inc.
+.\" Copyright 2019 Richard Laager. All rights reserved.
+.\" Copyright 2018 Nexenta Systems, Inc.
+.\" Copyright 2019 Joyent, Inc.
.\"
-.Dd January 10, 2018
+.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
.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
.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 DLPRbcenpvw
+.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
.Nm
.Cm program
.Op Fl jn
-.Op Fl t Ar timeout
-.Op Fl m Ar memory_limit
+.Op Fl t Ar instruction-limit
+.Op Fl m Ar memory-limit
.Ar pool script
-.Op Ar arg1 No ...
+.Op --
+.Ar arg1 No ...
.Nm
.Cm load-key
.Op Fl nr
.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.
.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.
.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.
.Pp
Changing this property affects only newly-written data.
-.Pp
-Salted checksum algorithms
-.Pq Cm edonr , skein
-are currently not supported for any filesystem on the boot pools.
.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
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
.Pp
If set to
.Sy verify ,
-ZFS will do a byte-to-byte comparsion in case of two blocks having the same
+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
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
.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
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
.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
.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.
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 childrens. It will
+Show the directory project ID and inherit flag, not its children. It will
overwrite the former specified
.Fl r
option.
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 childrens. It will
+Check the directory project ID and inherit flag, not its children. It will
overwrite the former specified
.Fl r
option.
.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 DLPRbcenpvw
+.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
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
.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
.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
encrypted datasets, either through inheritance or by specifying encryption
parameters with the
.Fl o
-options.
+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
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
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
.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
.Nm
.Cm program
.Op Fl jn
-.Op Fl t Ar timeout
-.Op Fl m Ar memory_limit
+.Op Fl t Ar instruction-limit
+.Op Fl m Ar memory-limit
.Ar pool script
-.Op Ar arg1 No ...
+.Op --
+.Ar arg1 No ...
.Xc
Executes
.Ar script
determining if changes would succeed (zfs.check.*).
Without this flag, all pending changes must be synced to disk before
a channel program can complete.
-.It Fl t Ar timeout
-Execution time limit, in milliseconds.
-If a channel program executes for longer than the provided timeout, it will
-be stopped and an error will be returned.
-The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
+.It Fl 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,
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
.Xr mount 8 ,
.Xr net 8 ,
.Xr selinux 8 ,
+.Xr zfs-program 8 ,
.Xr zpool 8
projects / zfs / blobdiff