filters/cache/nbdkit-cache-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-cache-filter - nbdkit caching filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=cache plugin [plugin-args...]
   8                               [cache=writeback|writethrough|unsafe]
   9                               [cache-min-block-size=SIZE]
  10                               [cache-max-size=SIZE]
  11                               [cache-high-threshold=N]
  12                               [cache-low-threshold=N]
  13                               [cache-on-read=true|false|/PATH]
  14
  15 =head1 DESCRIPTION
  16
  17 C<nbdkit-cache-filter> is a filter that adds caching on top of a
  18 plugin.  This is useful if a plugin is slow or expensive to use,
  19 because nbdkit will try to minimize requests to the plugin by caching
  20 previous requests.
  21
  22 Note that many NBD I<clients> are able to do caching, and because the
  23 caching happens on the client side it will usually be more effective
  24 than caching inside the server.  This filter can be used if the client
  25 does not have effective caching, or (with C<cache=unsafe>) to defeat
  26 flush requests from the client (which is unsafe and can cause data
  27 loss, as the name suggests).
  28
  29 This filter only caches image contents.  To cache image metadata, use
  30 L<nbdkit-cacheextents-filter(1)> between this filter and the plugin.
  31 To accelerate sequential reads, use L<nbdkit-readahead-filter(1)> or
  32 L<nbdkit-scan-filter(1)> on top of this filter.
  33
  34 =head1 PARAMETERS
  35
  36 =over 4
  37
  38 =item B<cache=writeback>
  39
  40 Store writes in the cache.  They are not written to the plugin unless
  41 an explicit flush is done by the client.
  42
  43 This is the default caching mode, and is safe if your client issues
  44 flush requests correctly (which is true for modern Linux and other
  45 well-written NBD clients).
  46
  47 =item B<cache=writethrough>
  48
  49 Always force writes through to the plugin.
  50
  51 This makes the cache less effective, but is necessary if your client
  52 does not issue correct flush requests.
  53
  54 =item B<cache=unsafe>
  55
  56 Ignore flush requests.  Never write to the plugin unless the cache
  57 grows too large.
  58
  59 This is dangerous and can cause data loss, but this may be acceptable
  60 if you only use it for testing or with data that you don't care about
  61 or can cheaply reconstruct.
  62
  63 =item B<cache-min-block-size=>SIZE
  64
  65 Set the minimum block size used by the cache.  This must be a power of
  66 2 and E<ge> 4096.
  67
  68 The default is 64K, or the block size of the filesystem which contains
  69 the temporary file storing the cache (whichever is larger).
  70
  71 =item B<cache-max-size=>SIZE
  72
  73 =item B<cache-high-threshold=>N
  74
  75 =item B<cache-low-threshold=>N
  76
  77 (nbdkit E<ge> 1.10)
  78
  79 Limit the size of the cache to C<SIZE>.  See L</CACHE MAXIMUM SIZE> below.
  80
  81 =item B<cache-on-read=true>
  82
  83 (nbdkit E<ge> 1.10)
  84
  85 Cache read requests as well as write and cache requests.  Any time a
  86 block is read from the plugin, it is saved in the cache (if there is
  87 sufficient space) so the same data can be served more quickly later.
  88
  89 Note that if the underlying data served by the plugin can be modified
  90 by some other means (eg. something else can write to a file which is
  91 being served by L<nbdkit-file-plugin(1)>), this option will cause
  92 nbdkit to serve stale data because reads won't always go through to
  93 the plugin.
  94
  95 =item B<cache-on-read=false>
  96
  97 Do not cache read requests (this is the default).
  98
  99 =item B<cache-on-read=/PATH>
 100
 101 (nbdkit E<ge> 1.28)
 102
 103 When F</PATH> (which must be an absolute path) exists, this behaves
 104 like C<cache-on-read=true>, and when it does not exist like
 105 C<cache-on-read=false>.  This allows you to control the cache-on-read
 106 behaviour while nbdkit is running.
 107
 108 =back
 109
 110 =head1 CACHE MAXIMUM SIZE
 111
 112 By default the cache can grow to any size (although not larger than
 113 the virtual size of the underlying plugin) and you have to ensure
 114 there is sufficient space in C<$TMPDIR> for it.
 115
 116 Using the parameters C<cache-max-size>, C<cache-high-threshold> and
 117 C<cache-low-threshold> you can limit the maximum size of the cache.
 118
 119 This requires kernel and filesystem support (for L<fallocate(2)>
 120 C<FALLOC_FL_PUNCH_HOLE>), so it may not work on all platforms.
 121
 122 Some examples:
 123
 124 =over 4
 125
 126 =item C<cache-max-size=1G>
 127
 128 The cache is limited to around 1 gigabyte.
 129
 130 =item C<cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80>
 131
 132 Once the cache size reaches 972M (95% of 1G), blocks are reclaimed
 133 from the cache until the size is reduced to 819M (80% of 1G).
 134
 135 =back
 136
 137 The way this works is once the size of the cache exceeds
 138 S<C<SIZE> ✕ the high threshold>, the filter works to reduce the size
 139 of the cache until it is less than S<C<SIZE> ✕ the low threshold>.
 140 Once the size is below the low threshold, no more reclaim work is done
 141 until the size exceeds the high threshold again.
 142
 143 The default thresholds are high 95% and low 80%.  You must set
 144 S<0 E<lt> low E<lt> high>.  The thresholds are expressed as integer
 145 percentages of C<cache-max-size>.
 146
 147 Least recently used blocks are discarded first.
 148
 149 =head1 ENVIRONMENT VARIABLES
 150
 151 =over 4
 152
 153 =item C<TMPDIR>
 154
 155 The cache is stored in a temporary file located in F</var/tmp> by
 156 default.  You can override this location by setting the C<TMPDIR>
 157 environment variable before starting nbdkit.
 158
 159 =back
 160
 161 =head1 FILES
 162
 163 =over 4
 164
 165 =item F<$filterdir/nbdkit-cache-filter.so>
 166
 167 The filter.
 168
 169 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 170
 171 =back
 172
 173 =head1 VERSION
 174
 175 C<nbdkit-cache-filter> first appeared in nbdkit 1.2.
 176
 177 =head1 SEE ALSO
 178
 179 L<nbdkit(1)>,
 180 L<nbdkit-file-plugin(1)>,
 181 L<nbdkit-cacheextents-filter(1)>,
 182 L<nbdkit-cow-filter(1)>,
 183 L<nbdkit-readahead-filter(1)>,
 184 L<nbdkit-filter(3)>,
 185 L<qemu-img(1)>.
 186
 187 =head1 AUTHORS
 188
 189 Eric Blake
 190
 191 Richard W.M. Jones
 192
 193 =head1 COPYRIGHT
 194
 195 Copyright Red Hat