1nbdkit-python-plugin(3) NBDKIT nbdkit-python-plugin(3)
2
6 nbdkit-python-plugin - nbdkit python plugin
7
9 nbdkit python /path/to/plugin.py [arguments...]
10
12 "nbdkit-python-plugin" is an embedded Python interpreter for nbdkit(1),
13 allowing you to write nbdkit plugins in Python 3.
14 If you have been given an nbdkit Python plugin
16 Assuming you have a Python script which is an nbdkit plugin, you run it
17 like this:
18 nbdkit python /path/to/plugin.py
20 You may have to add further "key=value" arguments to the command line.
22 Read the Python script to see if it requires any.
23
25 For example plugins written in Python, see:
26 https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/python/examples
27 Broadly speaking, Python nbdkit plugins work like C ones, so you should
29 read nbdkit-plugin(3) first.
30 To write a Python nbdkit plugin, you create a Python file which
32 contains at least the following required functions (in the top level
33 "__main__" module):
34 API_VERSION = 2
36 def open(readonly):
37 # see below
38 def get_size(h):
39 # see below
40 def pread(h, buf, offset, flags):
41 # see below
42 Note that the subroutines must have those literal names (like "open"),
44 because the C part looks up and calls those functions directly. You
45 may want to include documentation and globals (eg. for storing global
46 state). Any other top level statements are run when the script is
47 loaded, just like ordinary Python.
48 Python versions
50 Since nbdkit ≥ 1.16 only Python 3 is supported. If you wish to
51 continue using nbdkit plugins written in Python 2 then you must use
52 nbdkit ≤ 1.14, but we advise you to update your plugins.
53 The version of Python 3 is chosen when nbdkit is built. This is
55 compiled in and can't be changed at runtime. "./configure" looks for
56 (in order):
57 • the "PYTHON" variable (eg "./configure PYTHON=/usr/bin/python3.9")
59 • python3 on $PATH
61 • python on $PATH
63 "./configure" will fail if the first interpreter found is a Python 2
65 interpreter.
66 To find out which version of Python "nbdkit-python-plugin" was compiled
68 for, use the --dump-plugin option:
69 $ nbdkit python --dump-plugin
71 ...
72 python_version=3.7.0
73 python_pep_384_abi_version=3
74 API versions
76 The nbdkit API has evolved and new versions are released periodically.
77 To ensure backwards compatibility plugins have to opt in to the new
78 version. From Python you do this by declaring a constant in your
79 module:
80 API_VERSION = 2
82 (where 2 is the latest version at the time this documentation was
84 written). All newly written Python modules must have this constant.
85 Executable script
87 If you want you can make the script executable and include a "shebang"
88 at the top:
89 #!/usr/sbin/nbdkit python
91 See also "Shebang scripts" in nbdkit(1).
93 These scripts can also be installed in the $plugindir. See "WRITING
95 PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
96 Module functions
98 Your script may use "import nbdkit" to have access to the following
99 methods in the "nbdkit" module:
100 "nbdkit.debug(msg)"
102 Send a debug message to stderr or syslog if verbose messages are
104 enabled.
105 "nbdkit.export_name()"
107 Return the export name negotiated with the client as a Unicode string.
109 Note this should not be trusted because the client can send whatever it
110 wants.
111 "nbdkit.set_error(err)"
113 Record "err" as the reason you are about to throw an exception. "err"
115 should correspond to usual errno values, where it may help to "import
116 errno".
117 "nbdkit.parse_size(str)"
119 Parse a string (such as "100M") into a size in bytes. Wraps the
121 nbdkit_parse_size() C function.
122 "nbdkit.shutdown()"
124 Request asynchronous server shutdown.
126 Module constants
128 After "import nbdkit" the following constants are available. These are
129 used in the callbacks below.
130 "nbdkit.THREAD_MODEL_SERIALIZE_CONNECTIONS"
132 "nbdkit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
133 "nbdkit.THREAD_MODEL_SERIALIZE_REQUESTS"
134 "nbdkit.THREAD_MODEL_PARALLEL"
135 Possible return values from thread_model().
136 "nbdkit.FLAG_MAY_TRIM"
138 "nbdkit.FLAG_FUA"
139 "nbdkit.FLAG_REQ_ONE"
140 "nbdkit.FLAG_FAST_ZERO"
141 Flags bitmap passed to certain plugin callbacks. Not all callbacks
142 with a flags parameter use all of these flags, consult the
143 documentation below and nbdkit-plugin(3).
144 "nbdkit.FUA_NONE"
146 "nbdkit.FUA_EMULATE"
147 "nbdkit.FUA_NATIVE"
148 Possible return values from can_fua().
149 "nbdkit.CACHE_NONE"
151 "nbdkit.CACHE_EMULATE"
152 "nbdkit.CACHE_NATIVE"
153 Possible return values from can_cache().
154 "nbdkit.EXTENT_HOLE"
156 "nbdkit.EXTENT_ZERO"
157 Used in the "type" field returned by extents().
158 Threads
160 The thread model for Python callbacks defaults to
161 "nbdkit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS".
162 Since nbdkit 1.22 it has been possible to set this by implementing a
164 thread_model() function which returns one of the constants
165 "nbdkit.THREAD_MODEL_*".
166 The Python Global Interpreter Lock (GIL) is still used, so Python code
168 does not run in parallel. However if a plugin callback calls a library
169 which blocks (eg. to make an HTTP request), then another callback might
170 be executed in parallel. Plugins which use
171 "nbdkit.THREAD_MODEL_SERIALIZE_REQUESTS" or
172 "nbdkit.THREAD_MODEL_PARALLEL" may need to use locks on shared data.
173 Exceptions
175 Python callbacks should throw exceptions to indicate errors. Remember
176 to use "nbdkit.set_error" if you need to control which error is sent
177 back to the client; if omitted, the client will see an error of "EIO".
178 Python callbacks
180 This just documents the arguments to the callbacks in Python, and any
181 way that they differ from the C callbacks. In all other respects they
182 work the same way as the C callbacks, so you should go and read
183 nbdkit-plugin(3).
184 "dump_plugin"
186 (Optional)
187 There are no arguments or return value.
189 "config"
191 (Optional)
192 def config(key, value):
194 # no return value
195 "config_complete"
197 (Optional)
198 There are no arguments or return value.
200 "thread_model"
202 (Optional, nbdkit ≥ 1.22)
203 def thread_model():
205 return nbdkit.THEAD_MODEL_SERIALIZE_ALL_REQUESTS
206 See "Threads" above.
208 "get_ready"
210 (Optional)
211 There are no arguments or return value.
213 "after_fork"
215 (Optional, nbdkit ≥ 1.26)
216 There are no arguments or return value.
218 "cleanup"
220 (Optional, nbdkit ≥ 1.28)
221 There are no arguments or return value.
223 "list_exports"
225 (Optional)
226 def list_exports(readonly, is_tls):
228 # return an iterable object (eg. list) of
229 # (name, description) tuples or bare names:
230 return [ (name1, desc1), name2, (name3, desc3), ... ]
231 "default_export"
233 (Optional)
234 def default_export(readonly, is_tls):
236 # return a string
237 return "name"
238 "preconnect"
240 (Optional, nbdkit ≥ 1.26)
241 def preconnect(readonly):
243 # no return value
244 "open"
246 (Required)
247 def open(readonly):
249 # return handle
250 You can return any non-NULL Python value as the handle. It is
252 passed back in subsequent calls.
253 "close"
255 (Optional)
256 def close(h):
258 # no return value
259 After "close" returns, the reference count of the handle is
261 decremented in the C part, which usually means that the handle and
262 its contents will be garbage collected.
263 "export_description"
265 (Optional)
266 def export_description(h):
268 # return a string
269 return "description"
270 "get_size"
272 (Required)
273 def get_size(h):
275 # return the size of the disk
276 "block_size"
278 (Option)
279 def block_size(h):
281 # return triple (minimum, preferred, maximum) block size
282 "is_rotational"
284 (Optional)
285 def is_rotational(h):
287 # return a boolean
288 "can_multi_conn"
290 (Optional)
291 def can_multi_conn(h):
293 # return a boolean
294 "can_write"
296 (Optional)
297 def can_write(h):
299 # return a boolean
300 "can_flush"
302 (Optional)
303 def can_flush(h):
305 # return a boolean
306 "can_trim"
308 (Optional)
309 def can_trim(h):
311 # return a boolean
312 "can_zero"
314 (Optional)
315 def can_zero(h):
317 # return a boolean
318 "can_fast_zero"
320 (Optional)
321 def can_fast_zero(h):
323 # return a boolean
324 "can_fua"
326 (Optional)
327 def can_fua(h):
329 # return nbdkit.FUA_NONE or nbdkit.FUA_EMULATE
330 # or nbdkit.FUA_NATIVE
331 "can_cache"
333 (Optional)
334 def can_cache(h):
336 # return nbdkit.CACHE_NONE or nbdkit.CACHE_EMULATE
337 # or nbdkit.CACHE_NATIVE
338 "can_extents"
340 (Optional)
341 def can_extents(h):
343 # return a boolean
344 "pread"
346 (Required)
347 def pread(h, buf, offset, flags):
349 # read into the buffer
350 The body of your "pread" function should read exactly len(buf)
352 bytes of data starting at disk "offset" and write it into the
353 buffer "buf". "flags" is always 0.
354 NBD only supports whole reads, so your function should try to read
356 the whole region (perhaps requiring a loop). If the read fails or
357 is partial, your function should throw an exception, optionally
358 using "nbdkit.set_error" first.
359 "pwrite"
361 (Optional)
362 def pwrite(h, buf, offset, flags):
364 length = len(buf)
365 # no return value
366 The body of your "pwrite" function should write the buffer "buf" to
368 the disk. You should write "count" bytes to the disk starting at
369 "offset". "flags" may contain "nbdkit.FLAG_FUA".
370 NBD only supports whole writes, so your function should try to
372 write the whole region (perhaps requiring a loop). If the write
373 fails or is partial, your function should throw an exception,
374 optionally using "nbdkit.set_error" first.
375 "flush"
377 (Optional)
378 def flush(h, flags):
380 # no return value
381 The body of your "flush" function should do a sync(2) or
383 fdatasync(2) or equivalent on the backing store. "flags" is always
384 0.
385 If the flush fails, your function should throw an exception,
387 optionally using "nbdkit.set_error" first.
388 "trim"
390 (Optional)
391 def trim(h, count, offset, flags):
393 # no return value
394 The body of your "trim" function should "punch a hole" in the
396 backing store. "flags" may contain "nbdkit.FLAG_FUA". If the trim
397 fails, your function should throw an exception, optionally using
398 "nbdkit.set_error" first.
399 "zero"
401 (Optional)
402 def zero(h, count, offset, flags):
404 # no return value
405 The body of your "zero" function should ensure that "count" bytes
407 of the disk, starting at "offset", will read back as zero. "flags"
408 is a bitmask which may include "nbdkit.FLAG_MAY_TRIM",
409 "nbdkit.FLAG_FUA", "nbdkit.FLAG_FAST_ZERO".
410 NBD only supports whole writes, so your function should try to
412 write the whole region (perhaps requiring a loop).
413 If the write fails or is partial, your function should throw an
415 exception, optionally using "nbdkit.set_error" first. In
416 particular, if you would like to automatically fall back to
417 "pwrite" (perhaps because there is nothing to optimize if
418 "flags & nbdkit.FLAG_MAY_TRIM" is false), use
419 "nbdkit.set_error(errno.EOPNOTSUPP)".
420 "cache"
422 (Optional)
423 def cache(h, count, offset, flags):
425 # no return value
426 The body of your "cache" function should prefetch data in the
428 indicated range.
429 If the cache operation fails, your function should throw an
431 exception, optionally using "nbdkit.set_error" first.
432 "extents"
434 (Optional)
435 def extents(h, count, offset, flags):
437 # return an iterable object (eg. list) of
438 # (offset, length, type) tuples:
439 return [ (off1, len1, type1), (off2, len2, type2), ... ]
440 Missing callbacks
442 Missing: "load"
443 This is not needed since you can use regular Python mechanisms like
444 top level statements to run code when the module is loaded.
445 Missing: "unload"
447 This is missing, but in nbdkit ≥ 1.28 you can put code in the
448 cleanup() function to have it run when nbdkit exits. In earlier
449 versions of nbdkit, using a Python atexit handler is recommended.
450 Missing: "name", "version", "longname", "description", "config_help",
452 "magic_config_key".
453 These are not yet supported.
454
456 $plugindir/nbdkit-python-plugin.so
457 The plugin.
458 Use "nbdkit --dump-config" to find the location of $plugindir.
460
462 "nbdkit-python-plugin" first appeared in nbdkit 1.2.
463
465 nbdkit(1), nbdkit-plugin(3), python(1).
466
468 Eric Blake
469 Richard W.M. Jones
471 Nir Soffer
473
475 Copyright Red Hat
476
478 Redistribution and use in source and binary forms, with or without
479 modification, are permitted provided that the following conditions are
480 met:
481 • Redistributions of source code must retain the above copyright
483 notice, this list of conditions and the following disclaimer.
484 • Redistributions in binary form must reproduce the above copyright
486 notice, this list of conditions and the following disclaimer in the
487 documentation and/or other materials provided with the
488 distribution.
489 • Neither the name of Red Hat nor the names of its contributors may
491 be used to endorse or promote products derived from this software
492 without specific prior written permission.
493 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
495 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
496 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
497 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
498 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
499 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
500 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
501 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
502 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
503 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
504 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
505nbdkit-1.34.4 2023-09-26 nbdkit-python-plugin(3)