nbdkit-sh-plugin man page

"nbdkit-sh-plugin" allows you to write plugins for nbdkit(1) using arbitrary scripting languages, including shells like bash(1), dash(1), csh(1), zsh(1) etc., other scripting environments, or any executable. Note if you want to use an established scripting language like Perl or Python, then nbdkit has specific plugins to handle those languages and those will be more efficient (see nbdkit(1) for a complete list).

This plugin has a simple programming model: For every plugin method that needs to be called, the external script is invoked with parameters describing the method and its arguments. The first parameter is always the method name. For example:

A fresh script is invoked for each method call (ie. scripts are stateless), so if the script needs to store state it has to store it somewhere in the filesystem in a format and location which is left up to the author of the script.

However nbdkit helps by creating a randomly named, empty directory for the script. This directory persists for the lifetime of nbdkit and is deleted when nbdkit exits. The name of the directory is passed to each script invocation in the $tmpdir environment variable.

Handles are arbitrary strings, but it is best to limit them to short alphanumeric strings.

Per-connection state

The temporary directory described above can be used for state for the lifetime of the nbdkit instance (across multiple connections). If you want to store state per connection then one way to do it is to create a randomly named subdirectory under the temporary directory:

case "$1" in
...
open)
mktemp -d $tmpdir/handle-XXXXXX ;;

The handle will be the subdirectory name, returned to the script as $2 in all connected calls (eg. "pread", "get_size"). You can delete the subdirectory explicitly in "close":

case "$1" in
...
close)
rm -rf "$2" ;;

or rely on nbdkit deleting the whole temporary directory including all per-handle subdirectories when it exits.

This just documents the arguments to the script corresponding to each plugin method, and any way that they differ from the C callbacks. In all other respects they work the same way as the C callbacks, so you should go and read nbdkit-plugin(3).

"load"

/path/to/script load

"unload"

/path/to/script unload

This is called just before nbdkit exits. Errors from this method are ignored.

"dump_plugin"

/path/to/script dump_plugin

"config"

/path/to/script config <key> <value>

"config_complete"

/path/to/script config_complete

"open"

/path/to/script open <readonly>

The "readonly" parameter will be "true" or "false".

On success this should print the handle (any string) on stdout and exit with code 0. If the handle ends with a newline character then the newline is removed.

Unlike C plugins, this method is not required. If omitted then the handle will be "" (empty string).

"close"

/path/to/script close <handle>

"get_size"

/path/to/script get_size <handle>

The script should print the size of the disk image on stdout. You can print the size in bytes, or use any format understood by "nbdkit_parse_size" such as "1M" (see "PARSING SIZE PARAMETERS" in nbdkit-plugin(3)).

This method is required.

"can_write"

"can_flush"

"can_trim"

"can_zero"

Unlike in other languages, you must provide the "can_*" methods otherwise they are assumed to all return false and your "pwrite", "flush", "trim" and "zero" methods will never be called. The reason for this is obscure: In other languages we can detect if (eg) a "pwrite" method is defined and synthesize an appropriate response if no actual "can_write" method is defined. However detecting if methods are present without running them is not possible with this plugin.

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.