--- name: "zstreamdump" section: "8" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/zstream" --- # zstreamdump(8) manipulate ZFS send streams Part of [zstream(8)](/zstream/8.md). ## NAME **zstream** – manipulate ZFS send streams ## SYNOPSIS **zstream** **decompress** \[**-v**\] \[*object***,***offset*\[**,***compress\_type*\]…\] \[*file*\] **zstream** **drop\_records** \[**-v**\] \[*object***,***offset*…\] \[*file*\] **zstream** **dump** \[**-Cvd**\] \[*file*\] **zstream** **raw** \[**-v**\] \[**-b** *max\_buffers*\] \[**-g** *fromguid*\] *image*\|*device* \[*file*\] **zstream** **recompress** \[**-t** *num\_threads*\] *compress\_type* \[*file*\] **zstream** **redup** \[**-v**\] *file* **zstream** **token** *resume\_token* ## DESCRIPTION **zstream** performs various operations on send streams created by the **zfs** **send** command. Aside from the **token** subcommand, which takes a resume token rather than a stream, every subcommand reads a send stream either from the *file* named as its last argument or, when no *file* is given, from standard input. The **redup** subcommand requires a *file*; it rereads earlier parts of the stream to resolve deduplicated records, so it cannot accept input from a pipe. - **zstream** **decompress** \[**-v**\] \[*object***,***offset*\[**,***compress\_type*\]…\] \[*file*\] Decompresses specified records within a send stream. This subcommand can be used to recover data when the compression type recorded in the ZFS metadata is incorrect. Specify the object number and byte offset of each record to be decompressed. Optionally, specify the (true) *compress\_type*. The *compress\_type* can be any value accepted by the **compression** property except **on**, such as **off**, **gzip**, **lz4**, **lzjb**, **zstd**, or **zle**. A compression level (e.g., **gzip-3** or **zstd-5**) is accepted but ignored; only the algorithm matters when decompressing. If no *compress\_type* is given, the compression type recorded in the record's own metadata is used. Every record for that object beginning at that offset is decompressed, if possible. It may not be possible, because a record can be corrupt in some of the stream's snapshots but not in others. Specifying a compression type of **off** changes the stream's metadata accordingly, without attempting decompression. This can be useful if the record is already uncompressed but the metadata insists otherwise. The repaired stream is written to standard output. - **-v** Verbose. Prints a summary of decompressed records. - **zstream** **drop\_records** \[**-v**\] \[*object***,***offset*…\] \[*file*\] Removes selected records, specified by object number and byte offset, from a send stream read from the specified *file* or from standard input. Currently, only WRITE and WRITE\_EMBEDDED records can be dropped. The repaired stream is written to standard output. - **-v** Verbose. Prints a summary of dropped records. - **zstream** **dump** \[**-Cvd**\] \[*file*\] Prints information about the specified send stream, including headers and record counts. The stream is read from either the specified *file* or standard input. - **-C** Suppresses the validation of checksums. - **-v** Verbose. Prints metadata for each record. This option can be repeated to also print record checksums. - **-d** Dumps the data contained in each record as well as checksums. Implies verbose. The **zstreamdump** alias is provided for compatibility and is equivalent to running **zstream** **dump**. - **zstream** **raw** \[**-v**\] \[**-b** *max\_buffers*\] \[**-g** *fromguid*\] *image*\|*device* \[*file*\] Applies a zvol send stream, read from the specified *file* or from standard input, to a raw image or block device. By default, at most 32 SPA\_MAXBLOCKSIZE buffers can be written at a time. With *max\_buffers* set to some value between 1 and IOV\_MAX, contiguous write records are combined into one write operation using up to this many buffers, at the cost of additional memory use. When a *fromguid* is provided, the initial fromguid of the stream is checked to ensure that it matches the given value. The final toguid of the stream is printed to standard output on completion. With the **-v** option, details of the records in the stream are printed in similar fashion to **zstream** **dump**. - **zstream** **recompress** \[**-t** *num\_threads*\] *compress\_type* \[*file*\] Recompresses a send stream, read from the specified *file* or from standard input, using the specified *compress\_type*, and writes the modified stream to standard output. All WRITE records in the send stream are compressed unless compression fails to reduce their size compared to leaving them uncompressed. The *compress\_type* can be any value accepted by the **compression** property except **on**, including those that name a compression level, such as **gzip-3** or **zstd-5**. A *compress\_type* of **off** decompresses every record and leaves the stream uncompressed. Note that encrypted send streams cannot be recompressed. - **-t** *num\_threads* Specifies the number of compression worker threads. By default, **zstream** **recompress** creates a thread for every CPU core. It is generally unproductive to raise *num\_threads* above this default. On some architectures, contention for resources such as memory caches can reduce efficiency when many threads are active. On those systems, it may be helpful to run with fewer threads, particularly when automating operations on shared servers. - **-l** *level* This option is deprecated. It formerly specified a numeric compression level for **zstd**. Use a standard compression specifier such as **zstd-5** instead. - **zstream** **redup** \[**-v**\] *file* It was formerly possible to create deduplicated send streams with the **zfs** **send** **-D** option. However, support for stream-level deduplication has been deprecated and removed from both **zfs** **send** and **zfs** **receive**. **zstream** **redup** reads a deduplicated stream from the specified *file* and outputs an equivalent, non-deduplicated send stream on standard output. Therefore, a deduplicated stream can be received by running: ``` # zstream redup file | zfs receive … ``` A real *file* is required here because resolving deduplicated records involves rereading earlier parts of the stream. - **-v** Verbose. Prints a summary of reduplicated records. - **zstream** **token** *resume\_token* Dumps ZFS resume token information. ## EXAMPLES ### Recovering from OpenZFS bug #12762 First, determine which records are corrupt. That cannot be done automatically; it requires information beyond ZFS's metadata. If object **128** is corrupted at offset **0** and is compressed using **lz4**, then run this command: ``` # zfs send -c … | zstream decompress 128,0,lz4 | zfs recv … ``` ### Recovering from OpenZFS bug #18239 The bogus records typically have an absurdly large offset that can be discovered by running **zdb** **-ddddd** *dataset* *object* or **zstream** **dump** **-v**. To recover, send the dataset and use **zstream** to drop the bogus record, then receive it into a new dataset. ``` # zfs send … | zstream drop_records 3545761,18446744073709486080 | zfs recv … ``` ### Migrating from a zvol to a physical disk Given an adequately sized physical disk */dev/sdd* and a zvol *tank/vol* with snapshots *@1*, *@2*, and *@3*: ``` # zfs send -Lec tank/vol@1 | zstream raw /dev/sdd 16731506615198184313 # zfs send -Lec -I @1 tank/vol@3 | zstream raw -g 16731506615198184313 /dev/sdd 10690368765373298656 ``` ## SEE ALSO [zdb(8)](/zdb/8.md), [zfs(8)](/zfs/8.md), [zfs-receive(8)](/zfs-receive/8.md), [zfs-send(8)](/zfs-send/8.md), **https://github.com/openzfs/zfs/issues/12762**, **https://github.com/openzfs/zfs/issues/18239**