1nbdkit-eval-plugin(1) NBDKIT nbdkit-eval-plugin(1)
2
6 nbdkit-eval-plugin - write a shell script plugin on the command line
7
9 nbdkit eval get_size='SCRIPT' pread='SCRIPT' pwrite='SCRIPT' [...]
10
12 "nbdkit-eval-plugin" is an nbdkit(1) plugin which allows you to write
13 custom plugins as shell scripts snippets ‘eval’d on the command line.
14 A common alternative to this plugin is nbdkit-sh-plugin(1). Both
16 plugins share the same source code and work in almost the same way.
17 You should read nbdkit-sh-plugin(1) first. It is easier to describe
18 the differences between the two plugins and look at the examples below.
19 • nbdkit-sh-plugin(1) plugins are written as a single script in a
21 separate file. Eval plugins are shell script fragments written on
22 the nbdkit command line — there is no separate script file.
23 • nbdkit-sh-plugin(1) has no way to know if a method is missing or
25 not and so each "can_*" method (eg. "can_write") must be written
26 explicitly. In eval plugins you have the option of omitting
27 "can_*" methods if the associated callback (eg. "pwrite") is
28 defined. In this way eval plugins work more like regular nbdkit
29 plugins.
30 • Eval plugins can only use /bin/sh to run the script snippets, but
32 nbdkit-sh-plugin(1) (in spite of the name) can run any executable.
33 • There is no "load" method (although there is an "unload" method and
35 all other methods are identical).
36
38 Create a 64M read-only disk of zeroes:
39 nbdkit eval get_size=' echo 64M ' \
41 pread=' dd if=/dev/zero count=$3 iflag=count_bytes '
42 The following command is the eval plugin equivalent of
44 nbdkit-file-plugin(1) (except not as fast and missing many features):
45 nbdkit eval \
47 config='ln -sf "$(realpath "$3")" $tmpdir/file' \
48 get_size='stat -Lc %s $tmpdir/file' \
49 pread='dd if=$tmpdir/file skip=$4 count=$3 iflag=count_bytes,skip_bytes' \
50 pwrite='dd of=$tmpdir/file seek=$4 conv=notrunc oflag=seek_bytes' \
51 file=disk.img
52
54 after_fork=SCRIPT
55 block_size=SCRIPT
56 cache=SCRIPT
57 can_cache=SCRIPT
58 can_extents=SCRIPT
59 can_fast_zero=SCRIPT
60 can_flush=SCRIPT
61 can_fua=SCRIPT
62 can_multi_conn=SCRIPT
63 can_trim=SCRIPT
64 can_write=SCRIPT
65 can_zero=SCRIPT
66 close=SCRIPT
67 config=SCRIPT
68 config_complete=SCRIPT
69 default_export=SCRIPT
70 dump_plugin=SCRIPT
71 export_description=SCRIPT
72 extents=SCRIPT
73 flush=SCRIPT
74 get_ready=SCRIPT
75 get_size=SCRIPT
76 is_rotational=SCRIPT
77 list_exports=SCRIPT
78 default_export=SCRIPT
79 open=SCRIPT
80 pread=SCRIPT
81 preconnect=SCRIPT
82 pwrite=SCRIPT
83 thread_model=SCRIPT
84 trim=SCRIPT
85 unload=SCRIPT
86 zero=SCRIPT
87 Define the script associated with each method. "SCRIPT" is a
88 fragment of shell script which is executed when nbdkit wants to
89 invoke the associated method.
90 If you are typing these commands at the shell, be careful about
92 quoting. Normally you will need to enclose "SCRIPT" in '...'
93 (single quotes) to prevent it from being modified by your shell.
94 The script fragment behaves the same way as the corresponding
96 method in nbdkit-sh-plugin(1). In particular, parameters are
97 identical, $tmpdir is present and used in the same way, the exit
98 code must be one of the valid exit codes described in that manual
99 page, and error handling works the same way too. Likewise, nbdkit
100 --dump-plugin eval includes a line for max_known_status= in nbdkit
101 ≥ 1.34.
102 Note that a "config" callback will only handle keys not recognized
104 as callback names; when picking key=value pairs that you want your
105 script fragment to understand, be aware that if a future nbdkit
106 release creates a callback by that name, your "config" script
107 fragment will no longer see that key.
108 All of these parameters are optional.
110 missing=SCRIPT
112 The parameter "missing" defines a script that will be called in
113 place of any other callback not explicitly provided. If omitted,
114 this defaults to the script "exit 2".
115
117 "tmpdir"
118 This is defined to the name of a temporary directory which can be
119 used by the script snippets. It is deleted when nbdkit exits.
120
122 /bin/sh
123 Shell script fragments are executed using /bin/sh.
124 $plugindir/nbdkit-eval-plugin.so
126 The plugin.
127 Use "nbdkit --dump-config" to find the location of $plugindir.
129
131 "nbdkit-eval-plugin" first appeared in nbdkit 1.18.
132
134 nbdkit(1), nbdkit-plugin(3), nbdkit-sh-plugin(1). nbdkit-cc-plugin(1).
135
137 Richard W.M. Jones
138
140 Copyright (C) 2019 Red Hat Inc.
141
143 Redistribution and use in source and binary forms, with or without
144 modification, are permitted provided that the following conditions are
145 met:
146 • Redistributions of source code must retain the above copyright
148 notice, this list of conditions and the following disclaimer.
149 • Redistributions in binary form must reproduce the above copyright
151 notice, this list of conditions and the following disclaimer in the
152 documentation and/or other materials provided with the
153 distribution.
154 • Neither the name of Red Hat nor the names of its contributors may
156 be used to endorse or promote products derived from this software
157 without specific prior written permission.
158 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
160 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
161 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
162 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
163 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
164 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
165 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
166 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
167 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
168 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
169 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
170nbdkit-1.32.5 2023-01-03 nbdkit-eval-plugin(1)