4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or https://opensource.org/licenses/CDDL-1.0.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
21 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
22 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
23 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
24 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
25 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
26 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
27 .\" Copyright (c) 2014 Integros [integros.com]
28 .\" Copyright 2019 Richard Laager. All rights reserved.
29 .\" Copyright 2018 Nexenta Systems, Inc.
30 .\" Copyright 2019 Joyent, Inc.
38 .Nd create snapshot from backup stream
43 .Op Fl o Sy origin Ns = Ns Ar snapshot
44 .Op Fl o Ar property Ns = Ns Ar value
46 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
51 .Op Fl o Sy origin Ns = Ns Ar snapshot
52 .Op Fl o Ar property Ns = Ns Ar value
58 .Ar filesystem Ns | Ns Ar volume
64 .Ar filesystem Ns | Ns Ar snapshot
72 .Op Fl o Sy origin Ns = Ns Ar snapshot
73 .Op Fl o Ar property Ns = Ns Ar value
75 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
82 .Op Fl o Sy origin Ns = Ns Ar snapshot
83 .Op Fl o Ar property Ns = Ns Ar value
87 Creates a snapshot whose contents are as specified in the stream provided on
89 If a full stream is received, then a new file system is created as well.
90 Streams are created using the
92 subcommand, which by default creates a full stream.
94 can be used as an alias for
97 If an incremental stream is received, then the destination file system must
98 already exist, and its most recent snapshot must match the incremental stream's
102 the destination device link is destroyed and recreated, which means the
104 cannot be accessed during the
108 When a snapshot replication package stream that is generated by using the
110 command is received, any snapshots that do not exist on the sending location are
111 destroyed by using the
112 .Nm zfs Cm destroy Fl d
115 The ability to send and receive deduplicated send streams has been removed.
116 However, a deduplicated send stream created with older software can be converted
117 to a regular (non-deduplicated) stream by using the
122 .Fl o Em property Ns = Ns Ar value
125 is specified, it applies to the effective value of the property throughout
126 the entire subtree of replicated datasets.
127 Effective property values will be set
131 on the topmost in the replicated subtree.
132 In descendant datasets, if the
133 property is set by the send stream, it will be overridden by forcing the
134 property to be inherited from the top‐most file system.
135 Received properties are retained in spite of being overridden
136 and may be restored with
137 .Nm zfs Cm inherit Fl S .
139 .Fl o Sy origin Ns = Ns Em snapshot
140 is a special case because, even if
142 is a read-only property and cannot be set, it's allowed to receive the send
143 stream as a clone of the given snapshot.
145 Raw encrypted send streams (created with
146 .Nm zfs Cm send Fl w )
147 may only be received as is, and cannot be re-encrypted, decrypted, or
148 recompressed by the receive process.
149 Unencrypted streams can be received as
150 encrypted datasets, either through inheritance or by specifying encryption
156 property cannot be overridden to
159 This is because the receive process itself is already using
160 the standard input for the send stream.
161 Instead, the property can be overridden after the receive completes.
163 The added security provided by raw sends adds some restrictions to the send
165 ZFS will not allow a mix of raw receives and non-raw receives.
166 Specifically, any raw incremental receives that are attempted after
167 a non-raw receive will fail.
168 Non-raw receives do not have this restriction and,
169 therefore, are always possible.
170 Because of this, it is best practice to always
171 use either raw sends for their security benefits or non-raw sends for their
172 flexibility when working with encrypted datasets, but not a combination.
174 The reason for this restriction stems from the inherent restrictions of the
175 AEAD ciphers that ZFS uses to encrypt data.
176 When using ZFS native encryption,
177 each block of data is encrypted against a randomly generated number known as
178 the "initialization vector" (IV), which is stored in the filesystem metadata.
179 This number is required by the encryption algorithms whenever the data is to
181 Together, all of the IVs provided for all of the blocks in a
182 given snapshot are collectively called an "IV set".
183 When ZFS performs a raw send, the IV set is transferred from the source
184 to the destination in the send stream.
185 When ZFS performs a non-raw send, the data is decrypted by the source
186 system and re-encrypted by the destination system, creating a snapshot with
187 effectively the same data, but a different IV set.
188 In order for decryption to work after a raw send, ZFS must ensure that
189 the IV set used on both the source and destination side match.
190 When an incremental raw receive is performed on
191 top of an existing snapshot, ZFS will check to confirm that the "from"
192 snapshot on both the source and destination were using the same IV set,
193 ensuring the new IV set is consistent.
195 The name of the snapshot
196 .Pq and file system, if a full stream is received
197 that this subcommand creates depends on the argument type and the use of the
203 If the argument is a snapshot name, the specified
206 If the argument is a file system or volume name, a snapshot with the same name
207 as the sent snapshot is created within the specified
215 options are specified, the provided target snapshot name is used exactly as
222 options cause the file system name of the target snapshot to be determined by
223 appending a portion of the sent snapshot's name to the specified target
227 option is specified, all but the first element of the sent snapshot's file
229 .Pq usually the pool name
230 is used and any required intermediate file systems within the specified one are
234 option is specified, then only the last element of the sent snapshot's file
236 .Pq i.e. the name of the source file system itself
237 is used as the target file system name.
240 Force a rollback of the file system to the most recent snapshot before
241 performing the receive operation.
242 If receiving an incremental replication stream
243 .Po for example, one generated by
244 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
246 destroy snapshots and file systems that do not exist on the sending side.
248 Discard the first element of the sent snapshot's file system name, using the
249 remaining elements to determine the name of the target file system for the new
250 snapshot as described in the paragraph above.
252 Discard all but the last element of the sent snapshot's file system name, using
253 that element to determine the name of the target file system for the new
254 snapshot as described in the paragraph above.
256 Skip the receive of holds.
257 There is no effect if holds are not sent.
259 Force an unmount of the file system while receiving a snapshot.
260 This option is not supported on Linux.
262 Do not actually receive the stream.
263 This can be useful in conjunction with the
265 option to verify the name the receive operation would use.
266 .It Fl o Sy origin Ns = Ns Ar snapshot
267 Forces the stream to be received as a clone of the given snapshot.
268 If the stream is a full send stream, this will create the filesystem
269 described by the stream as a clone of the specified snapshot.
270 Which snapshot was specified will not affect the success or failure of the
271 receive, as long as the snapshot does exist.
272 If the stream is an incremental send stream, all the normal verification will be
274 .It Fl o Em property Ns = Ns Ar value
275 Sets the specified property as if the command
276 .Nm zfs Cm set Em property Ns = Ns Ar value
277 was invoked immediately before the receive.
278 When receiving a stream from
279 .Nm zfs Cm send Fl R ,
280 causes the property to be inherited by all descendant datasets, as through
281 .Nm zfs Cm inherit Em property
282 was run on any descendant datasets that have this property set on the
285 If the send stream was sent with
289 property will have no effect on received data but the
291 property will be set.
292 To have the data recompressed on receive remove the
294 flag from the send stream.
296 Any editable property can be set at receive time.
297 Set-once properties bound
298 to the received data, such as
301 .Sy casesensitivity ,
302 cannot be set at receive time even when the datasets are newly created by
304 Additionally both settable properties
308 cannot be set at receive time.
312 option may be specified multiple times, for different properties.
313 An error results if the same property is specified in multiple
321 option may also be used to override encryption properties upon initial receive.
322 This allows unencrypted streams to be received as encrypted datasets.
323 To cause the received dataset (or root dataset of a recursive stream) to be
324 received as an encryption root, specify encryption properties in the same
325 manner as is required for
328 .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
331 .Fl o Sy keylocation Ns = Ns Sy prompt
332 may not be specified here, since the standard input
333 is already being utilized for the send stream.
334 Once the receive has completed, you can use
336 to change this setting after the fact.
337 Similarly, you can receive a dataset as an encrypted child by specifying
339 to force the property to be inherited.
340 Overriding encryption properties (except for
342 is not possible with raw send streams.
344 If the receive is interrupted, save the partially received state, rather
346 Interruption may be due to premature termination of the stream
347 .Po e.g. due to network failure or failure of the remote system
348 if the stream is being read over a network connection
350 a checksum error in the stream, termination of the
352 process, or unclean shutdown of the system.
354 The receive can be resumed with a stream generated by
355 .Nm zfs Cm send Fl t Ar token ,
359 .Sy receive_resume_token
360 property of the filesystem or volume which is received into.
362 To use this flag, the storage pool must have the
363 .Sy extensible_dataset
367 for details on ZFS feature flags.
369 File system that is associated with the received stream is not mounted.
371 Print verbose information about the stream and the time required to perform the
374 Ensures that the effective value of the specified property after the
375 receive is unaffected by the value of that property in the send stream (if any),
376 as if the property had been excluded from the send stream.
378 If the specified property is not present in the send stream, this option does
381 If a received property needs to be overridden, the effective value will be
382 set or inherited, depending on whether the property is inheritable or not.
384 In the case of an incremental update,
386 leaves any existing local setting or explicit inheritance unchanged.
390 restrictions (e.g. set-once) apply equally to
397 .Ar filesystem Ns | Ns Ar volume
400 .Nm zfs Cm receive Fl s ,
401 deleting its saved partially received state.
407 .Ar filesystem Ns | Ns Ar snapshot
409 Attempt to correct data corruption in the specified dataset,
410 by using the provided stream as the source of healthy data.
411 This method of healing can only heal data blocks present in the stream.
412 Metadata can not be healed by corrective receive.
413 Running a scrub is recommended post-healing to ensure all corruption was
416 It's important to consider why corruption has happened in the first place
417 since if you have slowly failing hardware periodically healing the data
418 is not going to save you from data loss later on when the hardware fails
423 .\" These are, respectively, examples 12, 13 from zfs.8
424 .\" Make sure to update them bidirectionally
425 .Ss Example 1 : No Remotely Replicating ZFS Data
426 The following commands send a full stream and then an incremental stream to a
427 remote machine, restoring them into
428 .Em poolB/received/fs@a
430 .Em poolB/received/fs@b ,
433 must contain the file system
435 and must not initially contain
436 .Em poolB/received/fs .
437 .Bd -literal -compact -offset Ds
438 .No # Nm zfs Cm send Ar pool/fs@a |
439 .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs Ns @ Ns Ar a
440 .No # Nm zfs Cm send Fl i Ar a pool/fs@b |
441 .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs
444 .Ss Example 2 : No Using the Nm zfs Cm receive Fl d No Option
445 The following command sends a full stream of
446 .Ar poolA/fsA/fsB@snap
447 to a remote machine, receiving it into
448 .Ar poolB/received/fsA/fsB@snap .
451 portion of the received snapshot's name is determined from the name of the sent
454 must contain the file system
457 .Ar poolB/received/fsA
458 does not exist, it is created as an empty file system.
459 .Bd -literal -compact -offset Ds
460 .No # Nm zfs Cm send Ar poolA/fsA/fsB@snap |
461 .No " " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received
projects / FreeBSD / FreeBSD.git / blob