1nbdkit-sh-plugin(3) NBDKIT nbdkit-sh-plugin(3)
2
6 nbdkit-sh-plugin - nbdkit shell, script or executable plugin
7
9 nbdkit sh /path/to/script [arguments...]
10 nbdkit sh - <<'EOF'
12 ... shell script ...
13 EOF
14
16 "nbdkit-sh-plugin" allows you to write plugins for nbdkit(1) using
17 arbitrary scripting languages, including shells like bash(1), dash(1),
18 csh(1), zsh(1) etc., other scripting environments, or any executable.
19 Note if you want to use an established scripting language like Perl or
21 Python, then nbdkit has specific plugins to handle those languages and
22 those will be more efficient (see nbdkit(1) for a complete list).
23 To use shell script fragments from the nbdkit command line (rather than
25 a separate script) see nbdkit-eval-plugin(1).
26 If you have been given an nbdkit sh plugin
28 Assuming you have a shell script which is an nbdkit plugin, you run it
29 like this:
30 nbdkit sh /path/to/script
32 You may have to add further "key=value" arguments to the command line.
34 The script must be executable ("chmod +x").
35 Inline shell scripts
37 It is also possible to write a shell script plugin "inline" using "-"
38 as the name of the script, like this:
39 nbdkit sh - <<'EOF'
41 case "$1" in
42 get_size) echo 1M ;;
43 pread) dd if=/dev/zero count=$3 iflag=count_bytes ;;
44 *) exit 2 ;;
45 esac
46 EOF
47 By default the inline script runs under /bin/sh. You can add a shebang
49 ("#!") to use other scripting languages.
50
52 For an example plugin written in Bash, see:
53 https://github.com/libguestfs/nbdkit/blob/master/plugins/sh/example.sh
54 Broadly speaking, nbdkit shell plugins work like C ones, so you should
56 read nbdkit-plugin(3) first.
57 Programming model
59 This plugin has a simple programming model: For every plugin method
60 that needs to be called, the external script is invoked with parameters
61 describing the method and its arguments. The first parameter is always
62 the method name. For example:
63 /path/to/script config file disk.img
65 │ │ │
66 │ │ └─ value ($3)
67 │ └── key ($2)
68 method ($1)
69 /path/to/script pread <handle> <count> <offset>
71 │ │ │ │
72 │ │ │ └─ offset in bytes ($4)
73 │ │ └── request size in bytes ($3)
74 method ($1) └── handle ($2) ─ see "Handles" below
75 Scripts should ignore extra parameters that they don't understand since
77 we may add new parameters in future.
78 Exit codes
80 The script should exit with specific exit codes:
81 0 The method was executed successfully.
83 1 and 8-127
85 There was an error. The script may print on stderr an errno name,
86 optionally followed by whitespace and a message, for example:
87 ENOSPC Out of space
89 If the script doesn't print anything or the output cannot be parsed
91 then nbdkit assumes error "EIO". Note that output to stderr is
92 ignored if the command succeeds, so it is acceptable to output a
93 potential error message prefix prior to attempting a command which
94 will add further details if a failure occurs.
95 2 The requested method is not supported by the script.
97 3 For methods which return booleans, this code indicates false.
99 4, 5, 6, 7
101 These exit codes are reserved for future use.
102 Temporary directory
104 A fresh script is invoked for each method call (ie. scripts are
105 stateless), so if the script needs to store state it has to store it
106 somewhere in the filesystem in a format and location which is left up
107 to the author of the script.
108 However nbdkit helps by creating a randomly named, empty directory for
110 the script. This directory persists for the lifetime of nbdkit and is
111 deleted when nbdkit exits. The name of the directory is passed to each
112 script invocation in the $tmpdir environment variable.
113 Handles
115 Handles are arbitrary strings, but it is best to limit them to short
116 alphanumeric strings.
117 Per-connection state
119 The temporary directory described above can be used for state for the
121 lifetime of the nbdkit instance (across multiple connections). If you
122 want to store state per connection then one way to do it is to create a
123 randomly named subdirectory under the temporary directory:
124 case "$1" in
126 ...
127 open)
128 mktemp -d $tmpdir/handle-XXXXXX ;;
129 The handle will be the subdirectory name, returned to the script as $2
131 in all connected calls (eg. "pread", "get_size"). You can delete the
132 subdirectory explicitly in "close":
133 case "$1" in
135 ...
136 close)
137 rm -rf "$2" ;;
138 or rely on nbdkit deleting the whole temporary directory including all
140 per-handle subdirectories when it exits.
141 Performance
143 This plugin has to fork on every request, so performance will never be
144 great. For best performance, consider using the nbdkit-plugin(3) API
145 directly. Having said that, if you have a sh plugin and want to
146 improve performance then the following tips may help:
147 Relax the thread model.
149 The default "thread_model" is "serialize_all_requests" meaning that
150 two instances of the script can never be running at the same time.
151 This is safe but slow. If your script is safe to be called in
152 parallel, set this to "parallel".
153 Implement the "zero" method.
155 If the "zero" method is not implemented then nbdkit will fall back
156 to using "pwrite" which is considerably slower because nbdkit has
157 to send blocks of zeroes to the script.
158 You don't have to write shell scripts.
160 This plugin can run any external binary, not only shell scripts.
161 You should get more performance by rewriting the shell script as a
162 program in a compiled language.
163 Methods
165 This just documents the arguments to the script corresponding to each
166 plugin method, and any way that they differ from the C callbacks. In
167 all other respects they work the same way as the C callbacks, so you
168 should go and read nbdkit-plugin(3).
169 "load"
171 /path/to/script load
172 "unload"
174 /path/to/script unload
175 This is called just before nbdkit exits. Errors from this method
177 are ignored.
178 "dump_plugin"
180 /path/to/script dump_plugin
181 "config"
183 /path/to/script config <key> <value>
184 "config_complete"
186 /path/to/script config_complete
187 "magic_config_key"
189 /path/to/script magic_config_key
190 If a magic config key is needed, this should echo it to stdout.
192 See "Magic parameters" in nbdkit(1).
193 "thread_model"
195 /path/to/script thread_model
196 On success this should print the desired thread model of the
198 script, one of "serialize_connections", "serialize_all_requests",
199 "serialize_requests", or "parallel".
200 This method is not required; if omitted, then the plugin will be
202 executed under the safe "serialize_all_requests" model. However,
203 this means that this method must be provided if you want to use the
204 "parallel" or "serialize_requests" model. Even then your request
205 may be restricted for other reasons; look for "thread_model" in the
206 output of "nbdkit --dump-plugin sh script" to see what actually
207 gets selected.
208 If an error occurs, the script should output an error message and
210 exit with status 1; unrecognized output is ignored.
211 "get_ready"
213 /path/to/script get_ready
214 "preconnect"
216 /path/to/script preconnect <readonly> <exportname>
217 "open"
219 /path/to/script open <readonly> <exportname>
220 The "readonly" parameter will be "true" or "false". The
222 "exportname" parameter, if present, is the export name passed to
223 the server from the client.
224 On success this should print the handle (any string) on stdout and
226 exit with code 0. If the handle ends with a newline character then
227 the newline is removed.
228 Unlike C plugins, this method is not required. If omitted then the
230 handle will be "" (empty string).
231 "close"
233 /path/to/script close <handle>
234 "get_size"
236 /path/to/script get_size <handle>
237 The script should print the size of the disk image on stdout. You
239 can print the size in bytes, or use any format understood by
240 "nbdkit_parse_size" such as "1M" (see "PARSING SIZE PARAMETERS" in
241 nbdkit-plugin(3)).
242 This method is required.
244 "can_write"
246 "can_flush"
247 "can_trim"
248 "can_zero"
249 "can_extents"
250 Unlike in other languages, you must provide the "can_*" methods
251 otherwise they are assumed to all return false and your "pwrite",
252 "flush", "trim", "zero" and "extents" methods will never be called.
253 The reason for this is obscure: In other languages we can detect if
254 (eg) a "pwrite" method is defined and synthesize an appropriate
255 response if no actual "can_write" method is defined. However
256 detecting if methods are present without running them is not
257 possible with this plugin.
258 /path/to/script can_write <handle>
260 /path/to/script can_flush <handle>
261 /path/to/script can_trim <handle>
262 /path/to/script can_zero <handle>
263 /path/to/script can_extents <handle>
264 The script should exit with code 0 for true or code 3 for false.
266 "is_rotational"
268 "can_fast_zero"
269 /path/to/script is_rotational <handle>
270 /path/to/script can_fast_zero <handle>
271 The script should exit with code 0 for true or code 3 for false.
273 "can_fua"
275 "can_cache"
276 /path/to/script can_fua <handle>
277 /path/to/script can_cache <handle>
278 These control Forced Unit Access (FUA) and caching behaviour of the
280 core server.
281 Unlike the other "can_*" callbacks, these two are not a boolean.
283 They must print either "none", "emulate" or "native" to stdout.
284 The meaning of these is described in nbdkit-plugin(3).
285 Furthermore, you must provide a "can_cache" method if you desire
286 the "cache" callback to be utilized, similar to the reasoning
287 behind requiring "can_write" to utilize "pwrite".
288 "can_multi_conn"
290 /path/to/script can_multi_conn <handle>
291 The script should exit with code 0 for true or code 3 for false.
293 "pread"
295 /path/to/script pread <handle> <count> <offset>
296 The script should print the requested binary data on stdout.
298 Exactly "count" bytes must be printed.
299 This method is required.
301 "pwrite"
303 /path/to/script pwrite <handle> <count> <offset> <flags>
304 The script should read the binary data to be written from stdin.
306 The "flags" parameter can be an empty string or "fua". In the
308 future, a comma-separated list of flags may be present.
309 Unlike in other languages, if you provide a "pwrite" method you
311 must also provide a "can_write" method which exits with code 0
312 (true).
313 "flush"
315 /path/to/script flush <handle>
316 Unlike in other languages, if you provide a "flush" method you must
318 also provide a "can_flush" method which exits with code 0 (true).
319 "trim"
321 /path/to/script trim <handle> <count> <offset> <flags>
322 The "flags" parameter can be an empty string or "fua". In the
324 future, a comma-separated list of flags may be present.
325 Unlike in other languages, if you provide a "trim" method you must
327 also provide a "can_trim" method which exits with code 0 (true).
328 "zero"
330 /path/to/script zero <handle> <count> <offset> <flags>
331 The "flags" parameter can be an empty string or a comma-separated
333 list of the flags: "fua", "may_trim", and "fast" (eg. "", "fua",
334 "fua,may_trim,fast" are some of the 8 possible values).
335 Unlike in other languages, if you provide a "zero" method you must
337 also provide a "can_zero" method which exits with code 0 (true).
338 To trigger a fallback to <pwrite> on a normal zero request, or to
340 respond quickly to the "fast" flag that a specific zero request is
341 no faster than a corresponding write, the script must output
342 "ENOTSUP" or "EOPNOTSUPP" to stderr (possibly followed by a
343 description of the problem) before exiting with code 1 (failure).
344 "extents"
346 /path/to/script extents <handle> <count> <offset> <flags>
347 The "flags" parameter can be an empty string or "req_one".
349 This must print, one per line on stdout, a list of one or more
351 extents in the format:
352 offset length type
354 which correspond to the inputs of the C "nbdkit_add_extent"
356 function (see nbdkit-plugin(3)). The "offset" and "length" fields
357 may use any format understood by "nbdkit_parse_size". The optional
358 "type" field may be an integer, missing (same as 0), or a comma-
359 separated list of the words "hole" and "zero". An example of a
360 valid set of extents covering a "10M" disk where the first megabyte
361 only is allocated data:
362 0 1M
364 1M 9M hole,zero
365 Unlike in other languages, if you provide an "extents" method you
367 must also provide a "can_extents" method which exits with code 0
368 (true).
369 "cache"
371 /path/to/script cache <handle> <count> <offset>
372 Unlike in other languages, if you provide a "cache" method you must
374 also provide a "can_cache" method which prints "native" and exits
375 with code 0 (true).
376 Missing callbacks
378 Missing: "name", "version", "longname", "description", "config_help"
379 These are not yet supported.
380
382 $plugindir/nbdkit-sh-plugin.so
383 The plugin.
384 Use "nbdkit --dump-config" to find the location of $plugindir.
386
388 "nbdkit-sh-plugin" first appeared in nbdkit 1.8.
389
391 nbdkit(1), nbdkit-plugin(3), nbdkit-eval-plugin(1).
392
394 Richard W.M. Jones
395
397 Copyright (C) 2018-2019 Red Hat Inc.
398
400 Redistribution and use in source and binary forms, with or without
401 modification, are permitted provided that the following conditions are
402 met:
403 · Redistributions of source code must retain the above copyright
405 notice, this list of conditions and the following disclaimer.
406 · Redistributions in binary form must reproduce the above copyright
408 notice, this list of conditions and the following disclaimer in the
409 documentation and/or other materials provided with the
410 distribution.
411 · Neither the name of Red Hat nor the names of its contributors may
413 be used to endorse or promote products derived from this software
414 without specific prior written permission.
415 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
417 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
418 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
419 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
420 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
421 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
422 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
423 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
424 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
425 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
426 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
427nbdkit-1.18.4 2020-04-16 nbdkit-sh-plugin(3)