1nbdkit-plugin(3) NBDKIT nbdkit-plugin(3)
2
6 nbdkit-plugin - how to write nbdkit plugins
7
9 #define NBDKIT_API_VERSION 2
10 #include <nbdkit-plugin.h>
12 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
14 static void *
16 myplugin_open (void)
17 {
18 /* create a handle ... */
19 return handle;
20 }
21 static struct nbdkit_plugin plugin = {
23 .name = "myplugin",
24 .open = myplugin_open,
25 .get_size = myplugin_get_size,
26 .pread = myplugin_pread,
27 .pwrite = myplugin_pwrite,
28 /* etc */
29 };
30 NBDKIT_REGISTER_PLUGIN(plugin)
32 When this has been compiled to a shared library, do:
34 nbdkit [--args ...] ./myplugin.so [key=value ...]
36 When debugging, use the -fv options:
38 nbdkit -fv ./myplugin.so [key=value ...]
40
42 An nbdkit plugin is a new source device which can be served using the
43 Network Block Device (NBD) protocol. This manual page describes how to
44 create an nbdkit plugin in C.
45 To see example plugins:
47 https://github.com/libguestfs/nbdkit/tree/master/plugins
48 Plugins written in C have an ABI guarantee: a plugin compiled against
50 an older version of nbdkit will still work correctly when loaded with a
51 newer nbdkit. We also try (but cannot guarantee) to support plugins
52 compiled against a newer version of nbdkit when loaded with an older
53 nbdkit, although the plugin may have reduced functionality if it
54 depends on features only provided by newer nbdkit.
55 For plugins written in C, we also provide an API guarantee: a plugin
57 written against an older header will still compile unmodified with a
58 newer nbdkit.
59 The API guarantee does not always apply to plugins written in other
61 (non-C) languages which may have to adapt to changes when recompiled
62 against a newer nbdkit.
63 To write plugins in other languages, see: nbdkit-lua-plugin(3),
65 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
66 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
67 nbdkit-tcl-plugin(3) .
68
70 Plugins must choose which API version they want to use, by defining
71 NBDKIT_API_VERSION to a positive integer prior to including
72 "nbdkit-plugin.h" (or any other nbdkit header). The default version is
73 1 for backwards-compatibility with nbdkit v1.1.26 and earlier; however,
74 it is recommended that new plugins be written to the maximum version
75 (currently 2) as it enables more features and better interaction with
76 nbdkit filters. Therefore, the rest of this document only covers the
77 version 2 interface. A newer nbdkit will always support plugins
78 written in C which were compiled against any prior API version.
79
81 All plugins should start by including this header file, after
82 optionally choosing an API version.
83
85 All plugins must define a thread model. See "THREADS" below for
86 details. It is generally safe to use:
87 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
89
91 All plugins must define and register one "struct nbdkit_plugin", which
92 contains the name of the plugin and pointers to callback functions.
93 static struct nbdkit_plugin plugin = {
95 .name = "myplugin",
96 .longname = "My Plugin",
97 .description = "This is my great plugin for nbdkit",
98 .open = myplugin_open,
99 .get_size = myplugin_get_size,
100 .pread = myplugin_pread,
101 .pwrite = myplugin_pwrite,
102 /* etc */
103 };
104 NBDKIT_REGISTER_PLUGIN(plugin)
106 The ".name" field is the name of the plugin.
108 The callbacks are described below (see "CALLBACKS"). Only ".name",
110 ".open", ".get_size" and ".pread" are required. All other callbacks
111 can be omitted. However almost all plugins should have a ".close"
112 callback. Most real-world plugins will also want to declare some of
113 the other callbacks.
114 The nbdkit server calls the callbacks in the following order over the
116 lifetime of the plugin:
117 ".load"
119 is called once just after the plugin is loaded into memory.
120 ".config" and ".config_complete"
122 ".config" is called zero or more times during command line parsing.
123 ".config_complete" is called once after all configuration
124 information has been passed to the plugin.
125 Both are called after loading the plugin but before any connections
127 are accepted.
128 ".open"
130 A new client has connected.
131 ".can_write", ".get_size" and other option negotiation callbacks
133 These are called during option negotiation with the client, but
134 before any data is served. These callbacks may return different
135 values across different ".open" calls, but within a single
136 connection, must always return the same value; other code in nbdkit
137 may cache the per-connection value returned rather than using the
138 callback a second time.
139 ".pread", ".pwrite" and other data serving callbacks
141 After option negotiation has finished, these may be called to serve
142 data. Depending on the thread model chosen, they might be called
143 in parallel from multiple threads. The data serving callbacks
144 include a flags argument; the results of the negotiation callbacks
145 influence whether particular flags will ever be passed to a data
146 callback.
147 ".close"
149 The client has disconnected.
150 ".open" ... ".close"
152 The sequence ".open" ... ".close" can be called repeatedly over the
153 lifetime of the plugin, and can be called in parallel (depending on
154 the thread model).
155 ".unload"
157 is called once just before the plugin is unloaded from memory.
158
160 The following flags are defined by nbdkit, and used in various data
161 serving callbacks as follows:
162 "NBDKIT_FLAG_MAY_TRIM"
164 This flag is used by the ".zero" callback; there is no way to
165 disable this flag, although a plugin that does not support trims as
166 a way to write zeroes may ignore the flag without violating
167 expected semantics.
168 "NBDKIT_FLAG_FUA"
170 This flag represents Forced Unit Access semantics. It is used by
171 the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
172 plugin must not return a result until the action has landed in
173 persistent storage. This flag will not be sent to the plugin
174 unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
175 The following defines are valid as successful return values for
177 ".can_fua":
178 "NBDKIT_FUA_NONE"
180 Forced Unit Access is not supported; the client must manually
181 request a flush after writes have completed. The "NBDKIT_FLAG_FUA"
182 flag will not be passed to the plugin's write callbacks.
183 "NBDKIT_FUA_EMULATE"
185 The client may request Forced Unit Access, but it is implemented by
186 emulation, where nbdkit calls ".flush" after a write operation;
187 this is semantically correct, but may hurt performance as it tends
188 to flush more data than just what the client requested. The
189 "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
190 callbacks.
191 "NBDKIT_FUA_NATIVE"
193 The client may request Forced Unit Access, which results in the
194 "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
195 (".pwrite", ".trim", and ".zero"). When the flag is set, these
196 callbacks must not return success until the client's request has
197 landed in persistent storage.
198
200 If there is an error in the plugin, the plugin should call
201 "nbdkit_error" to report an error message; additionally, if the
202 callback is involved in serving data, the plugin should call
203 "nbdkit_set_error" to influence the error code that will be sent to the
204 client. These two functions can be called in either order. Then, the
205 callback should return the appropriate error indication, eg. "NULL" or
206 "-1".
207 If the call to "nbdkit_set_error" is omitted while serving data, then
209 the global variable "errno" may be used. For plugins which have
210 ".errno_is_preserved == 1" the core code will use "errno". In plugins
211 written in non-C languages, we usually cannot trust that "errno" will
212 not be overwritten when returning from that language to C. In that
213 case, either the plugin must call "nbdkit_set_error" or hard-coded
214 "EIO" is used.
215 "nbdkit_error" has the following prototype and works like printf(3):
217 void nbdkit_error (const char *fs, ...);
219 void nbdkit_verror (const char *fs, va_list args);
220 For convenience, "nbdkit_error" preserves the value of "errno", and
222 also supports the glibc extension of a single %m in a format string
223 expanding to "strerror(errno)", even on platforms that don't support
224 that natively.
225 "nbdkit_set_error" can be called at any time, but only has an impact
227 during callbacks for serving data, and only when the callback returns
228 an indication of failure. It has the following prototype:
229 void nbdkit_set_error (int err);
231
233 The server usually (not always) changes directory to "/" before it
234 starts serving connections. This means that any relative paths passed
235 during configuration will not work when the server is running (example:
236 "nbdkit plugin.so disk.img").
237 To avoid problems, prepend relative paths with the current directory
239 before storing them in the handle. Or open files and store the file
240 descriptor.
241 "nbdkit_absolute_path"
243 char *nbdkit_absolute_path (const char *filename);
244 The utility function "nbdkit_absolute_path" converts any path to an
246 absolute path: if it is relative, then all this function does is
247 prepend the current working directory to the path, with no extra
248 checks.
249 Note that this function works only when used in the ".config", and
251 ".config_complete" callbacks.
252 If conversion was not possible, this calls "nbdkit_error" and returns
254 "NULL". Note that this function does not check that the file exists.
255 The returned string must be freed by the caller.
257 "nbdkit_realpath"
259 char *nbdkit_realpath (const char *filename);
260 The utility function "nbdkit_realpath" converts any path to an absolute
262 path, resolving symlinks. Under the hood it uses the "realpath"
263 function, and thus it fails if the path does not exist, or it is not
264 possible to access to any of the components of the path.
265 Note that this function works only when used in the ".config", and
267 ".config_complete" callbacks.
268 If the path resolution was not possible, this calls "nbdkit_error" and
270 returns "NULL".
271 The returned string must be freed by the caller.
273 umask
275 All plugins will see a umask(2) of 0022.
276
278 ".name"
279 const char *name;
280 This field (a string) is required, and must contain only ASCII
282 alphanumeric characters and be unique amongst all plugins.
283 ".version"
285 const char *version;
286 Plugins may optionally set a version string which is displayed in help
288 and debugging output.
289 ".longname"
291 const char *longname;
292 An optional free text name of the plugin. This field is used in error
294 messages.
295 ".description"
297 const char *description;
298 An optional multi-line description of the plugin.
300 ".load"
302 void load (void);
303 This is called once just after the plugin is loaded into memory. You
305 can use this to perform any global initialization needed by the plugin.
306 ".unload"
308 void unload (void);
309 This may be called once just before the plugin is unloaded from memory.
311 Note that it's not guaranteed that ".unload" will always be called (eg.
312 the server might be killed or segfault), so you should try to make the
313 plugin as robust as possible by not requiring cleanup. See also
314 "SHUTDOWN" below.
315 ".dump_plugin"
317 void dump_plugin (void);
318 This optional callback is called when the "nbdkit plugin --dump-plugin"
320 command is used. It should print any additional informative
321 "key=value" fields to stdout as needed. Prefixing the keys with the
322 name of the plugin will avoid conflicts.
323 ".config"
325 int config (const char *key, const char *value);
326 On the nbdkit command line, after the plugin filename, come an optional
328 list of "key=value" arguments. These are passed to the plugin through
329 this callback when the plugin is first loaded and before any
330 connections are accepted.
331 This callback may be called zero or more times.
333 Both "key" and "value" parameters will be non-NULL. The strings are
335 owned by nbdkit but will remain valid for the lifetime of the plugin,
336 so the plugin does not need to copy them.
337 The key will be a non-empty string beginning with an ASCII alphabetic
339 character ("A-Z" "a-z"). The rest of the key must contain only ASCII
340 alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
341 "0-9" "." "_" "-"). The value may be an arbitrary string, including an
342 empty string.
343 The names of "key"s accepted by plugins is up to the plugin, but you
345 should probably look at other plugins and follow the same conventions.
346 If the value is a relative path, then note that the server changes
348 directory when it starts up. See "FILENAMES AND PATHS" above.
349 If the ".config" callback is not provided by the plugin, and the user
351 tries to specify any "key=value" arguments, then nbdkit will exit with
352 an error.
353 If there is an error, ".config" should call "nbdkit_error" with an
355 error message and return "-1".
356 ".magic_config_key"
358 const char *magic_config_key;
359 This optional string can be used to set a "magic" key used when parsing
361 plugin parameters. It affects how "bare parameters" (those which do
362 not contain an "=" character) are parsed on the command line.
363 If "magic_config_key != NULL" then any bare parameters are passed to
365 the ".config" method as: "config (magic_config_key, argv[i]);".
366 If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
368 the first parameter on the command line is bare then it is passed to
369 the ".config" method as: "config ("script", value);". Any other bare
370 parameters give errors.
371 ".config_complete"
373 int config_complete (void);
374 This optional callback is called after all the configuration has been
376 passed to the plugin. It is a good place to do checks, for example
377 that the user has passed the required parameters to the plugin.
378 If there is an error, ".config_complete" should call "nbdkit_error"
380 with an error message and return "-1".
381 ".config_help"
383 const char *config_help;
384 This optional multi-line help message should summarize any "key=value"
386 parameters that it takes. It does not need to repeat what already
387 appears in ".description".
388 If the plugin doesn't take any config parameters you should probably
390 omit this.
391 ".open"
393 void *open (int readonly);
394 This is called when a new client connects to the nbdkit server. The
396 callback should allocate a handle and return it. This handle is passed
397 back to other callbacks and could be freed in the ".close" callback.
398 Note that the handle is completely opaque to nbdkit, but it must not be
400 NULL. If you don't need to use a handle, return
401 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
402 The "readonly" flag informs the plugin that the user requested a read-
404 only connection using the -r flag on the command line. Note that the
405 plugin may additionally force the connection to be readonly (even if
406 this flag is false) by returning false from the ".can_write" callback.
407 So if your plugin can only serve read-only, you can ignore this
408 parameter.
409 If there is an error, ".open" should call "nbdkit_error" with an error
411 message and return "NULL".
412 ".close"
414 void close (void *handle);
415 This is called when the client closes the connection. It should clean
417 up any per-connection resources.
418 Note there is no way in the NBD protocol to communicate close errors
420 back to the client, for example if your plugin calls close(2) and you
421 are checking for errors (as you should do). Therefore the best you can
422 do is to log the error on the server. Well-behaved NBD clients should
423 try to flush the connection before it is closed and check for errors,
424 but obviously this is outside the scope of nbdkit.
425 ".get_size"
427 int64_t get_size (void *handle);
428 This is called during the option negotiation phase of the protocol to
430 get the size (in bytes) of the block device being exported.
431 The returned size must be ≥ 0. If there is an error, ".get_size"
433 should call "nbdkit_error" with an error message and return "-1".
434 ".can_write"
436 int can_write (void *handle);
437 This is called during the option negotiation phase to find out if the
439 handle supports writes.
440 If there is an error, ".can_write" should call "nbdkit_error" with an
442 error message and return "-1".
443 This callback is not required. If omitted, then we return true iff a
445 ".pwrite" callback has been defined.
446 ".can_flush"
448 int can_flush (void *handle);
449 This is called during the option negotiation phase to find out if the
451 handle supports the flush-to-disk operation.
452 If there is an error, ".can_flush" should call "nbdkit_error" with an
454 error message and return "-1".
455 This callback is not required. If omitted, then we return true iff a
457 ".flush" callback has been defined.
458 ".is_rotational"
460 int is_rotational (void *handle);
461 This is called during the option negotiation phase to find out if the
463 backing disk is a rotational medium (like a traditional hard disk) or
464 not (like an SSD). If true, this may cause the client to reorder
465 requests to make them more efficient for a slow rotating disk.
466 If there is an error, ".is_rotational" should call "nbdkit_error" with
468 an error message and return "-1".
469 This callback is not required. If omitted, then we return false.
471 ".can_trim"
473 int can_trim (void *handle);
474 This is called during the option negotiation phase to find out if the
476 plugin supports the trim/discard operation for punching holes in the
477 backing storage.
478 If there is an error, ".can_trim" should call "nbdkit_error" with an
480 error message and return "-1".
481 This callback is not required. If omitted, then we return true iff a
483 ".trim" callback has been defined.
484 ".can_zero"
486 int can_zero (void *handle);
487 This is called during the option negotiation phase to find out if the
489 plugin wants the ".zero" callback to be utilized. Support for writing
490 zeroes is still advertised to the client (unless the nbdkit filter
491 nozero is also used), so returning false merely serves as a way to
492 avoid complicating the ".zero" callback to have to fail with
493 "EOPNOTSUPP" on the connections where it will never be more efficient
494 than using ".pwrite" up front.
495 If there is an error, ".can_zero" should call "nbdkit_error" with an
497 error message and return "-1".
498 This callback is not required. If omitted, then nbdkit always tries
500 ".zero" first if it is present, and gracefully falls back to ".pwrite"
501 if ".zero" was absent or failed with "EOPNOTSUPP".
502 ".can_extents"
504 int can_extents (void *handle);
505 This is called during the option negotiation phase to find out if the
507 plugin supports detecting allocated (non-sparse) regions of the disk
508 with the ".extents" callback.
509 If there is an error, ".can_extents" should call "nbdkit_error" with an
511 error message and return "-1".
512 This callback is not required. If omitted, then we return true iff a
514 ".extents" callback has been defined.
515 ".can_fua"
517 int can_fua (void *handle);
518 This is called during the option negotiation phase to find out if the
520 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
521 trim requests. If this returns "NBDKIT_FUA_NONE", FUA support is not
522 advertised to the guest; if this returns "NBDKIT_FUA_EMULATE", the
523 ".flush" callback must work (even if ".can_flush" returns false), and
524 FUA support is emulated by calling ".flush" after any write operation;
525 if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
526 ".trim" callbacks (if implemented) must handle the flag
527 "NBDKIT_FLAG_FUA", by not returning until that action has landed in
528 persistent storage.
529 If there is an error, ".can_fua" should call "nbdkit_error" with an
531 error message and return "-1".
532 This callback is not required unless a plugin wants to specifically
534 handle FUA requests. If omitted, nbdkit checks whether ".flush"
535 exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
536 "NBDKIT_FUA_EMULATE" as appropriate.
537 ".can_multi_conn"
539 int can_multi_conn (void *handle);
540 This is called during the option negotiation phase to find out if the
542 plugin is prepared to handle multiple connections from a single client.
543 If the plugin sets this to true then a client may try to open multiple
544 connections to the nbdkit server and spread requests across all
545 connections to maximize parallelism. If the plugin sets it to false
546 (which is the default) then well-behaved clients should only open a
547 single connection, although we cannot control what clients do in
548 practice.
549 Specifically it means that either the plugin does not cache requests at
551 all. Or if it does cache them then the effects of a ".flush" request
552 or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
553 connections to the plugin before the plugin replies to that request.
554 If you use Linux nbd-client(8) option -C num with num > 1 then Linux
556 checks this flag and will refuse to connect if ".can_multi_conn" is
557 false.
558 If there is an error, ".can_multi_conn" should call "nbdkit_error" with
560 an error message and return "-1".
561 This callback is not required. If omitted, then we return false.
563 ".pread"
565 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
566 uint32_t flags);
567 During the data serving phase, nbdkit calls this callback to read data
569 from the backing store. "count" bytes starting at "offset" in the
570 backing store should be read and copied into "buf". nbdkit takes care
571 of all bounds- and sanity-checking, so the plugin does not need to
572 worry about that.
573 The parameter "flags" exists in case of future NBD protocol extensions;
575 at this time, it will be 0 on input.
576 The callback must read the whole "count" bytes if it can. The NBD
578 protocol doesn't allow partial reads (instead, these would be errors).
579 If the whole "count" bytes was read, the callback should return 0 to
580 indicate there was no error.
581 If there is an error (including a short read which couldn't be
583 recovered from), ".pread" should call "nbdkit_error" with an error
584 message, and "nbdkit_set_error" to record an appropriate error (unless
585 "errno" is sufficient), then return "-1".
586 ".pwrite"
588 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
589 uint32_t flags);
590 During the data serving phase, nbdkit calls this callback to write data
592 to the backing store. "count" bytes starting at "offset" in the
593 backing store should be written using the data in "buf". nbdkit takes
594 care of all bounds- and sanity-checking, so the plugin does not need to
595 worry about that.
596 This function will not be called if ".can_write" returned false. The
598 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
599 result of ".can_fua".
600 The callback must write the whole "count" bytes if it can. The NBD
602 protocol doesn't allow partial writes (instead, these would be errors).
603 If the whole "count" bytes was written successfully, the callback
604 should return 0 to indicate there was no error.
605 If there is an error (including a short write which couldn't be
607 recovered from), ".pwrite" should call "nbdkit_error" with an error
608 message, and "nbdkit_set_error" to record an appropriate error (unless
609 "errno" is sufficient), then return "-1".
610 ".flush"
612 int flush (void *handle, uint32_t flags);
613 During the data serving phase, this callback is used to fdatasync(2)
615 the backing store, ie. to ensure it has been completely written to a
616 permanent medium. If that is not possible then you can omit this
617 callback.
618 This function will not be called directly by the client if ".can_flush"
620 returned false; however, it may still be called by nbdkit if ".can_fua"
621 returned "NBDKIT_FUA_EMULATE". The parameter "flags" exists in case of
622 future NBD protocol extensions; at this time, it will be 0 on input.
623 If there is an error, ".flush" should call "nbdkit_error" with an error
625 message, and "nbdkit_set_error" to record an appropriate error (unless
626 "errno" is sufficient), then return "-1".
627 ".trim"
629 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
630 During the data serving phase, this callback is used to "punch holes"
632 in the backing store. If that is not possible then you can omit this
633 callback.
634 This function will not be called if ".can_trim" returned false. The
636 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
637 result of ".can_fua".
638 If there is an error, ".trim" should call "nbdkit_error" with an error
640 message, and "nbdkit_set_error" to record an appropriate error (unless
641 "errno" is sufficient), then return "-1".
642 ".zero"
644 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
645 During the data serving phase, this callback is used to write "count"
647 bytes of zeroes at "offset" in the backing store.
648 This function will not be called if ".can_zero" returned false. On
650 input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
651 unconditionally, and "NBDKIT_FLAG_FUA" based on the result of
652 ".can_fua".
653 If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
655 instead of writing actual zero bytes, but only if subsequent reads from
656 the hole read as zeroes. If this callback is omitted, or if it fails
657 with "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then
658 ".pwrite" will be used instead.
659 The callback must write the whole "count" bytes if it can. The NBD
661 protocol doesn't allow partial writes (instead, these would be errors).
662 If the whole "count" bytes was written successfully, the callback
663 should return 0 to indicate there was no error.
664 If there is an error, ".zero" should call "nbdkit_error" with an error
666 message, and "nbdkit_set_error" to record an appropriate error (unless
667 "errno" is sufficient), then return "-1".
668 ".extents"
670 int extents (void *handle, uint32_t count, uint64_t offset,
671 uint32_t flags, struct nbdkit_extents *extents);
672 During the data serving phase, this callback is used to detect
674 allocated, sparse and zeroed regions of the disk.
675 This function will not be called if ".can_extents" returned false.
677 nbdkit's default behaviour in this case is to treat the whole virtual
678 disk as if it was allocated.
679 The callback should detect and return the list of extents overlapping
681 the range "[offset...offset+count-1]". The "extents" parameter points
682 to an opaque object which the callback should fill in by calling
683 "nbdkit_add_extent". See "Extents list" below.
684 If there is an error, ".extents" should call "nbdkit_error" with an
686 error message, and "nbdkit_set_error" to record an appropriate error
687 (unless "errno" is sufficient), then return "-1".
688 Extents list
690 The plugin "extents" callback is passed an opaque pointer "struct
692 nbdkit_extents *extents". This structure represents a list of
693 filesystem extents describing which areas of the disk are allocated,
694 which are sparse (“holes”), and, if supported, which are zeroes.
695 The "extents" callback should scan the disk starting at "offset" and
697 call "nbdkit_add_extent" for each extent found.
698 Extents overlapping the range "[offset...offset+count-1]" should be
700 returned if possible. However nbdkit ignores extents < offset so the
701 plugin may, if it is easier to implement, return all extent information
702 for the whole disk. The plugin may return extents beyond the end of
703 the range. It may also return extent information for less than the
704 whole range, but it must return at least one extent overlapping
705 "offset".
706 The extents must be added in ascending order, and must be contiguous.
708 The "flags" parameter of the ".extents" callback may contain the flag
710 "NBDKIT_FLAG_REQ_ONE". This means that the client is only requesting
711 information about the extent overlapping "offset". The plugin may
712 ignore this flag, or as an optimization it may return just a single
713 extent for "offset".
714 int nbdkit_add_extent (struct nbdkit_extents *extents,
716 uint64_t offset, uint64_t length, uint32_t type);
717 Add an extent covering "[offset...offset+length-1]" of one of the
719 following four types:
720 "type = 0"
722 A normal, allocated data extent.
723 "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
725 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
726 This is the normal type of hole applicable to most disks.
727 "type = NBDKIT_EXTENT_ZERO"
729 An allocated extent which is known to contain only zeroes.
730 "type = NBDKIT_EXTENT_HOLE"
732 An unallocated extent (hole) which does not read back as zeroes.
733 Note this should only be used in specialized circumstances such as
734 when writing a plugin for (or to emulate) certain SCSI drives which
735 do not guarantee that trimmed blocks read back as zeroes.
736 "nbdkit_extent_add" returns 0 on success or "-1" on failure. On
738 failure "nbdkit_error" and/or "nbdkit_set_error" has already been
739 called. "errno" will be set to a suitable value.
740
742 Each nbdkit plugin must declare its thread safety model by defining the
743 "THREAD_MODEL" macro. (This macro is used by
744 "NBDKIT_REGISTER_PLUGIN").
745 The possible settings for "THREAD_MODEL" are defined below.
747 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
749 Only a single handle can be open at any time, and all requests
750 happen from one thread.
751 Note this means only one client can connect to the server at any
753 time. If a second client tries to connect it will block waiting
754 for the first client to close the connection.
755 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
757 This is a safe default for most plugins.
758 Multiple handles can be open at the same time, but requests are
760 serialized so that for the plugin as a whole only one
761 open/read/write/close (etc) request will be in progress at any
762 time.
763 This is a useful setting if the library you are using is not
765 thread-safe. However performance may not be good.
766 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
768 Multiple handles can be open and multiple data requests can happen
769 in parallel. However only one request will happen per handle at a
770 time (but requests on different handles might happen concurrently).
771 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
773 Multiple handles can be open and multiple data requests can happen
774 in parallel (even on the same handle).
775 All the libraries you use must be thread-safe and reentrant. You
777 may also need to provide mutexes for fields in your connection
778 handle.
779 If none of the above thread models are suitable, then use
781 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
782 "pthread_mutex_t" etc.
783
785 When nbdkit receives certain signals it will shut down (see "SIGNALS"
786 in nbdkit(1)). The server will wait for any currently running plugin
787 callbacks to finish and also call the ".unload" callback before
788 unloading the plugin.
789 Note that it's not guaranteed this can always happen (eg. the server
791 might be killed by "SIGKILL" or segfault).
792
794 Use the "nbdkit_parse_size" utility function to parse human-readable
795 size strings such as "100M" into the size in bytes.
796 int64_t nbdkit_parse_size (const char *str);
798 "str" can be a string in a number of common formats. The function
800 returns the size in bytes. If there was an error, it returns "-1".
801
803 Use the "nbdkit_parse_bool" utility function to parse human-readable
804 strings such as "on" into a boolean value.
805 int nbdkit_parse_bool (const char *str);
807 "str" can be a string containing a case-insensitive form of various
809 common toggle values. The function returns 0 or 1 if the parse was
810 successful. If there was an error, it returns "-1".
811
813 The "nbdkit_read_password" utility function can be used to read
814 passwords from config parameters:
815 int nbdkit_read_password (const char *value, char **password);
817 For example:
819 char *password = NULL;
821 static int
823 myplugin_config (const char *key, const char *value)
824 {
825 ..
826 if (strcmp (key, "password") == 0) {
827 free (password);
828 if (nbdkit_read_password (value, &password) == -1)
829 return -1;
830 }
831 ..
832 }
833 The "password" result string is allocated by malloc, and so you may
835 need to free it.
836 This function recognizes several password formats. A password may be
838 used directly on the command line, eg:
839 nbdkit myplugin password=mostsecret
841 But more securely this function can also read a password interactively:
843 nbdkit myplugin password=-
845 or from a file:
847 nbdkit myplugin password=+/tmp/secret
849 (If the password begins with a "-" or "+" character then it must be
851 passed in a file).
852
854 Run the server with -f and -v options so it doesn't fork and you can
855 see debugging information:
856 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
858 To print debugging information from within the plugin, call
860 "nbdkit_debug", which has the following prototype and works like
861 printf(3):
862 void nbdkit_debug (const char *fs, ...);
864 void nbdkit_vdebug (const char *fs, va_list args);
865 For convenience, "nbdkit_debug" preserves the value of "errno", and
867 also supports the glibc extension of a single %m in a format string
868 expanding to "strerror(errno)", even on platforms that don't support
869 that natively. Note that "nbdkit_debug" only prints things when the
870 server is in verbose mode (-v option).
871 Debug Flags
873 The -v option switches general debugging on or off, and this debugging
874 should be used for messages which are useful for all users of your
875 plugin.
876 In cases where you want to enable specific extra debugging to track
878 down bugs in plugins or filters — mainly for use by the plugin/filter
879 developers themselves — you can define Debug Flags. These are global
880 ints called "myplugin_debug_*":
881 int myplugin_debug_foo;
883 int myplugin_debug_bar;
884 ...
885 if (myplugin_debug_foo) {
886 nbdkit_debug ("lots of extra debugging about foo: ...");
887 }
888 Debug Flags can be controlled on the command line using the -D (or
890 --debug) option:
891 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
893 Note "myplugin" is the name passed to ".name" in the "struct
895 nbdkit_plugin".
896 You should only use this feature for debug settings. For general
898 settings use ordinary plugin parameters. Debug Flags can only be C
899 ints. They are not supported by non-C language plugins.
900
902 The plugin is a "*.so" file and possibly a manual page. You can of
903 course install the plugin "*.so" file wherever you want, and users will
904 be able to use it by running:
905 nbdkit /path/to/plugin.so [args]
907 However if the shared library has a name of the form
909 "nbdkit-name-plugin.so" and if the library is installed in the
910 $plugindir directory, then users can be run it by only typing:
911 nbdkit name [args]
913 The location of the $plugindir directory is set when nbdkit is compiled
915 and can be found by doing:
916 nbdkit --dump-config
918 If using the pkg-config/pkgconf system then you can also find the
920 plugin directory at compile time by doing:
921 pkgconf nbdkit --variable=plugindir
923
925 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
926 should be installed on the correct path when the nbdkit plugin
927 development environment is installed. You can use this in autoconf
928 configure.ac scripts to test for the development environment:
929 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
931 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
933 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
934 for compiling plugins.
935 You can also run pkg-config/pkgconf directly, for example:
937 if ! pkgconf nbdkit --exists; then
939 echo "you must install the nbdkit plugin development environment"
940 exit 1
941 fi
942 You can also substitute the plugindir variable by doing:
944 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
946 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
948
950 You can also write nbdkit plugins in Lua, OCaml, Perl, Python, Ruby,
951 Rust, shell script or Tcl. Other programming languages may be offered
952 in future.
953 For more information see: nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
955 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
956 nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
957 Plugins written in scripting languages may also be installed in
959 $plugindir. These must be called "nbdkit-name-plugin" without any
960 extension. They must be executable, and they must use the shebang
961 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
962 written in Perl called "foo.pl" might be installed like this:
963 $ head -1 foo.pl
965 #!/usr/sbin/nbdkit perl
966 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
968 and then users will be able to run it like this:
970 $ nbdkit foo [args ...]
972
974 nbdkit(1), nbdkit-filter(3).
975 Standard plugins provided by nbdkit:
977 nbdkit-curl-plugin(1), nbdkit-data-plugin(1),
979 nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
980 nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
981 nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
982 nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1), nbdkit-gzip-plugin(1),
983 nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
984 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
985 nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
986 nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
987 nbdkit-random-plugin(1), nbdkit-split-plugin(1), nbdkit-ssh-plugin(1),
988 nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
989 nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-lua-plugin(3),
990 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
991 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
992 nbdkit-tcl-plugin(3) .
993
995 Eric Blake
996 Richard W.M. Jones
998 Pino Toscano
1000
1002 Copyright (C) 2013-2018 Red Hat Inc.
1003
1005 Redistribution and use in source and binary forms, with or without
1006 modification, are permitted provided that the following conditions are
1007 met:
1008 · Redistributions of source code must retain the above copyright
1010 notice, this list of conditions and the following disclaimer.
1011 · Redistributions in binary form must reproduce the above copyright
1013 notice, this list of conditions and the following disclaimer in the
1014 documentation and/or other materials provided with the
1015 distribution.
1016 · Neither the name of Red Hat nor the names of its contributors may
1018 be used to endorse or promote products derived from this software
1019 without specific prior written permission.
1020 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1022 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1023 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1024 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1025 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1026 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1027 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1028 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1029 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1030 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1031 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1032nbdkit-1.12.3 2019-05-22 nbdkit-plugin(3)