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) instead.
33
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 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 cache=writethrough
44 Always force writes through to the plugin.
45 This makes the cache less effective, but is necessary if your
47 client does not issue correct flush requests.
48 cache=unsafe
50 Ignore flush requests. Never write to the plugin unless the cache
51 grows too large.
52 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 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 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 cache-max-size=SIZE
66 cache-high-threshold=N
67 cache-low-threshold=N
68 (nbdkit ≥ 1.10)
69 Limit the size of the cache to "SIZE". See "CACHE MAXIMUM SIZE"
71 below.
72 cache-on-read=true
74 (nbdkit ≥ 1.10)
75 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 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 cache-on-read=false
88 Do not cache read requests (this is the default).
89 cache-on-read=/PATH
91 (nbdkit ≥ 1.28)
92 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
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 Using the parameters "cache-max-size", "cache-high-threshold" and
104 "cache-low-threshold" you can limit the maximum size of the cache.
105 This requires kernel and filesystem support (for fallocate(2)
107 "FALLOC_FL_PUNCH_HOLE"), so it may not work on all platforms.
108 Some examples:
110 "cache-max-size=1G"
112 The cache is limited to around 1 gigabyte.
113 "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 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 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 Least recently used blocks are discarded first.
129
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
137 $filterdir/nbdkit-cache-filter.so
138 The filter.
139 Use "nbdkit --dump-config" to find the location of $filterdir.
141
143 "nbdkit-cache-filter" first appeared in nbdkit 1.2.
144
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
151 Eric Blake
152 Richard W.M. Jones
154
156 Copyright (C) 2018-2021 Red Hat Inc.
157
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 • Redistributions of source code must retain the above copyright
164 notice, this list of conditions and the following disclaimer.
165 • 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 • 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 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.
186nbdkit-1.28.2 2021-11-09 nbdkit-cache-filter(1)