| blob | 22cb567c1c96b06ccb2e8fdc1a45d21ce0a7c490 |
1 .\"
2 .\" CDDL HEADER START
3 .\"
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.
7 .\"
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.
12 .\"
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]
18 .\"
19 .\" CDDL HEADER END
20 .\"
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.
31 .\"
32 .Dd April 26, 2022
33 .Dt ZFS-RECEIVE 8
34 .Os
35 .
36 .Sh NAME
37 .Nm zfs-receive
38 .Nd create snapshot from backup stream
39 .Sh SYNOPSIS
40 .Nm zfs
41 .Cm receive
42 .Op Fl FhMnsuv
43 .Op Fl o Sy origin Ns = Ns Ar snapshot
44 .Op Fl o Ar property Ns = Ns Ar value
45 .Op Fl x Ar property
46 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
47 .Nm zfs
48 .Cm receive
49 .Op Fl FhMnsuv
50 .Op Fl d Ns | Ns Fl e
51 .Op Fl o Sy origin Ns = Ns Ar snapshot
52 .Op Fl o Ar property Ns = Ns Ar value
53 .Op Fl x Ar property
54 .Ar filesystem
55 .Nm zfs
56 .Cm receive
57 .Fl A
58 .Ar filesystem Ns | Ns Ar volume
59 .
60 .Nm
61 .Cm receive
62 .Fl c
63 .Op Fl vn
64 .Ar filesystem Ns | Ns Ar snapshot
65 .
66 .Sh DESCRIPTION
67 .Bl -tag -width ""
68 .It Xo
69 .Nm zfs
70 .Cm receive
71 .Op Fl FhMnsuv
72 .Op Fl o Sy origin Ns = Ns Ar snapshot
73 .Op Fl o Ar property Ns = Ns Ar value
74 .Op Fl x Ar property
75 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
76 .Xc
77 .It Xo
78 .Nm zfs
79 .Cm receive
80 .Op Fl FhMnsuv
81 .Op Fl d Ns | Ns Fl e
82 .Op Fl o Sy origin Ns = Ns Ar snapshot
83 .Op Fl o Ar property Ns = Ns Ar value
84 .Op Fl x Ar property
85 .Ar filesystem
86 .Xc
87 Creates a snapshot whose contents are as specified in the stream provided on
88 standard input.
89 If a full stream is received, then a new file system is created as well.
90 Streams are created using the
91 .Nm zfs Cm send
92 subcommand, which by default creates a full stream.
93 .Nm zfs Cm recv
94 can be used as an alias for
95 .Nm zfs Cm receive .
96 .Pp
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
99 source.
100 For
101 .Sy zvols ,
102 the destination device link is destroyed and recreated, which means the
103 .Sy zvol
104 cannot be accessed during the
105 .Cm receive
106 operation.
107 .Pp
108 When a snapshot replication package stream that is generated by using the
109 .Nm zfs Cm send Fl R
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
113 command.
114 .Pp
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
118 .Nm zstream Cm redup
119 command.
120 .Pp
121 If
122 .Fl o Em property Ns = Ns Ar value
123 or
124 .Fl x Em property
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
128 .Pq Fl o
129 or inherited
130 .Pq Fl x
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 .
138 Specifying
139 .Fl o Sy origin Ns = Ns Em snapshot
140 is a special case because, even if
141 .Sy origin
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.
144 .Pp
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
151 parameters with the
152 .Fl o
153 options.
154 Note that the
155 .Sy keylocation
156 property cannot be overridden to
157 .Sy prompt
158 during a receive.
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.
162 .Pp
163 The added security provided by raw sends adds some restrictions to the send
164 and receive process.
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.
173 .Pp
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
180 be decrypted.
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.
194 .Pp
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
198 .Fl d
199 or
200 .Fl e
201 options.
202 .Pp
203 If the argument is a snapshot name, the specified
204 .Ar snapshot
205 is created.
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
208 .Ar filesystem
209 or
210 .Ar volume .
211 If neither of the
212 .Fl d
213 or
214 .Fl e
215 options are specified, the provided target snapshot name is used exactly as
216 provided.
217 .Pp
218 The
219 .Fl d
220 and
221 .Fl e
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
224 .Ar filesystem .
225 If the
226 .Fl d
227 option is specified, all but the first element of the sent snapshot's file
228 system path
229 .Pq usually the pool name
230 is used and any required intermediate file systems within the specified one are
231 created.
232 If the
233 .Fl e
234 option is specified, then only the last element of the sent snapshot's file
235 system name
236 .Pq i.e. the name of the source file system itself
237 is used as the target file system name.
238 .Bl -tag -width "-F"
239 .It Fl F
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
245 .Pc ,
246 destroy snapshots and file systems that do not exist on the sending side.
247 .It Fl d
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.
251 .It Fl e
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.
255 .It Fl h
256 Skip the receive of holds.
257 There is no effect if holds are not sent.
258 .It Fl M
259 Force an unmount of the file system while receiving a snapshot.
260 This option is not supported on Linux.
261 .It Fl n
262 Do not actually receive the stream.
263 This can be useful in conjunction with the
264 .Fl v
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
273 performed.
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
283 sending system.
284 .Pp
285 If the send stream was sent with
286 .Fl c
287 then overriding the
288 .Sy compression
289 property will have no effect on received data but the
290 .Sy compression
291 property will be set.
292 To have the data recompressed on receive remove the
293 .Fl c
294 flag from the send stream.
295 .Pp
296 Any editable property can be set at receive time.
297 Set-once properties bound
298 to the received data, such as
299 .Sy normalization
300 and
301 .Sy casesensitivity ,
302 cannot be set at receive time even when the datasets are newly created by
303 .Nm zfs Cm receive .
304 Additionally both settable properties
305 .Sy version
306 and
307 .Sy volsize
308 cannot be set at receive time.
309 .Pp
310 The
311 .Fl o
312 option may be specified multiple times, for different properties.
313 An error results if the same property is specified in multiple
314 .Fl o
315 or
316 .Fl x
317 options.
318 .Pp
319 The
320 .Fl o
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
326 .Nm zfs Cm create .
327 For instance:
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
329 .Pp
330 Note that
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
335 .Nm zfs Cm set
336 to change this setting after the fact.
337 Similarly, you can receive a dataset as an encrypted child by specifying
338 .Fl x Sy encryption
339 to force the property to be inherited.
340 Overriding encryption properties (except for
341 .Sy keylocation )
342 is not possible with raw send streams.
343 .It Fl s
344 If the receive is interrupted, save the partially received state, rather
345 than deleting it.
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
349 .Pc ,
350 a checksum error in the stream, termination of the
351 .Nm zfs Cm receive
352 process, or unclean shutdown of the system.
353 .Pp
354 The receive can be resumed with a stream generated by
355 .Nm zfs Cm send Fl t Ar token ,
356 where the
357 .Ar token
358 is the value of the
359 .Sy receive_resume_token
360 property of the filesystem or volume which is received into.
361 .Pp
362 To use this flag, the storage pool must have the
363 .Sy extensible_dataset
364 feature enabled.
365 See
366 .Xr zpool-features 7
367 for details on ZFS feature flags.
368 .It Fl u
369 File system that is associated with the received stream is not mounted.
370 .It Fl v
371 Print verbose information about the stream and the time required to perform the
372 receive operation.
373 .It Fl x Em property
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.
377 .Pp
378 If the specified property is not present in the send stream, this option does
379 nothing.
380 .Pp
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.
383 .Pp
384 In the case of an incremental update,
385 .Fl x
386 leaves any existing local setting or explicit inheritance unchanged.
387 .Pp
388 All
389 .Fl o
390 restrictions (e.g. set-once) apply equally to
391 .Fl x .
392 .El
393 .It Xo
394 .Nm zfs
395 .Cm receive
396 .Fl A
397 .Ar filesystem Ns | Ns Ar volume
398 .Xc
399 Abort an interrupted
400 .Nm zfs Cm receive Fl s ,
401 deleting its saved partially received state.
402 .It Xo
403 .Nm zfs
404 .Cm receive
405 .Fl c
406 .Op Fl vn
407 .Ar filesystem Ns | Ns Ar snapshot
408 .Xc
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
414 healed.
415 .Pp
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
419 completely.
420 .El
421 .
422 .Sh EXAMPLES
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
429 and
430 .Em poolB/received/fs@b ,
431 respectively.
432 .Em poolB
433 must contain the file system
434 .Em poolB/received ,
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
442 .Ed
443 .
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 .
449 The
450 .Ar fsA/fsB@snap
451 portion of the received snapshot's name is determined from the name of the sent
452 snapshot.
453 .Ar poolB
454 must contain the file system
455 .Ar poolB/received .
456 If
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
462 .Ed
463 .
464 .Sh SEE ALSO
465 .Xr zfs-send 8 ,
466 .Xr zstream 8