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 a send stream, which may be of a filesystem, and may
     be	incremental from a bookmark.

SYNOPSIS
     zfs send [-DLPRbcehnpvw] [[-I|-i] snapshot] snapshot
     zfs send [-DLPRcenpvw] [-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	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(5) 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(5) 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 us-
	   ing this flag.

       -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 [-DLPRcenpvw] [-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--".

       -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(5) 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(5) 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
       snapshots the bookmark specified	by the --redact	flag was created with.
       The bookmark must have been created by running zfs redact on the	snap-
       shot 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 produce a normal snapshot,
       which can be used just like other snapshots.

       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 (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	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 either	pro-
       duce 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_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 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 cre-
     ated 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 ser-
     vices.

     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 cre-
     ated. 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 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 re-
     ceived 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 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 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.

SEE ALSO
     zfs-bookmark(8), zfs-receive(8), zfs-redact(8), zfs-snapshot(8)

FreeBSD	13.0			 June 30, 2019			  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-send&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help