filters/blocksize-policy/nbdkit-blocksize-policy-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-blocksize-policy-filter - set minimum, preferred and
   4 maximum block size, and apply error policy
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit --filter=blocksize-policy PLUGIN
   9         [blocksize-error-policy=allow|error]
  10         [blocksize-minimum=N]
  11         [blocksize-preferred=N]
  12         [blocksize-maximum=N]
  13         [blocksize-write-disconnect=N]
  14
  15 =head1 DESCRIPTION
  16
  17 C<nbdkit-blocksize-policy-filter> is an L<nbdkit(1)> filter that
  18 can add block size constraints to plugins which don't already support
  19 them.  It can also enforce an error policy for badly behaved clients
  20 which do not obey the block size constraints.
  21
  22 For more information about block size constraints, see section
  23 "Block size constraints" in
  24 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>.
  25
  26 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 C<blocksize-minimum>, C<blocksize-preferred> and C<blocksize-maximum>
  29 parameters with the desired constraints.  For example:
  30
  31  nbdkit --filter=blocksize-policy memory 1G \
  32         blocksize-preferred=32K
  33
  34 would adjust L<nbdkit-memory-plugin(1)> so that clients should
  35 prefer 32K requests.  You can query the NBD server advertised constraints
  36 using L<nbdinfo(1)>:
  37
  38  $ nbdinfo nbd://localhost
  39  [...]
  40      block_size_minimum: 1
  41      block_size_preferred: 32768
  42      block_size_maximum: 4294967295
  43
  44 The second part of this filter is adjusting the error policy when
  45 badly 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
  49 read-modify-write for an unaligned write).  With this filter you can
  50 use C<blocksize-error-policy=error> to reject these requests in the
  51 filter with an EINVAL error.  The plugin will not see them.
  52
  53 Normally, nbdkit will accept write requests up to 64M in length, and
  54 reply with a gracful error message rather than a hard disconnect for a
  55 buffer up to twice that large.  But many other servers (for example,
  56 qemu-nbd) will give a hard disconnect for a write request larger than
  57 32M.  With this filter you can use C<blocksize-write-disconnect=32M>
  58 to emulate the behavior of other servers.
  59
  60 =head2 Combining with L<nbdkit-blocksize-filter(1)>
  61
  62 A related filter is L<nbdkit-blocksize-filter(1)>.  That filter can
  63 split and combine requests for plugins that cannot handle requests
  64 under or over a particular size.
  65
  66 Both filters may be used together like this (note that the order of
  67 the 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
  77 S<E<lt> 64K> which will be converted to slow 64K read-modify-write
  78 cycles to the underlying plugin.  In either case the plugin will only
  79 see requests on 64K (or multiples of 64K) boundaries.
  80
  81 =head1 PARAMETERS
  82
  83 =over 4
  84
  85 =item B<blocksize-error-policy=allow>
  86
  87 =item B<blocksize-error-policy=error>
  88
  89 If a client sends a request which is smaller than the permitted
  90 minimum size or larger than the permitted maximum size, or not aligned
  91 to the minimum size, C<blocksize-error-policy> chooses what the filter
  92 will do.  The default (and also nbdkit's default) is C<allow> which
  93 means pass the request through to the plugin.
  94
  95 Use C<error> to return an EINVAL error back to the client.  The plugin
  96 will not see the badly formed request in this case.
  97
  98 =item B<blocksize-write-disconnect=>N
  99
 100 (nbdkit E<ge> 1.34)
 101
 102 If a client sends a write request which is larger than the specified
 103 I<size> (using the usual size modifiers like C<32M>), abruptly close
 104 the connection.  This can be used to emulate qemu's behavior of
 105 disconnecting for write requests larger than 32M, rather than nbdkit's
 106 default of keeping the connection alive for write requests up to 128M
 107 (although nbdkit does not let the plugin see requests larger than
 108 64M).  The write disconnect size is independent of any advertised
 109 maximum block size or its accompanying error policy.
 110
 111 =item B<blocksize-minimum=>N
 112
 113 =item B<blocksize-preferred=>N
 114
 115 =item B<blocksize-maximum=>N
 116
 117 Advertise minimum, preferred and/or maximum block size to the client.
 118 Well-behaved clients should obey these constraints.
 119
 120 For each parameter, you can specify it as a size (using the usual
 121 modifiers like C<4K>).
 122
 123 If the parameter is omitted then either the constraint advertised by
 124 the plugin itself is used, or a sensible default for plugins which do
 125 not advertise block size constraints.
 126
 127 =back
 128
 129 =head1 FILES
 130
 131 =over 4
 132
 133 =item F<$filterdir/nbdkit-blocksize-policy-filter.so>
 134
 135 The filter.
 136
 137 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 138
 139 =back
 140
 141 =head1 VERSION
 142
 143 C<nbdkit-limit-filter> first appeared in nbdkit 1.30.
 144
 145 =head1 SEE ALSO
 146
 147 L<nbdkit(1)>,
 148 L<nbdkit-blocksize-filter(1)>,
 149 L<nbdkit-filter(3)>,
 150 L<nbdkit-plugin(3)>.
 151
 152 =head1 AUTHORS
 153
 154 Richard W.M. Jones
 155
 156 =head1 COPYRIGHT
 157
 158 Copyright Red Hat