zfs-recv.8 (15341B)
- .\"
- .\" CDDL HEADER START
- .\"
- .\" The contents of this file are subject to the terms of the
- .\" Common Development and Distribution License (the "License").
- .\" You may not use this file except in compliance with the License.
- .\"
- .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
- .\" or https://opensource.org/licenses/CDDL-1.0.
- .\" See the License for the specific language governing permissions
- .\" and limitations under the License.
- .\"
- .\" When distributing Covered Code, include this CDDL HEADER in each
- .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
- .\" If applicable, add the following below this CDDL HEADER, with the
- .\" fields enclosed by brackets "[]" replaced with your own identifying
- .\" information: Portions Copyright [yyyy] [name of copyright owner]
- .\"
- .\" CDDL HEADER END
- .\"
- .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
- .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
- .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
- .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
- .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
- .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
- .\" Copyright (c) 2014 Integros [integros.com]
- .\" Copyright 2019 Richard Laager. All rights reserved.
- .\" Copyright 2018 Nexenta Systems, Inc.
- .\" Copyright 2019 Joyent, Inc.
- .\"
- .Dd March 12, 2023
- .Dt ZFS-RECEIVE 8
- .Os
- .
- .Sh NAME
- .Nm zfs-receive
- .Nd create snapshot from backup stream
- .Sh SYNOPSIS
- .Nm zfs
- .Cm receive
- .Op Fl FhMnsuv
- .Op Fl o Sy origin Ns = Ns Ar snapshot
- .Op Fl o Ar property Ns = Ns Ar value
- .Op Fl x Ar property
- .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
- .Nm zfs
- .Cm receive
- .Op Fl FhMnsuv
- .Op Fl d Ns | Ns Fl e
- .Op Fl o Sy origin Ns = Ns Ar snapshot
- .Op Fl o Ar property Ns = Ns Ar value
- .Op Fl x Ar property
- .Ar filesystem
- .Nm zfs
- .Cm receive
- .Fl A
- .Ar filesystem Ns | Ns Ar volume
- .Nm zfs
- .Cm receive
- .Fl c
- .Op Fl vn
- .Ar filesystem Ns | Ns Ar snapshot
- .
- .Sh DESCRIPTION
- .Bl -tag -width ""
- .It Xo
- .Nm zfs
- .Cm receive
- .Op Fl FhMnsuv
- .Op Fl o Sy origin Ns = Ns Ar snapshot
- .Op Fl o Ar property Ns = Ns Ar value
- .Op Fl x Ar property
- .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
- .Xc
- .It Xo
- .Nm zfs
- .Cm receive
- .Op Fl FhMnsuv
- .Op Fl d Ns | Ns Fl e
- .Op Fl o Sy origin Ns = Ns Ar snapshot
- .Op Fl o Ar property Ns = Ns Ar value
- .Op Fl x Ar property
- .Ar filesystem
- .Xc
- Creates a snapshot whose contents are as specified in the stream provided on
- standard input.
- If a full stream is received, then a new file system is created as well.
- Streams are created using the
- .Nm zfs Cm send
- subcommand, which by default creates a full stream.
- .Nm zfs Cm recv
- can be used as an alias for
- .Nm zfs Cm receive .
- .Pp
- If an incremental stream is received, then the destination file system must
- already exist, and its most recent snapshot must match the incremental stream's
- source.
- For
- .Sy zvols ,
- the destination device link is destroyed and recreated, which means the
- .Sy zvol
- cannot be accessed during the
- .Cm receive
- operation.
- .Pp
- When a snapshot replication package stream that is generated by using the
- .Nm zfs Cm send Fl R
- command is received, any snapshots that do not exist on the sending location are
- destroyed by using the
- .Nm zfs Cm destroy Fl d
- command.
- .Pp
- The ability to send and receive deduplicated send streams has been removed.
- However, a deduplicated send stream created with older software can be converted
- to a regular (non-deduplicated) stream by using the
- .Nm zstream Cm redup
- command.
- .Pp
- If
- .Fl o Em property Ns = Ns Ar value
- or
- .Fl x Em property
- is specified, it applies to the effective value of the property throughout
- the entire subtree of replicated datasets.
- Effective property values will be set
- .Pq Fl o
- or inherited
- .Pq Fl x
- on the topmost in the replicated subtree.
- In descendant datasets, if the
- property is set by the send stream, it will be overridden by forcing the
- property to be inherited from the top‐most file system.
- Received properties are retained in spite of being overridden
- and may be restored with
- .Nm zfs Cm inherit Fl S .
- Specifying
- .Fl o Sy origin Ns = Ns Em snapshot
- is a special case because, even if
- .Sy origin
- is a read-only property and cannot be set, it's allowed to receive the send
- stream as a clone of the given snapshot.
- .Pp
- Raw encrypted send streams (created with
- .Nm zfs Cm send Fl w )
- may only be received as is, and cannot be re-encrypted, decrypted, or
- recompressed by the receive process.
- Unencrypted streams can be received as
- encrypted datasets, either through inheritance or by specifying encryption
- parameters with the
- .Fl o
- options.
- Note that the
- .Sy keylocation
- property cannot be overridden to
- .Sy prompt
- during a receive.
- This is because the receive process itself is already using
- the standard input for the send stream.
- Instead, the property can be overridden after the receive completes.
- .Pp
- The added security provided by raw sends adds some restrictions to the send
- and receive process.
- ZFS will not allow a mix of raw receives and non-raw receives.
- Specifically, any raw incremental receives that are attempted after
- a non-raw receive will fail.
- Non-raw receives do not have this restriction and,
- therefore, are always possible.
- Because of this, it is best practice to always
- use either raw sends for their security benefits or non-raw sends for their
- flexibility when working with encrypted datasets, but not a combination.
- .Pp
- The reason for this restriction stems from the inherent restrictions of the
- AEAD ciphers that ZFS uses to encrypt data.
- When using ZFS native encryption,
- each block of data is encrypted against a randomly generated number known as
- the "initialization vector" (IV), which is stored in the filesystem metadata.
- This number is required by the encryption algorithms whenever the data is to
- be decrypted.
- Together, all of the IVs provided for all of the blocks in a
- given snapshot are collectively called an "IV set".
- When ZFS performs a raw send, the IV set is transferred from the source
- to the destination in the send stream.
- When ZFS performs a non-raw send, the data is decrypted by the source
- system and re-encrypted by the destination system, creating a snapshot with
- effectively the same data, but a different IV set.
- In order for decryption to work after a raw send, ZFS must ensure that
- the IV set used on both the source and destination side match.
- When an incremental raw receive is performed on
- top of an existing snapshot, ZFS will check to confirm that the "from"
- snapshot on both the source and destination were using the same IV set,
- ensuring the new IV set is consistent.
- .Pp
- The name of the snapshot
- .Pq and file system, if a full stream is received
- that this subcommand creates depends on the argument type and the use of the
- .Fl d
- or
- .Fl e
- options.
- .Pp
- If the argument is a snapshot name, the specified
- .Ar snapshot
- is created.
- If the argument is a file system or volume name, a snapshot with the same name
- as the sent snapshot is created within the specified
- .Ar filesystem
- or
- .Ar volume .
- If neither of the
- .Fl d
- or
- .Fl e
- options are specified, the provided target snapshot name is used exactly as
- provided.
- .Pp
- The
- .Fl d
- and
- .Fl e
- options cause the file system name of the target snapshot to be determined by
- appending a portion of the sent snapshot's name to the specified target
- .Ar filesystem .
- If the
- .Fl d
- option is specified, all but the first element of the sent snapshot's file
- system path
- .Pq usually the pool name
- is used and any required intermediate file systems within the specified one are
- created.
- If the
- .Fl e
- option is specified, then only the last element of the sent snapshot's file
- system name
- .Pq i.e. the name of the source file system itself
- is used as the target file system name.
- .Bl -tag -width "-F"
- .It Fl F
- Force a rollback of the file system to the most recent snapshot before
- performing the receive operation.
- If receiving an incremental replication stream
- .Po for example, one generated by
- .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
- .Pc ,
- destroy snapshots and file systems that do not exist on the sending side.
- .It Fl d
- Discard the first element of the sent snapshot's file system name, using the
- remaining elements to determine the name of the target file system for the new
- snapshot as described in the paragraph above.
- .It Fl e
- Discard all but the last element of the sent snapshot's file system name, using
- that element to determine the name of the target file system for the new
- snapshot as described in the paragraph above.
- .It Fl h
- Skip the receive of holds.
- There is no effect if holds are not sent.
- .It Fl M
- Force an unmount of the file system while receiving a snapshot.
- This option is not supported on Linux.
- .It Fl n
- Do not actually receive the stream.
- This can be useful in conjunction with the
- .Fl v
- option to verify the name the receive operation would use.
- .It Fl o Sy origin Ns = Ns Ar snapshot
- Forces the stream to be received as a clone of the given snapshot.
- If the stream is a full send stream, this will create the filesystem
- described by the stream as a clone of the specified snapshot.
- Which snapshot was specified will not affect the success or failure of the
- receive, as long as the snapshot does exist.
- If the stream is an incremental send stream, all the normal verification will be
- performed.
- .It Fl o Em property Ns = Ns Ar value
- Sets the specified property as if the command
- .Nm zfs Cm set Em property Ns = Ns Ar value
- was invoked immediately before the receive.
- When receiving a stream from
- .Nm zfs Cm send Fl R ,
- causes the property to be inherited by all descendant datasets, as through
- .Nm zfs Cm inherit Em property
- was run on any descendant datasets that have this property set on the
- sending system.
- .Pp
- If the send stream was sent with
- .Fl c
- then overriding the
- .Sy compression
- property will have no effect on received data but the
- .Sy compression
- property will be set.
- To have the data recompressed on receive remove the
- .Fl c
- flag from the send stream.
- .Pp
- Any editable property can be set at receive time.
- Set-once properties bound
- to the received data, such as
- .Sy normalization
- and
- .Sy casesensitivity ,
- cannot be set at receive time even when the datasets are newly created by
- .Nm zfs Cm receive .
- Additionally both settable properties
- .Sy version
- and
- .Sy volsize
- cannot be set at receive time.
- .Pp
- The
- .Fl o
- option may be specified multiple times, for different properties.
- An error results if the same property is specified in multiple
- .Fl o
- or
- .Fl x
- options.
- .Pp
- The
- .Fl o
- option may also be used to override encryption properties upon initial receive.
- This allows unencrypted streams to be received as encrypted datasets.
- To cause the received dataset (or root dataset of a recursive stream) to be
- received as an encryption root, specify encryption properties in the same
- manner as is required for
- .Nm zfs Cm create .
- For instance:
- .Dl # Nm zfs Cm send Pa tank/test@snap1 | Nm zfs Cm recv Fl o Sy encryption Ns = Ns Sy on Fl o Sy keyformat Ns = Ns Sy passphrase Fl o Sy keylocation Ns = Ns Pa file:///path/to/keyfile
- .Pp
- Note that
- .Fl o Sy keylocation Ns = Ns Sy prompt
- may not be specified here, since the standard input
- is already being utilized for the send stream.
- Once the receive has completed, you can use
- .Nm zfs Cm set
- to change this setting after the fact.
- Similarly, you can receive a dataset as an encrypted child by specifying
- .Fl x Sy encryption
- to force the property to be inherited.
- Overriding encryption properties (except for
- .Sy keylocation )
- is not possible with raw send streams.
- .It Fl s
- If the receive is interrupted, save the partially received state, rather
- than deleting it.
- Interruption may be due to premature termination of the stream
- .Po e.g. due to network failure or failure of the remote system
- if the stream is being read over a network connection
- .Pc ,
- a checksum error in the stream, termination of the
- .Nm zfs Cm receive
- process, or unclean shutdown of the system.
- .Pp
- The receive can be resumed with a stream generated by
- .Nm zfs Cm send Fl t Ar token ,
- where the
- .Ar token
- is the value of the
- .Sy receive_resume_token
- property of the filesystem or volume which is received into.
- .Pp
- To use this flag, the storage pool must have the
- .Sy extensible_dataset
- feature enabled.
- See
- .Xr zpool-features 7
- for details on ZFS feature flags.
- .It Fl u
- File system that is associated with the received stream is not mounted.
- .It Fl v
- Print verbose information about the stream and the time required to perform the
- receive operation.
- .It Fl x Em property
- Ensures that the effective value of the specified property after the
- receive is unaffected by the value of that property in the send stream (if any),
- as if the property had been excluded from the send stream.
- .Pp
- If the specified property is not present in the send stream, this option does
- nothing.
- .Pp
- If a received property needs to be overridden, the effective value will be
- set or inherited, depending on whether the property is inheritable or not.
- .Pp
- In the case of an incremental update,
- .Fl x
- leaves any existing local setting or explicit inheritance unchanged.
- .Pp
- All
- .Fl o
- restrictions (e.g. set-once) apply equally to
- .Fl x .
- .El
- .It Xo
- .Nm zfs
- .Cm receive
- .Fl A
- .Ar filesystem Ns | Ns Ar volume
- .Xc
- Abort an interrupted
- .Nm zfs Cm receive Fl s ,
- deleting its saved partially received state.
- .It Xo
- .Nm zfs
- .Cm receive
- .Fl c
- .Op Fl vn
- .Ar filesystem Ns | Ns Ar snapshot
- .Xc
- Attempt to repair data corruption in the specified dataset,
- by using the provided stream as the source of healthy data.
- This method of healing can only heal data blocks present in the stream.
- Metadata can not be healed by corrective receive.
- Running a scrub is recommended post-healing to ensure all data corruption was
- repaired.
- .Pp
- It's important to consider why corruption has happened in the first place.
- If you have slowly failing hardware - periodically repairing the data
- is not going to save you from data loss later on when the hardware fails
- completely.
- .El
- .
- .Sh EXAMPLES
- .\" These are, respectively, examples 12, 13 from zfs.8
- .\" Make sure to update them bidirectionally
- .Ss Example 1 : No Remotely Replicating ZFS Data
- The following commands send a full stream and then an incremental stream to a
- remote machine, restoring them into
- .Em poolB/received/fs@a
- and
- .Em poolB/received/fs@b ,
- respectively.
- .Em poolB
- must contain the file system
- .Em poolB/received ,
- and must not initially contain
- .Em poolB/received/fs .
- .Bd -literal -compact -offset Ds
- .No # Nm zfs Cm send Ar pool/fs@a |
- .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs Ns @ Ns Ar a
- .No # Nm zfs Cm send Fl i Ar a pool/fs@b |
- .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs
- .Ed
- .
- .Ss Example 2 : No Using the Nm zfs Cm receive Fl d No Option
- The following command sends a full stream of
- .Ar poolA/fsA/fsB@snap
- to a remote machine, receiving it into
- .Ar poolB/received/fsA/fsB@snap .
- The
- .Ar fsA/fsB@snap
- portion of the received snapshot's name is determined from the name of the sent
- snapshot.
- .Ar poolB
- must contain the file system
- .Ar poolB/received .
- If
- .Ar poolB/received/fsA
- does not exist, it is created as an empty file system.
- .Bd -literal -compact -offset Ds
- .No # Nm zfs Cm send Ar poolA/fsA/fsB@snap |
- .No " " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received
- .Ed
- .
- .Sh SEE ALSO
- .Xr zfs-send 8 ,
- .Xr zstream 8