NAME

       nbdkit-cache-filter - nbdkit caching filter

SYNOPSIS

        nbdkit --filter=cache plugin [plugin-args...]
                                     [cache=writeback|writethrough|unsafe]
                                     [cache-min-block-size=SIZE]
                                     [cache-max-size=SIZE]
                                     [cache-high-threshold=N]
                                     [cache-low-threshold=N]
                                     [cache-on-read=true|false|/PATH]

DESCRIPTION

       "nbdkit-cache-filter" is a filter that adds caching on top of a plugin.  This is useful if
       a plugin is slow or expensive to use, because nbdkit will try to minimize requests to the
       plugin by caching previous requests.

       Note that many NBD clients are able to do caching, and because the caching happens on the
       client side it will usually be more effective than caching inside the server.  This filter
       can be used if the client does not have effective caching, or (with "cache=unsafe") to
       defeat flush requests from the client (which is unsafe and can cause data loss, as the
       name suggests).

       This filter only caches image contents.  To cache image metadata, use
       nbdkit-cacheextents-filter(1) between this filter and the plugin.  To accelerate
       sequential reads, use nbdkit-readahead-filter(1) or nbdkit-scan-filter(1) on top of this
       filter.

PARAMETERS

       cache=writeback
           Store writes in the cache.  They are not written to the plugin unless an explicit
           flush is done by the client.

           This is the default caching mode, and is safe if your client issues flush requests
           correctly (which is true for modern Linux and other well-written NBD clients).

       cache=writethrough
           Always force writes through to the plugin.

           This makes the cache less effective, but is necessary if your client does not issue
           correct flush requests.

       cache=unsafe
           Ignore flush requests.  Never write to the plugin unless the cache grows too large.

           This is dangerous and can cause data loss, but this may be acceptable if you only use
           it for testing or with data that you don't care about or can cheaply reconstruct.

       cache-min-block-size=SIZE
           Set the minimum block size used by the cache.  This must be a power of 2 and ≥ 4096.

           The default is 64K, or the block size of the filesystem which contains the temporary
           file storing the cache (whichever is larger).

       cache-max-size=SIZE
       cache-high-threshold=N
       cache-low-threshold=N
           (nbdkit ≥ 1.10)

           Limit the size of the cache to "SIZE".  See "CACHE MAXIMUM SIZE" below.

       cache-on-read=true
           (nbdkit ≥ 1.10)

           Cache read requests as well as write and cache requests.  Any time a block is read
           from the plugin, it is saved in the cache (if there is sufficient space) so the same
           data can be served more quickly later.

           Note that if the underlying data served by the plugin can be modified by some other
           means (eg. something else can write to a file which is being served by
           nbdkit-file-plugin(1)), this option will cause nbdkit to serve stale data because
           reads won't always go through to the plugin.

       cache-on-read=false
           Do not cache read requests (this is the default).

       cache-on-read=/PATH
           (nbdkit ≥ 1.28)

           When /PATH (which must be an absolute path) exists, this behaves like
           "cache-on-read=true", and when it does not exist like "cache-on-read=false".  This
           allows you to control the cache-on-read behaviour while nbdkit is running.

CACHE MAXIMUM SIZE

       By default the cache can grow to any size (although not larger than the virtual size of
       the underlying plugin) and you have to ensure there is sufficient space in $TMPDIR for it.

       Using the parameters "cache-max-size", "cache-high-threshold" and "cache-low-threshold"
       you can limit the maximum size of the cache.

       This requires kernel and filesystem support (for fallocate(2) "FALLOC_FL_PUNCH_HOLE"), so
       it may not work on all platforms.

       Some examples:

       "cache-max-size=1G"
           The cache is limited to around 1 gigabyte.

       "cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80"
           Once the cache size reaches 972M (95% of 1G), blocks are reclaimed from the cache
           until the size is reduced to 819M (80% of 1G).

       The way this works is once the size of the cache exceeds "SIZE" ✕ the high threshold, the
       filter works to reduce the size of the cache until it is less than
       "SIZE" ✕ the low threshold.  Once the size is below the low threshold, no more reclaim
       work is done until the size exceeds the high threshold again.

       The default thresholds are high 95% and low 80%.  You must set 0 < low < high.  The
       thresholds are expressed as integer percentages of "cache-max-size".

       Least recently used blocks are discarded first.

ENVIRONMENT VARIABLES

       "TMPDIR"
           The cache is stored in a temporary file located in /var/tmp by default.  You can
           override this location by setting the "TMPDIR" environment variable before starting
           nbdkit.

FILES

       $filterdir/nbdkit-cache-filter.so
           The filter.

           Use "nbdkit --dump-config" to find the location of $filterdir.

VERSION

       "nbdkit-cache-filter" first appeared in nbdkit 1.2.

SEE ALSO

       nbdkit(1), nbdkit-file-plugin(1), nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
       nbdkit-readahead-filter(1), nbdkit-filter(3), qemu-img(1).

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2018-2021 Red Hat Inc.

LICENSE

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of
           conditions and the following disclaimer in the documentation and/or other materials
           provided with the distribution.

       •   Neither the name of Red Hat nor the names of its contributors may be used to endorse
           or promote products derived from this software without specific prior written
           permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.