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