375 lines
13 KiB
Groff
375 lines
13 KiB
Groff
.\"
|
||
.\" 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 http://www.opensolaris.org/os/licensing.
|
||
.\" 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 February 16, 2020
|
||
.Dt ZFS-RECEIVE 8
|
||
.Os
|
||
.Sh NAME
|
||
.Nm zfs-receive
|
||
.Nd Creates a snapshot whose contents are as specified in the stream provided on standard input.
|
||
.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
|
||
.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 (
|
||
.Fl o
|
||
) or inherited (
|
||
.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
|
||
stdin 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
|
||
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:
|
||
.Bd -literal
|
||
# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile
|
||
.Ed
|
||
.Pp
|
||
Note that
|
||
.Op Fl o Ar keylocation Ns = Ns Ar prompt
|
||
may not be specified here, since stdin 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
|
||
.Op Fl x Ar encryption
|
||
to force the property to be inherited. Overriding encryption properties (except
|
||
for
|
||
.Sy keylocation Ns )
|
||
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 5
|
||
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.
|
||
.El
|
||
.Sh SEE ALSO
|
||
.Xr zfs-send 8
|
||
.Xr zstream 8
|