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

NAME

6       nbdkit-plugin - how to write nbdkit plugins
7

SYNOPSIS

9        #define NBDKIT_API_VERSION 2
10
11        #include <nbdkit-plugin.h>
12
13        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
14
15        static void *
16        myplugin_open (void)
17        {
18          /* create a handle ... */
19          return handle;
20        }
21
22        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
31        NBDKIT_REGISTER_PLUGIN(plugin)
32
33       When this has been compiled to a shared library, do:
34
35        nbdkit [--args ...] ./myplugin.so [key=value ...]
36
37       When debugging, use the -fv options:
38
39        nbdkit -fv ./myplugin.so [key=value ...]
40

DESCRIPTION

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
46       To see example plugins:
47       https://github.com/libguestfs/nbdkit/tree/master/plugins
48
49       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
56       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
60       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
64       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

"#define NBDKIT_API_VERSION 2"

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

"#include <nbdkit-plugin.h>"

81       All plugins should start by including this header file, after
82       optionally choosing an API version.
83

"#define THREAD_MODEL"

85       All plugins must define a thread model.  See "THREADS" below for
86       details.  It is generally safe to use:
87
88        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
89

"struct nbdkit_plugin"

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
94        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
105        NBDKIT_REGISTER_PLUGIN(plugin)
106
107       The ".name" field is the name of the plugin.
108
109       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
115       The nbdkit server calls the callbacks in the following order over the
116       lifetime of the plugin:
117
118       ".load"
119           is called once just after the plugin is loaded into memory.
120
121       ".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
126           Both are called after loading the plugin but before any connections
127           are accepted.
128
129       ".open"
130           A new client has connected.
131
132       ".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
140       ".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
148       ".close"
149           The client has disconnected.
150
151       ".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
156       ".unload"
157           is called once just before the plugin is unloaded from memory.
158

FLAGS

160       The following flags are defined by nbdkit, and used in various data
161       serving callbacks as follows:
162
163       "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
169       "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
176       The following defines are valid as successful return values for
177       ".can_fua":
178
179       "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
184       "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
192       "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

ERROR HANDLING

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
208       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
216       "nbdkit_error" has the following prototype and works like printf(3):
217
218        void nbdkit_error (const char *fs, ...);
219        void nbdkit_verror (const char *fs, va_list args);
220
221       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
226       "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
230        void nbdkit_set_error (int err);
231

FILENAMES AND PATHS

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
238       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
242   "nbdkit_absolute_path"
243        char *nbdkit_absolute_path (const char *filename);
244
245       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
250       Note that this function works only when used in the ".config", and
251       ".config_complete" callbacks.
252
253       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
256       The returned string must be freed by the caller.
257
258   "nbdkit_realpath"
259        char *nbdkit_realpath (const char *filename);
260
261       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
266       Note that this function works only when used in the ".config", and
267       ".config_complete" callbacks.
268
269       If the path resolution was not possible, this calls "nbdkit_error" and
270       returns "NULL".
271
272       The returned string must be freed by the caller.
273
274   umask
275       All plugins will see a umask(2) of 0022.
276

CALLBACKS

