1nbdkit-blocksize-policy-filter(1)   NBDKIT   nbdkit-blocksize-policy-filter(1)
2
3
4

NAME

6       nbdkit-blocksize-policy-filter - set minimum, preferred and maximum
7       block size, and apply error policy
8

SYNOPSIS

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

DESCRIPTION

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
23       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
27       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
32        nbdkit --filter=blocksize-policy memory 1G \
33               blocksize-preferred=32K
34
35       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
39        $ nbdinfo nbd://localhost
40        [...]
41            block_size_minimum: 1
42            block_size_preferred: 32768
43            block_size_maximum: 4294967295
44
45       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
54       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
61   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
66       Both filters may be used together like this (note that the order of the
67       filters is important):
68
69         nbdkit --filter=blocksize-policy \
70                --filter=blocksize \
71                PLUGIN ... \
72                blocksize-error-policy=allow \
73                blocksize-minimum=64K minblock=64K
74
75       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

PARAMETERS

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
90           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
93       blocksize-write-disconnect=N
94           (nbdkit ≥ 1.34)
95
96           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
106       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
112           For each parameter, you can specify it as a size (using the usual
113           modifiers like "4K").
114
115           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

FILES

120       $filterdir/nbdkit-blocksize-policy-filter.so
121           The filter.
122
123           Use "nbdkit --dump-config" to find the location of $filterdir.
124

VERSION

126       "nbdkit-limit-filter" first appeared in nbdkit 1.30.
127

SEE ALSO

129       nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-filter(3),
130       nbdkit-plugin(3).
131

AUTHORS

133       Richard W.M. Jones
134
136       Copyright Red Hat
137

LICENSE

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
143       •   Redistributions of source code must retain the above copyright
144           notice, this list of conditions and the following disclaimer.
145
146       •   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
151       •   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
155       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.
166
167
168
169nbdkit-1.36.2                     2023-11-26 nbdkit-blocksize-policy-filter(1)
Impressum