docs/nbdkit-probing.pod

   1 =head1 NAME
   2
   3 nbdkit-probing - how to probe for nbdkit configuration and plugins
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --dump-config
   8
   9 =for paragraph
  10
  11  nbdkit PLUGIN --dump-plugin
  12
  13 =for paragraph
  14
  15  nbdkit --version
  16
  17 =for paragraph
  18
  19  nbdkit PLUGIN --version
  20
  21 =for paragraph
  22
  23  nbdkit --filter=FILTER null --version
  24
  25 =head1 DESCRIPTION
  26
  27 You can query information about nbdkit and available plugins and
  28 filters using the nbdkit binary.  This can include whether nbdkit is
  29 installed, and whether plugins or filters are installed.
  30
  31 =head2 Query if nbdkit is installed
  32
  33 Use this command to see if the nbdkit program is installed:
  34
  35  nbdkit --version
  36
  37 This will fail with an error and non-zero exit code if nbdkit is not
  38 installed or not working.
  39
  40 =head2 Query basic configuration
  41
  42  nbdkit --dump-config
  43
  44 lists information about how nbdkit was configured.  The most important
  45 fields in the output are the name of the directory where nbdkit looks
  46 for plugins and the version of nbdkit, eg:
  47
  48  plugindir=/usr/lib64/nbdkit/plugins
  49  version=1.20.1
  50  version_major=1
  51  version_minor=20
  52
  53 =head2 Test nbdkit E<ge> version
  54
  55 To test if nbdkit E<ge> a particular version is installed, use the
  56 I<--dump-config> option and look for the C<version_major> and
  57 C<version_minor> fields:
  58
  59  $ nbdkit --dump-config | grep ^version_minor
  60  version_minor=20
  61  $ major=$( nbdkit --dump-config | grep ^version_major | cut -d= -f2 )
  62  $ minor=$( nbdkit --dump-config | grep ^version_minor | cut -d= -f2 )
  63  $ if [ $major -eq 1 ] && [ $minor -lt 12 ]
  64    then echo 'nbdkit >= 1.12 is required'; exit 1; fi
  65
  66 These fields were first added in nbdkit 1.16.5 and were not present in
  67 earlier versions.
  68
  69 You can also probe the minimum version using L<pkg-config(1)>.  See
  70 L<nbdkit-plugin(3)/PKG-CONFIG/PKGCONF>.
  71
  72 =head2 Query information about a particular plugin
  73
  74  nbdkit pluginname --dump-plugin
  75
  76 (where I<pluginname> is the name or full path of a plugin) will dump
  77 information about that plugin, eg:
  78
  79  $ nbdkit file --dump-plugin
  80  path=/usr/lib64/nbdkit/plugins/nbdkit-file-plugin.so
  81  name=file
  82  version=1.20.1
  83  api_version=1
  84  struct_size=176
  85  thread_model=serialize_requests
  86  [etc]
  87
  88 Plugins which ship with nbdkit usually have the same version as the
  89 corresponding nbdkit binary.  The nbdkit binary will always be able to
  90 utilize plugins compiled against an older version of the header;
  91 however, newer plugins may not be fully supported by an older nbdkit
  92 binary (for example, a plugin compiled with C<NBDKIT_API_VERSION> of 2
  93 fails to load with an older nbdkit that only knows
  94 C<NBDKIT_API_VERSION> 1).
  95
  96 =head2 Detect if a plugin is installed
  97
  98 To find out if a plugin is installed (and working) in the plugin
  99 directory, use:
 100
 101  $ nbdkit foo --version
 102  nbdkit: error: cannot open plugin 'foo': /usr/lib64/nbdkit/plugins/nbdkit-foo-plugin.so: cannot open shared object file: No such file or directory
 103  Use 'nbdkit --help' or read the nbdkit(1) manual page for documentation.
 104
 105 This will fail with an error and non-zero exit code if the C<foo>
 106 plugin cannot be loaded.
 107
 108 Note it is better to test for the existence of plugins this way rather
 109 than just seeing if the F<.so> file exists, because nbdkit will load
 110 the plugin and check that all its dependencies can be satisfied, and
 111 also that plugin registration works.
 112
 113 =head2 List all plugins in the plugin directory
 114
 115 You could simply get the plugin directory (from I<--dump-config>) and
 116 list all files in this directory called F<nbdkit-*-plugin.so>.
 117
 118 However a better test is to run I<--dump-plugin> (see above) on each
 119 one to check that it is working and all of its dependencies are
 120 installed.  A complete shell script which does this is:
 121
 122  #!/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
 131 =head2 Detect if a filter is installed
 132
 133 To find out if a filter is installed (and working) use I<--version>
 134 with the C<null> plugin and the name of the filter to test:
 135
 136  nbdkit --version --filter=foo null
 137
 138 This will fail with an error and non-zero exit code if the C<foo>
 139 filter cannot be loaded.
 140
 141 =head1 SEE ALSO
 142
 143 L<nbdkit(1)>.
 144
 145 =head1 AUTHORS
 146
 147 Eric Blake
 148
 149 Richard W.M. Jones
 150
 151 Pino Toscano
 152
 153 =head1 COPYRIGHT
 154
 155 Copyright Red Hat