nbdkit-nozero-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💅 nbdkit-nozero-filter(1) 💅

okay so bestie, you found your way to nbdkit-nozero-filter(1) — part of the NBDKIT manual pages, and honestly? this one is a whole mood. it's a filter that is petty on purpose. let's get into it 🫶

✨ NAME ✨

nbdkit-nozero-filter — the nbdkit nozero filter. that's it, that's the name, she's simple and she knows what she wants 💁‍♀️

🎀 SYNOPSIS 🎀

nbdkit --filter=nozero plugin [plugin-args...] \
  [zero-mode=MODE] [fast-zero-mode=MODE]

🦋 DESCRIPTION 🦋

so nbdkit-nozero-filter is a filter that intentionally disables the efficient handling of sparse file holes (aka ranges of all-zero bytes) across the NBD protocol. like, on purpose. deliberately. it's giving chaos but make it useful 😭

why would anyone do this?? two reasons, and they're both valid:

  • to evaluate timing differences between naive connections vs. sparse-aware ones ⏱️
  • to test client or server fallbacks 🧪

that's it. that's the gig. no cap.

🌈 PARAMETERS 🌈

the parameters zero-mode and fast-zero-mode are both optional, and they control which mode the filter will use. pick your fighter 💖

  • zero-mode=none, zeromode=none — zero support is not advertised to the client at all. clients have to explicitly write any regions of zero like any other normal write. no shortcuts, no glamour, just work. this is the default if the zeromode parameter is not specified.
  • zero-mode=emulate, zeromode=emulate — zero support is advertised, but it's emulated by the filter using the plugin's pwrite callback. and it does this regardless of whether the plugin itself has a more efficient zero callback. so like, even if your plugin could do it better, the filter says "no bestie, we're doing it the long way" 💀
  • zero-mode=notrim, zeromode=notrim — (nbdkit ≥ 1.14) — zero requests get forwarded on to the plugin, EXCEPT the plugin will never see the NBDKIT_MAY_TRIM flag. this can help determine if the client permitting trimming during zero operations actually makes a difference. ⚠️ it is an error to request this mode if the plugin lacks the zero callback.
  • zero-mode=plugin, zeromode=plugin — (nbdkit ≥ 1.16) — zero requests are forwarded on to the plugin, unchanged by the filter. this mode is helpful when you're experimenting with the fastzeromode parameter 🔬. ⚠️ it is an error to request this mode if the plugin lacks the zero callback.
  • fast-zero-mode=none, fastzeromode=none — (nbdkit ≥ 1.16) — support for fast zeroing is not advertised to the client. that's it. nothing to see here 🚫
  • fast-zero-mode=slow, fastzeromode=slow — (nbdkit ≥ 1.16) — fast zero support is advertised to the client, but every single fast zero request results in an immediate ENOTSUP failure instead of performing any fallback attempts. it says yes and then immediately says no. iconic behavior tbh 💅
  • fast-zero-mode=ignore, fastzeromode=ignore — (nbdkit ≥ 1.16) — 🚨 this mode is unsafe 🚨 — fast zero support is advertised to the client, but all fast zero requests behave as if the fast zero flag had not been included. this behavior is typically contrary to the NBD specification, but it can be useful for comparison against the actual fast zero implementation to see if fast zeroes make a difference. dangerous? yes. useful for science? also yes 🙈
  • fast-zero-mode=default, fastzeromode=default — (nbdkit ≥ 1.16) — this mode is the default. here's how she pairs up:
    • when paired with zero-mode=emulate, fast zeroes are advertised but fast zero requests always fail (similar to slow)
    • when paired with zero-mode=notrim or zero-mode=plugin, fast zero support is left to the plugin (although in the latter case, the nozero filter could be omitted for the same behavior)

🍓 EXAMPLES 🍓

exhibit one — serve the file disk.img, but force the client to write zeroes explicitly rather than with NBD_CMD_WRITE_ZEROES:

nbdkit --filter=nozero file disk.img

exhibit two — serve the file disk.img, allowing the client to take advantage of less network traffic via NBD_CMD_WRITE_ZEROES, but fail any fast zero requests up front and force all other zero requests to write data explicitly rather than punching any holes:

nbdkit --filter=nozero file zero-mode=emulate disk.img

exhibit three — serve the file disk.img, but do not advertise fast zero support to the client even if the plugin supports it:

nbdkit --filter=nozero file zero-mode=plugin fast-zero-mode=none disk.img

🧚 FILES 🧚

  • $filterdir/nbdkit-nozero-filter.so — the filter itself 💖

use nbdkit --dump-config to find the location of $filterdir. go get her 📍

⭐ VERSION ⭐

nbdkit-nozero-filter first appeared in nbdkit 1.4. a legend from the start 👑

🌸 SEE ALSO 🌸

the whole squad, go read them too:

💜 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:

  • 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.

okay that's the whole page bestie, you're officially smarter than you were five minutes ago 💅✨ this was nbdkit-1.48.1, dated 2026-08-29, and she ate. no crumbs left. bye pookie 🫶💖🌈

📦 where this page comes from