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