If you have been given an nbdkit sh plugin

Assuming you have a shell script which is an nbdkit plugin, you run it like this:

 nbdkit sh /path/to/script

You may have to add further "key=value" arguments to the command line. The script must be executable ("chmod +x").

Inline shell scripts

It is also possible to write a shell script plugin "inline" using "-" as the name of the script, like this:

 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.

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

Exit codes

The script should exit with specific exit codes:

0

The method was executed successfully.

1 and 8-127

There was an error. The script may print on stderr an errno and a message, for example:

 ENOSPC Out of space
    

If the script doesn't print anything or the output cannot be parsed then nbdkit assumes error "EIO".

2

The requested method is not supported by the script.

3

For methods which return booleans, this code indicates false.

4, 5, 6, 7

These exit codes are reserved for future use.

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.

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

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.

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.

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

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

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

"is_rotational"

 /path/to/script is_rotational <handle>
    

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

"can_fua"

 /path/to/script can_fua <handle>
    

This controls Forced Unit Access (FUA) behaviour of the core server.

Unlike the other "can_*" callbacks, this one is not a boolean. It must print either "none", "emulate" or "native" to stdout. The meaning of these is described in nbdkit-plugin(3).

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

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>
    

Unlike in other languages, 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.

Unlike in other languages, 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" and "may_trim" (eg. "", "fua", "fua,may_trim" are all possible values).

Unlike in other languages, if you provide a "zero" method you must also provide a "can_zero" method which exits with code 0 (true).

Missing callbacks

Missing: "name", "version", "longname", "description", "config_help"

These are not yet supported.

Threads

The thread model for scripts currently cannot be set from this plugin. It is hard-coded in the C part to "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS". This may change or be settable in future.