1nbdkit-cache-filter(1) NBDKIT nbdkit-cache-filter(1)
2
6 nbdkit-cache-filter - nbdkit caching filter
7
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
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 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 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) or
33 nbdkit-scan-filter(1) on top of this filter.
34
36 cache=writeback
37 Store writes in the cache. They are not written to the plugin
38 unless an explicit flush is done by the client.
39 This is the default caching mode, and is safe if your client issues
41 flush requests correctly (which is true for modern Linux and other
42 well-written NBD clients).
43 cache=writethrough
45 Always force writes through to the plugin.
46 This makes the cache less effective, but is necessary if your
48 client does not issue correct flush requests.
49 cache=unsafe
51 Ignore flush requests. Never write to the plugin unless the cache
52 grows too large.
53 This is dangerous and can cause data loss, but this may be
55 acceptable if you only use it for testing or with data that you
56 don't care about or can cheaply reconstruct.
57 cache-min-block-size=SIZE
59 Set the minimum block size used by the cache. This must be a power
60 of 2 and ≥ 4096.
61 The default is 64K, or the block size of the filesystem which
63 contains the temporary file storing the cache (whichever is
64 larger).
65 cache-max-size=SIZE
67 cache-high-threshold=N
68 cache-low-threshold=N
69 (nbdkit ≥ 1.10)
70 Limit the size of the cache to "SIZE". See "CACHE MAXIMUM SIZE"
72 below.
73 cache-on-read=true
75 (nbdkit ≥ 1.10)
76 Cache read requests as well as write and cache requests. Any time
78 a block is read from the plugin, it is saved in the cache (if there
79 is sufficient space) so the same data can be served more quickly
80 later.
81 Note that if the underlying data served by the plugin can be
83 modified by some other means (eg. something else can write to a
84 file which is being served by nbdkit-file-plugin(1)), this option
85 will cause nbdkit to serve stale data because reads won't always go
86 through to the plugin.
87 cache-on-read=false
89 Do not cache read requests (this is the default).
90 cache-on-read=/PATH
92 (nbdkit ≥ 1.28)
93 When /PATH (which must be an absolute path) exists, this behaves
95 like "cache-on-read=true", and when it does not exist like
96 "cache-on-read=false". This allows you to control the cache-on-
97 read behaviour while nbdkit is running.
98
100 By default the cache can grow to any size (although not larger than the
101 virtual size of the underlying plugin) and you have to ensure there is
102 sufficient space in $TMPDIR for it.
103 Using the parameters "cache-max-size", "cache-high-threshold" and
105 "cache-low-threshold" you can limit the maximum size of the cache.
106 This requires kernel and filesystem support (for fallocate(2)
108 "FALLOC_FL_PUNCH_HOLE"), so it may not work on all platforms.
109 Some examples:
111 "cache-max-size=1G"
113 The cache is limited to around 1 gigabyte.
114 "cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80"
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 The way this works is once the size of the cache exceeds
120 "SIZE" ✕ the high threshold, the filter works to reduce the size of the
121 cache until it is less than "SIZE" ✕ the low threshold. Once the size
122 is below the low threshold, no more reclaim work is done until the size
123 exceeds the high threshold again.
124 The default thresholds are high 95% and low 80%. You must set
126 0 < low < high. The thresholds are expressed as integer percentages of
127 "cache-max-size".
128 Least recently used blocks are discarded first.
130
132 "TMPDIR"
133 The cache is stored in a temporary file located in /var/tmp by
134 default. You can override this location by setting the "TMPDIR"
135 environment variable before starting nbdkit.
136
138 $filterdir/nbdkit-cache-filter.so
139 The filter.
140 Use "nbdkit --dump-config" to find the location of $filterdir.
142
144 "nbdkit-cache-filter" first appeared in nbdkit 1.2.
145
147 nbdkit(1), nbdkit-file-plugin(1), nbdkit-cacheextents-filter(1),
148 nbdkit-cow-filter(1), nbdkit-readahead-filter(1), nbdkit-filter(3),
149 qemu-img(1).
150
152 Eric Blake
153 Richard W.M. Jones
155
157 Copyright (C) 2018-2021 Red Hat Inc.
158
160 Redistribution and use in source and binary forms, with or without
161 modification, are permitted provided that the following conditions are
162 met:
163 • Redistributions of source code must retain the above copyright
165 notice, this list of conditions and the following disclaimer.
166 • Redistributions in binary form must reproduce the above copyright
168 notice, this list of conditions and the following disclaimer in the
169 documentation and/or other materials provided with the
170 distribution.
171 • Neither the name of Red Hat nor the names of its contributors may
173 be used to endorse or promote products derived from this software
174 without specific prior written permission.
175 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
177 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
178 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
179 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
180 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
181 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
182 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
183 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
184 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
185 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
186 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
187nbdkit-1.32.5 2023-01-03 nbdkit-cache-filter(1)