nbdkit-multi-conn-filter(1)

1nbdkit-multi-conn-filter(1)         NBDKIT         nbdkit-multi-conn-filter(1)
2
3
4

NAME

6       nbdkit-multi-conn-filter - enable, emulate or disable multi-conn
7

SYNOPSIS

9        nbdkit --filter=multi-conn plugin
10               [multi-conn-mode=MODE] [multi-conn-track-dirty=LEVEL]
11               [multi-conn-exportname=BOOL]
12               [plugin-args...]
13

DESCRIPTION

15       "NBD_FLAG_CAN_MULTI_CONN" ("multi-conn") is an NBD protocol feature
16       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 read
20       request will behave the same whether all three commands shared a single
21       connection or were split among three connections.  When an NBD client
22       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       nbdkit(1) plugins must normally opt in to multi-conn, after carefully
31       ensuring the implementation meets the consistency requirements.  This
32       filter can emulate flush-consistent semantics across multiple
33       connections for plugins that do not advertise this feature.
34
35       This filter also has additional modes useful for evaluating performance
36       and correctness of client and plugin multi-conn behaviors.
37
38       This filter assumes that multiple connections to a plugin will
39       eventually share data, other than any caching effects.  It is not
40       suitable for use with a plugin that produces completely independent
41       data per connection from the same export name.  An example of a plugin
42       that must not be used with this filter is nbdkit-tmpdisk-plugin(1).
43
44       Additional control over the behavior of client flush commands is
45       possible by combining this filter with nbdkit-fua-filter(1).  Note that
46       nbdkit-cache-filter(1) is also able to provide multi-connection flush
47       consistency, but at the expense of an extra layer of caching not needed
48       with this filter.
49

PARAMETERS

