logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zfs-send.8 (25926B)


  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. .\" Copyright (c) 2024, Klara, Inc.
  32. .\"
  33. .Dd October 2, 2024
  34. .Dt ZFS-SEND 8
  35. .Os
  36. .
  37. .Sh NAME
  38. .Nm zfs-send
  39. .Nd generate backup stream of ZFS dataset
  40. .Sh SYNOPSIS
  41. .Nm zfs
  42. .Cm send
  43. .Op Fl DLPVbcehnpsvw
  44. .Op Fl R Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns …
  45. .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
  46. .Ar snapshot
  47. .Nm zfs
  48. .Cm send
  49. .Op Fl DLPVcensvw
  50. .Op Fl i Ar snapshot Ns | Ns Ar bookmark
  51. .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  52. .Nm zfs
  53. .Cm send
  54. .Fl -redact Ar redaction_bookmark
  55. .Op Fl DLPVcenpv
  56. .Op Fl i Ar snapshot Ns | Ns Ar bookmark
  57. .Ar snapshot
  58. .Nm zfs
  59. .Cm send
  60. .Op Fl PVenv
  61. .Fl t
  62. .Ar receive_resume_token
  63. .Nm zfs
  64. .Cm send
  65. .Op Fl PVnv
  66. .Fl S Ar filesystem
  67. .Nm zfs
  68. .Cm redact
  69. .Ar snapshot redaction_bookmark
  70. .Ar redaction_snapshot Ns …
  71. .
  72. .Sh DESCRIPTION
  73. .Bl -tag -width ""
  74. .It Xo
  75. .Nm zfs
  76. .Cm send
  77. .Op Fl DLPVbcehnpsvw
  78. .Op Fl R Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns …
  79. .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
  80. .Ar snapshot
  81. .Xc
  82. Creates a stream representation of the second
  83. .Ar snapshot ,
  84. which is written to standard output.
  85. The output can be redirected to a file or to a different system
  86. .Po for example, using
  87. .Xr ssh 1
  88. .Pc .
  89. By default, a full stream is generated.
  90. .Bl -tag -width "-D"
  91. .It Fl D , -dedup
  92. Deduplicated send is no longer supported.
  93. This flag is accepted for backwards compatibility, but a regular,
  94. non-deduplicated stream will be generated.
  95. .It Fl I Ar snapshot
  96. Generate a stream package that sends all intermediary snapshots from the first
  97. snapshot to the second snapshot.
  98. For example,
  99. .Fl I Em @a Em fs@d
  100. is similar to
  101. .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
  102. The incremental source may be specified as with the
  103. .Fl i
  104. option.
  105. .It Fl L , -large-block
  106. Generate a stream which may contain blocks larger than 128 KiB.
  107. This flag has no effect if the
  108. .Sy large_blocks
  109. pool feature is disabled, or if the
  110. .Sy recordsize
  111. property of this filesystem has never been set above 128 KiB.
  112. The receiving system must have the
  113. .Sy large_blocks
  114. pool feature enabled as well.
  115. This flag is required if the
  116. .Sy large_microzap
  117. pool feature is active.
  118. See
  119. .Xr zpool-features 7
  120. for details on ZFS feature flags and the
  121. .Sy large_blocks
  122. feature.
  123. .It Fl P , -parsable
  124. Print machine-parsable verbose information about the stream package generated.
  125. .It Fl R , -replicate
  126. Generate a replication stream package, which will replicate the specified
  127. file system, and all descendent file systems, up to the named snapshot.
  128. When received, all properties, snapshots, descendent file systems, and clones
  129. are preserved.
  130. .Pp
  131. If the
  132. .Fl i
  133. or
  134. .Fl I
  135. flags are used in conjunction with the
  136. .Fl R
  137. flag, an incremental replication stream is generated.
  138. The current values of properties, and current snapshot and file system names are
  139. set when the stream is received.
  140. If the
  141. .Fl F
  142. flag is specified when this stream is received, snapshots and file systems that
  143. do not exist on the sending side are destroyed.
  144. If the
  145. .Fl R
  146. flag is used to send encrypted datasets, then
  147. .Fl w
  148. must also be specified.
  149. .It Fl V , -proctitle
  150. Set the process title to a per-second report of how much data has been sent.
  151. .It Fl X , -exclude Ar dataset Ns Oo , Ns Ar dataset Oc Ns …
  152. With
  153. .Fl R ,
  154. .Fl X
  155. specifies a set of datasets (and, hence, their descendants),
  156. to be excluded from the send stream.
  157. The root dataset may not be excluded.
  158. .Fl X Ar a Fl X Ar b
  159. is equivalent to
  160. .Fl X Ar a , Ns Ar b .
  161. .It Fl e , -embed
  162. Generate a more compact stream by using
  163. .Sy WRITE_EMBEDDED
  164. records for blocks which are stored more compactly on disk by the
  165. .Sy embedded_data
  166. pool feature.
  167. This flag has no effect if the
  168. .Sy embedded_data
  169. feature is disabled.
  170. The receiving system must have the
  171. .Sy embedded_data
  172. feature enabled.
  173. If the
  174. .Sy lz4_compress
  175. feature is active on the sending system, then the receiving system must have
  176. that feature enabled as well.
  177. Datasets that are sent with this flag may not be
  178. received as an encrypted dataset, since encrypted datasets cannot use the
  179. .Sy embedded_data
  180. feature.
  181. See
  182. .Xr zpool-features 7
  183. for details on ZFS feature flags and the
  184. .Sy embedded_data
  185. feature.
  186. .It Fl b , -backup
  187. Sends only received property values whether or not they are overridden by local
  188. settings, but only if the dataset has ever been received.
  189. Use this option when you want
  190. .Nm zfs Cm receive
  191. to restore received properties backed up on the sent dataset and to avoid
  192. sending local settings that may have nothing to do with the source dataset,
  193. but only with how the data is backed up.
  194. .It Fl c , -compressed
  195. Generate a more compact stream by using compressed WRITE records for blocks
  196. which are compressed on disk and in memory
  197. .Po see the
  198. .Sy compression
  199. property for details
  200. .Pc .
  201. If the
  202. .Sy lz4_compress
  203. feature is active on the sending system, then the receiving system must have
  204. that feature enabled as well.
  205. If the
  206. .Sy large_blocks
  207. feature is enabled on the sending system but the
  208. .Fl L
  209. option is not supplied in conjunction with
  210. .Fl c ,
  211. then the data will be decompressed before sending so it can be split into
  212. smaller block sizes.
  213. Streams sent with
  214. .Fl c
  215. will not have their data recompressed on the receiver side using
  216. .Fl o Sy compress Ns = Ar value .
  217. The data will stay compressed as it was from the sender.
  218. The new compression property will be set for future data.
  219. Note that uncompressed data from the sender will still attempt to
  220. compress on the receiver, unless you specify
  221. .Fl o Sy compress Ns = Em off .
  222. .It Fl w , -raw
  223. For encrypted datasets, send data exactly as it exists on disk.
  224. This allows backups to be taken even if encryption keys are not currently
  225. loaded.
  226. The backup may then be received on an untrusted machine since that machine will
  227. not have the encryption keys to read the protected data or alter it without
  228. being detected.
  229. Upon being received, the dataset will have the same encryption
  230. keys as it did on the send side, although the
  231. .Sy keylocation
  232. property will be defaulted to
  233. .Sy prompt
  234. if not otherwise provided.
  235. For unencrypted datasets, this flag will be equivalent to
  236. .Fl Lec .
  237. Note that if you do not use this flag for sending encrypted datasets, data will
  238. be sent unencrypted and may be re-encrypted with a different encryption key on
  239. the receiving system, which will disable the ability to do a raw send to that
  240. system for incrementals.
  241. .It Fl h , -holds
  242. Generate a stream package that includes any snapshot holds (created with the
  243. .Nm zfs Cm hold
  244. command), and indicating to
  245. .Nm zfs Cm receive
  246. that the holds be applied to the dataset on the receiving system.
  247. .It Fl i Ar snapshot
  248. Generate an incremental stream from the first
  249. .Ar snapshot
  250. .Pq the incremental source
  251. to the second
  252. .Ar snapshot
  253. .Pq the incremental target .
  254. The incremental source can be specified as the last component of the snapshot
  255. name
  256. .Po the
  257. .Sy @
  258. character and following
  259. .Pc
  260. and it is assumed to be from the same file system as the incremental target.
  261. .Pp
  262. If the destination is a clone, the source may be the origin snapshot, which must
  263. be fully specified
  264. .Po for example,
  265. .Em pool/fs@origin ,
  266. not just
  267. .Em @origin
  268. .Pc .
  269. .It Fl n , -dryrun
  270. Do a dry-run
  271. .Pq Qq No-op
  272. send.
  273. Do not generate any actual send data.
  274. This is useful in conjunction with the
  275. .Fl v
  276. or
  277. .Fl P
  278. flags to determine what data will be sent.
  279. In this case, the verbose output will be written to standard output
  280. .Po contrast with a non-dry-run, where the stream is written to standard output
  281. and the verbose output goes to standard error
  282. .Pc .
  283. .It Fl p , -props
  284. Include the dataset's properties in the stream.
  285. This flag is implicit when
  286. .Fl R
  287. is specified.
  288. The receiving system must also support this feature.
  289. Sends of encrypted datasets must use
  290. .Fl w
  291. when using this flag.
  292. .It Fl s , -skip-missing
  293. Allows sending a replication stream even when there are snapshots missing in the
  294. hierarchy.
  295. When a snapshot is missing, instead of throwing an error and aborting the send,
  296. a warning is printed to the standard error stream and the dataset to which it
  297. belongs
  298. and its descendents are skipped.
  299. This flag can only be used in conjunction with
  300. .Fl R .
  301. .It Fl v , -verbose
  302. Print verbose information about the stream package generated.
  303. This information includes a per-second report of how much data has been sent.
  304. The same report can be requested by sending
  305. .Dv SIGINFO
  306. or
  307. .Dv SIGUSR1 ,
  308. regardless of
  309. .Fl v .
  310. .Pp
  311. The format of the stream is committed.
  312. You will be able to receive your streams on future versions of ZFS.
  313. .El
  314. .It Xo
  315. .Nm zfs
  316. .Cm send
  317. .Op Fl DLPVcenvw
  318. .Op Fl i Ar snapshot Ns | Ns Ar bookmark
  319. .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  320. .Xc
  321. Generate a send stream, which may be of a filesystem, and may be incremental
  322. from a bookmark.
  323. If the destination is a filesystem or volume, the pool must be read-only, or the
  324. filesystem must not be mounted.
  325. When the stream generated from a filesystem or volume is received, the default
  326. snapshot name will be
  327. .Qq --head-- .
  328. .Bl -tag -width "-D"
  329. .It Fl D , -dedup
  330. Deduplicated send is no longer supported.
  331. This flag is accepted for backwards compatibility, but a regular,
  332. non-deduplicated stream will be generated.
  333. .It Fl L , -large-block
  334. Generate a stream which may contain blocks larger than 128 KiB.
  335. This flag has no effect if the
  336. .Sy large_blocks
  337. pool feature is disabled, or if the
  338. .Sy recordsize
  339. property of this filesystem has never been set above 128 KiB.
  340. The receiving system must have the
  341. .Sy large_blocks
  342. pool feature enabled as well.
  343. See
  344. .Xr zpool-features 7
  345. for details on ZFS feature flags and the
  346. .Sy large_blocks
  347. feature.
  348. .It Fl P , -parsable
  349. Print machine-parsable verbose information about the stream package generated.
  350. .It Fl c , -compressed
  351. Generate a more compact stream by using compressed WRITE records for blocks
  352. which are compressed on disk and in memory
  353. .Po see the
  354. .Sy compression
  355. property for details
  356. .Pc .
  357. If the
  358. .Sy lz4_compress
  359. feature is active on the sending system, then the receiving system must have
  360. that feature enabled as well.
  361. If the
  362. .Sy large_blocks
  363. feature is enabled on the sending system but the
  364. .Fl L
  365. option is not supplied in conjunction with
  366. .Fl c ,
  367. then the data will be decompressed before sending so it can be split into
  368. smaller block sizes.
  369. .It Fl w , -raw
  370. For encrypted datasets, send data exactly as it exists on disk.
  371. This allows backups to be taken even if encryption keys are not currently
  372. loaded.
  373. The backup may then be received on an untrusted machine since that machine will
  374. not have the encryption keys to read the protected data or alter it without
  375. being detected.
  376. Upon being received, the dataset will have the same encryption
  377. keys as it did on the send side, although the
  378. .Sy keylocation
  379. property will be defaulted to
  380. .Sy prompt
  381. if not otherwise provided.
  382. For unencrypted datasets, this flag will be equivalent to
  383. .Fl Lec .
  384. Note that if you do not use this flag for sending encrypted datasets, data will
  385. be sent unencrypted and may be re-encrypted with a different encryption key on
  386. the receiving system, which will disable the ability to do a raw send to that
  387. system for incrementals.
  388. .It Fl e , -embed
  389. Generate a more compact stream by using
  390. .Sy WRITE_EMBEDDED
  391. records for blocks which are stored more compactly on disk by the
  392. .Sy embedded_data
  393. pool feature.
  394. This flag has no effect if the
  395. .Sy embedded_data
  396. feature is disabled.
  397. The receiving system must have the
  398. .Sy embedded_data
  399. feature enabled.
  400. If the
  401. .Sy lz4_compress
  402. feature is active on the sending system, then the receiving system must have
  403. that feature enabled as well.
  404. Datasets that are sent with this flag may not be received as an encrypted
  405. dataset,
  406. since encrypted datasets cannot use the
  407. .Sy embedded_data
  408. feature.
  409. See
  410. .Xr zpool-features 7
  411. for details on ZFS feature flags and the
  412. .Sy embedded_data
  413. feature.
  414. .It Fl i Ar snapshot Ns | Ns Ar bookmark
  415. Generate an incremental send stream.
  416. The incremental source must be an earlier snapshot in the destination's history.
  417. It will commonly be an earlier snapshot in the destination's file system, in
  418. which case it can be specified as the last component of the name
  419. .Po the
  420. .Sy #
  421. or
  422. .Sy @
  423. character and following
  424. .Pc .
  425. .Pp
  426. If the incremental target is a clone, the incremental source can be the origin
  427. snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
  428. origin, etc.
  429. .It Fl n , -dryrun
  430. Do a dry-run
  431. .Pq Qq No-op
  432. send.
  433. Do not generate any actual send data.
  434. This is useful in conjunction with the
  435. .Fl v
  436. or
  437. .Fl P
  438. flags to determine what data will be sent.
  439. In this case, the verbose output will be written to standard output
  440. .Po contrast with a non-dry-run, where the stream is written to standard output
  441. and the verbose output goes to standard error
  442. .Pc .
  443. .It Fl v , -verbose
  444. Print verbose information about the stream package generated.
  445. This information includes a per-second report of how much data has been sent.
  446. The same report can be requested by sending
  447. .Dv SIGINFO
  448. or
  449. .Dv SIGUSR1 ,
  450. regardless of
  451. .Fl v .
  452. .El
  453. .It Xo
  454. .Nm zfs
  455. .Cm send
  456. .Fl -redact Ar redaction_bookmark
  457. .Op Fl DLPVcenpv
  458. .Op Fl i Ar snapshot Ns | Ns Ar bookmark
  459. .Ar snapshot
  460. .Xc
  461. Generate a redacted send stream.
  462. This send stream contains all blocks from the snapshot being sent that aren't
  463. included in the redaction list contained in the bookmark specified by the
  464. .Fl -redact
  465. (or
  466. .Fl d )
  467. flag.
  468. The resulting send stream is said to be redacted with respect to the snapshots
  469. the bookmark specified by the
  470. .Fl -redact No flag was created with .
  471. The bookmark must have been created by running
  472. .Nm zfs Cm redact
  473. on the snapshot being sent.
  474. .Pp
  475. This feature can be used to allow clones of a filesystem to be made available on
  476. a remote system, in the case where their parent need not (or needs to not) be
  477. usable.
  478. For example, if a filesystem contains sensitive data, and it has clones where
  479. that sensitive data has been secured or replaced with dummy data, redacted sends
  480. can be used to replicate the secured data without replicating the original
  481. sensitive data, while still sharing all possible blocks.
  482. A snapshot that has been redacted with respect to a set of snapshots will
  483. contain all blocks referenced by at least one snapshot in the set, but will
  484. contain none of the blocks referenced by none of the snapshots in the set.
  485. In other words, if all snapshots in the set have modified a given block in the
  486. parent, that block will not be sent; but if one or more snapshots have not
  487. modified a block in the parent, they will still reference the parent's block, so
  488. that block will be sent.
  489. Note that only user data will be redacted.
  490. .Pp
  491. When the redacted send stream is received, we will generate a redacted
  492. snapshot.
  493. Due to the nature of redaction, a redacted dataset can only be used in the
  494. following ways:
  495. .Bl -enum -width "a."
  496. .It
  497. To receive, as a clone, an incremental send from the original snapshot to one
  498. of the snapshots it was redacted with respect to.
  499. In this case, the stream will produce a valid dataset when received because all
  500. blocks that were redacted in the parent are guaranteed to be present in the
  501. child's send stream.
  502. This use case will produce a normal snapshot, which can be used just like other
  503. snapshots.
  504. .
  505. .It
  506. To receive an incremental send from the original snapshot to something
  507. redacted with respect to a subset of the set of snapshots the initial snapshot
  508. was redacted with respect to.
  509. In this case, each block that was redacted in the original is still redacted
  510. (redacting with respect to additional snapshots causes less data to be redacted
  511. (because the snapshots define what is permitted, and everything else is
  512. redacted)).
  513. This use case will produce a new redacted snapshot.
  514. .It
  515. To receive an incremental send from a redaction bookmark of the original
  516. snapshot that was created when redacting with respect to a subset of the set of
  517. snapshots the initial snapshot was created with respect to
  518. anything else.
  519. A send stream from such a redaction bookmark will contain all of the blocks
  520. necessary to fill in any redacted data, should it be needed, because the sending
  521. system is aware of what blocks were originally redacted.
  522. This will either produce a normal snapshot or a redacted one, depending on
  523. whether the new send stream is redacted.
  524. .It
  525. To receive an incremental send from a redacted version of the initial
  526. snapshot that is redacted with respect to a subject of the set of snapshots the
  527. initial snapshot was created with respect to.
  528. A send stream from a compatible redacted dataset will contain all of the blocks
  529. necessary to fill in any redacted data.
  530. This will either produce a normal snapshot or a redacted one, depending on
  531. whether the new send stream is redacted.
  532. .It
  533. To receive a full send as a clone of the redacted snapshot.
  534. Since the stream is a full send, it definitionally contains all the data needed
  535. to create a new dataset.
  536. This use case will either produce a normal snapshot or a redacted one, depending
  537. on whether the full send stream was redacted.
  538. .El
  539. .Pp
  540. These restrictions are detected and enforced by
  541. .Nm zfs Cm receive ;
  542. a redacted send stream will contain the list of snapshots that the stream is
  543. redacted with respect to.
  544. These are stored with the redacted snapshot, and are used to detect and
  545. correctly handle the cases above.
  546. Note that for technical reasons,
  547. raw sends and redacted sends cannot be combined at this time.
  548. .It Xo
  549. .Nm zfs
  550. .Cm send
  551. .Op Fl PVenv
  552. .Fl t
  553. .Ar receive_resume_token
  554. .Xc
  555. Creates a send stream which resumes an interrupted receive.
  556. The
  557. .Ar receive_resume_token
  558. is the value of this property on the filesystem or volume that was being
  559. received into.
  560. See the documentation for
  561. .Nm zfs Cm receive Fl s
  562. for more details.
  563. .It Xo
  564. .Nm zfs
  565. .Cm send
  566. .Op Fl PVnv
  567. .Op Fl i Ar snapshot Ns | Ns Ar bookmark
  568. .Fl S
  569. .Ar filesystem
  570. .Xc
  571. Generate a send stream from a dataset that has been partially received.
  572. .Bl -tag -width "-L"
  573. .It Fl S , -saved
  574. This flag requires that the specified filesystem previously received a resumable
  575. send that did not finish and was interrupted.
  576. In such scenarios this flag
  577. enables the user to send this partially received state.
  578. Using this flag will always use the last fully received snapshot
  579. as the incremental source if it exists.
  580. .El
  581. .It Xo
  582. .Nm zfs
  583. .Cm redact
  584. .Ar snapshot redaction_bookmark
  585. .Ar redaction_snapshot Ns …
  586. .Xc
  587. Generate a new redaction bookmark.
  588. In addition to the typical bookmark information, a redaction bookmark contains
  589. the list of redacted blocks and the list of redaction snapshots specified.
  590. The redacted blocks are blocks in the snapshot which are not referenced by any
  591. of the redaction snapshots.
  592. These blocks are found by iterating over the metadata in each redaction snapshot
  593. to determine what has been changed since the target snapshot.
  594. Redaction is designed to support redacted zfs sends; see the entry for
  595. .Nm zfs Cm send
  596. for more information on the purpose of this operation.
  597. If a redact operation fails partway through (due to an error or a system
  598. failure), the redaction can be resumed by rerunning the same command.
  599. .El
  600. .Ss Redaction
  601. ZFS has support for a limited version of data subsetting, in the form of
  602. redaction.
  603. Using the
  604. .Nm zfs Cm redact
  605. command, a
  606. .Sy redaction bookmark
  607. can be created that stores a list of blocks containing sensitive information.
  608. When provided to
  609. .Nm zfs Cm send ,
  610. this causes a
  611. .Sy redacted send
  612. to occur.
  613. Redacted sends omit the blocks containing sensitive information,
  614. replacing them with REDACT records.
  615. When these send streams are received, a
  616. .Sy redacted dataset
  617. is created.
  618. A redacted dataset cannot be mounted by default, since it is incomplete.
  619. It can be used to receive other send streams.
  620. In this way datasets can be used for data backup and replication,
  621. with all the benefits that zfs send and receive have to offer,
  622. while protecting sensitive information from being
  623. stored on less-trusted machines or services.
  624. .Pp
  625. For the purposes of redaction, there are two steps to the process.
  626. A redact step, and a send/receive step.
  627. First, a redaction bookmark is created.
  628. This is done by providing the
  629. .Nm zfs Cm redact
  630. command with a parent snapshot, a bookmark to be created, and a number of
  631. redaction snapshots.
  632. These redaction snapshots must be descendants of the parent snapshot,
  633. and they should modify data that is considered sensitive in some way.
  634. Any blocks of data modified by all of the redaction snapshots will
  635. be listed in the redaction bookmark, because it represents the truly sensitive
  636. information.
  637. When it comes to the send step, the send process will not send
  638. the blocks listed in the redaction bookmark, instead replacing them with
  639. REDACT records.
  640. When received on the target system, this will create a
  641. redacted dataset, missing the data that corresponds to the blocks in the
  642. redaction bookmark on the sending system.
  643. The incremental send streams from
  644. the original parent to the redaction snapshots can then also be received on
  645. the target system, and this will produce a complete snapshot that can be used
  646. normally.
  647. Incrementals from one snapshot on the parent filesystem and another
  648. can also be done by sending from the redaction bookmark, rather than the
  649. snapshots themselves.
  650. .Pp
  651. In order to make the purpose of the feature more clear, an example is provided.
  652. Consider a zfs filesystem containing four files.
  653. These files represent information for an online shopping service.
  654. One file contains a list of usernames and passwords, another contains purchase
  655. histories,
  656. a third contains click tracking data, and a fourth contains user preferences.
  657. The owner of this data wants to make it available for their development teams to
  658. test against, and their market research teams to do analysis on.
  659. The development teams need information about user preferences and the click
  660. tracking data, while the market research teams need information about purchase
  661. histories and user preferences.
  662. Neither needs access to the usernames and passwords.
  663. However, because all of this data is stored in one ZFS filesystem,
  664. it must all be sent and received together.
  665. In addition, the owner of the data
  666. wants to take advantage of features like compression, checksumming, and
  667. snapshots, so they do want to continue to use ZFS to store and transmit their
  668. data.
  669. Redaction can help them do so.
  670. First, they would make two clones of a snapshot of the data on the source.
  671. In one clone, they create the setup they want their market research team to see;
  672. they delete the usernames and passwords file,
  673. and overwrite the click tracking data with dummy information.
  674. In another, they create the setup they want the development teams
  675. to see, by replacing the passwords with fake information and replacing the
  676. purchase histories with randomly generated ones.
  677. They would then create a redaction bookmark on the parent snapshot,
  678. using snapshots on the two clones as redaction snapshots.
  679. The parent can then be sent, redacted, to the target
  680. server where the research and development teams have access.
  681. Finally, incremental sends from the parent snapshot to each of the clones can be
  682. sent
  683. to and received on the target server; these snapshots are identical to the
  684. ones on the source, and are ready to be used, while the parent snapshot on the
  685. target contains none of the username and password data present on the source,
  686. because it was removed by the redacted send operation.
  687. .
  688. .Sh SIGNALS
  689. See
  690. .Fl v .
  691. .
  692. .Sh EXAMPLES
  693. .\" These are, respectively, examples 12, 13 from zfs.8
  694. .\" Make sure to update them bidirectionally
  695. .Ss Example 1 : No Remotely Replicating ZFS Data
  696. The following commands send a full stream and then an incremental stream to a
  697. remote machine, restoring them into
  698. .Em poolB/received/fs@a
  699. and
  700. .Em poolB/received/fs@b ,
  701. respectively.
  702. .Em poolB
  703. must contain the file system
  704. .Em poolB/received ,
  705. and must not initially contain
  706. .Em poolB/received/fs .
  707. .Bd -literal -compact -offset Ds
  708. .No # Nm zfs Cm send Ar pool/fs@a |
  709. .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs Ns @ Ns Ar a
  710. .No # Nm zfs Cm send Fl i Ar a pool/fs@b |
  711. .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs
  712. .Ed
  713. .
  714. .Ss Example 2 : No Using the Nm zfs Cm receive Fl d No Option
  715. The following command sends a full stream of
  716. .Ar poolA/fsA/fsB@snap
  717. to a remote machine, receiving it into
  718. .Ar poolB/received/fsA/fsB@snap .
  719. The
  720. .Ar fsA/fsB@snap
  721. portion of the received snapshot's name is determined from the name of the sent
  722. snapshot.
  723. .Ar poolB
  724. must contain the file system
  725. .Ar poolB/received .
  726. If
  727. .Ar poolB/received/fsA
  728. does not exist, it is created as an empty file system.
  729. .Bd -literal -compact -offset Ds
  730. .No # Nm zfs Cm send Ar poolA/fsA/fsB@snap |
  731. .No " " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received
  732. .Ed
  733. .
  734. .Sh SEE ALSO
  735. .Xr zfs-bookmark 8 ,
  736. .Xr zfs-receive 8 ,
  737. .Xr zfs-redact 8 ,
  738. .Xr zfs-snapshot 8