nbdkit-multi-conn-filter(1)

📦

version 1.48.1 · 13 versions

🦋 nbdkit-multi-conn-filter 🦋

okay bestie, this is the nbdkit-multi-conn-filter page from the NBDKIT manual, and it's genuinely one of the most "trust me bro, it's about consistency" filters in the whole toolkit. let's get into it 💅

✨ NAME ✨

nbdkit-multi-conn-filter — enable, emulate or disable multi-conn

🌸 SYNOPSIS 🌸

nbdkit --filter=multi-conn plugin
       [multi-conn-mode=MODE] [multi-conn-track-dirty=LEVEL]
       [multi-conn-exportname=BOOL]
       [plugin-args...]

💜 DESCRIPTION 💜

so NBD_FLAG_CAN_MULTI_CONN (aka "multi-conn", ikyk) is an NBD protocol feature that lets multiple clients connect to the same export at the same time, and it guarantees flush operations are consistent across those connections. like, specifically: if you get a write response, then send a flush and wait for the flush response, then send a read request — that whole sequence behaves exactly the same whether all three commands went down one single connection or got split across three different connections. when an NBD client and server can negotiate this, it's giving significant performance benefits ✨

and conversely, if the feature is not advertised, clients have to presume that separate connections can cache writes independently (so even after waiting for a flush on one connection, a read on another connection may see stale data from a cache 😭). the NBD standard literally advises clients not to multiplex commands across connections if the server doesn't support multi-conn.

nbdkit(1) plugins must normally opt in to multi-conn, after carefully making sure the implementation actually meets the consistency requirements. this filter can emulate flush-consistent semantics across multiple connections for plugins that don't advertise this feature. iconic.

this filter also has extra modes that are useful for evaluating performance and correctness of client and plugin multi-conn behaviors 🔥

⚠️ this filter assumes that multiple connections to a plugin will eventually share data, other than any caching effects. it is not suitable for use with a plugin that produces completely independent data per connection from the same export name. an example of a plugin that must not be used with this filter is nbdkit-tmpdisk-plugin(1). no cap, don't do it 🙈

additional control over the behavior of client flush commands is possible by combining this filter with nbdkit-fua-filter(1). also note that nbdkit-cache-filter(1) is also able to provide multi-connection flush consistency, but at the expense of an extra layer of caching that isn't needed with this filter.

🎀 PARAMETERS 🎀

multi-conn-mode=auto — this is the default mode. the behaviour of auto is as follows:
- if the selected thread model is SERIALIZE_CONNECTIONS, then this filter behaves the same as disable mode.
- if the plugin advertises multi-conn, then this filter behaves the same as plugin mode.
- otherwise, this filter behaves the same as emulate mode.

in other words, this mode advertises multi-conn to the client exactly when the plugin supports, or can be made to support, multiple simultaneous connections. 💖

multi-conn-mode=emulate — when emulate mode is chosen, this filter tracks all parallel connections. when a client issues a flush command over any one connection (including an implied flush by a write command with the FUA (force unit access) flag set), the filter then replicates that flush across each connection to the plugin. the number of plugin calls made by the filter can be tuned by adjusting multi-conn-track-dirty.

this mode assumes that flushing each connection is enough to clear any per-connection cached data, in order to give each connection a consistent view of the image; therefore, this mode advertises multi-conn to the client.

note that in this mode, a client will be unable to connect if the plugin lacks support for flush, because there'd be no way to emulate cross-connection flush consistency. 😭

