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 [cache=writeback|writethrough|unsafe]
10                                     [cache-max-size=SIZE]
11                                     [cache-high-threshold=N]
12                                     [cache-low-threshold=N]
13                                     [cache-on-read=true|false]
14                                     [plugin-args...]
15

DESCRIPTION

17       "nbdkit-cache-filter" is a filter that adds caching on top of a plugin.
18       This is useful if a plugin is slow or expensive to use, because nbdkit
19       will try to minimize requests to the plugin by caching previous
20       requests.
21
22       Note that many NBD 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 "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       Note that the use of this filter rounds the image size down to a
30       multiple of the caching granularity (the larger of 4096 or the
31       "f_bsize" field of fstatvfs(3)), to ease the implementation. If you
32       need to round the image size up instead to access the last few bytes,
33       combine this filter with nbdkit-truncate-filter(1).
34
35       This filter only caches image contents.  To cache image metadata, use
36       nbdkit-cacheextents-filter(1) between this filter and the plugin.  To
37       accelerate sequential reads, use nbdkit-readahead-filter(1) instead.
38

PARAMETERS

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

CACHE MAXIMUM SIZE

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

ENVIRONMENT VARIABLES

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

FILES

126       $filterdir/nbdkit-cache-filter.so
127           The filter.
128
129           Use "nbdkit --dump-config" to find the location of $filterdir.
130

VERSION

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

SEE ALSO

135       nbdkit(1), nbdkit-file-plugin(1), nbdkit-cacheextents-filter(1),
136       nbdkit-readahead-filter(1), nbdkit-truncate-filter(1),
137       nbdkit-filter(3), qemu-img(1).
138

AUTHORS

140       Eric Blake
141
142       Richard W.M. Jones
143
145       Copyright (C) 2018-2020 Red Hat Inc.
146

LICENSE

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