zstreamdump

ZSTREAM(8) System Manager's Manual ZSTREAM(8)

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

   The zstream utility manipulates ZFS send streams output by the zfs send command.

   zstream dump [-Cvd] [file]
     Print information about the specified send stream, including headers and record counts.  The send stream may either be in the specified file, or provided on standard input.

     -C  Suppress the validation of checksums.

     -v  Verbose.  Print metadata for each record.

     -d  Dump data contained in each record.  Implies verbose.

     The zstreamdump alias is provided for compatibility and is equivalent to running zstream dump.

   zstream token resume_token
     Dumps zfs resume token information

   zstream decompress [-v] [object,offset[,type...]]
     Decompress selected records in a ZFS send stream provided on standard input, when the compression type recorded in ZFS metadata may be incorrect.  Specify the object number and byte
     offset  of  each  record that you wish to decompress.  Optionally specify the compression type.  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, because the record may be corrupted in some but  not  all  of
     the  stream's  snapshots.  Specifying a compression type of off will change 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 will be written to standard output.

     -v  Verbose.  Print summary of decompressed records.

   zstream redup [-v] file
     Deduplicated send streams can be generated by using the zfs send -D command.  The ability to send deduplicated send streams is deprecated.  In the future, the ability to  receive  a
     deduplicated send stream with zfs receive will be removed.  However, deduplicated send streams can still be received by utilizing zstream redup.

     The zstream redup command is provided a file containing a deduplicated send stream, and outputs an equivalent non-deduplicated send stream on standard output.  Therefore, a dedupli
     cated send stream can be received by running:
           # zstream redup DEDUP_STREAM_FILE | zfs receive …

     -v  Verbose.  Print 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.  All WRITE records in the
     send  stream  will  be recompressed, unless they fail to result in size reduction compared to being left uncompressed.  The provided algorithm can be any valid value to the compress
     property.  Note that encrypted send streams cannot be recompressed.

     -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).

EXAMPLES

   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.  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 …

SEE ALSO

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

OpenZFS October 4, 2022 ZSTREAM(8)