zstream8

Usage

Overview

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

# zfs send -c … | zstream decompress 128,0,lz4 | zfs recv …

# zfs send … | zstream drop_records 3545761,18446744073709486080 | zfs recv …

# 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