Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-probing(1)		    NBDKIT		     nbdkit-probing(1)

NAME
       nbdkit-probing -	how to probe for nbdkit	configuration and plugins

SYNOPSIS
	nbdkit --dump-config

	nbdkit PLUGIN --dump-plugin

	nbdkit --version

	nbdkit PLUGIN --version

	nbdkit --filter=FILTER null --version

DESCRIPTION
       You can query information about nbdkit and available plugins and
       filters using the nbdkit	binary.	 This can include whether nbdkit is
       installed, and whether plugins or filters and installed.

   Query if nbdkit is installed
       Use this	command	to see if the nbdkit program is	installed:

	nbdkit --version

       This will fail with an error and	non-zero exit code if nbdkit is	not
       installed or not	working.

   Query basic configuration
	nbdkit --dump-config

       lists information about how nbdkit was configured.  The most important
       fields in the output are	the name of the	directory where	nbdkit looks
       for plugins and the version of nbdkit, eg:

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

   Test	nbdkit ^a=Y version
       To test if nbdkit aY a particular version is installed, use the
       --dump-config option and	look 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

       These fields were first added in	nbdkit 1.16.5 and were not present in
       earlier versions.

   Query information about a particular	plugin
	nbdkit pluginname --dump-plugin

       (where pluginname is the	name or	full path of a plugin) will dump
       information about that plugin, eg:

	$ 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 which ship with nbdkit usually have the same version as the
       corresponding nbdkit binary.  The nbdkit	binary will always be able to
       utilize plugins compiled	against	an older version of the	header;
       however,	newer plugins may not be fully supported by an older nbdkit
       binary (for example, a plugin compiled with "NBDKIT_API_VERSION"	of 2
       fails to	load with an older nbdkit that only knows "NBDKIT_API_VERSION"
       1).

   Detect if a plugin is installed
       To find out if a	plugin is installed (and working) in the plugin
       directory, use:

	$ 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	non-zero exit code if the "foo"	plugin
       cannot be loaded.

       Note it is better to test for the existence of plugins this way rather
       than just seeing	if the .so file	exists,	because	nbdkit will load the
       plugin and check	that all its dependencies can be satisfied, and	also
       that plugin registration	works.

   List	all plugins in the plugin directory
       You could simply	get the	plugin directory (from --dump-config) and list
       all files in this directory called nbdkit-*-plugin.so.

       However a better	test is	to run --dump-plugin (see above) on each one
       to check	that it	is working and all of its dependencies are installed.
       A complete shell	script which does this is:

	#!/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 and the name of the filter to test:

	nbdkit --version --filter=foo null

       This will fail with an error and	non-zero exit code if the "foo"	filter
       cannot be loaded.

SEE ALSO
       nbdkit(1).

AUTHORS
       Eric Blake

       Richard W.M. Jones

       Pino Toscano

COPYRIGHT
       Copyright (C) 2013-2020 Red Hat Inc.

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

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

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

nbdkit-1.20.4			  2020-08-28		     nbdkit-probing(1)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-probing&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help