nbdkit-eval-plugin(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

🎀 nbdkit-eval-plugin — write a shell script plugin on the command line 🎀

okay so hi bestie 💖 you've landed on nbdkit-eval-plugin(1), one of the nbdkit manual pages, and honestly? this one is kind of iconic. it's the plugin that lets you write a whole custom nbdkit plugin as little shell script snippets right there on the command line. no cap. let's get into it ✨

SYNOPSIS 💅

nbdkit eval get_size='SCRIPT' pread='SCRIPT' pwrite='SCRIPT' [...]

DESCRIPTION 🌸

nbdkit-eval-plugin is an nbdkit(1) plugin, and the whole vibe is: you write custom plugins as shell script snippets that get ‘eval’d on the command line. that's it, that's the plugin 🫶

A super common alternative to this plugin is nbdkit-sh-plugin(3). lowkey they're siblings — both plugins share the same source code and work in almost the same way. so the move is: go read nbdkit-sh-plugin(3) first, bestie. it's genuinely easier to just describe the differences between the two plugins and then peek at the examples below. so here are the differences 👇

  • nbdkit-sh-plugin(3) plugins are written as a single script in a separate file. Eval plugins are shell script fragments written on the nbdkit command line — there is no separate script file. it's giving "no file, just vibes" ✨
  • nbdkit-sh-plugin(3) has no way to know if a method is missing or not, so each can_* method (eg. can_write) has to be written explicitly. In eval plugins you have the option of omitting can_* methods if the associated callback (eg. pwrite) is defined. so eval plugins work more like regular nbdkit plugins. slay 💅
  • Eval plugins can only use /bin/sh to run the script snippets, but nbdkit-sh-plugin(3) (in spite of the name 😭) can run any executable.
  • There is no load method (although there is an unload method, and all other methods are identical).

EXAMPLES 🍓

okay bestie, example time. create a 64M read-only disk of zeroes:

 nbdkit eval get_size=' echo 64M ' \
                pread=' dd if=/dev/zero count=$3 iflag=count_bytes '

and the following command is the eval plugin equivalent of nbdkit-file-plugin(1) (except not as fast and missing many features, ngl):

 nbdkit eval \
   config='ln -sf "$(realpath "$3")" $tmpdir/file' \
   get_size='stat -Lc %s $tmpdir/file' \
   pread='dd if=$tmpdir/file skip=$4 count=$3 iflag=count_bytes,skip_bytes' \
   pwrite='dd of=$tmpdir/file seek=$4 conv=notrunc oflag=seek_bytes' \
   file=disk.img

PARAMETERS 👑

bestie here's the full menu, no skips, no skimming 🙈 every single one of these takes a script:

  • after_fork=SCRIPT — the script for the after_fork method ✨
  • block_size=SCRIPT — the script for the block_size method
  • cache=SCRIPT — the script for the cache method
  • can_cache=SCRIPT — the script for the can_cache method
  • can_extents=SCRIPT — the script for the can_extents method
  • can_fast_zero=SCRIPT — the script for the can_fast_zero method
  • can_flush=SCRIPT — the script for the can_flush method
  • can_fua=SCRIPT — the script for the can_fua method
  • can_multi_conn=SCRIPT — the script for the can_multi_conn method
  • can_trim=SCRIPT — the script for the can_trim method
  • can_write=SCRIPT — the script for the can_write method
  • can_zero=SCRIPT — the script for the can_zero method
  • close=SCRIPT — the script for the close method
  • config=SCRIPT — the script for the config method
  • config_complete=SCRIPT — the script for the config_complete method
  • default_export=SCRIPT — the script for the default_export method
  • dump_plugin=SCRIPT — the script for the dump_plugin method
  • export_description=SCRIPT — the script for the export_description method
  • extents=SCRIPT — the script for the extents method
  • flush=SCRIPT — the script for the flush method
  • get_ready=SCRIPT — the script for the get_ready method
  • get_size=SCRIPT — the script for the get_size method
  • is_rotational=SCRIPT — the script for the is_rotational method
  • list_exports=SCRIPT — the script for the list_exports method
  • default_export=SCRIPT — yep, the default_export method again, it really is listed twice in the original and we are not erasing her 💀
  • open=SCRIPT — the script for the open method
  • pread=SCRIPT — the script for the pread method
  • preconnect=SCRIPT — the script for the preconnect method
  • pwrite=SCRIPT — the script for the pwrite method
  • thread_model=SCRIPT — the script for the thread_model method
  • trim=SCRIPT — the script for the trim method
  • unload=SCRIPT — the script for the unload method
  • zero=SCRIPT — the script for the zero method

so what do all of these actually mean? Define the script associated with each method. SCRIPT is a fragment of shell script which is executed when nbdkit wants to invoke the associated method. periodt 💅

If you are typing these commands at the shell, be careful about quoting, bestie, fr fr. Normally you will need to enclose SCRIPT in '...' (single quotes) to prevent it from being modified by your shell. your shell is NOT your friend here 😭

The script fragment behaves the same way as the corresponding method in nbdkit-sh-plugin(3). In particular, parameters are identical, $tmpdir is present and used in the same way, the exit code must be one of the valid exit codes described in that manual page, and error handling works the same way too. Likewise, nbdkit --dump-plugin eval includes a line for max_known_status= in nbdkit ≥ 1.34.

Note that a config callback will only handle keys not recognized as callback names; when picking key=value pairs that you want your script fragment to understand, be aware that if a future nbdkit release creates a callback by that name, your config script fragment will no longer see that key. 👀

All of these parameters are optional. yes, all of them. go wild ✨

missing=SCRIPT 🧚

The parameter missing defines a script that will be called in place of any other callback not explicitly provided. If omitted, this defaults to the script exit 2.

ENVIRONMENT VARIABLES 🌈

  • tmpdir — this is defined to the name of a temporary directory which can be used by the script snippets. It is deleted when nbdkit exits. so like, don't go storing your diary in there 💜

FILES 📁

  • /bin/sh — shell script fragments are executed using /bin/sh.
  • $plugindir/nbdkit-eval-plugin.so — the plugin. use nbdkit --dump-config to find the location of $plugindir 🦋

VERSION ⭐

nbdkit-eval-plugin first appeared in nbdkit 1.18. a classic, honestly.

SEE ALSO 🎀

nbdkit(1), nbdkit-plugin(3), nbdkit-sh-plugin(3), nbdkit-cc-plugin(1).

AUTHORS 👑

Richard W.M. Jones

Copyright Red Hat

LICENSE

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 one's from nbdkit-1.48.1, dated 2026-08-29 — go forth and eval some shell snippets, you've got this 👑✨

📦 where this page comes from