1nbdkit-blocksize-policy-filter(1) NBDKIT nbdkit-blocksize-policy-filter(1)
2
6 nbdkit-blocksize-policy-filter - set minimum, preferred and maximum
7 block size, and apply error policy
8
10 nbdkit --filter=blocksize-policy PLUGIN
11 [blocksize-error-policy=allow|error]
12 [blocksize-minimum=N]
13 [blocksize-preferred=N]
14 [blocksize-maximum=N]
15 [blocksize-write-disconnect=N]
16
18 "nbdkit-blocksize-policy-filter" is an nbdkit(1) filter that can add
19 block size constraints to plugins which don't already support them. It
20 can also enforce an error policy for badly behaved clients which do not
21 obey the block size constraints.
22 For more information about block size constraints, see section "Block
24 size constraints" in
25 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md.
26 The simplest usage is to place this filter on top of any plugin which
28 does not advertise block size constraints, and set the
29 "blocksize-minimum", "blocksize-preferred" and "blocksize-maximum"
30 parameters with the desired constraints. For example:
31 nbdkit --filter=blocksize-policy memory 1G \
33 blocksize-preferred=32K
34 would adjust nbdkit-memory-plugin(1) so that clients should prefer 32K
36 requests. You can query the NBD server advertised constraints using
37 nbdinfo(1):
38 $ nbdinfo nbd://localhost
40 [...]
41 block_size_minimum: 1
42 block_size_preferred: 32768
43 block_size_maximum: 4294967295
44 The second part of this filter is adjusting the error policy when badly
46 behaved clients do not obey the minimum or maximum request size.
47 Normally nbdkit permits these requests, leaving it up to the plugin
48 whether it rejects the request with an error or tries to process the
49 request (eg. trying to split an over-large request or doing a read-
50 modify-write for an unaligned write). With this filter you can use
51 "blocksize-error-policy=error" to reject these requests in the filter
52 with an EINVAL error. The plugin will not see them.
53 Normally, nbdkit will accept write requests up to 64M in length, and
55 reply with a gracful error message rather than a hard disconnect for a
56 buffer up to twice that large. But many other servers (for example,
57 qemu-nbd) will give a hard disconnect for a write request larger than
58 32M. With this filter you can use "blocksize-write-disconnect=32M" to
59 emulate the behavior of other servers.
60 Combining with nbdkit-blocksize-filter(1)
62 A related filter is nbdkit-blocksize-filter(1). That filter can split
63 and combine requests for plugins that cannot handle requests under or
64 over a particular size.
65 Both filters may be used together like this (note that the order of the
67 filters is important):
68 nbdkit --filter=blocksize-policy \
70 --filter=blocksize \
71 PLUGIN ... \
72 blocksize-error-policy=allow \
73 blocksize-minimum=64K minblock=64K
74 This says to advertise a minimum block size of 64K. Well-behaved
76 clients will obey this. Badly behaved clients will send requests < 64K
77 which will be converted to slow 64K read-modify-write cycles to the
78 underlying plugin. In either case the plugin will only see requests on
79 64K (or multiples of 64K) boundaries.
80
82 blocksize-error-policy=allow
83 blocksize-error-policy=error
84 If a client sends a request which is smaller than the permitted
85 minimum size or larger than the permitted maximum size, or not
86 aligned to the minimum size, "blocksize-error-policy" chooses what
87 the filter will do. The default (and also nbdkit's default) is
88 "allow" which means pass the request through to the plugin.
89 Use "error" to return an EINVAL error back to the client. The
91 plugin will not see the badly formed request in this case.
92 blocksize-write-disconnect=N
94 (nbdkit ≥ 1.34)
95 If a client sends a write request which is larger than the
97 specified size (using the usual size modifiers like "32M"),
98 abruptly close the connection. This can be used to emulate qemu's
99 behavior of disconnecting for write requests larger than 32M,
100 rather than nbdkit's default of keeping the connection alive for
101 write requests up to 128M (although nbdkit does not let the plugin
102 see requests larger than 64M). The write disconnect size is
103 independent of any advertised maximum block size or its
104 accompanying error policy.
105 blocksize-minimum=N
107 blocksize-preferred=N
108 blocksize-maximum=N
109 Advertise minimum, preferred and/or maximum block size to the
110 client. Well-behaved clients should obey these constraints.
111 For each parameter, you can specify it as a size (using the usual
113 modifiers like "4K").
114 If the parameter is omitted then either the constraint advertised
116 by the plugin itself is used, or a sensible default for plugins
117 which do not advertise block size constraints.
118
120 $filterdir/nbdkit-blocksize-policy-filter.so
121 The filter.
122 Use "nbdkit --dump-config" to find the location of $filterdir.
124
126 "nbdkit-limit-filter" first appeared in nbdkit 1.30.
127
129 nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-filter(3),
130 nbdkit-plugin(3).
131
133 Richard W.M. Jones
134
136 Copyright Red Hat
137
139 Redistribution and use in source and binary forms, with or without
140 modification, are permitted provided that the following conditions are
141 met:
142 • Redistributions of source code must retain the above copyright
144 notice, this list of conditions and the following disclaimer.
145 • Redistributions in binary form must reproduce the above copyright
147 notice, this list of conditions and the following disclaimer in the
148 documentation and/or other materials provided with the
149 distribution.
150 • Neither the name of Red Hat nor the names of its contributors may
152 be used to endorse or promote products derived from this software
153 without specific prior written permission.
154 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
156 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
157 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
158 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
159 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
160 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
161 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
162 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
163 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
164 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
165 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
166nbdkit-1.36.2 2023-11-26 nbdkit-blocksize-policy-filter(1)