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

zstreamdump.8 (5078B)


  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) 2020 by Delphix. All rights reserved.
  22. .\"
  23. .Dd October 4, 2022
  24. .Dt ZSTREAM 8
  25. .Os
  26. .
  27. .Sh NAME
  28. .Nm zstream
  29. .Nd manipulate ZFS send streams
  30. .Sh SYNOPSIS
  31. .Nm
  32. .Cm dump
  33. .Op Fl Cvd
  34. .Op Ar file
  35. .Nm
  36. .Cm decompress
  37. .Op Fl v
  38. .Op Ar object Ns Sy \&, Ns Ar offset Ns Op Sy \&, Ns Ar type Ns ...
  39. .Nm
  40. .Cm redup
  41. .Op Fl v
  42. .Ar file
  43. .Nm
  44. .Cm token
  45. .Ar resume_token
  46. .Nm
  47. .Cm recompress
  48. .Op Fl l Ar level
  49. .Ar algorithm
  50. .
  51. .Sh DESCRIPTION
  52. The
  53. .Sy zstream
  54. utility manipulates ZFS send streams output by the
  55. .Sy zfs send
  56. command.
  57. .Bl -tag -width ""
  58. .It Xo
  59. .Nm
  60. .Cm dump
  61. .Op Fl Cvd
  62. .Op Ar file
  63. .Xc
  64. Print information about the specified send stream, including headers and
  65. record counts.
  66. The send stream may either be in the specified
  67. .Ar file ,
  68. or provided on standard input.
  69. .Bl -tag -width "-D"
  70. .It Fl C
  71. Suppress the validation of checksums.
  72. .It Fl v
  73. Verbose.
  74. Print metadata for each record.
  75. .It Fl d
  76. Dump data contained in each record.
  77. Implies verbose.
  78. .El
  79. .Pp
  80. The
  81. .Nm zstreamdump
  82. alias is provided for compatibility and is equivalent to running
  83. .Nm
  84. .Cm dump .
  85. .It Xo
  86. .Nm
  87. .Cm token
  88. .Ar resume_token
  89. .Xc
  90. Dumps zfs resume token information
  91. .It Xo
  92. .Nm
  93. .Cm decompress
  94. .Op Fl v
  95. .Op Ar object Ns Sy \&, Ns Ar offset Ns Op Sy \&, Ns Ar type Ns ...
  96. .Xc
  97. Decompress selected records in a ZFS send stream provided on standard input,
  98. when the compression type recorded in ZFS metadata may be incorrect.
  99. Specify the object number and byte offset of each record that you wish to
  100. decompress.
  101. Optionally specify the compression type.
  102. Valid compression types include
  103. .Sy off ,
  104. .Sy gzip ,
  105. .Sy lz4 ,
  106. .Sy lzjb ,
  107. .Sy zstd ,
  108. and
  109. .Sy zle .
  110. The default is
  111. .Sy lz4 .
  112. Every record for that object beginning at that offset will be decompressed, if
  113. possible.
  114. It may not be possible, because the record may be corrupted in some but not
  115. all of the stream's snapshots.
  116. Specifying a compression type of
  117. .Sy off
  118. will change the stream's metadata accordingly, without attempting decompression.
  119. This can be useful if the record is already uncompressed but the metadata
  120. insists otherwise.
  121. The repaired stream will be written to standard output.
  122. .Bl -tag -width "-v"
  123. .It Fl v
  124. Verbose.
  125. Print summary of decompressed records.
  126. .El
  127. .It Xo
  128. .Nm
  129. .Cm redup
  130. .Op Fl v
  131. .Ar file
  132. .Xc
  133. Deduplicated send streams can be generated by using the
  134. .Nm zfs Cm send Fl D
  135. command.
  136. The ability to send deduplicated send streams is deprecated.
  137. In the future, the ability to receive a deduplicated send stream with
  138. .Nm zfs Cm receive
  139. will be removed.
  140. However, deduplicated send streams can still be received by utilizing
  141. .Nm zstream Cm redup .
  142. .Pp
  143. The
  144. .Nm zstream Cm redup
  145. command is provided a
  146. .Ar file
  147. containing a deduplicated send stream, and outputs an equivalent
  148. non-deduplicated send stream on standard output.
  149. Therefore, a deduplicated send stream can be received by running:
  150. .Dl # Nm zstream Cm redup Pa DEDUP_STREAM_FILE | Nm zfs Cm receive No …
  151. .Bl -tag -width "-D"
  152. .It Fl v
  153. Verbose.
  154. Print summary of converted records.
  155. .El
  156. .It Xo
  157. .Nm
  158. .Cm recompress
  159. .Op Fl l Ar level
  160. .Ar algorithm
  161. .Xc
  162. Recompresses a send stream, provided on standard input, using the provided
  163. algorithm and optional level, and writes the modified stream to standard output.
  164. All WRITE records in the send stream will be recompressed, unless they fail
  165. to result in size reduction compared to being left uncompressed.
  166. The provided algorithm can be any valid value to the
  167. .Nm compress
  168. property.
  169. Note that encrypted send streams cannot be recompressed.
  170. .Bl -tag -width "-l"
  171. .It Fl l Ar level
  172. Specifies compression level.
  173. Only needed for algorithms where the level is not implied as part of the name
  174. of the algorithm (e.g. gzip-3 does not require it, while zstd does, if a
  175. non-default level is desired).
  176. .El
  177. .El
  178. .
  179. .Sh EXAMPLES
  180. Heal a dataset that was corrupted due to OpenZFS bug #12762.
  181. First, determine which records are corrupt.
  182. That cannot be done automatically; it requires information beyond ZFS's
  183. metadata.
  184. If object
  185. .Sy 128
  186. is corrupted at offset
  187. .Sy 0
  188. and is compressed using
  189. .Sy lz4 ,
  190. then run this command:
  191. .Bd -literal
  192. .No # Nm zfs Ar send Fl c Ar … | Nm zstream decompress Ar 128,0,lz4 | \
  193. Nm zfs recv Ar …
  194. .Ed
  195. .Sh SEE ALSO
  196. .Xr zfs 8 ,
  197. .Xr zfs-receive 8 ,
  198. .Xr zfs-send 8 ,
  199. .Lk https://github.com/openzfs/zfs/issues/12762