nbdkit-eval-plugin1

Usage

Overview

"nbdkit-eval-plugin" is an nbdkit(1) plugin which allows you to write custom plugins as shell scripts snippets ‘eval’d on the command line.

A common alternative to this plugin is nbdkit-sh-plugin(3). Both plugins share the same source code and work in almost the same way. You should read nbdkit-sh-plugin(3) first. It is easier to describe the differences between the two plugins and look at the examples below.

•

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.

•

nbdkit-sh-plugin(3) has no way to know if a method is missing or not and so each "can_*" method (eg. "can_write") must be written explicitly. In eval plugins you have the option of omitting "can_*" methods if the associated callback (eg. "pwrite") is defined. In this way eval plugins work more like regular nbdkit plugins.

•

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

Create a 64M read-only disk of zeroes:

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

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

 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

after_fork=SCRIPT

block_size=SCRIPT

cache=SCRIPT

can_cache=SCRIPT

can_extents=SCRIPT

can_fast_zero=SCRIPT

can_flush=SCRIPT

can_fua=SCRIPT

can_multi_conn=SCRIPT

can_trim=SCRIPT

can_write=SCRIPT

can_zero=SCRIPT

close=SCRIPT

config=SCRIPT

config_complete=SCRIPT

default_export=SCRIPT

dump_plugin=SCRIPT

export_description=SCRIPT

extents=SCRIPT

flush=SCRIPT

get_ready=SCRIPT

get_size=SCRIPT

is_rotational=SCRIPT

list_exports=SCRIPT

default_export=SCRIPT

open=SCRIPT

pread=SCRIPT

preconnect=SCRIPT

pwrite=SCRIPT

thread_model=SCRIPT

trim=SCRIPT

unload=SCRIPT

zero=SCRIPT

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.

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

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.

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

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

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.