.\" 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 2019 Richard Laager. All rights reserved.
.\" Copyright 2018 Nexenta Systems, Inc.
-.\" Copyright 2018 Joyent, Inc.
+.\" Copyright 2019 Joyent, Inc.
.\"
-.Dd Jan 05, 2019
+.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
.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
.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
.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
.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
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.
with a send/receive operation.
The
.Sy objsetid
-can be reused (for a new datatset) after the dataset is deleted.
+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.
and
.Sy edonr
checksum algorithms require enabling the appropriate features on the pool.
-These algorithms are not supported by GRUB and should not be set on the
-.Sy bootfs
-filesystem when using GRUB to boot the system.
+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.
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
.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
.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
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
.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 .
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
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 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
.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
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
.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
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
.Xr mount 8 ,
.Xr net 8 ,
.Xr selinux 8 ,
+.Xr zfs-program 8 ,
.Xr zpool 8
projects / zfs / blobdiff