Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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_snapshota|

DESCRIPTION
     zfs send [-DLPRbcehnpvw] [[-I|-i] snapshot] snapshot
       Creates a stream	representation of the second snapshot, which is	writ-
       ten 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 incre-
	   mental 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, descen-
	   dent	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 en-
	   crypted 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 fea-
	   ture	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 over-
	   ridden by local settings, but only if the dataset has ever been re-
	   ceived.  Use	this option when you want zfs receive to restore re-
	   ceived properties backed up on the sent dataset and to avoid	send-
	   ing 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 en-
	   abled 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 fu-
	   ture	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 encryp-
	   tion	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 com-
	   ponent of the snapshot name (the @ character	and following) and it
	   is assumed to be from the same file system as the incremental tar-
	   get.

	   If the destination is a clone, the source may be the	origin snap-
	   shot, 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 im-
	   plicit when -R is specified.	 The receiving system must also	sup-
	   port	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 con-
	   junction 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	incre-
       mental 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 en-
	   abled 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 encryp-
	   tion	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 fea-
	   ture	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 com-
	   monly 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	snap-
       shots 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 snap-
	   shot	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 pro-
	   duce	a normal snapshot, which can be	used just like other snap-
	   shots.

       2.  To receive an incremental send from the original snapshot to	some-
	   thing 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 (redact-
	   ing with respect to additional snapshots causes less	data to	be
	   redacted (because the snapshots define what is permitted, and ev-
	   erything 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 ini-
	   tial	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 ei-
	   ther	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 re-
	   ceived 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 re-
	   ceived snapshot as the incremental source if	it exists.

     zfs redact	snapshot redaction_bookmark redaction_snapshota|
       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 er-
       ror 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, replac-
     ing them with REDACT records.  When these send streams are	received, a
     redacted dataset is created.  A redacted dataset cannot be	mounted	by de-
     fault, since it is	incomplete.  It	can be used to receive other send
     streams.  In this way datasets can	be used	for data backup	and replica-
     tion, 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 in-
     formation.	 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 cre-
     ate 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	snap-
     shot that can be used normally.  Incrementals from	one snapshot on	the
     parent filesystem and another can also be done by sending from the	redac-
     tion 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 prefer-
     ences.  The owner of this data wants to make it available for their de-
     velopment teams to	test against, and their	market research	teams to do
     analysis on.  The development teams need information about	user prefer-
     ences 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 to-
     gether.  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 redac-
     tion 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.  Fi-
     nally, 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.0			April 15, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zfs-redact&sektion=8&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help