51       multi-conn-mode=auto
52           This is the default mode.  The behaviour of auto is as follows:
53
54           •   If the selected thread model is "SERIALIZE_CONNECTIONS", then
55               this filter behaves the same as disable mode.
56
57           •   If the plugin advertises multi-conn, then this filter behaves
58               the same as plugin mode.
59
60           •   Otherwise, this filter behaves the same as emulate mode.
61
62           In other words, this mode advertises multi-conn to the client
63           exactly when the plugin supports or can be made to support multiple
64           simultaneous connections.
65
66       multi-conn-mode=emulate
67           When emulate mode is chosen, then this filter tracks all parallel
68           connections.  When a client issues a flush command over any one
69           connection (including an implied flush by a write command with the
70           FUA (force unit access) flag set), the filter then replicates that
71           flush across each connection to the plugin.  The number of plugin
72           calls made by the filter can be tuned by adjusting multi-conn-
73           track-dirty.
74
75           This mode assumes that flushing each connection is enough to clear
76           any per-connection cached data, in order to give each connection a
77           consistent view of the image; therefore, this mode advertises
78           multi-conn to the client.
79
80           Note that in this mode, a client will be unable to connect if the
81           plugin lacks support for flush, as there would be no way to emulate
82           cross-connection flush consistency.
83
84       multi-conn-mode=disable
85           When disable mode is chosen, this filter disables advertisement of
86           multi-conn to the client, even if the plugin supports it, and does
87           not replicate flush commands across connections.  This is useful
88           for testing whether a client with multiple connections properly
89           sends multiple flushes in order to overcome per-connection caching.
90
91       multi-conn-mode=plugin
92           When plugin mode is chosen, the filter does not change whether
93           multi-conn is advertised by the plugin, and does not replicate
94           flush commands across connections; but still honors multi-conn-
95           track-dirty for minimizing the number of flush commands passed on
96           to the plugin.
97
98       multi-conn-mode=unsafe
99           When unsafe mode is chosen, this filter blindly advertises multi-
100           conn to the client even if the plugin lacks support.  This is
101           dangerous, and risks data corruption if the client makes
102           assumptions about flush consistency that the plugin does not
103           actually provide.  However, for a plugin that does not yet
104           advertise multi-conn, but where it is suspected that the plugin
105           behaves consistently, this is a great way to run timing and
106           accuracy tests to see whether enabling multi-conn in the plugin
107           will make a difference.
108
109       multi-conn-track-dirty=fast
110           When dirty tracking is set to fast, the filter tracks whether any
111           connection has caused the image to be dirty (any write, zero, or
112           trim commands since the last flush, regardless of connection); if
113           all connections are clean, a client flush command is ignored rather
114           than sent on to the plugin.  In this mode, a flush action on one
115           connection marks all other connections as clean, regardless of
116           whether the filter actually advertised multi-conn, which can result
117           in less activity when a client sends multiple flushes rather than
118           taking advantage of multi-conn semantics.  This is safe with
119           multi-conn-mode=emulate, but potentially unsafe with
120           multi-conn-mode=plugin when the plugin did not advertise multi-
121           conn, as it does not track whether a read may have cached stale
122           data prior to a flush.
123
124       multi-conn-track-dirty=connection
125           This is the default setting for multi-conn-track-dirty.
126
127           The filter tracks whether a given connection is dirty (any write,
128           zero, or trim commands since the last flush on the given
129           connection, and any read since the last flush on any other
130           connection); if the connection is clean, a flush command to that
131           connection (whether directly from the client, or replicated by
132           multi-conn-mode=emulate is ignored rather than sent on to the
133           plugin.  This mode may result in more flush calls than
134           multi-conn-track-dirty=fast, but in turn is safe to use with
135           multi-conn-mode=plugin.
136
137       multi-conn-track-dirty=off
138           When dirty tracking is set to off, all flush commands from the
139           client are passed on to the plugin, regardless of whether the flush
140           would be needed for cross-connection consistency.  Note that when
141           combined with multi-conn-mode=emulate, a client which disregards
142           multi-conn by flushing on each connection itself results in a
143           quadratic number of flush operations on the plugin.
144
145       multi-conn-exportname=false
146           The exportname switch defaults to false for safety, and causes the
147           filter to flush across all active connections regardless of the
148           export name in use by that connection when doing emulation.
149           However, when a plugin supports distinct data according to export
150           name, this behavior will penalize the performance of clients
151           visiting an unrelated export by spending time on replicated flush
152           operations not actually relevant to that export.
153
154       multi-conn-exportname=true
155           Setting the exportname switch to true causes the filter to only
156           synchronize flushes to connections visiting the same export name.
157           This avoids penalizing clients visiting an unrelated export name
158           (such as nbdkit-file-plugin(1) in dir= mode), but is unsafe when
159           used with a plugin that serves shared content across all
160           connections regardless of the export name requested by the client,
161           if that plugin is not already multi-conn consistent (such as
162           nbdkit-vddk-plugin(1)).
163

EXAMPLES

165       Provide consistent cross-connection flush semantics on top of a plugin
166       that lacks it natively:
167
168        nbdkit --filter=multi-conn vddk /absolute/path/to/file.vmdk
169
170       Minimize the number of expensive flush operations performed when
171       utilizing a plugin that has multi-conn consistency from a client that
172       blindly flushes across every connection:
173
174        nbdkit --filter=multi-conn file multi-conn-mode=plugin \
175          multi-conn-track-dirty=fast disk.img
176

FILES

178       $filterdir/nbdkit-multi-conn-filter.so
179           The filter.
180
181           Use "nbdkit --dump-config" to find the location of $filterdir.
182

VERSION

184       "nbdkit-multi-conn-filter" first appeared in nbdkit 1.26.
185

AUTHORS

194       Eric Blake
195

COPYRIGHT

197       Copyright Red Hat
198

LICENSE

200       Redistribution and use in source and binary forms, with or without
201       modification, are permitted provided that the following conditions are
202       met:
203
204       •   Redistributions of source code must retain the above copyright
205           notice, this list of conditions and the following disclaimer.
206
207       •   Redistributions in binary form must reproduce the above copyright
208           notice, this list of conditions and the following disclaimer in the
209           documentation and/or other materials provided with the
210           distribution.
211
212       •   Neither the name of Red Hat nor the names of its contributors may
213           be used to endorse or promote products derived from this software
214           without specific prior written permission.
215
216       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
217       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
218       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
219       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
220       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
221       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
222       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
223       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
224       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
225       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
226       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
227
228
229
230nbdkit-1.36.2                     2023-11-26       nbdkit-multi-conn-filter(1)