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.
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://github.com/libguestfs/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 In nbdkit ≤ 1.14, either Python 2 or 3 could be used. It was selected
51 at compile time by either:
52 ./configure
54 which selected the version of Python by looking at the "python"
56 interpreter found on the $PATH. Or:
57 ./configure PYTHON=/usr/bin/python3
59 which allowed you to select a different interpreter and hence a
61 different version of Python.
62 nbdkit ≥ 1.16 drops all support for Python 2, since Python 2 has
64 reached its end of life.
65 The new behaviour is that "./configure" looks for "python3" or "python"
67 (in that order) on the $PATH. It will fail if the first interpreter it
68 finds is a Python 2 interpreter. You may also still choose a Python
69 interpreter by setting the "PYTHON" variable at configure time as
70 above.
71 If you wish to continue using nbdkit plugins written in Python 2 then
73 you must use nbdkit ≤ 1.14, but we would advise you to update your
74 plugins.
75 To find out which version the Python plugin was compiled for, use the
77 --dump-plugin option, eg:
78 $ nbdkit python --dump-plugin
80 ...
81 python_version=3.7.0
82 python_pep_384_abi_version=3
83 API versions
85 The nbdkit API has evolved and new versions are released periodically.
86 To ensure backwards compatibility plugins have to opt in to the new
87 version. From Python you do this by declaring a constant in your
88 module:
89 API_VERSION = 2
91 (where 2 is the latest version at the time this documentation was
93 written). All newly written Python modules must have this constant.
94 Executable script
96 If you want you can make the script executable and include a "shebang"
97 at the top:
98 #!/usr/sbin/nbdkit python
100 See also "Shebang scripts" in nbdkit(1).
102 These scripts can also be installed in the $plugindir. See "WRITING
104 PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
105 Module functions
107 Your script may use "import nbdkit" to have access to the following
108 methods in the "nbdkit" module:
109 "nbdkit.debug(msg)"
111 Send a debug message to stderr or syslog if verbose messages are
113 enabled.
114 "nbdkit.export_name()"
116 Return the export name negotiated with the client as a Unicode string.
118 Note this should not be trusted because the client can send whatever it
119 wants.
120 "nbdkit.set_error(err)"
122 Record "err" as the reason you are about to throw an exception. "err"
124 should correspond to usual errno values, where it may help to "import
125 errno".
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 "list_exports"
215 (Optional)
216 def list_exports(readonly, is_tls):
218 # return an iterable object (eg. list) of
219 # (name, description) tuples or bare names:
220 return [ (name1, desc1), name2, (name3, desc3), ... ]
221 "default_export"
223 (Optional)
224 def default_export(readonly, is_tls):
226 # return a string
227 return "name"
228 "open"
230 (Required)
231 def open(readonly):
233 # return handle
234 You can return any non-NULL Python value as the handle. It is
236 passed back in subsequent calls.
237 "close"
239 (Optional)
240 def close(h):
242 # no return value
243 After "close" returns, the reference count of the handle is
245 decremented in the C part, which usually means that the handle and
246 its contents will be garbage collected.
247 "export_description"
249 (Optional)
250 def export_description(h):
252 # return a string
253 return "description"
254 "get_size"
256 (Required)
257 def get_size(h):
259 # return the size of the disk
260 "is_rotational"
262 (Optional)
263 def is_rotational(h):
265 # return a boolean
266 "can_multi_conn"
268 (Optional)
269 def can_multi_conn(h):
271 # return a boolean
272 "can_write"
274 (Optional)
275 def can_write(h):
277 # return a boolean
278 "can_flush"
280 (Optional)
281 def can_flush(h):
283 # return a boolean
284 "can_trim"
286 (Optional)
287 def can_trim(h):
289 # return a boolean
290 "can_zero"
292 (Optional)
293 def can_zero(h):
295 # return a boolean
296 "can_fast_zero"
298 (Optional)
299 def can_fast_zero(h):
301 # return a boolean
302 "can_fua"
304 (Optional)
305 def can_fua(h):
307 # return nbdkit.FUA_NONE or nbdkit.FUA_EMULATE
308 # or nbdkit.FUA_NATIVE
309 "can_cache"
311 (Optional)
312 def can_cache(h):
314 # return nbdkit.CACHE_NONE or nbdkit.CACHE_EMULATE
315 # or nbdkit.CACHE_NATIVE
316 "can_extents"
318 (Optional)
319 def can_extents(h):
321 # return a boolean
322 "pread"
324 (Required)
325 def pread(h, buf, offset, flags):
327 # read into the buffer
328 The body of your "pread" function should read exactly "len(buf)"
330 bytes of data starting at disk "offset" and write it into the
331 buffer "buf". "flags" is always 0.
332 NBD only supports whole reads, so your function should try to read
334 the whole region (perhaps requiring a loop). If the read fails or
335 is partial, your function should throw an exception, optionally
336 using "nbdkit.set_error" first.
337 "pwrite"
339 (Optional)
340 def pwrite(h, buf, offset, flags):
342 length = len(buf)
343 # no return value
344 The body of your "pwrite" function should write the buffer "buf" to
346 the disk. You should write "count" bytes to the disk starting at
347 "offset". "flags" may contain "nbdkit.FLAG_FUA".
348 NBD only supports whole writes, so your function should try to
350 write the whole region (perhaps requiring a loop). If the write
351 fails or is partial, your function should throw an exception,
352 optionally using "nbdkit.set_error" first.
353 "flush"
355 (Optional)
356 def flush(h, flags):
358 # no return value
359 The body of your "flush" function should do a sync(2) or
361 fdatasync(2) or equivalent on the backing store. "flags" is always
362 0.
363 If the flush fails, your function should throw an exception,
365 optionally using "nbdkit.set_error" first.
366 "trim"
368 (Optional)
369 def trim(h, count, offset, flags):
371 # no return value
372 The body of your "trim" function should "punch a hole" in the
374 backing store. "flags" may contain "nbdkit.FLAG_FUA". If the trim
375 fails, your function should throw an exception, optionally using
376 "nbdkit.set_error" first.
377 "zero"
379 (Optional)
380 def zero(h, count, offset, flags):
382 # no return value
383 The body of your "zero" function should ensure that "count" bytes
385 of the disk, starting at "offset", will read back as zero. "flags"
386 is a bitmask which may include "nbdkit.FLAG_MAY_TRIM",
387 "nbdkit.FLAG_FUA", "nbdkit.FLAG_FAST_ZERO".
388 NBD only supports whole writes, so your function should try to
390 write the whole region (perhaps requiring a loop).
391 If the write fails or is partial, your function should throw an
393 exception, optionally using "nbdkit.set_error" first. In
394 particular, if you would like to automatically fall back to
395 "pwrite" (perhaps because there is nothing to optimize if
396 "flags & nbdkit.FLAG_MAY_TRIM" is false), use
397 "nbdkit.set_error(errno.EOPNOTSUPP)".
398 "cache"
400 (Optional)
401 def cache(h, count, offset, flags):
403 # no return value
404 The body of your "cache" function should prefetch data in the
406 indicated range.
407 If the cache operation fails, your function should throw an
409 exception, optionally using "nbdkit.set_error" first.
410 "extents"
412 (Optional)
413 def extents(h, count, offset, flags):
415 # return an iterable object (eg. list) of
416 # (offset, length, type) tuples:
417 return [ (off1, len1, type1), (off2, len2, type2), ... ]
418 Missing callbacks
420 Missing: "load" and "unload"
421 These are not needed because you can just use ordinary Python
422 constructs.
423 Missing: "name", "version", "longname", "description", "config_help",
425 "magic_config_key".
426 These are not yet supported.
427
429 $plugindir/nbdkit-python-plugin.so
430 The plugin.
431 Use "nbdkit --dump-config" to find the location of $plugindir.
433
435 "nbdkit-python-plugin" first appeared in nbdkit 1.2.
436
438 nbdkit(1), nbdkit-plugin(3), python(1).
439
441 Eric Blake
442 Richard W.M. Jones
444 Nir Soffer
446
448 Copyright (C) 2013-2020 Red Hat Inc.
449
451 Redistribution and use in source and binary forms, with or without
452 modification, are permitted provided that the following conditions are
453 met:
454 · Redistributions of source code must retain the above copyright
456 notice, this list of conditions and the following disclaimer.
457 · Redistributions in binary form must reproduce the above copyright
459 notice, this list of conditions and the following disclaimer in the
460 documentation and/or other materials provided with the
461 distribution.
462 · Neither the name of Red Hat nor the names of its contributors may
464 be used to endorse or promote products derived from this software
465 without specific prior written permission.
466 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
468 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
469 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
470 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
471 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
472 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
473 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
474 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
475 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
476 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
477 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
478nbdkit-1.24.2 2021-03-02 nbdkit-python-plugin(3)