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

NAME

6       nbdkit-scan-filter - scan disk prefetching data ahead of sequential
7       reads
8

SYNOPSIS

10        nbdkit --filter=scan PLUGIN [scan-ahead=false] [scan-clock=false]
11                                    [scan-forever=true] [scan-size=]NN
12
13        nbdkit --filter=scan --filter=cache PLUGIN
14
15        nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true
16

DESCRIPTION

18       "nbdkit-scan-filter" is a filter that scans the disk prefetching data.
19       It is sometimes useful if you expect that the client will read the disk
20       sequentially.
21
22       The basic operation of the filter is that when a client connects, the
23       filter will start issuing ".cache" (prefetch) requests to the plugin
24       across the whole disk.  Plugins which support this command will
25       prefetch the data, making subsequent reads faster.  For plugins which
26       do not support this command, you can inject nbdkit-cache-filter(1)
27       below (after) this filter, giving approximately the same effect.
28       nbdkit-cow-filter(1) can be used instead of nbdkit-cache-filter, if you
29       add the "cow-on-cache=true" option.
30
31       Various parameters can be used to tune scanning, although the defaults
32       should be suitable in most cases.
33
34       A similar filter is nbdkit-readahead-filter(1).
35
36   Limitations
37       In a number of significant cases this filter will do nothing.  The
38       filter will print a warning message if this happens.
39
40       Thread model must be parallel*
41           For example nbdkit-curl-plugin(1) only supports
42           "serialize_requests", and so this filter cannot perform prefetches
43           in parallel with the read requests.
44
45       Only scans while clients are connected*
46           The current filter only scans while there is at least one client
47           connected.
48
49       Only scans the default export*
50           The current filter only scans the default export and ignores all
51           clients connecting to the non-default export name.
52
53           *We may be able to lift these restrictions in future.
54
55       Underlying filters or plugin must support ".cache" (prefetch)
56           Very many plugins do not have the concept of prefetching and/or do
57           not implement the ".cache" callback, and so there is no way for
58           this filter to issue prefetches.
59
60           You can usually get around this by adding --filter=cache after this
61           filter as explained above.
62
63       Prefetching the whole disk may load it all into cache
64           In particular if you use this filter together with
65           nbdkit-cache-filter(1) or nbdkit-cow-filter(1), they will cache the
66           whole content of the plugin into a temporary file.  This may be
67           many gigabytes of data, consuming all space in /var/tmp.  Of course
68           this is the whole point of using this filter, but you should be
69           aware of it.
70
71           If using the cache filter, the total size of the cache can be
72           limited (see "CACHE MAXIMUM SIZE" in nbdkit-cache-filter(1)).
73

PARAMETERS

75       scan-ahead=false
76           By default the filter tries to stay ahead of incoming read
77           requests.  That is to say, it starts prefetching at the beginning
78           of the disk and continues incrementally, but if the client issues a
79           read beyond the current prefetch point then the filter skips
80           forward and begins prefetching after the read.
81
82           However if you set this parameter to false, then this behaviour is
83           disabled.  The filter simply prefetches sequentially regardless of
84           client requests.
85
86       scan-clock=false
87           By default, if all clients disconnect and then another client
88           connects, prefetching resumes at the same place in the disk.  (Like
89           stopping and starting a clock.)
90
91           If you set this parameter to false, then the filter starts
92           prefetching from the beginning of the disk again.
93
94       scan-forever=true
95           By default the filter scans over the disk once and then stops.
96
97           If you set this parameter to true, then after the disk has been
98           prefetched completely, the filter goes back to the beginning and
99           starts over, repeating this for as long as nbdkit is running and
100           there are clients connected.
101
102       scan-size=NN
103           This parameter controls the prefetch block size.  The default is
104           "2M".  This must be a power of 2 and most plugins will have their
105           own limits on the amount of data they can prefetch in a single
106           request.
107

FILES

109       $filterdir/nbdkit-scan-filter.so
110           The filter.
111
112           Use "nbdkit --dump-config" to find the location of $filterdir.
113

VERSION

115       "nbdkit-scan-filter" first appeared in nbdkit 1.32.
116

SEE ALSO

118       nbdkit(1), nbdkit-cache-filter(1), nbdkit-cow-filter(1),
119       nbdkit-file-plugin(1), nbdkit-readahead-filter(1),
120       nbdkit-retry-filter(1), nbdkit-torrent-plugin(1),
121       nbdkit-vddk-plugin(1), nbdkit-filter(3), qemu-img(1).
122

AUTHORS

124       Richard W.M. Jones
125
127       Copyright Red Hat
128

LICENSE

130       Redistribution and use in source and binary forms, with or without
131       modification, are permitted provided that the following conditions are
132       met:
133
134       •   Redistributions of source code must retain the above copyright
135           notice, this list of conditions and the following disclaimer.
136
137       •   Redistributions in binary form must reproduce the above copyright
138           notice, this list of conditions and the following disclaimer in the
139           documentation and/or other materials provided with the
140           distribution.
141
142       •   Neither the name of Red Hat nor the names of its contributors may
143           be used to endorse or promote products derived from this software
144           without specific prior written permission.
145
146       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
147       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
148       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
149       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
150       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
151       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
152       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
153       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
154       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
155       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
156       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
157
158
159
160nbdkit-1.36.2                     2023-11-26             nbdkit-scan-filter(1)
Impressum