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