278   ".name"
279        const char *name;
280
281       This field (a string) is required, and must contain only ASCII
282       alphanumeric characters and be unique amongst all plugins.
283
284   ".version"
285        const char *version;
286
287       Plugins may optionally set a version string which is displayed in help
288       and debugging output.
289
290   ".longname"
291        const char *longname;
292
293       An optional free text name of the plugin.  This field is used in error
294       messages.
295
296   ".description"
297        const char *description;
298
299       An optional multi-line description of the plugin.
300
301   ".load"
302        void load (void);
303
304       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
307   ".unload"
308        void unload (void);
309
310       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
316   ".dump_plugin"
317        void dump_plugin (void);
318
319       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
324   ".config"
325        int config (const char *key, const char *value);
326
327       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
332       This callback may be called zero or more times.
333
334       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
338       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
344       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
347       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
350       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
354       If there is an error, ".config" should call "nbdkit_error" with an
355       error message and return "-1".
356
357   ".magic_config_key"
358        const char *magic_config_key;
359
360       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
364       If "magic_config_key != NULL" then any bare parameters are passed to
365       the ".config" method as: "config (magic_config_key, argv[i]);".
366
367       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
372   ".config_complete"
373        int config_complete (void);
374
375       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
379       If there is an error, ".config_complete" should call "nbdkit_error"
380       with an error message and return "-1".
381
382   ".config_help"
383        const char *config_help;
384
385       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
389       If the plugin doesn't take any config parameters you should probably
390       omit this.
391
392   ".open"
393        void *open (int readonly);
394
395       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
399       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
403       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
410       If there is an error, ".open" should call "nbdkit_error" with an error
411       message and return "NULL".
412
413   ".close"
414        void close (void *handle);
415
416       This is called when the client closes the connection.  It should clean
417       up any per-connection resources.
418
419       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
426   ".get_size"
427        int64_t get_size (void *handle);
428
429       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
432       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
435   ".can_write"
436        int can_write (void *handle);
437
438       This is called during the option negotiation phase to find out if the
439       handle supports writes.
440
441       If there is an error, ".can_write" should call "nbdkit_error" with an
442       error message and return "-1".
443
444       This callback is not required.  If omitted, then we return true iff a
445       ".pwrite" callback has been defined.
446
447   ".can_flush"
448        int can_flush (void *handle);
449
450       This is called during the option negotiation phase to find out if the
451       handle supports the flush-to-disk operation.
452
453       If there is an error, ".can_flush" should call "nbdkit_error" with an
454       error message and return "-1".
455
456       This callback is not required.  If omitted, then we return true iff a
457       ".flush" callback has been defined.
458
459   ".is_rotational"
460        int is_rotational (void *handle);
461
462       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
467       If there is an error, ".is_rotational" should call "nbdkit_error" with
468       an error message and return "-1".
469
470       This callback is not required.  If omitted, then we return false.
471
472   ".can_trim"
473        int can_trim (void *handle);
474
475       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
479       If there is an error, ".can_trim" should call "nbdkit_error" with an
480       error message and return "-1".
481
482       This callback is not required.  If omitted, then we return true iff a
483       ".trim" callback has been defined.
484
485   ".can_zero"
486        int can_zero (void *handle);
487
488       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
496       If there is an error, ".can_zero" should call "nbdkit_error" with an
497       error message and return "-1".
498
499       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
503   ".can_extents"
504        int can_extents (void *handle);
505
506       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
510       If there is an error, ".can_extents" should call "nbdkit_error" with an
511       error message and return "-1".
512
513       This callback is not required.  If omitted, then we return true iff a
514       ".extents" callback has been defined.
515
516   ".can_fua"
517        int can_fua (void *handle);
518
519       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
530       If there is an error, ".can_fua" should call "nbdkit_error" with an
531       error message and return "-1".
532
533       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
538   ".can_multi_conn"
539        int can_multi_conn (void *handle);
540
541       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
550       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
555       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
559       If there is an error, ".can_multi_conn" should call "nbdkit_error" with
560       an error message and return "-1".
561
562       This callback is not required.  If omitted, then we return false.
563
564   ".pread"
565        int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
566                   uint32_t flags);
567
568       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
574       The parameter "flags" exists in case of future NBD protocol extensions;
575       at this time, it will be 0 on input.
576
577       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
582       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
587   ".pwrite"
588        int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
589                    uint32_t flags);
590
591       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
597       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
601       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
606       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
611   ".flush"
612        int flush (void *handle, uint32_t flags);
613
614       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
619       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
624       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
628   ".trim"
629        int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
630
631       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
635       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
639       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
643   ".zero"
644        int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
645
646       During the data serving phase, this callback is used to write "count"
647       bytes of zeroes at "offset" in the backing store.
648
649       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
654       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
660       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
665       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
669   ".extents"
670        int extents (void *handle, uint32_t count, uint64_t offset,
671                     uint32_t flags, struct nbdkit_extents *extents);
672
673       During the data serving phase, this callback is used to detect
674       allocated, sparse and zeroed regions of the disk.
675
676       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
680       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
685       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
689       Extents list
690
691       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
696       The "extents" callback should scan the disk starting at "offset" and
697       call "nbdkit_add_extent" for each extent found.
698
699       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
707       The extents must be added in ascending order, and must be contiguous.
708
709       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
715        int nbdkit_add_extent (struct nbdkit_extents *extents,
716                               uint64_t offset, uint64_t length, uint32_t type);
717
718       Add an extent covering "[offset...offset+length-1]" of one of the
719       following four types:
720
721       "type = 0"
722           A normal, allocated data extent.
723
724       "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
728       "type = NBDKIT_EXTENT_ZERO"
729           An allocated extent which is known to contain only zeroes.
730
731       "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
737       "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

