nbdkit-checkwrite-filter(1)

💖 nbdkit-checkwrite-filter(1) 💖

okay bestie, welcome to the nbdkit-checkwrite-filter manual page — it lives in the nbdkit manual, section 1, and it's literally one of the cutest little testing filters you'll ever meet. grab a strawberry 🍓 and let's go.

---

✨ NAME ✨

nbdkit-checkwrite-filter — check writes match contents of plugin

✨ SYNOPSIS ✨

nbdkit --filter=checkwrite PLUGIN [-D checkwrite.showdiffs=1]

✨ DESCRIPTION ✨

so "nbdkit-checkwrite-filter" is an nbdkit filter, and what it does is iconic: it turns write operations into checks that whatever is being written matches the existing content of the plugin. no cap.

• if the content matches, the write operation succeeds (and, plot twist, does absolutely nothing 🙈)
• if it doesn't match, the write operation fails, returning EIO Input/output error 💀

the whole purpose of this filter is to test copying tools — more on that below, iykyk.

the underlying plugin is opened read-only and is never written to. every single write-like operation is covered by this filter, including trimming and zeroing. also, this filter tests the logical equivalence of the writes, so it's ignoring differences in sparseness. periodt.

🌸 Using this filter to test copying tools 🌸

you can check that a copying tool is copying data correctly by creating an nbdkit instance containing some test data, overlaying this filter, and copying from and to nbdkit at the same time:

nbdkit --filter=checkwrite data "@32768 1" \
       --run 'nbdcopy "$uri" "$uri"'

nbdkit --filter=checkwrite file disk.img \
       --run 'nbdcopy "$uri" "$uri"'

nbdkit --filter=checkwrite linuxdisk testdir/ \
       --run 'qemu-img convert -n "$uri" "$uri"'

if the copying program is buggy then you will see EIO errors, and (if the copying program also handles errors correctly) it should exit with an error. slay, that's the whole point 🎀

🦋 Other plugins for testing NBD tools 🦋

if you're doing this kind of testing, you'll also want to look at nbdkit-random-plugin(1) and nbdkit-sparse-random-plugin(1). those plugins already have this behaviour built in to them (because it is more efficient to build it into the plugin) — so you do not need to use this filter with those plugins. this filter is the one you want when you're testing with arbitrary plugins. 💅

✨ PARAMETERS ✨

there are no parameters specific to this filter. parameters are passed straight through to the underlying plugin. that's it, that's the section 🫶

✨ DEBUG FLAG ✨

when both foreground mode and debugging are enabled (-fv) you can get checkwrite to show the differences between what was written and what should have been written by adding:

nbdkit -fv --filter=checkwrite -D checkwrite.showdiffs=1 [...]

for further information on the format used see nbdkit_debug_hexdiff(3). 🔥

✨ FILES ✨

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

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

✨ VERSION ✨

"nbdkit-checkwrite-filter" first appeared in nbdkit 1.24. a whole era ⭐

✨ SEE ALSO ✨

nbdkit(1), nbdkit-random-plugin(1), nbdkit-sparse-random-plugin(1), nbdkit-filter(3), nbdkit-plugin(3), nbdkit_debug_hexdiff(3), nbdcopy(1), qemu-img(1).

✨ AUTHORS ✨

Richard W.M. Jones 👑

✨ COPYRIGHT ✨

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.

---

and that's the whole page bestie!! this one's from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-checkwrite-filter(1) page — so go forth, test those copying tools, and remember: if it matches, it's a slay; if it doesn't, it's an EIO. no cap 💖✨🦋