1nbdkit-cache-filter(1)              NBDKIT              nbdkit-cache-filter(1)
2
3
4

NAME

6       nbdkit-cache-filter - nbdkit caching filter
7

SYNOPSIS

9        nbdkit --filter=cache plugin [plugin-args...]
10                                     [cache=writeback|writethrough|unsafe]
11                                     [cache-min-block-size=SIZE]
12                                     [cache-max-size=SIZE]
13                                     [cache-high-threshold=N]
14                                     [cache-low-threshold=N]
15                                     [cache-on-read=true|false|/PATH]
16

DESCRIPTION

18       "nbdkit-cache-filter" is a filter that adds caching on top of a plugin.
19       This is useful if a plugin is slow or expensive to use, because nbdkit
20       will try to minimize requests to the plugin by caching previous
21       requests.
22
23       Note that many NBD clients are able to do caching, and because the
24       caching happens on the client side it will usually be more effective
25       than caching inside the server.  This filter can be used if the client
26       does not have effective caching, or (with "cache=unsafe") to defeat
27       flush requests from the client (which is unsafe and can cause data
28       loss, as the name suggests).
29
30       This filter only caches image contents.  To cache image metadata, use
31       nbdkit-cacheextents-filter(1) between this filter and the plugin.  To
32       accelerate sequential reads, use nbdkit-readahead-filter(1) instead.
33

PARAMETERS

35       cache=writeback
36           Store writes in the cache.  They are not written to the plugin
37           unless an explicit flush is done by the client.
38
39           This is the default caching mode, and is safe if your client issues
40           flush requests correctly (which is true for modern Linux and other
41           well-written NBD clients).
42
43       cache=writethrough
44           Always force writes through to the plugin.
45
46           This makes the cache less effective, but is necessary if your
47           client does not issue correct flush requests.
48
49       cache=unsafe
50           Ignore flush requests.  Never write to the plugin unless the cache
51           grows too large.
52
53           This is dangerous and can cause data loss, but this may be
54           acceptable if you only use it for testing or with data that you
55           don't care about or can cheaply reconstruct.
56
57       cache-min-block-size=SIZE
58           Set the minimum block size used by the cache.  This must be a power
59           of 2 and ≥ 4096.
60
61           The default is 64K, or the block size of the filesystem which
62           contains the temporary file storing the cache (whichever is
63           larger).
64
65       cache-max-size=SIZE
66       cache-high-threshold=N
67       cache-low-threshold=N
68           (nbdkit ≥ 1.10)
69
70           Limit the size of the cache to "SIZE".  See "CACHE MAXIMUM SIZE"
71           below.
72
73       cache-on-read=true
74           (nbdkit ≥ 1.10)
75
76           Cache read requests as well as write and cache requests.  Any time
77           a block is read from the plugin, it is saved in the cache (if there
78           is sufficient space) so the same data can be served more quickly
79           later.
80
81           Note that if the underlying data served by the plugin can be
82           modified by some other means (eg. something else can write to a
83           file which is being served by nbdkit-file-plugin(1)), this option
84           will cause nbdkit to serve stale data because reads won't always go
85           through to the plugin.
86
87       cache-on-read=false
88           Do not cache read requests (this is the default).
89
90       cache-on-read=/PATH
91           (nbdkit ≥ 1.28)
92
93           When /PATH (which must be an absolute path) exists, this behaves
94           like "cache-on-read=true", and when it does not exist like
95           "cache-on-read=false".  This allows you to control the cache-on-
96           read behaviour while nbdkit is running.
97

CACHE MAXIMUM SIZE

99       By default the cache can grow to any size (although not larger than the
100       virtual size of the underlying plugin) and you have to ensure there is
101       sufficient space in $TMPDIR for it.
102
103       Using the parameters "cache-max-size", "cache-high-threshold" and
104       "cache-low-threshold" you can limit the maximum size of the cache.
105
106       This requires kernel and filesystem support (for fallocate(2)
107       "FALLOC_FL_PUNCH_HOLE"), so it may not work on all platforms.
108
109       Some examples:
110
111       "cache-max-size=1G"
112           The cache is limited to around 1 gigabyte.
113
114       "cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80"
115           Once the cache size reaches 972M (95% of 1G), blocks are reclaimed
116           from the cache until the size is reduced to 819M (80% of 1G).
117
118       The way this works is once the size of the cache exceeds
119       "SIZE" ✕ the high threshold, the filter works to reduce the size of the
120       cache until it is less than "SIZE" ✕ the low threshold.  Once the size
121       is below the low threshold, no more reclaim work is done until the size
122       exceeds the high threshold again.
123
124       The default thresholds are high 95% and low 80%.  You must set
125       0 < low < high.  The thresholds are expressed as integer percentages of
126       "cache-max-size".
127
128       Least recently used blocks are discarded first.
129

ENVIRONMENT VARIABLES

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

FILES

137       $filterdir/nbdkit-cache-filter.so
138           The filter.
139
140           Use "nbdkit --dump-config" to find the location of $filterdir.
141

VERSION

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

SEE ALSO

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

AUTHORS

151       Eric Blake
152
153       Richard W.M. Jones
154
156       Copyright (C) 2018-2021 Red Hat Inc.
157

LICENSE

159       Redistribution and use in source and binary forms, with or without
160       modification, are permitted provided that the following conditions are
161       met:
162
163       •   Redistributions of source code must retain the above copyright
164           notice, this list of conditions and the following disclaimer.
165
166       •   Redistributions in binary form must reproduce the above copyright
167           notice, this list of conditions and the following disclaimer in the
168           documentation and/or other materials provided with the
169           distribution.
170
171       •   Neither the name of Red Hat nor the names of its contributors may
172           be used to endorse or promote products derived from this software
173           without specific prior written permission.
174
175       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
176       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
177       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
178       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
179       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
180       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
181       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
182       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
183       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
184       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
185       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
186
187
188
189nbdkit-1.30.7                     2022-07-10            nbdkit-cache-filter(1)
Impressum