nbdkit-sh-plugin(3)

📦

version 1.48.1 · 14 versions

✨ NAME ✨

nbdkit-sh-plugin — the nbdkit plugin that lets you build plugins out of shell scripts, other scripts, or honestly any executable you want 🐚💖

🌈 SYNOPSIS 🌈

nbdkit sh /path/to/script [arguments...]

nbdkit sh - <<'EOF'
... shell script ...
EOF

🎀 DESCRIPTION 🎀

Okay so nbdkit-sh-plugin is the moment. It lets you write plugins for nbdkit(1) using literally any scripting language — shells like bash(1), dash(1), csh(1), zsh(1) etc., other scripting environments, or honestly just any executable that exists. Bestie, the range.

Heads up tho 👀 if you want to use an established scripting language like Perl or Python, nbdkit already has specific plugins for those languages, and those will be more efficient (peep nbdkit(1) for the complete list). No shade to sh, it's just how it is 💅

If you want to use shell script fragments straight from the nbdkit command line instead of a separate script file, go look at nbdkit-eval-plugin(1).

💖 If you have been given an nbdkit sh plugin 💖

Say someone hands you a shell script that's an nbdkit plugin (lucky you 🍓). You run it like this:

nbdkit sh /path/to/script

You may have to add further key=value arguments to the command line. And the script must be executable — that's chmod +x, no skipping this step, it's giving "I forgot the chmod" energy and we don't do that 🙈

🦋 Inline shell scripts 🦋

You can also write a shell script plugin "inline" by using - as the name of the script, like so:

nbdkit sh - <<'EOF'
  case "$1" in
    get_size) echo 1M ;;
    pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
    *) exit 2 ;;
  esac
EOF

