nbdkit-fua-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 NAME 💖

okay so this is nbdkit-fua-filter(1) — a page from the NBDKIT manual, section 1, and it's all about nbdkit-fua-filter, the filter that messes with flush and Forced Unit Access (FUA) on purpose. bestie, it's literally in the name. 💅

🌸 SYNOPSIS 🌸

nbdkit --filter=fua plugin [fua-mode=MODE] [flush-on-close=true]
                           [plugin-args...]

✨ DESCRIPTION ✨

nbdkit-fua-filter is a filter that intentionally modifies how the “Forced Unit Access” (FUA) flag gets handled across the NBD protocol. yes, on purpose. that's the whole job. 🎀

so like, why would you even want that? a few reasons, and they're all valid:

  • to disable FUA and flush requests for speed — but lowkey that's unsafe, we'll get to that
  • to test client or server fallbacks (does your thing behave when FUA just… isn't there?)
  • to evaluate timing differences between using FUA properly vs. doing a full flush
  • to force a flush when the client closes the connection
heads up bestie 🫶 — by default the NBD protocol does not guarantee that FUA from one connection will be visible from another connection, unless the server advertised NBD_FLAG_MULTI_CONN. so if you're planning on making multiple connections to the plugin, you might wanna pair this filter up with nbdkit-multi-conn-filter(1). iykyk.

🎀 PARAMETERS 🎀

fua-mode is optional and it controls which mode the filter runs in. (also, every mode has a fua-mode= spelling and a fuamode= spelling, they're the same thing, pick whichever your fingers vibe with.)

  • fua-mode=discard, fuamode=discard — (nbdkit ≥ 1.22) the filter will straight up discard FUA and flush requests. this mode is unsafe: if the NBD disk has a filesystem on it, you will likely lose data if there's a crash. only use it for ephemeral stuff you can easily recreate — caches, builds, test data, that kind of thing. 💀
  • fua-mode=pass, fuamode=pass — (nbdkit ≥ 1.22) passes FUA and flush requests through unchanged. this turns the filter into a total no-op. it's giving "why am i even here" energy and honestly, iconic. 👑
  • fua-mode=none, fuamode=none — FUA support is not advertised to the client. clients won't be able to send FUA write requests, but they can still send flush commands if the plugin supports it. this is the default when you don't specify fua-mode at all. 🍓
  • fua-mode=emulate, fuamode=emulate — the filter emulates FUA support using the plugin's .flush callback, no matter whether the plugin itself has a more efficient native FUA. it refuses to load if the plugin doesn't support flush. 🙈
  • fua-mode=native, fuamode=native — the filter advertises native FUA support to the client and to earlier filters in the chain. super useful for comparing how FUA handling gets optimized when large requests are split into sub-requests. it refuses to load if the plugin's .can_fua callback returns NBDKIT_FUA_NONE. ⭐
  • fua-mode=force, fuamode=force — the filter requests FUA on every single write transaction, even when the client didn't ask for it. that's “write-through” mode, bestie. and in turn, client flush requests become total no-ops. it refuses to load if the plugin's .can_fua callback returns NBDKIT_FUA_NONE. 🔥
  • flush-on-close=true — (nbdkit ≥ 1.44) if you set this, it calls .flush on the underlying plugin whenever the client closes any NBD connection. this is for those misbehaving clients that don't properly issue flush commands (we've all met one). if the plugin doesn't support flush, the filter will refuse to start. 🌸

🌈 EXAMPLES 🌈

  • serve the file disk.img while discarding all FUA and flush requests. this can greatly improve performance, but you will likely lose data if there's a crash, so it is not safe. like, at all. 🔥
nbdkit --filter=fua file disk.img fua-mode=discard
  • serve the file disk.img, but force the client to submit explicit flush requests instead of using NBD_CMD_FLAG_FUA:
nbdkit --filter=fua file disk.img
  • serve a file and flush data to disk when the NBD client closes the connection. peep the fua-mode=pass — it stops the filter from changing how normal FUA requests behave:
nbdkit --filter=fua file disk.img fua-mode=pass flush-on-close=true
  • watch the blocksize filter optimize its FUA handling based on whether it knows nbdkit will be emulating FUA with a flush. you do this by comparing the log filter output on top of different fua filter modes:
nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
  maxlen=4k logfile=fua_emulated fua-mode=emulate
nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
  maxlen=4k logfile=fua_native fua-mode=native
  • serve the file disk.img in write-through mode, where every write from the client gets immediately flushed to disk as if the client had always requested FUA:
nbdkit --filter=fua file disk.img fua-mode=force

💜 FILES 💜

  • $filterdir/nbdkit-fua-filter.so — the filter itself. 🦋

use nbdkit --dump-config to find out where $filterdir actually lives.

⭐ VERSION ⭐

nbdkit-fua-filter first appeared in nbdkit 1.4. so it's been around a minute, fr fr.

👑 SEE ALSO 👑

nbdkit(1), nbdkit-file-plugin(1), nbdkit-filter(3), nbdkit-blocksize-filter(1), nbdkit-log-filter(1), nbdkit-multi-conn-filter(1), nbdkit-nocache-filter(1), nbdkit-noextents-filter(1), nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1).

go read those too bestie, the whole filter fam is there 🫶

💖 AUTHORS 💖

Eric Blake

Copyright Red Hat

✨ LICENSE ✨

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met — and yes, all of them, no skipping:

  • 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 one's from nbdkit-1.48.1, dated 2026-08-29, and it slayed the entire time. go forth and FUA responsibly 💅✨🦋

📦 where this page comes from