filters/multi-conn/nbdkit-multi-conn-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-multi-conn-filter - enable, emulate or disable multi-conn
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=multi-conn plugin
   8         [multi-conn-mode=MODE] [multi-conn-track-dirty=LEVEL]
   9         [multi-conn-exportname=BOOL]
  10         [plugin-args...]
  11
  12 =head1 DESCRIPTION
  13
  14 C<NBD_FLAG_CAN_MULTI_CONN> ("multi-conn") is an L<NBD protocol|
  15 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
  16 feature that permits multiple clients to connect to the same export
  17 simultaneously, guaranteeing that flush operations are consistent
  18 across connections.  Specifically a sequence of getting a write
  19 response, sending and waiting for a flush response, then sending a
  20 read request will behave the same whether all three commands shared a
  21 single connection or were split among three connections.  When an NBD
  22 client and server are able to negotiate this feature it can provide
  23 significant performance benefits.  Conversely if the feature is not
  24 advertised, clients must presume that separate connections can cache
  25 writes independently (so even after waiting for a flush on one
  26 connection, a read on another connection may see stale data from a
  27 cache).  The NBD standard advises clients not to multiplex commands
  28 across connections if the server does not support multi-conn.
  29
  30 L<nbdkit(1)> plugins must normally opt in to multi-conn, after
  31 carefully ensuring the implementation meets the consistency
  32 requirements.  This filter can emulate flush-consistent semantics
  33 across multiple connections for plugins that do not advertise this
  34 feature.
  35
  36 This filter also has additional modes useful for evaluating
  37 performance and correctness of client and plugin multi-conn behaviors.
  38
  39 This filter assumes that multiple connections to a plugin will
  40 eventually share data, other than any caching effects.  It is not
  41 suitable for use with a plugin that produces completely independent
  42 data per connection from the same export name.  An example of a plugin
  43 that must I<not> be used with this filter is
  44 L<nbdkit-tmpdisk-plugin(1)>.
  45
  46 Additional control over the behavior of client flush commands is
  47 possible by combining this filter with L<nbdkit-fua-filter(1)>.  Note
  48 that L<nbdkit-cache-filter(1)> is also able to provide
  49 multi-connection flush consistency, but at the expense of an extra
  50 layer of caching not needed with this filter.
  51
  52 =head1 PARAMETERS
  53
  54 =over 4
  55
  56 =item B<multi-conn-mode=auto>
  57
  58 This is the default mode.  The behaviour of B<auto> is as follows:
  59
  60 =over 4
  61
  62 =item *
  63
  64 If the selected thread model is C<SERIALIZE_CONNECTIONS>, then this
  65 filter behaves the same as B<disable> mode.
  66
  67 =item *
  68
  69 If the plugin advertises multi-conn, then this filter behaves the same
  70 as B<plugin> mode.
  71
  72 =item *
  73
  74 Otherwise, this filter behaves the same as B<emulate> mode.
  75
  76 =back
  77
  78 In other words, this mode advertises multi-conn to the client exactly
  79 when the plugin supports or can be made to support multiple
  80 simultaneous connections.
  81
  82 =item B<multi-conn-mode=emulate>
  83
  84 When B<emulate> mode is chosen, then this filter tracks all parallel
  85 connections.  When a client issues a flush command over any one
  86 connection (including an implied flush by a write command with the FUA
  87 (force unit access) flag set), the filter then replicates that flush
  88 across each connection to the plugin.  The number of plugin calls made
  89 by the filter can be tuned by adjusting B<multi-conn-track-dirty>.
  90
  91 This mode assumes that flushing each connection is enough to clear any
  92 per-connection cached data, in order to give each connection a
  93 consistent view of the image; therefore, this mode advertises
  94 multi-conn to the client.
  95
  96 Note that in this mode, a client will be unable to connect if the
  97 plugin lacks support for flush, as there would be no way to emulate
  98 cross-connection flush consistency.
  99
 100 =item B<multi-conn-mode=disable>
 101
 102 When B<disable> mode is chosen, this filter disables advertisement of
 103 multi-conn to the client, even if the plugin supports it, and does not
 104 replicate flush commands across connections.  This is useful for
 105 testing whether a client with multiple connections properly sends
 106 multiple flushes in order to overcome per-connection caching.
 107
 108 =item B<multi-conn-mode=plugin>
 109
 110 When B<plugin> mode is chosen, the filter does not change whether
 111 multi-conn is advertised by the plugin, and does not replicate flush
 112 commands across connections; but still honors
 113 B<multi-conn-track-dirty> for minimizing the number of flush commands
 114 passed on to the plugin.
 115
 116 =item B<multi-conn-mode=unsafe>
 117
 118 When B<unsafe> mode is chosen, this filter blindly advertises
 119 multi-conn to the client even if the plugin lacks support.  This is
 120 dangerous, and risks data corruption if the client makes assumptions
 121 about flush consistency that the plugin does not actually provide.
 122 However, for a plugin that does not yet advertise multi-conn, but
 123 where it is suspected that the plugin behaves consistently, this is a
 124 great way to run timing and accuracy tests to see whether enabling
 125 multi-conn in the plugin will make a difference.
 126
 127 =item B<multi-conn-track-dirty=fast>
 128
 129 When dirty tracking is set to B<fast>, the filter tracks whether any
 130 connection has caused the image to be dirty (any write, zero, or trim
 131 commands since the last flush, regardless of connection); if all
 132 connections are clean, a client flush command is ignored rather than
 133 sent on to the plugin.  In this mode, a flush action on one connection
 134 marks all other connections as clean, regardless of whether the filter
 135 actually advertised multi-conn, which can result in less activity when
 136 a client sends multiple flushes rather than taking advantage of
 137 multi-conn semantics.  This is safe with B<multi-conn-mode=emulate>,
 138 but potentially unsafe with B<multi-conn-mode=plugin> when the plugin
 139 did not advertise multi-conn, as it does not track whether a read may
 140 have cached stale data prior to a flush.
 141
 142 =item B<multi-conn-track-dirty=connection>
 143
 144 This is the default setting for B<multi-conn-track-dirty>.
 145
 146 The filter tracks whether a given connection is dirty (any write,
 147 zero, or trim commands since the last flush on the given connection,
 148 and any read since the last flush on any other connection); if the
 149 connection is clean, a flush command to that connection (whether
 150 directly from the client, or replicated by B<multi-conn-mode=emulate>
 151 is ignored rather than sent on to the plugin.  This mode may result in
 152 more flush calls than B<multi-conn-track-dirty=fast>, but in turn is
 153 safe to use with B<multi-conn-mode=plugin>.
 154
 155 =item B<multi-conn-track-dirty=off>
 156
 157 When dirty tracking is set to B<off>, all flush commands from the
 158 client are passed on to the plugin, regardless of whether the flush
 159 would be needed for cross-connection consistency.  Note that when
 160 combined with B<multi-conn-mode=emulate>, a client which disregards
 161 multi-conn by flushing on each connection itself results in a
 162 quadratic number of flush operations on the plugin.
 163
 164 =item B<multi-conn-exportname=false>
 165
 166 The exportname switch defaults to false for safety, and causes the
 167 filter to flush across all active connections regardless of the export
 168 name in use by that connection when doing emulation.  However, when a
 169 plugin supports distinct data according to export name, this behavior
 170 will penalize the performance of clients visiting an unrelated export
 171 by spending time on replicated flush operations not actually relevant
 172 to that export.
 173
 174 =item B<multi-conn-exportname=true>
 175
 176 Setting the exportname switch to true causes the filter to only
 177 synchronize flushes to connections visiting the same export name.
 178 This avoids penalizing clients visiting an unrelated export name (such
 179 as L<nbdkit-file-plugin(1)> in B<dir=> mode), but is unsafe when used
 180 with a plugin that serves shared content across all connections
 181 regardless of the export name requested by the client, if that plugin
 182 is not already multi-conn consistent (such as
 183 L<nbdkit-vddk-plugin(1)>).
 184
 185 =back
 186
 187 =head1 EXAMPLES
 188
 189 Provide consistent cross-connection flush semantics on top of a plugin
 190 that lacks it natively:
 191
 192  nbdkit --filter=multi-conn vddk /absolute/path/to/file.vmdk
 193
 194 Minimize the number of expensive flush operations performed when
 195 utilizing a plugin that has multi-conn consistency from a client that
 196 blindly flushes across every connection:
 197
 198  nbdkit --filter=multi-conn file multi-conn-mode=plugin \
 199    multi-conn-track-dirty=fast disk.img
 200
 201 =head1 FILES
 202
 203 =over 4
 204
 205 =item F<$filterdir/nbdkit-multi-conn-filter.so>
 206
 207 The filter.
 208
 209 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 210
 211 =back
 212
 213 =head1 VERSION
 214
 215 C<nbdkit-multi-conn-filter> first appeared in nbdkit 1.26.
 216
 217 =head1 SEE ALSO
 218
 219 L<nbdkit(1)>,
 220 L<nbdkit-file-plugin(1)>,
 221 L<nbdkit-vddk-plugin(1)>,
 222 L<nbdkit-filter(3)>,
 223 L<nbdkit-cache-filter(1)>,
 224 L<nbdkit-fua-filter(1)>,
 225 L<nbdkit-nocache-filter(1)>,
 226 L<nbdkit-noextents-filter(1)>,
 227 L<nbdkit-noparallel-filter(1)>,
 228 L<nbdkit-nozero-filter(1)>,
 229 L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
 230
 231 =head1 AUTHORS
 232
 233 Eric Blake
 234
 235 =head1 COPYRIGHT
 236
 237 Copyright Red Hat