By default the inline script runs under /bin/sh. You can add a shebang (#!) to use other scripting languages — slay 💅 Of course, reading an inline script from stdin is incompatible with the -s (--single) mode of nbdkit that connects a client on stdin. Like, obviously, stdin can only do one job at a time bestie 😭

👑 WRITING AN NBDKIT SH PLUGIN 👑

For example plugins written in Bash, see:

https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/sh/examples/

Broadly speaking, nbdkit shell plugins work like C ones, so you should read nbdkit-plugin(3) first. Yes, fr fr, go read it 🫶

🌸 Programming model 🌸

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:

/path/to/script config file disk.img
                  │      │   │
                  │      │   └─ value ($3)
                  │      └── key ($2)
              method ($1)

/path/to/script pread <handle> <count> <offset>
                  │       │       │       │
                  │       │       │       └─ offset in bytes ($4)
                  │       │       └── request size in bytes ($3)
              method ($1) └── handle ($2) ─ see "Handles" below

Scripts should ignore extra parameters that they don't understand, since we may add new parameters in future. Future-proofing, we love to see it ✨

💀 Exit codes 💀

The script should exit with specific exit codes:

0 — The method was executed successfully. Periodt 🎉
1 and 16-255 — There was an error. The script may print on stderr an errno name, optionally followed by whitespace and a message, for example:

echo 'ENOSPC Out of space' >&2
exit 1

or if you don't need the log message:

echo ENOSPC >&2
exit 1

If the script doesn't print anything, or the output cannot be parsed, then nbdkit assumes error EIO. Note that output to stderr is ignored if the command succeeds, so it is acceptable to output a potential error message prefix prior to attempting a command which will add further details if a failure occurs.

2 — The requested method is not supported by the script. Not me finding out you never implemented that method 🙈
3 — For methods which return booleans, this code indicates false.
4 and 5 — Triggers a call to the C function nbdkit_shutdown(3), which requests an asynchronous exit of the nbdkit server (disconnecting all clients). The client will usually get a response before shutdown is complete (although this is racy); so once the shutdown is requested, code 4 then behaves like code 0 (stderr is ignored, and the server tries to return success), and code 5 behaves like code 1 (the server tries to return an error to the client parsed from stderr, although a missing error defaults to ESHUTDOWN instead of EIO).
6 — Triggers a call to the C function nbdkit_disconnect(3) with force set to true, which requests an abrupt disconnect of the current client. The contents of stderr are irrelevant with this status, since the client will not get a response. Just gone. Ghosted 💀
7 and 8 — Triggers a call to the C function nbdkit_disconnect(3) with force set to false, which requests a soft disconnect of the current client (future client requests are rejected with ESHUTDOWN without calling into the plugin, but current requests may complete). Since the client will likely get the response to this command, code 7 then behaves like code 0 (stderr is ignored, and the server tries to return success), and code 8 behaves like code 1 (the server tries to return an error to the client parsed from stderr, although a missing error defaults to ESHUTDOWN instead of EIO).
9-15 — These exit codes are reserved for future use. Note that versions of nbdkit < 1.34 documented that codes 8 through 15 behaved like code 1; although it is unlikely that many scripts relied on this similarity in practice.

In nbdkit > 1.34, it is possible to probe whether additional exit codes have been assigned meaning, by looking for the line max_known_status= in the output of nbdkit --dump-plugin sh. If this line is not present, exit codes 4 and above behave like status 1.

🧚 Temporary directory 🧚

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. Your state, your rules ✨

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. Free real estate 🏠

💅 Handles 💅

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. Cleanup queen 👑

🔥 Performance 🔥

Real talk: this plugin has to fork on every request, so performance will never be great. For best performance, consider using the nbdkit-plugin(3) API directly. Having said that, if you have a sh plugin and want to improve performance then the following tips may help:

Relax the thread model. — The default thread_model is serialize_all_requests meaning that two instances of the script can never be running at the same time. This is safe but slow. If your script is safe to be called in parallel, set this to parallel.
Implement the zero method. — If the zero method is not implemented then nbdkit will fall back to using pwrite which is considerably slower because nbdkit has to send blocks of zeroes to the script. Not the vibe.
You don't have to write shell scripts. — This plugin can run any external binary, not only shell scripts. You should get more performance by rewriting the shell script as a program in a compiled language. Glow up 🦋

⭐ Methods ⭐

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. We're leaving anyway bestie 😭

`dump_plugin`

/path/to/script dump_plugin

`config`

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

`config_complete`

/path/to/script config_complete

`magic_config_key`

/path/to/script magic_config_key

If a magic config key is needed, this should echo it to stdout. See "Magic parameters" in nbdkit(1).

`thread_model`

/path/to/script thread_model

On success this should print the desired thread model of the script, one of serialize_connections, serialize_all_requests, serialize_requests, or parallel.

This method is not required; if omitted, then the plugin will be executed under the safe serialize_all_requests model. However, this means that this method must be provided if you want to use the parallel or serialize_requests model. Even then your request may be restricted for other reasons; look for thread_model in the output of nbdkit --dump-plugin sh script to see what actually gets selected. The truth is in the dump 🔍

If an error occurs, the script should output an error message and exit with status 1; unrecognized output is ignored.

`get_ready`

/path/to/script get_ready

`after_fork`

/path/to/script after_fork

`preconnect`

/path/to/script preconnect <readonly>

`list_exports`

/path/to/script list_exports <readonly> <tls>

The readonly and tls parameters will be true or false.

The first line of output informs nbdkit how to parse the rest of the output, the remaining lines then supply the inputs of the C nbdkit_add_export function (see nbdkit-plugin(3)), as follows:

NAMES

The remaining output provides one export name per line, and no export will be given a description. For convenience, this form is also assumed if the first output line does not match one of the recognized parse modes.

INTERLEAVED

The remaining output provides pairs of lines, the first line being an export name, and the second the corresponding description.

NAMES+DESCRIPTIONS

The number of remaining lines is counted, with the first half being used as export names, and the second half providing descriptions to pair with names from the first half.

okay bestie, here's how that looks irl — say you wanna list everything in the current directory and then follow it up with the ls(1) long description of each one, your script would go:

echo NAMES+DESCRIPTIONS
ls
ls -l

heads up tho — other output modes might get introduced in the future. And as of rn, none of the existing modes let you put a literal newline inside an export name or description. That could be possible under some new mode with escape sequences, but like… not today. 🙈

And this whole method is optional — if it's missing, the list of exports nbdkit advertises is just the single name that comes back from default_export, with no description.

🎀 `default_export` 🎀

/path/to/script default_export <readonly> <tls>

The readonly and tls parameters will be true or false.

On success, print a name on stdout to use in place of the default export "", then exit with code 0. For convenience, the output can be any of the list forms list_exports recognizes — in that case the first listed export name gets used, and an empty list means "". Given the current set of recognized export lists, it is not possible for the resulting name to contain a newline. the universe simply said no 💅

This method is not required either — if it's absent, the default export name is the empty string, "".

💖 `open` 💖

/path/to/script open <readonly> <exportname> <tls>

The readonly parameter will be true or false. The exportname parameter, if present, is the export name passed to the server from the client. The tls parameter, if present, will be true or false depending on whether the client is using TLS.

On success, print the handle (any string you want, go wild) on stdout and exit with code 0. If the handle ends with a newline character, that newline gets removed. ✂️

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

🦋 `close` 🦋

/path/to/script close <handle>

🌸 `export_description` 🌸

/path/to/script export_description <handle>

The script should print a human-readable description of the disk image on stdout. If the description ends with a newline character, the newline is removed.

This method is not required — if it's absent, no export description gets provided to the client.

⭐ `get_size` ⭐

/path/to/script get_size <handle>

The script should print the size of the disk image on stdout. You can print it in bytes, or use literally any format nbdkit_parse_size(3) understands, such as 1M.

This method is REQUIRED. 🚨

💀 `block_size` 💀

/path/to/script block_size <handle>

This script should print three numbers on stdout, separated by whitespace. In order, those are the minimum block size, the preferred block size, and the maximum block size. Print them in bytes, or use any format nbdkit_parse_size(3) understands, such as 1M.

👑 `can_write`, `can_flush`, `can_trim`, `can_zero`, `can_extents` 👑

okay this part is lowkey the plot twist. Unlike in other languages, you must provide the can_* methods — otherwise they're all assumed to return false, and your pwrite, flush, trim, zero and extents methods will never be called. The reason 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. 😭

/path/to/script can_write <handle>
/path/to/script can_flush <handle>
/path/to/script can_trim <handle>
/path/to/script can_zero <handle>
/path/to/script can_extents <handle>

The script should exit with code 0 for true or code 3 for false.

🌈 `is_rotational`, `can_fast_zero` 🌈

/path/to/script is_rotational <handle>
/path/to/script can_fast_zero <handle>

The script should exit with code 0 for true or code 3 for false.

🧚 `can_fua`, `can_cache` 🧚

/path/to/script can_fua <handle>
/path/to/script can_cache <handle>

These control Forced Unit Access (FUA) and caching behaviour of the core server.

Unlike the other can_* callbacks, these two are not a boolean. They must print either none, emulate or native to stdout. The meaning of those is described in nbdkit-plugin(3). And also: you must provide a can_cache method if you desire the cache callback to be utilized — same energy as the reasoning behind requiring can_write to utilize pwrite.

🍓 `can_multi_conn` 🍓

/path/to/script can_multi_conn <handle>

The script should exit with code 0 for true or code 3 for false.

💜 `pread` 💜

/path/to/script pread <handle> <count> <offset>

The script should print the requested binary data on stdout. Exactly count bytes must be printed. Not one byte more, not one byte less. 🎯

This method is REQUIRED.

✨ `pwrite` ✨

/path/to/script pwrite <handle> <count> <offset> <flags>

The script should read the binary data to be written from stdin.

The flags parameter can be an empty string or fua. In the future, a comma-separated list of flags may be present.

Unlike in other languages: if you provide a pwrite method you must also provide a can_write method which exits with code 0 (true).

🫶 `flush` 🫶

/path/to/script flush <handle>

Same rule as above — if you provide a flush method you must also provide a can_flush method which exits with code 0 (true).

🎀 `trim` 🎀

/path/to/script trim <handle> <count> <offset> <flags>

The flags parameter can be an empty string or fua. In the future, a comma-separated list of flags may be present.

And yeah — if you provide a trim method you must also provide a can_trim method which exits with code 0 (true).

🌟 `zero` 🌟

/path/to/script zero <handle> <count> <offset> <flags>

The flags parameter can be an empty string or a comma-separated list of the flags: fua, may_trim, and fast (eg. "", "fua", "fua,may_trim,fast" are some of the 8 possible values).

You already know the drill: if you provide a zero method you must also provide a can_zero method which exits with code 0 (true).

To trigger a fallback to pwrite on a normal zero request, or to respond quickly to the fast flag that a specific zero request is no faster than a corresponding write, the script must output ENOTSUP or EOPNOTSUPP to stderr (possibly followed by a description of the problem) before exiting with code 1 (failure).

🔥 `extents` 🔥

/path/to/script extents <handle> <count> <offset> <flags>

The flags parameter can be an empty string or req_one.

This must print, one per line on stdout, a list of one or more extents in the format:

offset length type

which correspond to the inputs of the C nbdkit_add_extent function (see nbdkit-plugin(3)). The offset and length fields may use any format understood by nbdkit_parse_size(3). The optional type field may be an integer, missing (same as 0), or a comma-separated list of the words hole and zero. Blank lines and lines beginning with # are comments. Here's an example of a valid set of extents covering a 10M disk where the first megabyte only is allocated data:

0  1M
1M 9M  hole,zero

And obviously: if you provide an extents method you must also provide a can_extents method which exits with code 0 (true).

💅 `cache` 💅

/path/to/script cache <handle> <count> <offset>

Yep, one more: if you provide a cache method you must also provide a can_cache method which prints native and exits with code 0 (true).

🙈 Missing callbacks 🙈

Missing: name, version, longname, description, config_help

These are not yet supported. manifesting them for a future release tho ✨

📁 FILES 📁

$plugindir/nbdkit-sh-plugin.so — the plugin.

Wanna know where $plugindir actually lives? Run nbdkit --dump-config.

🌈 VERSION 🌈

nbdkit-sh-plugin first appeared in nbdkit 1.8.

👀 SEE ALSO 👀

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

🫶 AUTHORS 🫶

Richard W.M. Jones

📜 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 was nbdkit-sh-plugin(3) from nbdkit 1.48.1, dated 2026-08-29. go write the most unhinged shell plugin of your life, you absolute icon 👑🦋

📦 where this page comes from

fedora 44: nbdkit-basic-plugins 1.48.1-1.fc44 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

nbdkit-sh-plugin(3)

✨ NAME ✨

🌈 SYNOPSIS 🌈

🎀 DESCRIPTION 🎀

💖 If you have been given an nbdkit sh plugin 💖

🦋 Inline shell scripts 🦋

👑 WRITING AN NBDKIT SH PLUGIN 👑

🌸 Programming model 🌸

💀 Exit codes 💀

🧚 Temporary directory 🧚

💅 Handles 💅

🌟 Per-connection state 🌟

🔥 Performance 🔥

⭐ Methods ⭐

load

unload

dump_plugin

config

config_complete

magic_config_key

thread_model

get_ready

after_fork

preconnect

list_exports

NAMES

INTERLEAVED

NAMES+DESCRIPTIONS

🎀 default_export 🎀

💖 open 💖

🦋 close 🦋

🌸 export_description 🌸

⭐ get_size ⭐

💀 block_size 💀

👑 can_write, can_flush, can_trim, can_zero, can_extents 👑

🌈 is_rotational, can_fast_zero 🌈

🧚 can_fua, can_cache 🧚

🍓 can_multi_conn 🍓

💜 pread 💜

✨ pwrite ✨

🫶 flush 🫶

🎀 trim 🎀

🌟 zero 🌟

🔥 extents 🔥

💅 cache 💅

🙈 Missing callbacks 🙈

📁 FILES 📁

🌈 VERSION 🌈

👀 SEE ALSO 👀

🫶 AUTHORS 🫶

©️ COPYRIGHT ©️

📜 LICENSE 📜

`load`

`unload`

`dump_plugin`

`config`

`config_complete`

`magic_config_key`

`thread_model`

`get_ready`

`after_fork`

`preconnect`

`list_exports`

🎀 `default_export` 🎀

💖 `open` 💖

🦋 `close` 🦋

🌸 `export_description` 🌸

⭐ `get_size` ⭐

💀 `block_size` 💀

👑 `can_write`, `can_flush`, `can_trim`, `can_zero`, `can_extents` 👑

🌈 `is_rotational`, `can_fast_zero` 🌈

🧚 `can_fua`, `can_cache` 🧚

🍓 `can_multi_conn` 🍓

💜 `pread` 💜

✨ `pwrite` ✨

🫶 `flush` 🫶

🎀 `trim` 🎀

🌟 `zero` 🌟

🔥 `extents` 🔥

💅 `cache` 💅