Ubuntu Manpage: zfs-send — generate backup stream of ZFS dataset

Provided by: zfsutils-linux_2.1.5-1ubuntu6~22.04.5_amd64

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.

-P, --parsable
Print machine-parsable verbose information about the stream package generated.

-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.

-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.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO