nbdkit-probing(1)

🎀 NAME

nbdkit-probing — the whole vibe of figuring out what nbdkit setup you've got going on, like how to probe for nbdkit configuration and plugins. Yes bestie, this is the nbdkit-probing(1) manual page. Pull up a chair. 💖

---

✨ SYNOPSIS

nbdkit --version

nbdkit --dump-config

nbdkit --short-options

nbdkit --long-options

nbdkit PLUGIN --dump-plugin

nbdkit PLUGIN --version

nbdkit --filter=FILTER null --version

nbdkit --filter=FILTER null --dump-plugin

---

🌸 DESCRIPTION

Okay so, you can interrogate the nbdkit binary for intel about nbdkit itself, plus all the plugins and filters you've got lying around. That means: is nbdkit even installed? Are your plugins installed? Are your filters installed? All of it, bestie, it's giving detective era. 🕵️‍♀️

Heads up queen: if you're hunting for info about USDT probes, that's a whole different page — go read nbdkit-tracing(3). Not this one. 💅

🔍 Query if nbdkit is installed

Run this to check whether the nbdkit program is even on your machine:

nbdkit --version

If nbdkit isn't installed, or it's installed but lowkey broken, this fails with an error and a non-zero exit code. So if you get a clean output, you're thriving. ✨

📋 Query basic configuration

nbdkit --dump-config

This spills the tea on how nbdkit was configured when it was built. The two fields you actually care about are (a) the directory where nbdkit goes looking for plugins, and (b) the version of nbdkit. Like, for example:

plugindir=/usr/lib64/nbdkit/plugins
version=1.20.1
version_major=1
version_minor=20

🧮 Test nbdkit ≥ version

Wanna know if you've got nbdkit at least as new as some version? Grab --dump-config and go hunting for the "version_major" and "version_minor" fields:

$ nbdkit --dump-config | grep ^version_minor
version_minor=20
$ major=$( nbdkit --dump-config | grep ^version_major | cut -d= -f2 )
$ minor=$( nbdkit --dump-config | grep ^version_minor | cut -d= -f2 )
$ if [ $major -eq 1 ] && [ $minor -lt 12 ]
  then echo 'nbdkit >= 1.12 is required'; exit 1; fi

Real talk: these fields were first added in nbdkit 1.16.5 and they were not present in earlier versions. So don't be shocked if an old build just… doesn't have them. 🙈

You can also probe the minimum version using pkg-config(1). Peep "PKG-CONFIG/PKGCONF" in nbdkit-plugin(3) for that one. 🫶

🔤 Find out if nbdkit implements a command line option

Testing whether a specific single letter option (like -D) or a long option (like --name) is supported by your nbdkit? Easy:

nbdkit --short-options | grep -sq '^-D$'

nbdkit --long-options | grep -sq '^--name$'

🔌 Query information about a particular plugin

nbdkit pluginname --dump-plugin

(where pluginname is the name or the full path of a plugin) — this dumps all the info about that plugin, like:

$ nbdkit file --dump-plugin
path=/usr/lib64/nbdkit/plugins/nbdkit-file-plugin.so
name=file
version=1.20.1
api_version=1
struct_size=176
thread_model=serialize_requests
[etc]

Plugins that ship with nbdkit usually have the exact same version as the nbdkit binary they came with. And here's the compatibility lore: the nbdkit binary will always be able to utilize plugins compiled against an older version of the header. But newer plugins might not be fully supported by an older nbdkit binary — for example, a plugin compiled with "NBDKIT_API_VERSION" of 2 will fail to load with an older nbdkit that only knows "NBDKIT_API_VERSION" 1. It's giving generational divide. 😭

🧼 Query information about a particular filter

You can use the --dump-plugin option to dump info about a filter too — just pair the null plugin with the --filter parameter:

$ nbdkit null --filter=qcow2dec --dump-plugin
[...]
qcow2dec_path=/usr/lib64/nbdkit/filters/nbdkit-qcow2dec-filter.so
qcow2dec_name=qcow2dec
qcow2dec_deflate=yes
qcow2dec_zstd=yes

✅ Detect if a plugin is installed

Wanna know if a plugin is installed (and actually working) in the plugin directory? Do this:

$ nbdkit foo --version
nbdkit: error: cannot open plugin 'foo': /usr/lib64/nbdkit/plugins/nbdkit-foo-plugin.so: cannot open shared object file: No such file or directory
Use 'nbdkit --help' or read the nbdkit(1) manual page for documentation.

This will fail with an error and a non-zero exit code if the "foo" plugin can't be loaded. Rude, but informative. 💀

Not me telling you to test for plugins this way instead of just checking whether the .so file exists — because nbdkit actually loads the plugin and checks that all its dependencies can be satisfied, and that plugin registration works. So it's a way more honest test. Periodt. 👑

📜 List all plugins in the plugin directory

You could just grab the plugin directory (from --dump-config) and list every file in there named nbdkit-*-plugin.so.

But the better glow-up of a test is running --dump-plugin (see above) on each one, so you actually confirm it works and all its dependencies are installed. A complete shell script that does exactly that:

#!/bin/sh -
plugindir=`nbdkit --dump-config | grep ^plugindir= | sed 's/[^=]*=//'`
for f in $plugindir/nbdkit-*-plugin.so; do
    if nbdkit "$f" --version >/dev/null 2>&1; then
        b=`echo "$f" | sed 's,.*/nbdkit-\(.*\)-plugin.so$,\1,'`
        echo "$b ($f)"
    fi
done

🦋 Detect if a filter is installed

To find out if a filter is installed (and working), use --version with the "null" plugin plus the name of the filter you're testing:

nbdkit --version --filter=foo null

This will fail with an error and a non-zero exit code if the "foo" filter can't be loaded. Same energy as the plugin check, just filter-flavored. 🍓

---

👀 SEE ALSO

• nbdkit(1).

---

💜 AUTHORS

• Eric Blake
• Richard W.M. Jones
• Pino Toscano

---

🌈 COPYRIGHT

Copyright Red Hat

---

📄 LICENSE

Okay so legally I have to give you the whole thing, no skipping, bestie — 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 drop is from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-probing(1) manual — go forth and probe, you absolute icon 💅✨