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  nbdkit PLUGIN --dump-plugin
  10
  11  nbdkit --version
  12
  13  nbdkit PLUGIN --version
  14
  15  nbdkit --filter=FILTER null --version
  16
  17 =head1 DESCRIPTION
  18
  19 You can query information about nbdkit and available plugins and
  20 filters using the nbdkit binary.  This can include whether nbdkit is
  21 installed, and whether plugins or filters and installed.
  22
  23 =head2 Query if nbdkit is installed
  24
  25 Use this command to see if the nbdkit program is installed:
  26
  27  nbdkit --version
  28
  29 This will fail with an error and non-zero exit code if the nbdkit is
  30 not installed or not working.
  31
  32 =head2 Query basic configuration
  33
  34  nbdkit --dump-config
  35
  36 lists information about how nbdkit was configured.  The most important
  37 fields in the output are the name of the directory where nbdkit looks
  38 for plugins and the version of nbdkit, eg:
  39
  40  plugindir=/usr/lib64/nbdkit/plugins
  41  version=1.2.3
  42
  43 =head2 Query information about a particular plugin
  44
  45  nbdkit pluginname --dump-plugin
  46
  47 (where I<pluginname> is the name or full path of a plugin) will dump
  48 information about that plugin, eg:
  49
  50  $ nbdkit file --dump-plugin
  51  path=/usr/lib64/nbdkit/plugins/nbdkit-file-plugin.so
  52  name=file
  53  version=1.2.3
  54  api_version=1
  55  struct_size=176
  56  thread_model=serialize_requests
  57  [etc]
  58
  59 Plugins which ship with nbdkit usually have the same version as the
  60 corresponding nbdkit binary.  The nbdkit binary will always be able to
  61 utilize plugins compiled against an older version of the header;
  62 however, newer plugins may not be fully supported by an older nbdkit
  63 binary (for example, a plugin compiled with C<NBDKIT_API_VERSION> of 2
  64 fails to load with an older nbdkit that only knows
  65 C<NBDKIT_API_VERSION> 1).
  66
  67 =head2 Detect if a plugin is installed
  68
  69 To find out if a plugin is installed (and working) in the plugin
  70 directory, use:
  71
  72  $ nbdkit foo --version
  73  nbdkit: error: cannot open plugin 'foo': /usr/lib64/nbdkit/plugins/nbdkit-foo-plugin.so: cannot open shared object file: No such file or directory
  74  Use 'nbdkit --help' or read the nbdkit(1) manual page for documentation.
  75
  76 This will fail with an error and non-zero exit code if the C<foo>
  77 plugin cannot be loaded.
  78
  79 Note it is better to test for the existence of plugins this way rather
  80 than just seeing if the F<.so> file exists, because nbdkit will load
  81 the plugin and check that all its dependencies can be satisfied, and
  82 also that plugin registration works.
  83
  84 =head2 List all plugins in the plugin directory
  85
  86 You could simply get the plugin directory (from I<--dump-config>) and
  87 list all files in this directory called F<nbdkit-*-plugin.so>.
  88
  89 However a better test is to run I<--dump-plugin> (see above) on each
  90 one to check that it is working and all of its dependencies are
  91 installed.  A complete shell script which does this is:
  92
  93  #!/bin/sh -
  94  plugindir=`nbdkit --dump-config | grep ^plugindir= | sed 's/[^=]*=//'`
  95  for f in $plugindir/nbdkit-*-plugin.so; do
  96      if nbdkit "$f" --version >/dev/null 2>&1; then
  97          b=`echo "$f" | sed 's,.*/nbdkit-\(.*\)-plugin.so$,\1,'`
  98          echo "$b ($f)"
  99      fi
 100  done
 101
 102 =head2 Detect if a filter is installed
 103
 104 To find out if a filter is installed (and working) use I<--version>
 105 with the C<null> plugin and the name of the filter to test:
 106
 107  nbdkit --version --filter=foo null
 108
 109 This will fail with an error and non-zero exit code if the C<foo>
 110 filter cannot be loaded.
 111
 112 =head1 SEE ALSO
 113
 114 L<nbdkit(1)>.
 115
 116 =head1 AUTHORS
 117
 118 Eric Blake
 119
 120 Richard W.M. Jones
 121
 122 Pino Toscano
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright (C) 2013-2020 Red Hat Inc.