.\" Automatically generated by Podwrapper::Man 1.32.5 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-cache-filter 1"
.TH nbdkit-cache-filter 1 "2023-01-04" "nbdkit-1.32.5" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-cache\-filter \- nbdkit caching filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& 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]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-cache\-filter\*(C'\fR 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.
.PP
Note that many \s-1NBD\s0 \fIclients\fR 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 \f(CW\*(C`cache=unsafe\*(C'\fR) to defeat
flush requests from the client (which is unsafe and can cause data
loss, as the name suggests).
.PP
This filter only caches image contents.  To cache image metadata, use
\&\fBnbdkit\-cacheextents\-filter\fR\|(1) between this filter and the plugin.
To accelerate sequential reads, use \fBnbdkit\-readahead\-filter\fR\|(1) or
\&\fBnbdkit\-scan\-filter\fR\|(1) on top of this filter.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
.IP "\fBcache=writeback\fR" 4
.IX Item "cache=writeback"
Store writes in the cache.  They are not written to the plugin unless
an explicit flush is done by the client.
.Sp
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 \s-1NBD\s0 clients).
.IP "\fBcache=writethrough\fR" 4
.IX Item "cache=writethrough"
Always force writes through to the plugin.
.Sp
This makes the cache less effective, but is necessary if your client
does not issue correct flush requests.
.IP "\fBcache=unsafe\fR" 4
.IX Item "cache=unsafe"
Ignore flush requests.  Never write to the plugin unless the cache
grows too large.
.Sp
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.
.IP "\fBcache\-min\-block\-size=\fR\s-1SIZE\s0" 4
.IX Item "cache-min-block-size=SIZE"
Set the minimum block size used by the cache.  This must be a power of
2 and ≥ 4096.
.Sp
The default is 64K, or the block size of the filesystem which contains
the temporary file storing the cache (whichever is larger).
.IP "\fBcache\-max\-size=\fR\s-1SIZE\s0" 4
.IX Item "cache-max-size=SIZE"
.PD 0
.IP "\fBcache\-high\-threshold=\fRN" 4
.IX Item "cache-high-threshold=N"
.IP "\fBcache\-low\-threshold=\fRN" 4
.IX Item "cache-low-threshold=N"
.PD
(nbdkit ≥ 1.10)
.Sp
Limit the size of the cache to \f(CW\*(C`SIZE\*(C'\fR.  See \*(L"\s-1CACHE MAXIMUM SIZE\*(R"\s0 below.
.IP "\fBcache\-on\-read=true\fR" 4
.IX Item "cache-on-read=true"
(nbdkit ≥ 1.10)
.Sp
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.
.Sp
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 \fBnbdkit\-file\-plugin\fR\|(1)), this option will cause
nbdkit to serve stale data because reads won't always go through to
the plugin.
.IP "\fBcache\-on\-read=false\fR" 4
.IX Item "cache-on-read=false"
Do not cache read requests (this is the default).
.IP "\fBcache\-on\-read=/PATH\fR" 4
.IX Item "cache-on-read=/PATH"
(nbdkit ≥ 1.28)
.Sp
When \fI/PATH\fR (which must be an absolute path) exists, this behaves
like \f(CW\*(C`cache\-on\-read=true\*(C'\fR, and when it does not exist like
\&\f(CW\*(C`cache\-on\-read=false\*(C'\fR.  This allows you to control the cache-on-read
behaviour while nbdkit is running.
.SH "CACHE MAXIMUM SIZE"
.IX Header "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 \f(CW$TMPDIR\fR for it.
.PP
Using the parameters \f(CW\*(C`cache\-max\-size\*(C'\fR, \f(CW\*(C`cache\-high\-threshold\*(C'\fR and
\&\f(CW\*(C`cache\-low\-threshold\*(C'\fR you can limit the maximum size of the cache.
.PP
This requires kernel and filesystem support (for \fBfallocate\fR\|(2)
\&\f(CW\*(C`FALLOC_FL_PUNCH_HOLE\*(C'\fR), so it may not work on all platforms.
.PP
Some examples:
.ie n .IP """cache\-max\-size=1G""" 4
.el .IP "\f(CWcache\-max\-size=1G\fR" 4
.IX Item "cache-max-size=1G"
The cache is limited to around 1 gigabyte.
.ie n .IP """cache\-max\-size=1G cache\-high\-threshold=95 cache\-low\-threshold=80""" 4
.el .IP "\f(CWcache\-max\-size=1G cache\-high\-threshold=95 cache\-low\-threshold=80\fR" 4
.IX Item "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).
.PP
The way this works is once the size of the cache exceeds
\&\f(CW\*(C`SIZE\*(C'\fR ✕ the high threshold, the filter works to reduce the size
of the cache until it is less than \f(CW\*(C`SIZE\*(C'\fR ✕ 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.
.PP
The default thresholds are high 95% and low 80%.  You must set
0 < low < high.  The thresholds are expressed as integer
percentages of \f(CW\*(C`cache\-max\-size\*(C'\fR.
.PP
Least recently used blocks are discarded first.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """TMPDIR""" 4
.el .IP "\f(CWTMPDIR\fR" 4
.IX Item "TMPDIR"
The cache is stored in a temporary file located in \fI/var/tmp\fR by
default.  You can override this location by setting the \f(CW\*(C`TMPDIR\*(C'\fR
environment variable before starting nbdkit.
.SH "FILES"
.IX Header "FILES"
.IP "\fI\f(CI$filterdir\fI/nbdkit\-cache\-filter.so\fR" 4
.IX Item "$filterdir/nbdkit-cache-filter.so"
The filter.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$filterdir\fR.
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-cache\-filter\*(C'\fR first appeared in nbdkit 1.2.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-cacheextents\-filter\fR\|(1),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-readahead\-filter\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3),
\&\fBqemu\-img\fR\|(1).
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2018\-2021 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0