filters/xz/nbdkit-xz-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-xz-filter - nbdkit xz filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=xz file FILENAME.xz
   8
   9 =for paragraph
  10
  11  nbdkit --filter=xz curl https://example.com/FILENAME.xz
  12
  13 =head1 DESCRIPTION
  14
  15 C<nbdkit-xz-filter> is a filter for L<nbdkit(1)> which uncompresses
  16 the underlying plugin on the fly.  The filter only supports read-only
  17 connections.
  18
  19 =head2 Getting best random access performance from xz
  20
  21 L<xz(1)> files are split into streams and blocks.  Most xz files
  22 contain only one stream which contains one or more blocks.  You can
  23 find out how many streams and blocks are in an xz file by doing:
  24
  25  $ xz --list winxp.img.xz
  26  Strms  Blocks   Compressed Uncompressed  Ratio  Check   Filename
  27      1       1  2,100.0 MiB  6,144.0 MiB  0.342  CRC64   winxp.img.xz
  28     ↑↑↑     ↑↑↑
  29   streams  blocks
  30
  31 xz files are seekable on block boundaries only.  Seeking is done by
  32 seeking directly to the lower block boundary, then uncompressing data
  33 until the precise byte is reached.  As uncompressing xz data is slow,
  34 B<to get best random access performance, you must prepare your xz
  35 files with many small blocks.>
  36
  37 Use the I<--block-size> option with a small-ish block size.  For
  38 example this is the same image compressed with a 16 MB block size:
  39
  40  $ xz --best --block-size=16777216 winxp.img
  41              ─────────────────────
  42  $ xz --list winxp.img.xz
  43  Strms  Blocks   Compressed Uncompressed  Ratio  Check   Filename
  44      1     384  2,120.1 MiB  6,144.0 MiB  0.345  CRC64   winxp.img.xz
  45            ↑↑↑
  46           blocks
  47
  48 This file can be accessed randomly.  At most 16 MB will have to be
  49 uncompressed to seek to any byte.
  50
  51 As you would expect, xz cannot compress as efficiently when using a
  52 smaller block size.  The space penalty in the above example is
  53 S<E<lt> 1%> of the compressed file size.
  54
  55 =head1 PARAMETERS
  56
  57 =over 4
  58
  59 =item B<xz-max-block=>SIZE
  60
  61 The maximum block size that the filter will read.  The filter will
  62 refuse to read xz files that contain any block larger than this size.
  63
  64 See the discussion above about creating xz files with small block
  65 sizes in order to reduce memory usage and increase performance.
  66
  67 This parameter is optional.  If not specified it defaults to 512M.
  68
  69 =item B<xz-max-depth=>N
  70
  71 Maximum number of blocks stored in the LRU block cache.
  72
  73 This parameter is optional.  If not specified it defaults to 8.
  74
  75 The filter may allocate up to
  76 S<maximum block size in file × maxdepth>
  77 bytes of memory I<per connection>.
  78
  79 =back
  80
  81 =head1 FILES
  82
  83 =over 4
  84
  85 =item F<$filterdir/nbdkit-xz-filter.so>
  86
  87 The filter.
  88
  89 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
  90
  91 =back
  92
  93 =head1 VERSION
  94
  95 C<nbdkit-xz-filter> first appeared in nbdkit 1.10.
  96 It is derived from an earlier plugin that first appeared in nbdkit 1.0.
  97
  98 =head1 SEE ALSO
  99
 100 L<nbdkit(1)>,
 101 L<nbdkit-filter(3)>,
 102 L<nbdkit-curl-plugin(1)>,
 103 L<nbdkit-file-plugin(1)>,
 104 L<xz(1)>.
 105
 106 =head1 AUTHORS
 107
 108 Richard W.M. Jones
 109
 110 =head1 COPYRIGHT
 111
 112 Copyright (C) 2013-2020 Red Hat Inc.