nbdkit-lua-plugin(3)

1nbdkit-lua-plugin(3)                NBDKIT                nbdkit-lua-plugin(3)
2
3
4

NAME

6       nbdkit-lua-plugin - nbdkit Lua plugin
7

SYNOPSIS

9        nbdkit lua /path/to/plugin.lua [arguments...]
10

DESCRIPTION

12       "nbdkit-lua-plugin" is an embedded Lua interpreter for nbdkit(1),
13       allowing you to write nbdkit plugins in Lua.
14
15   If you have been given an nbdkit Lua plugin
16       Assuming you have a Lua script which is an nbdkit plugin, you run it
17       like this:
18
19        nbdkit lua /path/to/plugin.lua
20
21       You may have to add further "key=value" arguments to the command line.
22       Read the Lua script to see if it requires any.
23

WRITING A LUA NBDKIT PLUGIN

25       For an example plugin written in Lua, see:
26       https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/lua/example.lua
27
28       Broadly speaking, Lua nbdkit plugins work like C ones, so you should
29       read nbdkit-plugin(3) first.
30
31       To write a Lua nbdkit plugin, you create a Lua file which contains at
32       least the following required functions:
33
34        function open (readonly)
35            -- see below
36            return h
37        end
38        function get_size (h)
39            -- see below
40            return size
41        end
42        function pread (h, count, offset)
43            -- see below
44            return buf
45        end
46
47       Note that the subroutines must have those literal names (like "open"),
48       because the C part looks up and calls those functions directly.  You
49       may want to include documentation and globals (eg. for storing global
50       state).  Also any top-level statements are run when nbdkit starts up.
51
52   Executable script
53       If you want you can make the script executable and include a "shebang"
54       at the top:
55
56        #!/usr/sbin/nbdkit lua
57
58       See also "Shebang scripts" in nbdkit(1).
59
60       These scripts can also be installed in the $plugindir.  See "WRITING
61       PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
62
63   Errors
64       Lua plugin methods can indicate an error by calling "error" or
65       "assert".  The error message will contain the method name, filename and
66       line number where the error occurred, eg:
67
68        error ("could not open " .. filename)
69        --> nbdkit: error: open: myplugin.lua:123: could not open disk.img
70
71   Lua callbacks
72       This just documents the arguments to the callbacks in Lua, and any way
73       that they differ from the C callbacks.  In all other respects they work
74       the same way as the C callbacks, so you should go and read
75       nbdkit-plugin(3).
76
77       "dump_plugin"
78           (Optional)
79
80           There are no arguments or return value.
81
82       "config"
83           (Optional)
84
85            function config (key, value)
86                -- No return value.
87            end
88
89       "config_complete"
90           (Optional)
91
92           There are no arguments or return value.
93
94       "open"
95           (Required)
96
97            function open (readonly)
98                local handle
99                handle=...
100                return handle
101            end
102
103           The "readonly" flag is a boolean.
104
105           You can return any Lua string or object as the handle.  It is
106           passed back to subsequent calls.
107
108       "close"
109           (Optional)
110
111            function close (h)
112                -- No return value
113            end
114
115           After "close" returns, the reference count of the handle is
116           decremented in the C part, which usually means that the handle and
117           its contents will be garbage collected.
118
119       "get_size"
120           (Required)
121
122            function get_size (h)
123                local size
124                size= .. the size of the disk ..
125                return size
126            end
127
128           This returns the size of the disk.
129
130       "can_write"
131           (Optional)
132
133            function can_write (h)
134                return bool
135            end
136
137           Return a boolean indicating whether the disk is writable.
138
139       "can_flush"
140           (Optional)
141
142            function can_flush (h)
143                return bool
144            end
145
146           Return a boolean indicating whether flush can be performed.
147
148       "is_rotational"
149           (Optional)
150
151            function is_rotational (h)
152                return bool
153            end
154
155           Return a boolean indicating whether the disk is rotational.
156
157       "can_trim"
158           (Optional)
159
160            function can_trim (h)
161                return bool
162            end
163
164           Return a boolean indicating whether trim/discard can be performed.
165
166       "pread"
167           (Required)
168
169            function pread (h, count, offset)
170               -- Construct a buffer of length count bytes and return it.
171               return buf
172            end
173
174           The body of your "pread" function should construct a buffer of
175           length (at least) "count" bytes.  You should read "count" bytes
176           from the disk starting at "offset".
177
178           NBD only supports whole reads, so your function should try to read
179           the whole region (perhaps requiring a loop).  If the read fails or
180           is partial, your function should call "error".
181
182       "pwrite"
183           (Optional)
184
185            function pwrite (h, buf, offset)
186               -- No return value
187            end
188
189           The body of your "pwrite" function should write the "buf" string to
190           the disk.  You should write "count" bytes to the disk starting at
191           "offset".
192
193           NBD only supports whole writes, so your function should try to
194           write the whole region (perhaps requiring a loop).  If the write
195           fails or is partial, your function should call "error".
196
197       "flush"
198           (Optional)
199
200            function flush (h)
201                -- No return value
202            end
203
204           The body of your "flush" function should do a sync(2) or
205           fdatasync(2) or equivalent on the backing store.
206
207       "trim"
208           (Optional)
209
210            function trim (h, count, offset)
211                -- No return value
212            end
213
214           The body of your "trim" function should "punch a hole" in the
215           backing store.
216
217       "zero"
218           (Optional)
219
220            function zero (h, count, offset, may_trim)
221               -- No return value
222            end
223
224           The body of your "zero" function should ensure that "count" bytes
225           of the disk, starting at "offset", will read back as zero.  If
226           "may_trim" is true, the operation may be optimized as a trim as
227           long as subsequent reads see zeroes.
228
229           NBD only supports whole writes, so your function should try to
230           write the whole region (perhaps requiring a loop).  If the write
231           fails or is partial, your function should call "error".
232
233   Missing callbacks
234       Missing: "load", "unload", "name", "version", "longname",
235       "description", "config_help", "can_zero", "can_fua", "can_cache",
236       "cache"
237           These are not yet supported.
238
239   Threads
240       The thread model for Lua callbacks currently cannot be set from Lua.
241       It is hard-coded in the C part to
242       "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS".  This may change or be
243       settable in future.
244

FILES

246       $plugindir/nbdkit-lua-plugin.so
247           The plugin.
248
249           Use "nbdkit --dump-config" to find the location of $plugindir.
250

VERSION

252       "nbdkit-lua-plugin" first appeared in nbdkit 1.6.
253

AUTHORS

258       Richard W.M. Jones
259

COPYRIGHT

261       Copyright (C) 2018 Red Hat Inc.
262

LICENSE

264       Redistribution and use in source and binary forms, with or without
265       modification, are permitted provided that the following conditions are
266       met:
267
268       •   Redistributions of source code must retain the above copyright
269           notice, this list of conditions and the following disclaimer.
270
271       •   Redistributions in binary form must reproduce the above copyright
272           notice, this list of conditions and the following disclaimer in the
273           documentation and/or other materials provided with the
274           distribution.
275
276       •   Neither the name of Red Hat nor the names of its contributors may
277           be used to endorse or promote products derived from this software
278           without specific prior written permission.
279
280       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
281       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
282       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
283       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
284       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
285       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
286       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
287       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
288       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
289       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
290       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
291
292
293
294nbdkit-1.32.5                     2023-01-03              nbdkit-lua-plugin(3)