.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-sh-plugin 3"
.TH nbdkit-sh-plugin 3 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-sh\-plugin \- nbdkit shell, script or executable plugin
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit sh /path/to/script [arguments...]
\&
\& nbdkit sh \- <<\*(AqEOF\*(Aq
\& ... shell script ...
\& EOF
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-sh\-plugin\*(C'\fR allows you to write plugins for \fBnbdkit\fR\|(1) using
arbitrary scripting languages, including shells like \fBbash\fR\|(1),
\&\fBdash\fR\|(1), \fBcsh\fR\|(1), \fBzsh\fR\|(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
\&\fBnbdkit\fR\|(1) for a complete list).
.SS "If you have been given an nbdkit sh plugin"
.IX Subsection "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:
.PP
.Vb 1
\& nbdkit sh /path/to/script
.Ve
.PP
You may have to add further \f(CW\*(C`key=value\*(C'\fR arguments to the command
line.  The script must be executable (\f(CW\*(C`chmod +x\*(C'\fR).
.SS "Inline shell scripts"
.IX Subsection "Inline shell scripts"
It is also possible to write a shell script plugin \*(L"inline\*(R" using \f(CW\*(C`\-\*(C'\fR
as the name of the script, like this:
.PP
.Vb 7
\& nbdkit sh \- <<\*(AqEOF\*(Aq
\&   case "$1" in
\&     get_size) echo 1M ;;
\&     pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
\&     *) exit 2 ;;
\&   esac
\& EOF
.Ve
.PP
By default the inline script runs under \fI/bin/sh\fR.  You can add a
shebang (\f(CW\*(C`#!\*(C'\fR) to use other scripting languages.
.SH "WRITING AN NBDKIT SH PLUGIN"
.IX Header "WRITING AN NBDKIT SH PLUGIN"
For an example plugin written in Bash, see:
https://github.com/libguestfs/nbdkit/blob/master/plugins/sh/example.sh
.PP
Broadly speaking, nbdkit shell plugins work like C ones, so you should
read \fBnbdkit\-plugin\fR\|(3) first.
.SS "Programming model"
.IX Subsection "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:
.PP
.Vb 5
\& /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
.Ve
.SS "Exit codes"
.IX Subsection "Exit codes"
The script should exit with specific exit codes:
.IP "0" 4
The method was executed successfully.
.IP "1 and 8\-127" 4
.IX Item "1 and 8-127"
There was an error.  The script may print on stderr an errno and a
message, for example:
.Sp
.Vb 1
\& ENOSPC Out of space
.Ve
.Sp
If the script doesn't print anything or the output cannot be parsed
then nbdkit assumes error \f(CW\*(C`EIO\*(C'\fR.
.IP "2" 4
.IX Item "2"
The requested method is not supported by the script.
.IP "3" 4
.IX Item "3"
For methods which return booleans, this code indicates false.
.IP "4, 5, 6, 7" 4
.IX Item "4, 5, 6, 7"
These exit codes are reserved for future use.
.SS "Temporary directory"
.IX Subsection "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.
.PP
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 \f(CW$tmpdir\fR environment variable.
.SS "Handles"
.IX Subsection "Handles"
Handles are arbitrary strings, but it is best to limit them to short
alphanumeric strings.
.PP
\fIPer-connection state\fR
.IX Subsection "Per-connection state"
.PP
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:
.PP
.Vb 4
\& case "$1" in
\&   ...
\&   open)
\&     mktemp \-d $tmpdir/handle\-XXXXXX ;;
.Ve
.PP
The handle will be the subdirectory name, returned to the script as
\&\f(CW$2\fR in all connected calls (eg. \f(CW\*(C`pread\*(C'\fR, \f(CW\*(C`get_size\*(C'\fR).  You can
delete the subdirectory explicitly in \f(CW\*(C`close\*(C'\fR:
.PP
.Vb 4
\& case "$1" in
\&   ...
\&   close)
\&     rm \-rf "$2" ;;
.Ve
.PP
or rely on nbdkit deleting the whole temporary directory including all
per-handle subdirectories when it exits.
.SS "Methods"
.IX Subsection "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 \fBnbdkit\-plugin\fR\|(3).
.ie n .IP """load""" 4
.el .IP "\f(CWload\fR" 4
.IX Item "load"
.Vb 1
\& /path/to/script load
.Ve
.ie n .IP """unload""" 4
.el .IP "\f(CWunload\fR" 4
.IX Item "unload"
.Vb 1
\& /path/to/script unload
.Ve
.Sp
This is called just before nbdkit exits.  Errors from this method are
ignored.
.ie n .IP """dump_plugin""" 4
.el .IP "\f(CWdump_plugin\fR" 4
.IX Item "dump_plugin"
.Vb 1
\& /path/to/script dump_plugin
.Ve
.ie n .IP """config""" 4
.el .IP "\f(CWconfig\fR" 4
.IX Item "config"
.Vb 1
\& /path/to/script config <key> <value>
.Ve
.ie n .IP """config_complete""" 4
.el .IP "\f(CWconfig_complete\fR" 4
.IX Item "config_complete"
.Vb 1
\& /path/to/script config_complete
.Ve
.ie n .IP """open""" 4
.el .IP "\f(CWopen\fR" 4
.IX Item "open"
.Vb 1
\& /path/to/script open <readonly>
.Ve
.Sp
The \f(CW\*(C`readonly\*(C'\fR parameter will be \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR.
.Sp
On success this should print the handle (any string) on stdout and
exit with code \f(CW0\fR.  If the handle ends with a newline character then
the newline is removed.
.Sp
Unlike C plugins, this method is \fInot\fR required.  If omitted then the
handle will be \f(CW""\fR (empty string).
.ie n .IP """close""" 4
.el .IP "\f(CWclose\fR" 4
.IX Item "close"
.Vb 1
\& /path/to/script close <handle>
.Ve
.ie n .IP """get_size""" 4
.el .IP "\f(CWget_size\fR" 4
.IX Item "get_size"
.Vb 1
\& /path/to/script get_size <handle>
.Ve
.Sp
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
\&\f(CW\*(C`nbdkit_parse_size\*(C'\fR such as \f(CW\*(C`1M\*(C'\fR (see
\&\*(L"\s-1PARSING SIZE PARAMETERS\*(R"\s0 in \fBnbdkit\-plugin\fR\|(3)).
.Sp
This method is required.
.ie n .IP """can_write""" 4
.el .IP "\f(CWcan_write\fR" 4
.IX Item "can_write"
.PD 0
.ie n .IP """can_flush""" 4
.el .IP "\f(CWcan_flush\fR" 4
.IX Item "can_flush"
.ie n .IP """can_trim""" 4
.el .IP "\f(CWcan_trim\fR" 4
.IX Item "can_trim"
.ie n .IP """can_zero""" 4
.el .IP "\f(CWcan_zero\fR" 4
.IX Item "can_zero"
.PD
Unlike in other languages, you \fBmust\fR provide the \f(CW\*(C`can_*\*(C'\fR methods
otherwise they are assumed to all return false and your \f(CW\*(C`pwrite\*(C'\fR,
\&\f(CW\*(C`flush\*(C'\fR, \f(CW\*(C`trim\*(C'\fR and \f(CW\*(C`zero\*(C'\fR methods will never be called.  The
reason for this is obscure: In other languages we can detect if (eg) a
\&\f(CW\*(C`pwrite\*(C'\fR method is defined and synthesize an appropriate response if
no actual \f(CW\*(C`can_write\*(C'\fR method is defined.  However detecting if
methods are present without running them is not possible with this
plugin.
.Sp
.Vb 4
\& /path/to/script can_write <handle>
\& /path/to/script can_flush <handle>
\& /path/to/script can_trim <handle>
\& /path/to/script can_zero <handle>
.Ve
.Sp
The script should exit with code \f(CW0\fR for true or code \f(CW3\fR for false.
.ie n .IP """is_rotational""" 4
.el .IP "\f(CWis_rotational\fR" 4
.IX Item "is_rotational"
.Vb 1
\& /path/to/script is_rotational <handle>
.Ve
.Sp
The script should exit with code \f(CW0\fR for true or code \f(CW3\fR for false.
.ie n .IP """can_fua""" 4
.el .IP "\f(CWcan_fua\fR" 4
.IX Item "can_fua"
.Vb 1
\& /path/to/script can_fua <handle>
.Ve
.Sp
This controls Forced Unit Access (\s-1FUA\s0) behaviour of the core server.
.Sp
Unlike the other \f(CW\*(C`can_*\*(C'\fR callbacks, this one is \fInot\fR a boolean.  It
must print either \*(L"none\*(R", \*(L"emulate\*(R" or \*(L"native\*(R" to stdout.  The
meaning of these is described in \fBnbdkit\-plugin\fR\|(3).
.ie n .IP """can_multi_conn""" 4
.el .IP "\f(CWcan_multi_conn\fR" 4
.IX Item "can_multi_conn"
.Vb 1
\& /path/to/script can_multi_conn <handle>
.Ve
.Sp
The script should exit with code \f(CW0\fR for true or code \f(CW3\fR for false.
.ie n .IP """pread""" 4
.el .IP "\f(CWpread\fR" 4
.IX Item "pread"
.Vb 1
\& /path/to/script pread <handle> <count> <offset>
.Ve
.Sp
The script should print the requested binary data on stdout.  Exactly
\&\f(CW\*(C`count\*(C'\fR bytes must be printed.
.Sp
This method is required.
.ie n .IP """pwrite""" 4
.el .IP "\f(CWpwrite\fR" 4
.IX Item "pwrite"
.Vb 1
\& /path/to/script pwrite <handle> <count> <offset> <flags>
.Ve
.Sp
The script should read the binary data to be written from stdin.
.Sp
The \f(CW\*(C`flags\*(C'\fR parameter can be an empty string or \f(CW"fua"\fR.  In the
future, a comma-separated list of flags may be present.
.Sp
Unlike in other languages, if you provide a \f(CW\*(C`pwrite\*(C'\fR method you
\&\fBmust\fR also provide a \f(CW\*(C`can_write\*(C'\fR method which exits with code \f(CW0\fR
(true).
.ie n .IP """flush""" 4
.el .IP "\f(CWflush\fR" 4
.IX Item "flush"
.Vb 1
\& /path/to/script flush <handle>
.Ve
.Sp
Unlike in other languages, if you provide a \f(CW\*(C`flush\*(C'\fR method you
\&\fBmust\fR also provide a \f(CW\*(C`can_flush\*(C'\fR method which exits with code \f(CW0\fR
(true).
.ie n .IP """trim""" 4
.el .IP "\f(CWtrim\fR" 4
.IX Item "trim"
.Vb 1
\& /path/to/script trim <handle> <count> <offset> <flags>
.Ve
.Sp
The \f(CW\*(C`flags\*(C'\fR parameter can be an empty string or \f(CW"fua"\fR.  In the
future, a comma-separated list of flags may be present.
.Sp
Unlike in other languages, if you provide a \f(CW\*(C`trim\*(C'\fR method you \fBmust\fR
also provide a \f(CW\*(C`can_trim\*(C'\fR method which exits with code \f(CW0\fR (true).
.ie n .IP """zero""" 4
.el .IP "\f(CWzero\fR" 4
.IX Item "zero"
.Vb 1
\& /path/to/script zero <handle> <count> <offset> <flags>
.Ve
.Sp
The \f(CW\*(C`flags\*(C'\fR parameter can be an empty string or a comma-separated
list of the flags: \f(CW"fua"\fR and \f(CW"may_trim"\fR (eg. \f(CW""\fR, \f(CW"fua"\fR,
\&\f(CW"fua,may_trim"\fR are all possible values).
.Sp
Unlike in other languages, if you provide a \f(CW\*(C`zero\*(C'\fR method you \fBmust\fR
also provide a \f(CW\*(C`can_zero\*(C'\fR method which exits with code \f(CW0\fR (true).
.SS "Missing callbacks"
.IX Subsection "Missing callbacks"
.ie n .IP "Missing: ""name"", ""version"", ""longname"", ""description"", ""config_help""" 4
.el .IP "Missing: \f(CWname\fR, \f(CWversion\fR, \f(CWlongname\fR, \f(CWdescription\fR, \f(CWconfig_help\fR" 4
.IX Item "Missing: name, version, longname, description, config_help"
These are not yet supported.
.SS "Threads"
.IX Subsection "Threads"
The thread model for scripts currently cannot be set from this plugin.
It is hard-coded in the C part to
\&\f(CW\*(C`NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS\*(C'\fR.  This may change or be
settable in future.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3).
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0