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