THREADS

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
746       The possible settings for "THREAD_MODEL" are defined below.
747
748       "#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
752           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
756       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
757           This is a safe default for most plugins.
758
759           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
764           This is a useful setting if the library you are using is not
765           thread-safe.  However performance may not be good.
766
767       "#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
772       "#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
776           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
780       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

SHUTDOWN

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
790       Note that it's not guaranteed this can always happen (eg. the server
791       might be killed by "SIGKILL" or segfault).
792

PARSING SIZE PARAMETERS

794       Use the "nbdkit_parse_size" utility function to parse human-readable
795       size strings such as "100M" into the size in bytes.
796
797        int64_t nbdkit_parse_size (const char *str);
798
799       "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

PARSING BOOLEAN PARAMETERS

803       Use the "nbdkit_parse_bool" utility function to parse human-readable
804       strings such as "on" into a boolean value.
805
806        int nbdkit_parse_bool (const char *str);
807
808       "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

READING PASSWORDS

813       The "nbdkit_read_password" utility function can be used to read
814       passwords from config parameters:
815
816        int nbdkit_read_password (const char *value, char **password);
817
818       For example:
819
820        char *password = NULL;
821
822        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
834       The "password" result string is allocated by malloc, and so you may
835       need to free it.
836
837       This function recognizes several password formats.  A password may be
838       used directly on the command line, eg:
839
840        nbdkit myplugin password=mostsecret
841
842       But more securely this function can also read a password interactively:
843
844        nbdkit myplugin password=-
845
846       or from a file:
847
848        nbdkit myplugin password=+/tmp/secret
849
850       (If the password begins with a "-" or "+" character then it must be
851       passed in a file).
852

DEBUGGING

854       Run the server with -f and -v options so it doesn't fork and you can
855       see debugging information:
856
857        nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
858
859       To print debugging information from within the plugin, call
860       "nbdkit_debug", which has the following prototype and works like
861       printf(3):
862
863        void nbdkit_debug (const char *fs, ...);
864        void nbdkit_vdebug (const char *fs, va_list args);
865
866       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
872   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
877       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
882        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
889       Debug Flags can be controlled on the command line using the -D (or
890       --debug) option:
891
892        nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
893
894       Note "myplugin" is the name passed to ".name" in the "struct
895       nbdkit_plugin".
896
897       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

INSTALLING THE PLUGIN

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
906        nbdkit /path/to/plugin.so [args]
907
908       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
912        nbdkit name [args]
913
914       The location of the $plugindir directory is set when nbdkit is compiled
915       and can be found by doing:
916
917        nbdkit --dump-config
918
919       If using the pkg-config/pkgconf system then you can also find the
920       plugin directory at compile time by doing:
921
922        pkgconf nbdkit --variable=plugindir
923

PKG-CONFIG/PKGCONF

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
930        PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
931
932       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
936       You can also run pkg-config/pkgconf directly, for example:
937
938        if ! pkgconf nbdkit --exists; then
939          echo "you must install the nbdkit plugin development environment"
940          exit 1
941        fi
942
943       You can also substitute the plugindir variable by doing:
944
945        PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
946
947       which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
948

WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES

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
954       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
958       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
964        $ head -1 foo.pl
965        #!/usr/sbin/nbdkit perl
966
967        $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
968
969       and then users will be able to run it like this:
970
971        $ nbdkit foo [args ...]
972

SEE ALSO

974       nbdkit(1), nbdkit-filter(3).
975
976       Standard plugins provided by nbdkit:
977
978       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

AUTHORS

995       Eric Blake
996
997       Richard W.M. Jones
998
999       Pino Toscano
1000
1002       Copyright (C) 2013-2018 Red Hat Inc.
1003

LICENSE

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
1009       ·   Redistributions of source code must retain the above copyright
1010           notice, this list of conditions and the following disclaimer.
1011
1012       ·   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
1017       ·   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
1021       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.
1032
1033
1034
1035nbdkit-1.12.3                     2019-05-22                  nbdkit-plugin(3)
Impressum