ZFS-SEND(8) FreeBSD System Manager's Manual ZFS-SEND(8)
NAME
zfs-send - generate backup stream of ZFS dataset
SYNOPSIS
zfs send [-DLPRbcehnpsvw] [[-I|-i] snapshot] snapshot
zfs send [-DLPcensvw] [-i snapshot|bookmark] filesystem|volume|snapshot
zfs send --redact redaction_bookmark [-DLPcenpv] [-i snapshot|bookmark]
snapshot
zfs send [-Penv] -t receive_resume_token
zfs send [-Pnv] -S filesystem
zfs redact snapshot redaction_bookmark redaction_snapshot<?>
DESCRIPTION
zfs send [-DLPRbcehnpvw] [[-I|-i] snapshot] snapshot
Creates a stream representation of the second snapshot, which is
written to standard output. The output can be redirected to a file or
to a different system (for example, using ssh(1)). By default, a full
stream is generated.
-D, --dedup
Deduplicated send is no longer supported. This flag is accepted
for backwards compatibility, but a regular, non-deduplicated stream
will be generated.
-I snapshot
Generate a stream package that sends all intermediary snapshots
from the first snapshot to the second snapshot. For example, -I @a
fs@d is similar to -i @a fs@b; -i @b fs@c; -i @c fs@d. The
incremental source may be specified as with the -i option.
-L, --large-block
Generate a stream which may contain blocks larger than 128KB. This
flag has no effect if the large_blocks pool feature is disabled, or
if the recordsize property of this filesystem has never been set
above 128KB. The receiving system must have the large_blocks pool
feature enabled as well. See zpool-features(7) for details on ZFS
feature flags and the large_blocks feature.
-P, --parsable
Print machine-parsable verbose information about the stream package
generated.
-R, --replicate
Generate a replication stream package, which will replicate the
specified file system, and all descendent file systems, up to the
named snapshot. When received, all properties, snapshots,
descendent file systems, and clones are preserved.
If the -i or -I flags are used in conjunction with the -R flag, an
incremental replication stream is generated. The current values of
properties, and current snapshot and file system names are set when
the stream is received. If the -F flag is specified when this
stream is received, snapshots and file systems that do not exist on
the sending side are destroyed. If the -R flag is used to send
encrypted datasets, then -w must also be specified.
-e, --embed
Generate a more compact stream by using WRITE_EMBEDDED records for
blocks which are stored more compactly on disk by the embedded_data
pool feature. This flag has no effect if the embedded_data feature
is disabled. The receiving system must have the embedded_data
feature enabled. If the lz4_compress feature is active on the
sending system, then the receiving system must have that feature
enabled as well. Datasets that are sent with this flag may not be
received as an encrypted dataset, since encrypted datasets cannot
use the embedded_data feature. See zpool-features(7) for details
on ZFS feature flags and the embedded_data feature.
-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 zfs 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.
-c, --compressed
Generate a more compact stream by using compressed WRITE records
for blocks which are compressed on disk and in memory (see the
compression property for details). If the lz4_compress feature is
active on the sending system, then the receiving system must have
that feature enabled as well. If the large_blocks feature is
enabled on the sending system but the -L option is not supplied in
conjunction with -c, then the data will be decompressed before
sending so it can be split into smaller block sizes. Streams sent
with -c will not have their data recompressed on the receiver side
using -o compress= value. The data will stay compressed as it was
from the sender. The new compression property will be set for
future data.
-w, --raw
For encrypted datasets, send data exactly as it exists on disk.
This allows backups to be taken even if encryption keys are not
currently loaded. The backup may then be received on an untrusted
machine since that machine will not have the encryption keys to
read the protected data or alter it without being detected. Upon
being received, the dataset will have the same encryption keys as
it did on the send side, although the keylocation property will be
defaulted to prompt if not otherwise provided. For unencrypted
datasets, this flag will be equivalent to -Lec. Note that if you
do not use this flag for sending encrypted datasets, data will be
sent unencrypted and may be re-encrypted with a different
encryption key on the receiving system, which will disable the
ability to do a raw send to that system for incrementals.
-h, --holds
Generate a stream package that includes any snapshot holds (created
with the zfs hold command), and indicating to zfs receive that the
holds be applied to the dataset on the receiving system.
-i snapshot
Generate an incremental stream from the first snapshot (the
incremental source) to the second snapshot (the incremental
target). The incremental source can be specified as the last
component of the snapshot name (the @ character and following) and
it is assumed to be from the same file system as the incremental
target.
If the destination is a clone, the source may be the origin
snapshot, which must be fully specified (for example,
pool/fs@origin, not just @origin).
-n, --dryrun
Do a dry-run ("No-op") send. Do not generate any actual send data.
This is useful in conjunction with the -v or -P flags to determine
what data will be sent. In this case, the verbose output will be
written to standard output (contrast with a non-dry-run, where the
stream is written to standard output and the verbose output goes to
standard error).
-p, --props
Include the dataset's properties in the stream. This flag is
implicit when -R is specified. The receiving system must also
support this feature. Sends of encrypted datasets must use -w when
using this flag.
-s, --skip-missing
Allows sending a replication stream even when there are snapshots
missing in the hierarchy. When a snapshot is missing, instead of
throwing an error and aborting the send, a warning is printed to
the standard error stream and the dataset to which it belongs and
its descendents are skipped. This flag can only be used in
conjunction with -R.
-v, --verbose
Print verbose information about the stream package generated. This
information includes a per-second report of how much data has been
sent.
The format of the stream is committed. You will be able to receive
your streams on future versions of ZFS.
zfs send [-DLPcenvw] [-i snapshot|bookmark] filesystem|volume|snapshot
Generate a send stream, which may be of a filesystem, and may be
incremental from a bookmark. If the destination is a filesystem or
volume, the pool must be read-only, or the filesystem must not be
mounted. When the stream generated from a filesystem or volume is
received, the default snapshot name will be "--head--".
-D, --dedup
Deduplicated send is no longer supported. This flag is accepted
for backwards compatibility, but a regular, non-deduplicated stream
will be generated.
-L, --large-block
Generate a stream which may contain blocks larger than 128KB. This
flag has no effect if the large_blocks pool feature is disabled, or
if the recordsize property of this filesystem has never been set
above 128KB. The receiving system must have the large_blocks pool
feature enabled as well. See zpool-features(7) for details on ZFS
feature flags and the large_blocks feature.
-P, --parsable
Print machine-parsable verbose information about the stream package
generated.
-c, --compressed
Generate a more compact stream by using compressed WRITE records
for blocks which are compressed on disk and in memory (see the
compression property for details). If the lz4_compress feature is
active on the sending system, then the receiving system must have
that feature enabled as well. If the large_blocks feature is
enabled on the sending system but the -L option is not supplied in
conjunction with -c, then the data will be decompressed before
sending so it can be split into smaller block sizes.
-w, --raw
For encrypted datasets, send data exactly as it exists on disk.
This allows backups to be taken even if encryption keys are not
currently loaded. The backup may then be received on an untrusted
machine since that machine will not have the encryption keys to
read the protected data or alter it without being detected. Upon
being received, the dataset will have the same encryption keys as
it did on the send side, although the keylocation property will be
defaulted to prompt if not otherwise provided. For unencrypted
datasets, this flag will be equivalent to -Lec. Note that if you
do not use this flag for sending encrypted datasets, data will be
sent unencrypted and may be re-encrypted with a different
encryption key on the receiving system, which will disable the
ability to do a raw send to that system for incrementals.
-e, --embed
Generate a more compact stream by using WRITE_EMBEDDED records for
blocks which are stored more compactly on disk by the embedded_data
pool feature. This flag has no effect if the embedded_data feature
is disabled. The receiving system must have the embedded_data
feature enabled. If the lz4_compress feature is active on the
sending system, then the receiving system must have that feature
enabled as well. Datasets that are sent with this flag may not be
received as an encrypted dataset, since encrypted datasets cannot
use the embedded_data feature. See zpool-features(7) for details
on ZFS feature flags and the embedded_data feature.
-i snapshot|bookmark
Generate an incremental send stream. The incremental source must
be an earlier snapshot in the destination's history. It will
commonly be an earlier snapshot in the destination's file system,
in which case it can be specified as the last component of the name
(the # or @ character and following).
If the incremental target is a clone, the incremental source can be
the origin snapshot, or an earlier snapshot in the origin's
filesystem, or the origin's origin, etc.
-n, --dryrun
Do a dry-run ("No-op") send. Do not generate any actual send data.
This is useful in conjunction with the -v or -P flags to determine
what data will be sent. In this case, the verbose output will be
written to standard output (contrast with a non-dry-run, where the
stream is written to standard output and the verbose output goes to
standard error).
-v, --verbose
Print verbose information about the stream package generated. This
information includes a per-second report of how much data has been
sent.
zfs send --redact redaction_bookmark [-DLPcenpv] [-i snapshot|bookmark]
snapshot
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 --redact (or -d) flag. The
resulting send stream is said to be redacted with respect to the
snapshots the bookmark specified by the --redact flag was created with.
The bookmark must have been created by running zfs redact on the
snapshot being sent.
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.
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:
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.
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.
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.
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.
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.
These restrictions are detected and enforced by zfs receive; 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.
zfs send [-Penv] -t receive_resume_token
Creates a send stream which resumes an interrupted receive. The
receive_resume_token is the value of this property on the filesystem or
volume that was being received into. See the documentation for zfs
receive -s for more details.
zfs send [-Pnv] [-i snapshot|bookmark] -S filesystem
Generate a send stream from a dataset that has been partially received.
-S, --saved
This flag requires that the specified filesystem previously
received a resumable send that did not finish and was interrupted.
In such scenarios this flag enables the user to send this partially
received state. Using this flag will always use the last fully
received snapshot as the incremental source if it exists.
zfs redact snapshot redaction_bookmark redaction_snapshot<?>
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 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.
Redaction
ZFS has support for a limited version of data subsetting, in the form of
redaction. Using the zfs redact command, a redaction bookmark can be
created that stores a list of blocks containing sensitive information.
When provided to zfs send, this causes a redacted send to occur.
Redacted sends omit the blocks containing sensitive information,
replacing them with REDACT records. When these send streams are
received, a 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.
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 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.
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 sent 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.
SEE ALSO
zfs-bookmark(8), zfs-receive(8), zfs-redact(8), zfs-snapshot(8)
FreeBSD 13.1-RELEASE-p6 April 15, 2021 FreeBSD 13.1-RELEASE-p6
man2web Home...