1nbdkit-cache-filter(1) NBDKIT nbdkit-cache-filter(1)
2
6 nbdkit-cache-filter - nbdkit caching filter
7
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
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 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
30 cache=writeback
31 Store writes in the cache. They are not written to the plugin
32 unless an explicit flush is done by the client.
33 This is the default caching mode, and is safe if your client issues
35 flush requests correctly (which is true for modern Linux and other
36 well-written NBD clients).
37 cache=writethrough
39 Always force writes through to the plugin.
40 This makes the cache less effective, but is necessary if your
42 client does not issue correct flush requests.
43 cache=unsafe
45 Ignore flush requests. Never write to the plugin unless the cache
46 grows too large.
47 This is dangerous and can cause data loss, but this may be
49 acceptable if you only use it for testing or with data that you
50 don't care about or can cheaply reconstruct.
51 cache-max-size=SIZE
53 cache-high-threshold=N
54 cache-low-threshold=N
55 Limit the size of the cache to "SIZE". See "CACHE MAXIMUM SIZE"
56 below.
57 cache-on-read=true
59 Cache read requests as well as write requests. Any time a block is
60 read from the plugin, it is saved in the cache (if there is
61 sufficient space) so the same data can be served more quickly
62 later.
63 Note that if the underlying data served by the plugin can be
65 modified by some other means (eg. something else can write to a
66 file which is being served by nbdkit-file-plugin(1)), this option
67 will cause nbdkit to serve stale data because reads won't always go
68 through to the plugin.
69 cache-on-read=false
71 Do not cache read requests (this is the default).
72
74 By default the cache can grow to any size (although not larger than the
75 virtual size of the underlying plugin) and you have to ensure there is
76 sufficient space in $TMPDIR for it.
77 Using the parameters "cache-max-size", "cache-high-threshold" and
79 "cache-low-threshold" you can limit the maximum size of the cache.
80 This requires kernel and filesystem support (for fallocate(2)
82 "FALLOC_FL_PUNCH_HOLE"), so it may not work on all platforms.
83 Some examples:
85 "cache-max-size=1G"
87 The cache is limited to around 1 gigabyte.
88 "cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80"
90 Once the cache size reaches 972M (95% of 1G), blocks are reclaimed
91 from the cache until the size is reduced to 819M (80% of 1G).
92 The way this works is once the size of the cache exceeds
94 "SIZE" ✕ the high threshold, the filter works to reduce the size of the
95 cache until it is less than "SIZE" ✕ the low threshold. Once the size
96 is below the low threshold, no more reclaim work is done until the size
97 exceeds the high threshold again.
98 The default thresholds are high 95% and low 80%. You must set
100 0 < low < high. The thresholds are expressed as integer percentages of
101 "cache-max-size".
102 Least recently used blocks are discarded first.
104
106 "TMPDIR"
107 The cache is stored in a temporary file located in /var/tmp by
108 default. You can override this location by setting the "TMPDIR"
109 environment variable before starting nbdkit.
110
112 nbdkit(1), nbdkit-file-plugin(1), nbdkit-readahead-filter(1),
113 nbdkit-filter(3), qemu-img(1).
114
116 Eric Blake
117 Richard W.M. Jones
119
121 Copyright (C) 2018 Red Hat Inc.
122
124 Redistribution and use in source and binary forms, with or without
125 modification, are permitted provided that the following conditions are
126 met:
127 · Redistributions of source code must retain the above copyright
129 notice, this list of conditions and the following disclaimer.
130 · Redistributions in binary form must reproduce the above copyright
132 notice, this list of conditions and the following disclaimer in the
133 documentation and/or other materials provided with the
134 distribution.
135 · Neither the name of Red Hat nor the names of its contributors may
137 be used to endorse or promote products derived from this software
138 without specific prior written permission.
139 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
141 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
142 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
143 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
144 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
145 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
146 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
147 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
148 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
149 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
150 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
151nbdkit-1.12.3 2019-05-21 nbdkit-cache-filter(1)