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
52The
53.Sy zstream
54utility manipulates ZFS send streams output by the
55.Sy zfs send
56command.
57.Bl -tag -width ""
58.It Xo
59.Nm
60.Cm dump
61.Op Fl Cvd
62.Op Ar file
63.Xc
64Print information about the specified send stream, including headers and
65record counts.
66The send stream may either be in the specified
67.Ar file ,
68or provided on standard input.
69.Bl -tag -width "-D"
70.It Fl C
71Suppress the validation of checksums.
72.It Fl v
73Verbose.
74Print metadata for each record.
75.It Fl d
76Dump data contained in each record.
77Implies verbose.
78.El
79.Pp
80The
81.Nm zstreamdump
82alias 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
90Dumps 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
97Decompress selected records in a ZFS send stream provided on standard input,
98when the compression type recorded in ZFS metadata may be incorrect.
99Specify the object number and byte offset of each record that you wish to
100decompress.
101Optionally specify the compression type.
102Valid compression types include
103.Sy off ,
104.Sy gzip ,
105.Sy lz4 ,
106.Sy lzjb ,
107.Sy zstd ,
108and
109.Sy zle .
110The default is
111.Sy lz4 .
112Every record for that object beginning at that offset will be decompressed, if
113possible.
114It may not be possible, because the record may be corrupted in some but not
115all of the stream's snapshots.
116Specifying a compression type of
117.Sy off
118will change the stream's metadata accordingly, without attempting decompression.
119This can be useful if the record is already uncompressed but the metadata
120insists otherwise.
121The repaired stream will be written to standard output.
122.Bl -tag -width "-v"
123.It Fl v
124Verbose.
125Print summary of decompressed records.
126.El
127.It Xo
128.Nm
129.Cm redup
130.Op Fl v
131.Ar file
132.Xc
133Deduplicated send streams can be generated by using the
134.Nm zfs Cm send Fl D
135command.
136The ability to send deduplicated send streams is deprecated.
137In the future, the ability to receive a deduplicated send stream with
138.Nm zfs Cm receive
139will be removed.
140However, deduplicated send streams can still be received by utilizing
141.Nm zstream Cm redup .
142.Pp
143The
144.Nm zstream Cm redup
145command is provided a
146.Ar file
147containing a deduplicated send stream, and outputs an equivalent
148non-deduplicated send stream on standard output.
149Therefore, 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
153Verbose.
154Print 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
162Recompresses a send stream, provided on standard input, using the provided
163algorithm and optional level, and writes the modified stream to standard output.
164All WRITE records in the send stream will be recompressed, unless they fail
165to result in size reduction compared to being left uncompressed.
166The provided algorithm can be any valid value to the
167.Nm compress
168property.
169Note that encrypted send streams cannot be recompressed.
170.Bl -tag -width "-l"
171.It Fl l Ar level
172Specifies compression level.
173Only needed for algorithms where the level is not implied as part of the name
174of the algorithm (e.g. gzip-3 does not require it, while zstd does, if a
175non-default level is desired).
176.El
177.El
178.
179.Sh EXAMPLES
180Heal a dataset that was corrupted due to OpenZFS bug #12762.
181First, determine which records are corrupt.
182That cannot be done automatically; it requires information beyond ZFS's
183metadata.
184If object
185.Sy 128
186is corrupted at offset
187.Sy 0
188and is compressed using
189.Sy lz4 ,
190then run this command:
191.Bd -literal
192.No # Nm zfs Ar send Fl c Ar … | Nm zstream decompress Ar 128,0,lz4 | \
193Nm 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
200