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
17 "nbdkit-blocksize-policy-filter" is an nbdkit(1) filter that can add
18 block size constraints to plugins which don't already support them. It
19 can also enforce an error policy for badly behaved clients which do not
20 obey the block size constraints.
21 For more information about block size constraints, see section "Block
23 size constraints" in
24 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md.
25 The simplest usage is to place this filter on top of any plugin which
27 does not advertise block size constraints, and set the
28 "blocksize-minimum", "blocksize-preferred" and "blocksize-maximum"
29 parameters with the desired constraints. For example:
30 nbdkit --filter=blocksize-policy memory 1G \
32 blocksize-preferred=32K
33 would adjust nbdkit-memory-plugin(1) so that clients should prefer 32K
35 requests. You can query the NBD server advertised constraints using
36 nbdinfo(1):
37 $ nbdinfo nbd://localhost
39 [...]
40 block_size_minimum: 1
41 block_size_preferred: 32768
42 block_size_maximum: 4294967295
43 The second part of this filter is adjusting the error policy when badly
45 behaved clients do not obey the minimum or maximum request size.
46 Normally nbdkit permits these requests, leaving it up to the plugin
47 whether it rejects the request with an error or tries to process the
48 request (eg. trying to split an over-large request or doing a read-
49 modify-write for an unaligned write). With this filter you can use
50 "blocksize-error-policy=error" to reject these requests in the filter
51 with an EINVAL error. The plugin will not see them.
52 Combining with nbdkit-blocksize-filter(1)
54 A related filter is nbdkit-blocksize-filter(1). That filter can split
55 and combine requests for plugins that cannot handle requests under or
56 over a particular size.
57 Both filters may be used together like this (note that the order of the
59 filters is important):
60 nbdkit --filter=blocksize-policy \
62 --filter=blocksize \
63 PLUGIN ... \
64 blocksize-error-policy=allow \
65 blocksize-minimum=64K minblock=64K
66 This says to advertise a minimum block size of 64K. Well-behaved
68 clients will obey this. Badly behaved clients will send requests < 64K
69 which will be converted to slow 64K read-modify-write cycles to the
70 underlying plugin. In either case the plugin will only see requests on
71 64K (or multiples of 64K) boundaries.
72
74 blocksize-error-policy=allow
75 blocksize-error-policy=error
76 If a client sends a request which is smaller than the permitted
77 minimum size or larger than the permitted maximum size, or not
78 aligned to the minimum size, "blocksize-error-policy" chooses what
79 the filter will do. The default (and also nbdkit's default) is
80 "allow" which means pass the request through to the plugin.
81 Use "error" to return an EINVAL error back to the client. The
83 plugin will not see the badly formed request in this case.
84 blocksize-minimum=N
86 blocksize-preferred=N
87 blocksize-maximum=N
88 Advertise minimum, preferred and/or maximum block size to the
89 client. Well-behaved clients should obey these constraints.
90 For each parameter, you can specify it as a size (using the usual
92 modifiers like "4K").
93 If the parameter is omitted then either the constraint advertised
95 by the plugin itself is used, or a sensible default for plugins
96 which do not advertise block size constraints.
97
99 $filterdir/nbdkit-blocksize-policy-filter.so
100 The filter.
101 Use "nbdkit --dump-config" to find the location of $filterdir.
103
105 "nbdkit-limit-filter" first appeared in nbdkit 1.30.
106
108 nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-filter(3),
109 nbdkit-plugin(3).
110
112 Richard W.M. Jones
113
115 Copyright (C) 2022 Red Hat Inc.
116
118 Redistribution and use in source and binary forms, with or without
119 modification, are permitted provided that the following conditions are
120 met:
121 • Redistributions of source code must retain the above copyright
123 notice, this list of conditions and the following disclaimer.
124 • Redistributions in binary form must reproduce the above copyright
126 notice, this list of conditions and the following disclaimer in the
127 documentation and/or other materials provided with the
128 distribution.
129 • Neither the name of Red Hat nor the names of its contributors may
131 be used to endorse or promote products derived from this software
132 without specific prior written permission.
133 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
135 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
136 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
137 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
138 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
139 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
140 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
141 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
142 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
143 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
144 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
145nbdkit-1.32.5 2023-01-03 nbdkit-blocksize-policy-filter(1)