multi-conn-mode=disable — when disable mode is chosen, this filter disables advertisement of multi-conn to the client, even if the plugin supports it, and does not replicate flush commands across connections. this is useful for testing whether a client with multiple connections properly sends multiple flushes in order to overcome per-connection caching. 🧚
multi-conn-mode=plugin — when plugin mode is chosen, the filter does not change whether multi-conn is advertised by the plugin, and does not replicate flush commands across connections; but it still honors multi-conn-track-dirty for minimizing the number of flush commands passed on to the plugin.
multi-conn-mode=unsafe — when unsafe mode is chosen, this filter blindly advertises multi-conn to the client even if the plugin lacks support. this is dangerous, and risks data corruption if the client makes assumptions about flush consistency that the plugin does not actually provide. however, for a plugin that doesn't yet advertise multi-conn, but where it's suspected that the plugin behaves consistently, this is a great way to run timing and accuracy tests to see whether enabling multi-conn in the plugin will make a difference. 👑
multi-conn-track-dirty=fast — when dirty tracking is set to fast, the filter tracks whether any connection has caused the image to be dirty (any write, zero, or trim commands since the last flush, regardless of connection); if all connections are clean, a client flush command is ignored rather than sent on to the plugin. in this mode, a flush action on one connection marks all other connections as clean, regardless of whether the filter actually advertised multi-conn, which can result in less activity when a client sends multiple flushes rather than taking advantage of multi-conn semantics. this is safe with multi-conn-mode=emulate, but potentially unsafe with multi-conn-mode=plugin when the plugin did not advertise multi-conn, as it does not track whether a read may have cached stale data prior to a flush. 💀
multi-conn-track-dirty=connection — this is the default setting for multi-conn-track-dirty.

the filter tracks whether a given connection is dirty (any write, zero, or trim commands since the last flush on the given connection, and any read since the last flush on any other connection); if the connection is clean, a flush command to that connection (whether directly from the client, or replicated by multi-conn-mode=emulate is ignored rather than sent on to the plugin. this mode may result in more flush calls than multi-conn-track-dirty=fast, but in turn is safe to use with multi-conn-mode=plugin.

multi-conn-track-dirty=off — when dirty tracking is set to off, all flush commands from the client are passed on to the plugin, regardless of whether the flush would be needed for cross-connection consistency. note that when combined with multi-conn-mode=emulate, a client which disregards multi-conn by flushing on each connection itself results in a quadratic number of flush operations on the plugin. 😭 not the quadratic blowup bestie
multi-conn-exportname=false — the exportname switch defaults to false for safety, and causes the filter to flush across all active connections regardless of the export name in use by that connection when doing emulation. however, when a plugin supports distinct data according to export name, this behavior will penalize the performance of clients visiting an unrelated export by spending time on replicated flush operations that aren't actually relevant to that export.
multi-conn-exportname=true — setting the exportname switch to true causes the filter to only synchronize flushes to connections visiting the same export name. this avoids penalizing clients visiting an unrelated export name (such as nbdkit-file-plugin(1) in dir= mode), but is unsafe when used with a plugin that serves shared content across all connections regardless of the export name requested by the client, if that plugin is not already multi-conn consistent (such as nbdkit-vddk-plugin(1)). 🚨

🌈 EXAMPLES 🌈

provide consistent cross-connection flush semantics on top of a plugin that lacks it natively:

nbdkit --filter=multi-conn vddk /absolute/path/to/file.vmdk

minimize the number of expensive flush operations performed when utilizing a plugin that has multi-conn consistency from a client that blindly flushes across every connection:

nbdkit --filter=multi-conn file multi-conn-mode=plugin \
  multi-conn-track-dirty=fast disk.img

🍓 FILES 🍓

$filterdir/nbdkit-multi-conn-filter.so — the filter. 🫶

use nbdkit --dump-config to find the location of $filterdir.

⭐ VERSION ⭐

nbdkit-multi-conn-filter first appeared in nbdkit 1.26. periodt.

💖 AUTHORS 💖

Eric Blake — the main character, honestly.

🌸 COPYRIGHT 🌸

💜 LICENSE 💜

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's the whole page bestie!! 💖 this version came from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-multi-conn-filter(1) page — go forth and be flush-consistent, ily, slay 🦋✨

📦 where this page comes from

fedora 44: nbdkit-basic-filters 1.48.1-1.fc44 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

nbdkit-multi-conn-filter(1)