1nbdkit-probing(1) NBDKIT nbdkit-probing(1)
2
6 nbdkit-probing - how to probe for nbdkit configuration and plugins
7
9 nbdkit --dump-config
10 nbdkit PLUGIN --dump-plugin
12 nbdkit --version
14 nbdkit PLUGIN --version
16 nbdkit --filter=FILTER null --version
18 nbdkit --filter=FILTER null --dump-plugin
20
22 You can query information about nbdkit and available plugins and
23 filters using the nbdkit binary. This can include whether nbdkit is
24 installed, and whether plugins or filters are installed.
25 Query if nbdkit is installed
27 Use this command to see if the nbdkit program is installed:
28 nbdkit --version
30 This will fail with an error and non-zero exit code if nbdkit is not
32 installed or not working.
33 Query basic configuration
35 nbdkit --dump-config
36 lists information about how nbdkit was configured. The most important
38 fields in the output are the name of the directory where nbdkit looks
39 for plugins and the version of nbdkit, eg:
40 plugindir=/usr/lib64/nbdkit/plugins
42 version=1.20.1
43 version_major=1
44 version_minor=20
45 Test nbdkit ≥ version
47 To test if nbdkit ≥ a particular version is installed, use the
48 --dump-config option and look for the "version_major" and
49 "version_minor" fields:
50 $ nbdkit --dump-config | grep ^version_minor
52 version_minor=20
53 $ major=$( nbdkit --dump-config | grep ^version_major | cut -d= -f2 )
54 $ minor=$( nbdkit --dump-config | grep ^version_minor | cut -d= -f2 )
55 $ if [ $major -eq 1 ] && [ $minor -lt 12 ]
56 then echo 'nbdkit >= 1.12 is required'; exit 1; fi
57 These fields were first added in nbdkit 1.16.5 and were not present in
59 earlier versions.
60 You can also probe the minimum version using pkg-config(1). See
62 "PKG-CONFIG/PKGCONF" in nbdkit-plugin(3).
63 Query information about a particular plugin
65 nbdkit pluginname --dump-plugin
66 (where pluginname is the name or full path of a plugin) will dump
68 information about that plugin, eg:
69 $ nbdkit file --dump-plugin
71 path=/usr/lib64/nbdkit/plugins/nbdkit-file-plugin.so
72 name=file
73 version=1.20.1
74 api_version=1
75 struct_size=176
76 thread_model=serialize_requests
77 [etc]
78 Plugins which ship with nbdkit usually have the same version as the
80 corresponding nbdkit binary. The nbdkit binary will always be able to
81 utilize plugins compiled against an older version of the header;
82 however, newer plugins may not be fully supported by an older nbdkit
83 binary (for example, a plugin compiled with "NBDKIT_API_VERSION" of 2
84 fails to load with an older nbdkit that only knows "NBDKIT_API_VERSION"
85 1).
86 Query information about a particular filter
88 You can use the --dump-plugin option to dump information about a
89 filter, by using the null plugin with the --filter parameter:
90 $ nbdkit null --filter=qcow2dec --dump-plugin
92 [...]
93 qcow2dec_path=/usr/lib64/nbdkit/filters/nbdkit-qcow2dec-filter.so
94 qcow2dec_name=qcow2dec
95 qcow2dec_deflate=yes
96 qcow2dec_zstd=yes
97 Detect if a plugin is installed
99 To find out if a plugin is installed (and working) in the plugin
100 directory, use:
101 $ nbdkit foo --version
103 nbdkit: error: cannot open plugin 'foo': /usr/lib64/nbdkit/plugins/nbdkit-foo-plugin.so: cannot open shared object file: No such file or directory
104 Use 'nbdkit --help' or read the nbdkit(1) manual page for documentation.
105 This will fail with an error and non-zero exit code if the "foo" plugin
107 cannot be loaded.
108 Note it is better to test for the existence of plugins this way rather
110 than just seeing if the .so file exists, because nbdkit will load the
111 plugin and check that all its dependencies can be satisfied, and also
112 that plugin registration works.
113 List all plugins in the plugin directory
115 You could simply get the plugin directory (from --dump-config) and list
116 all files in this directory called nbdkit-*-plugin.so.
117 However a better test is to run --dump-plugin (see above) on each one
119 to check that it is working and all of its dependencies are installed.
120 A complete shell script which does this is:
121 #!/bin/sh -
123 plugindir=`nbdkit --dump-config | grep ^plugindir= | sed 's/[^=]*=//'`
124 for f in $plugindir/nbdkit-*-plugin.so; do
125 if nbdkit "$f" --version >/dev/null 2>&1; then
126 b=`echo "$f" | sed 's,.*/nbdkit-\(.*\)-plugin.so$,\1,'`
127 echo "$b ($f)"
128 fi
129 done
130 Detect if a filter is installed
132 To find out if a filter is installed (and working) use --version with
133 the "null" plugin and the name of the filter to test:
134 nbdkit --version --filter=foo null
136 This will fail with an error and non-zero exit code if the "foo" filter
138 cannot be loaded.
139
141 nbdkit(1).
142
144 Eric Blake
145 Richard W.M. Jones
147 Pino Toscano
149
151 Copyright Red Hat
152
154 Redistribution and use in source and binary forms, with or without
155 modification, are permitted provided that the following conditions are
156 met:
157 • Redistributions of source code must retain the above copyright
159 notice, this list of conditions and the following disclaimer.
160 • Redistributions in binary form must reproduce the above copyright
162 notice, this list of conditions and the following disclaimer in the
163 documentation and/or other materials provided with the
164 distribution.
165 • Neither the name of Red Hat nor the names of its contributors may
167 be used to endorse or promote products derived from this software
168 without specific prior written permission.
169 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
171 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
172 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
173 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
174 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
175 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
176 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
177 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
178 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
179 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
180 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
181nbdkit-1.36.2 2023-11-26 nbdkit-probing(1)