ZSTREAM(8)

📦
version 2.4.4 · 6 versions
, in alpine 3.23, alpine 3.24, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 ZSTREAM(8) 💖

okay bestie, so this is a page from the System Manager's Manual, section 8, and it's all about zstream — the little icon that manipulates ZFS send streams. yes. THE zstream. she's giving maintenance-girlie energy and honestly? we're obsessed. 🫶

✨ NAME ✨

zstream — manipulate ZFS send streams 🌊

✨ SYNOPSIS ✨

zstream dump [-Cvd] [file]
zstream decompress [-v] [object,offset[,type...]]
zstream redup [-v] file
zstream token resume_token
zstream recompress [-l level] algorithm

✨ DESCRIPTION ✨

so the zstream utility manipulates ZFS send streams that were output by the zfs send command. that's the whole vibe. 💅

🌸 zstream dump [-Cvd] [file]

Prints info about the send stream you point at — headers, record counts, the whole little résumé. 🎀 The send stream can either live in the specified file, or it can be handed to her on standard input. either way bestie, she'll read it.

  • -C — suppress the validation of checksums. (no cap, she just won't check.)
  • -v — verbose. prints metadata for each record. she's yapping but like, productively. 🔥
  • -d — dump the data contained in each record. this one implies verbose, so -v comes along for free.
  • The zstreamdump alias is provided for compatibility and is equivalent to running zstream dump. (a legacy bestie. we respect her. 🫶)

🌈 zstream token resume_token

Dumps zfs resume token information. 🦋 that's it. short queen, no notes.

✨ zstream decompress [-v] [object,offset[,type...]]

okay so this one is giving surgeon energy. 🧚 she decompresses selected records in a ZFS send stream provided on standard input — specifically for when the compression type recorded in ZFS metadata may be incorrect. messy, but we fix it.

You specify the object number and byte offset of each record that you wish to decompress. Optionally you can specify the compression type too, if you're feeling generous. ✨

Valid compression types include off, gzip, lz4, lzjb, zstd, and zle. The default is lz4. 🍓

Every record for that object beginning at that offset will be decompressed, if possible. it may not be possible, bestie 😭 — because the record may be corrupted in some but not all of the stream's snapshots. she's trying her best.

Specifying a compression type of off will change the stream's metadata accordingly, without attempting decompression. this is useful if the record is already uncompressed but the metadata insists otherwise (delusional metadata, we've all been there 💀).

The repaired stream will be written to standard output. 🌟

  • -v — verbose. prints a summary of decompressed records.

💜 zstream redup [-v] file

Deduplicated send streams can be generated by using the zfs send -D command. however — the ability to send deduplicated send streams is deprecated. and in the future, the ability to receive a deduplicated send stream with zfs receive will be removed. so heads up. 🚨

but like, plot twist: deduplicated send streams can still be received by utilizing zstream redup. she's the workaround. she's the moment. 👑

The zstream redup command is provided a file containing a deduplicated send stream, and outputs an equivalent non-deduplicated send stream on standard output. so basically, a deduplicated send stream can be received by running:

# zstream redup DEDUP_STREAM_FILE | zfs receive …

slay. pipe it, bestie. 🔥

  • -v — verbose. prints a summary of converted records.

🎀 zstream recompress [-l level] algorithm

Recompresses a send stream, provided on standard input, using the provided algorithm and optional level, and writes the modified stream to standard output. glow-up but for compression. ✨

All WRITE records in the send stream will be recompressed — unless they fail to result in size reduction compared to being left uncompressed. (if it's not shrinking, she's not forcing it. body neutrality. 💅)

The provided algorithm can be any valid value to the compress property.

⚠️ note: encrypted send streams cannot be recompressed. no cap. don't try it.
  • -l level — specifies compression level. Only needed for algorithms where the level is not implied as part of the name of the algorithm (e.g. gzip-3 does not require it, while zstd does, if a non-default level is desired). iykyk 🧠

✨ EXAMPLES ✨

okay so the goal here: heal a dataset that was corrupted due to OpenZFS bug #12762. 🩹

First, determine which records are corrupt. That cannot be done automatically — it requires information beyond ZFS's metadata. so like, you have to actually know things. sorry bestie. 😭

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 …

boom. healed. iconic. 🌈

✨ SEE ALSO ✨

zfs(8), zfs-receive(8), zfs-send(8), https://github.com/openzfs/zfs/issues/12762

and that's the whole page, bestie!! this one shipped from OpenZFS on November 10, 2022, so if you're citing her in your essay, that's the receipt. 💖✨ go forth and manipulate those send streams. periodt. 🎀🦋

📦 where this page comes from