]>
Commit | Line | Data |
---|---|---|
870fc32f RW |
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 | |
1d3ba0bf | 9 | .\" or https://opensource.org/licenses/CDDL-1.0. |
870fc32f RW |
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 | .\" | |
870fc32f RW |
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 | .\" | |
e8cf3a4f | 32 | .Dd April 26, 2022 |
870fc32f | 33 | .Dt ZFS-RECEIVE 8 |
6706552e | 34 | .Os |
f84fe3fc | 35 | . |
870fc32f | 36 | .Sh NAME |
1e36af8c | 37 | .Nm zfs-receive |
f84fe3fc | 38 | .Nd create snapshot from backup stream |
870fc32f | 39 | .Sh SYNOPSIS |
1e36af8c | 40 | .Nm zfs |
870fc32f | 41 | .Cm receive |
a57d3d45 | 42 | .Op Fl FhMnsuv |
870fc32f RW |
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 | |
1e36af8c | 47 | .Nm zfs |
870fc32f | 48 | .Cm receive |
a57d3d45 | 49 | .Op Fl FhMnsuv |
870fc32f RW |
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 | |
1e36af8c | 55 | .Nm zfs |
870fc32f RW |
56 | .Cm receive |
57 | .Fl A | |
58 | .Ar filesystem Ns | Ns Ar volume | |
f84fe3fc | 59 | . |
e8cf3a4f AP |
60 | .Nm |
61 | .Cm receive | |
62 | .Fl c | |
63 | .Op Fl vn | |
64 | .Ar filesystem Ns | Ns Ar snapshot | |
65 | . | |
870fc32f RW |
66 | .Sh DESCRIPTION |
67 | .Bl -tag -width "" | |
68 | .It Xo | |
1e36af8c | 69 | .Nm zfs |
870fc32f | 70 | .Cm receive |
a57d3d45 | 71 | .Op Fl FhMnsuv |
870fc32f RW |
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 | |
1e36af8c | 78 | .Nm zfs |
870fc32f | 79 | .Cm receive |
a57d3d45 | 80 | .Op Fl FhMnsuv |
870fc32f RW |
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 | |
f84fe3fc | 95 | .Nm zfs Cm receive . |
870fc32f RW |
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 | |
196bee4c MA |
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 | |
652bdc9b | 119 | command. |
652bdc9b | 120 | .Pp |
870fc32f RW |
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 | |
f84fe3fc AZ |
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 | |
870fc32f | 133 | property is set by the send stream, it will be overridden by forcing the |
f84fe3fc AZ |
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 | |
870fc32f RW |
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 | |
f84fe3fc AZ |
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 | |
870fc32f RW |
150 | encrypted datasets, either through inheritance or by specifying encryption |
151 | parameters with the | |
152 | .Fl o | |
f84fe3fc AZ |
153 | options. |
154 | Note that the | |
870fc32f RW |
155 | .Sy keylocation |
156 | property cannot be overridden to | |
157 | .Sy prompt | |
f84fe3fc AZ |
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. | |
870fc32f RW |
162 | .Pp |
163 | The added security provided by raw sends adds some restrictions to the send | |
f84fe3fc AZ |
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 | |
870fc32f RW |
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 | |
f84fe3fc AZ |
175 | AEAD ciphers that ZFS uses to encrypt data. |
176 | When using ZFS native encryption, | |
870fc32f RW |
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 | |
f84fe3fc AZ |
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 | |
870fc32f | 186 | system and re-encrypted by the destination system, creating a snapshot with |
f84fe3fc AZ |
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 | |
870fc32f RW |
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 | |
f84fe3fc AZ |
256 | Skip the receive of holds. |
257 | There is no effect if holds are not sent. | |
a57d3d45 MZ |
258 | .It Fl M |
259 | Force an unmount of the file system while receiving a snapshot. | |
260 | This option is not supported on Linux. | |
870fc32f RW |
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 | |
f84fe3fc AZ |
277 | was invoked immediately before the receive. |
278 | When receiving a stream from | |
870fc32f RW |
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 | |
b8fa03ef | 285 | If the send stream was sent with |
ecc277cf | 286 | .Fl c |
b8fa03ef | 287 | then overriding the |
ecc277cf | 288 | .Sy compression |
cfc62062 | 289 | property will have no effect on received data but the |
b8fa03ef | 290 | .Sy compression |
f84fe3fc AZ |
291 | property will be set. |
292 | To have the data recompressed on receive remove the | |
b8fa03ef MM |
293 | .Fl c |
294 | flag from the send stream. | |
ecc277cf | 295 | .Pp |
f84fe3fc AZ |
296 | Any editable property can be set at receive time. |
297 | Set-once properties bound | |
870fc32f RW |
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 | |
f84fe3fc AZ |
312 | option may be specified multiple times, for different properties. |
313 | An error results if the same property is specified in multiple | |
870fc32f RW |
314 | .Fl o |
315 | or | |
316 | .Fl x | |
317 | options. | |
318 | .Pp | |
319 | The | |
320 | .Fl o | |
f84fe3fc AZ |
321 | option may also be used to override encryption properties upon initial receive. |
322 | This allows unencrypted streams to be received as encrypted datasets. | |
870fc32f RW |
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 | |
f84fe3fc | 326 | .Nm zfs Cm create . |
870fc32f | 327 | For instance: |
0c8aab95 | 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 |
870fc32f RW |
329 | .Pp |
330 | Note that | |
f84fe3fc AZ |
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 | |
4631bf7b | 338 | .Fl x Sy encryption |
f84fe3fc AZ |
339 | to force the property to be inherited. |
340 | Overriding encryption properties (except for | |
341 | .Sy keylocation ) | |
870fc32f RW |
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 | |
2badb345 | 366 | .Xr zpool-features 7 |
870fc32f RW |
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 | |
1e36af8c | 394 | .Nm zfs |
870fc32f RW |
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. | |
e8cf3a4f AP |
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. | |
870fc32f | 420 | .El |
f84fe3fc | 421 | . |
2057b47b AZ |
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 | . | |
870fc32f | 464 | .Sh SEE ALSO |
f84fe3fc | 465 | .Xr zfs-send 8 , |
196bee4c | 466 | .Xr zstream 8 |