3 nbdkit-plugin - how to write nbdkit plugins
7 #define NBDKIT_API_VERSION 2
9 #include <nbdkit-plugin.h>
11 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
16 /* create a handle ... */
20 static struct nbdkit_plugin plugin = {
22 .open = myplugin_open,
23 .get_size = myplugin_get_size,
24 .pread = myplugin_pread,
25 .pwrite = myplugin_pwrite,
29 NBDKIT_REGISTER_PLUGIN(plugin)
31 When this has been compiled to a shared library, do:
33 nbdkit [--args ...] ./myplugin.so [key=value ...]
35 When debugging, use the I<-fv> options:
37 nbdkit -fv ./myplugin.so [key=value ...]
41 An nbdkit plugin is a new source device which can be served using the
42 Network Block Device (NBD) protocol. This manual page describes how
43 to create an nbdkit plugin in C.
45 To see example plugins:
46 L<https://github.com/libguestfs/nbdkit/tree/master/plugins>
48 Plugins written in C have an ABI guarantee: a plugin compiled against
49 an older version of nbdkit will still work correctly when loaded with
50 a newer nbdkit. We also try (but cannot guarantee) to support plugins
51 compiled against a newer version of nbdkit when loaded with an older
52 nbdkit, although the plugin may have reduced functionality if it
53 depends on features only provided by newer nbdkit.
55 For plugins written in C, we also provide an API guarantee: a plugin
56 written against an older header will still compile unmodified with a
59 The API guarantee does not always apply to plugins written in other
60 (non-C) languages which may have to adapt to changes when recompiled
61 against a newer nbdkit.
63 To write plugins in other languages, see:
64 __LANG_PLUGIN_LINKS__.
66 =head1 C<#define NBDKIT_API_VERSION 2>
68 Plugins must choose which API version they want to use, by defining
69 NBDKIT_API_VERSION to a positive integer prior to including
70 C<nbdkit-plugin.h> (or any other nbdkit header). The default version
71 is 1 for backwards-compatibility with nbdkit v1.1.26 and earlier;
72 however, it is recommended that new plugins be written to the maximum
73 version (currently 2) as it enables more features and better
74 interaction with nbdkit filters. Therefore, the rest of this document
75 only covers the version 2 interface. A newer nbdkit will always
76 support plugins written in C which were compiled against any prior API
79 =head1 C<#include E<lt>nbdkit-plugin.hE<gt>>
81 All plugins should start by including this header file, after
82 optionally choosing an API version.
84 =head1 C<#define THREAD_MODEL>
86 All plugins must define a thread model. See L</THREADS> below for
87 details. It is generally safe to use:
89 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
91 =head1 C<struct nbdkit_plugin>
93 All plugins must define and register one C<struct nbdkit_plugin>,
94 which contains the name of the plugin and pointers to callback
97 static struct nbdkit_plugin plugin = {
99 .longname = "My Plugin",
100 .description = "This is my great plugin for nbdkit",
101 .open = myplugin_open,
102 .get_size = myplugin_get_size,
103 .pread = myplugin_pread,
104 .pwrite = myplugin_pwrite,
108 NBDKIT_REGISTER_PLUGIN(plugin)
110 The C<.name> field is the name of the plugin.
112 The callbacks are described below (see L</CALLBACKS>). Only C<.name>,
113 C<.open>, C<.get_size> and C<.pread> are required. All other
114 callbacks can be omitted. However almost all plugins should have a
115 C<.close> callback. Most real-world plugins will also want to declare
116 some of the other callbacks.
118 The nbdkit server calls the callbacks in the following order over the
119 lifetime of the plugin:
125 is called once just after the plugin is loaded into memory.
127 =item C<.config> and C<.config_complete>
129 C<.config> is called zero or more times during command line parsing.
130 C<.config_complete> is called once after all configuration information
131 has been passed to the plugin (but not during C<nbdkit --dump-plugin>).
133 Both are called after loading the plugin but before any connections
136 =item C<.thread_model>
138 In normal operation, C<.thread_model> is called once after
139 C<.config_complete> has validated all configuration information, and
140 before any connections are accepted. However, during C<nbdkit
141 --dump-plugin>, it is called after any C<.config> calls but without
142 C<.config_complete> (so a plugin which determines the results from a
143 script must be prepared for a missing script).
147 A new client has connected.
149 =item C<.can_write>, C<.get_size> and other option negotiation callbacks
151 These are called during option negotiation with the client, but before
152 any data is served. These callbacks may return different values
153 across different C<.open> calls, but within a single connection, they
154 are called at most once and cached by nbdkit for that connection.
156 =item C<.pread>, C<.pwrite> and other data serving callbacks
158 After option negotiation has finished, these may be called to serve
159 data. Depending on the thread model chosen, they might be called in
160 parallel from multiple threads. The data serving callbacks include a
161 flags argument; the results of the negotiation callbacks influence
162 whether particular flags will ever be passed to a data callback.
166 The client has disconnected.
168 =item C<.open> ... C<.close>
170 The sequence C<.open> ... C<.close> can be called repeatedly over the
171 lifetime of the plugin, and can be called in parallel (depending on
176 is called once just before the plugin is unloaded from memory.
182 The following flags are defined by nbdkit, and used in various data
183 serving callbacks as follows:
187 =item C<NBDKIT_FLAG_MAY_TRIM>
189 This flag is used by the C<.zero> callback; there is no way to disable
190 this flag, although a plugin that does not support trims as a way to
191 write zeroes may ignore the flag without violating expected semantics.
193 =item C<NBDKIT_FLAG_FUA>
195 This flag represents Forced Unit Access semantics. It is used by the
196 C<.pwrite>, C<.zero>, and C<.trim> callbacks to indicate that the
197 plugin must not return a result until the action has landed in
198 persistent storage. This flag will not be sent to the plugin unless
199 C<.can_fua> is provided and returns C<NBDKIT_FUA_NATIVE>.
203 The following defines are valid as successful return values for
208 =item C<NBDKIT_FUA_NONE>
210 Forced Unit Access is not supported; the client must manually request
211 a flush after writes have completed. The C<NBDKIT_FLAG_FUA> flag will
212 not be passed to the plugin's write callbacks.
214 =item C<NBDKIT_FUA_EMULATE>
216 The client may request Forced Unit Access, but it is implemented by
217 emulation, where nbdkit calls C<.flush> after a write operation; this
218 is semantically correct, but may hurt performance as it tends to flush
219 more data than just what the client requested. The C<NBDKIT_FLAG_FUA>
220 flag will not be passed to the plugin's write callbacks.
222 =item C<NBDKIT_FUA_NATIVE>
224 The client may request Forced Unit Access, which results in the
225 C<NBDKIT_FLAG_FUA> flag being passed to the plugin's write callbacks
226 (C<.pwrite>, C<.trim>, and C<.zero>). When the flag is set, these
227 callbacks must not return success until the client's request has
228 landed in persistent storage.
232 The following defines are valid as successful return values for
237 =item C<NBDKIT_CACHE_NONE>
239 The server does not advertise caching support, and rejects any
240 client-requested caching. Any C<.cache> callback is ignored.
242 =item C<NBDKIT_CACHE_EMULATE>
244 The nbdkit server advertises cache support to the client, where the
245 client may request that the server cache a region of the export to
246 potentially speed up future read and/or write operations on that
247 region. The nbdkit server implements the caching by calling C<.pread>
248 and ignoring the results. This option exists to ease the
249 implementation of a common form of caching; any C<.cache> callback is
252 =item C<NBDKIT_CACHE_NATIVE>
254 The nbdkit server advertises cache support to the client, where the
255 client may request that the server cache a region of the export to
256 potentially speed up future read and/or write operations on that
257 region. The nbdkit server calls the C<.cache> callback to perform the
258 caching; if that callback is missing, the client's cache request
259 succeeds without doing anything.
263 =head1 ERROR HANDLING
265 If there is an error in the plugin, the plugin should call
266 C<nbdkit_error> to report an error message; additionally, if the
267 callback is involved in serving data, the plugin should call
268 C<nbdkit_set_error> to influence the error code that will be sent to
269 the client. These two functions can be called in either order. Then,
270 the callback should return the appropriate error indication,
271 eg. C<NULL> or C<-1>.
273 If the call to C<nbdkit_set_error> is omitted while serving data, then
274 the global variable C<errno> may be used. For plugins which have
275 C<.errno_is_preserved != 0> the core code will use C<errno>. In
276 plugins written in non-C languages, we usually cannot trust that
277 C<errno> will not be overwritten when returning from that language to
278 C. In that case, either the plugin must call C<nbdkit_set_error> or
279 hard-coded C<EIO> is used.
281 C<nbdkit_error> has the following prototype and works like
284 void nbdkit_error (const char *fs, ...);
285 void nbdkit_verror (const char *fs, va_list args);
287 For convenience, C<nbdkit_error> preserves the value of C<errno>, and
288 also supports the glibc extension of a single C<%m> in a format string
289 expanding to C<strerror(errno)>, even on platforms that don't support
292 C<nbdkit_set_error> can be called at any time, but only has an impact
293 during callbacks for serving data, and only when the callback returns
294 an indication of failure. It has the following prototype:
296 void nbdkit_set_error (int err);
304 This field (a string) is required, and B<must> contain only ASCII
305 alphanumeric characters and be unique amongst all plugins.
311 Plugins may optionally set a version string which is displayed in help
312 and debugging output.
316 const char *longname;
318 An optional free text name of the plugin. This field is used in error
321 =head2 C<.description>
323 const char *description;
325 An optional multi-line description of the plugin.
331 This is called once just after the plugin is loaded into memory. You
332 can use this to perform any global initialization needed by the
339 This may be called once just before the plugin is unloaded from
340 memory. Note that it's not guaranteed that C<.unload> will always be
341 called (eg. the server might be killed or segfault), so you should try
342 to make the plugin as robust as possible by not requiring cleanup.
343 See also L</SHUTDOWN> below.
345 =head2 C<.dump_plugin>
347 void dump_plugin (void);
349 This optional callback is called when the
350 S<C<nbdkit plugin --dump-plugin>> command is used. It should print
351 any additional informative C<key=value> fields to stdout as needed.
352 Prefixing the keys with the name of the plugin will avoid conflicts.
356 int config (const char *key, const char *value);
358 On the nbdkit command line, after the plugin filename, come an
359 optional list of C<key=value> arguments. These are passed to the
360 plugin through this callback when the plugin is first loaded and
361 before any connections are accepted.
363 This callback may be called zero or more times.
365 Both C<key> and C<value> parameters will be non-NULL. The strings are
366 owned by nbdkit but will remain valid for the lifetime of the plugin,
367 so the plugin does not need to copy them.
369 The key will be a non-empty string beginning with an ASCII alphabetic
370 character (C<A-Z> C<a-z>). The rest of the key must contain only
371 ASCII alphanumeric plus period, underscore or dash characters (C<A-Z>
372 C<a-z> C<0-9> C<.> C<_> C<->). The value may be an arbitrary string,
373 including an empty string.
375 The names of C<key>s accepted by plugins is up to the plugin, but you
376 should probably look at other plugins and follow the same conventions.
378 If the value is a relative path, then note that the server changes
379 directory when it starts up. See L</FILENAMES AND PATHS> above.
381 If the C<.config> callback is not provided by the plugin, and the user
382 tries to specify any C<key=value> arguments, then nbdkit will exit
385 If there is an error, C<.config> should call C<nbdkit_error> with an
386 error message and return C<-1>.
388 =head2 C<.magic_config_key>
390 const char *magic_config_key;
392 This optional string can be used to set a "magic" key used when
393 parsing plugin parameters. It affects how "bare parameters" (those
394 which do not contain an C<=> character) are parsed on the command
397 If C<magic_config_key != NULL> then any bare parameters are passed to
398 the C<.config> method as: S<C<config (magic_config_key, argv[i]);>>.
400 If C<magic_config_key> is not set then we behave as in nbdkit E<lt>
401 1.7: If the first parameter on the command line is bare then it is
402 passed to the C<.config> method as: S<C<config ("script", value);>>.
403 Any other bare parameters give errors.
405 =head2 C<.config_complete>
407 int config_complete (void);
409 This optional callback is called after all the configuration has been
410 passed to the plugin. It is a good place to do checks, for example
411 that the user has passed the required parameters to the plugin.
413 If there is an error, C<.config_complete> should call C<nbdkit_error>
414 with an error message and return C<-1>.
416 =head2 C<.config_help>
418 const char *config_help;
420 This optional multi-line help message should summarize any
421 C<key=value> parameters that it takes. It does I<not> need to repeat
422 what already appears in C<.description>.
424 If the plugin doesn't take any config parameters you should probably
427 =head2 C<.thread_model>
429 int thread_model (void)
431 This optional callback is called after all the configuration has been
432 passed to the plugin. It can be used to force a stricter thread model
433 based on configuration, compared to C<THREAD_MODEL>. See L</THREADS>
434 below for details. Attempts to request a looser (more parallel) model
435 are silently ignored.
437 If there is an error, C<.thread_model> should call C<nbdkit_error>
438 with an error message and return C<-1>.
442 void *open (int readonly);
444 This is called when a new client connects to the nbdkit server. The
445 callback should allocate a handle and return it. This handle
446 is passed back to other callbacks and could be freed in the C<.close>
449 Note that the handle is completely opaque to nbdkit, but it must not
450 be NULL. If you don't need to use a handle, return
451 C<NBDKIT_HANDLE_NOT_NEEDED> which is a static non-NULL pointer.
453 The C<readonly> flag informs the plugin that the user requested a
454 read-only connection using the I<-r> flag on the command line. Note
455 that the plugin may I<additionally> force the connection to be
456 readonly (even if this flag is false) by returning false from the
457 C<.can_write> callback. So if your plugin can only serve read-only,
458 you can ignore this parameter.
460 If there is an error, C<.open> should call C<nbdkit_error> with an
461 error message and return C<NULL>.
465 void close (void *handle);
467 This is called when the client closes the connection. It should clean
468 up any per-connection resources.
470 Note there is no way in the NBD protocol to communicate close errors
471 back to the client, for example if your plugin calls L<close(2)> and
472 you are checking for errors (as you should do). Therefore the best
473 you can do is to log the error on the server. Well-behaved NBD
474 clients I<should> try to flush the connection before it is closed and
475 check for errors, but obviously this is outside the scope of nbdkit.
479 int64_t get_size (void *handle);
481 This is called during the option negotiation phase of the protocol
482 to get the size (in bytes) of the block device being exported.
484 The returned size must be E<ge> 0. If there is an error, C<.get_size>
485 should call C<nbdkit_error> with an error message and return C<-1>.
489 int can_write (void *handle);
491 This is called during the option negotiation phase to find out if the
492 handle supports writes.
494 If there is an error, C<.can_write> should call C<nbdkit_error> with
495 an error message and return C<-1>.
497 This callback is not required. If omitted, then we return true iff a
498 C<.pwrite> callback has been defined.
502 int can_flush (void *handle);
504 This is called during the option negotiation phase to find out if the
505 handle supports the flush-to-disk operation.
507 If there is an error, C<.can_flush> should call C<nbdkit_error> with
508 an error message and return C<-1>.
510 This callback is not required. If omitted, then we return true iff a
511 C<.flush> callback has been defined.
513 =head2 C<.is_rotational>
515 int is_rotational (void *handle);
517 This is called during the option negotiation phase to find out if the
518 backing disk is a rotational medium (like a traditional hard disk) or
519 not (like an SSD). If true, this may cause the client to reorder
520 requests to make them more efficient for a slow rotating disk.
522 If there is an error, C<.is_rotational> should call C<nbdkit_error>
523 with an error message and return C<-1>.
525 This callback is not required. If omitted, then we return false.
529 int can_trim (void *handle);
531 This is called during the option negotiation phase to find out if the
532 plugin supports the trim/discard operation for punching holes in the
535 If there is an error, C<.can_trim> should call C<nbdkit_error> with an
536 error message and return C<-1>.
538 This callback is not required. If omitted, then we return true iff a
539 C<.trim> callback has been defined.
543 int can_zero (void *handle);
545 This is called during the option negotiation phase to find out if the
546 plugin wants the C<.zero> callback to be utilized. Support for
547 writing zeroes is still advertised to the client (unless the
548 L<nbdkit-nozero-filter(1)> is also used), so returning false merely
549 serves as a way to avoid complicating the C<.zero> callback to have to
550 fail with C<ENOTSUP> or C<EOPNOTSUPP> on the connections where it will
551 never be more efficient than using C<.pwrite> up front.
553 If there is an error, C<.can_zero> should call C<nbdkit_error> with an
554 error message and return C<-1>.
556 This callback is not required. If omitted, then for a normal zero
557 request, nbdkit always tries C<.zero> first if it is present, and
558 gracefully falls back to C<.pwrite> if C<.zero> was absent or failed
559 with C<ENOTSUP> or C<EOPNOTSUPP>.
561 =head2 C<.can_fast_zero>
563 int can_fast_zero (void *handle);
565 This is called during the option negotiation phase to find out if the
566 plugin wants to advertise support for fast zero requests. If this
567 support is not advertised, a client cannot attempt fast zero requests,
568 and has no way to tell if writing zeroes offers any speedups compared
569 to using C<.pwrite> (other than compressed network traffic). If
570 support is advertised, then C<.zero> will have
571 C<NBDKIT_FLAG_FAST_ZERO> set when the client has requested a fast
572 zero, in which case the plugin must fail with C<ENOTSUP> or
573 C<EOPNOTSUPP> up front if the request would not offer any benefits
574 over C<.pwrite>. Advertising support for fast zero requests does not
575 require that writing zeroes be fast, only that the result (whether
576 success or failure) is fast, so this should be advertised when
579 If there is an error, C<.can_fast_zero> should call C<nbdkit_error>
580 with an error message and return C<-1>.
582 This callback is not required. If omitted, then nbdkit returns true
583 if C<.zero> is absent or C<.can_zero> returns false (in those cases,
584 nbdkit fails all fast zero requests, as its fallback to C<.pwrite> is
585 not inherently faster), otherwise false (since it cannot be determined
586 in advance if the plugin's C<.zero> will properly honor the semantics
587 of C<NBDKIT_FLAG_FAST_ZERO>).
589 =head2 C<.can_extents>
591 int can_extents (void *handle);
593 This is called during the option negotiation phase to find out if the
594 plugin supports detecting allocated (non-sparse) regions of the disk
595 with the C<.extents> callback.
597 If there is an error, C<.can_extents> should call C<nbdkit_error> with
598 an error message and return C<-1>.
600 This callback is not required. If omitted, then we return true iff a
601 C<.extents> callback has been defined.
605 int can_fua (void *handle);
607 This is called during the option negotiation phase to find out if the
608 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
609 trim requests. If this returns C<NBDKIT_FUA_NONE>, FUA support is not
610 advertised to the client; if this returns C<NBDKIT_FUA_EMULATE>, the
611 C<.flush> callback must work (even if C<.can_flush> returns false),
612 and FUA support is emulated by calling C<.flush> after any write
613 operation; if this returns C<NBDKIT_FUA_NATIVE>, then the C<.pwrite>,
614 C<.zero>, and C<.trim> callbacks (if implemented) must handle the flag
615 C<NBDKIT_FLAG_FUA>, by not returning until that action has landed in
618 If there is an error, C<.can_fua> should call C<nbdkit_error> with an
619 error message and return C<-1>.
621 This callback is not required unless a plugin wants to specifically
622 handle FUA requests. If omitted, nbdkit checks whether C<.flush>
623 exists, and behaves as if this function returns C<NBDKIT_FUA_NONE> or
624 C<NBDKIT_FUA_EMULATE> as appropriate.
626 =head2 C<.can_multi_conn>
628 int can_multi_conn (void *handle);
630 This is called during the option negotiation phase to find out if the
631 plugin is prepared to handle multiple connections from a single
632 client. If the plugin sets this to true then a client may try to open
633 multiple connections to the nbdkit server and spread requests across
634 all connections to maximize parallelism. If the plugin sets it to
635 false (which is the default) then well-behaved clients should only
636 open a single connection, although we cannot control what clients do
639 Specifically it means that either the plugin does not cache requests
640 at all. Or if it does cache them then the effects of a C<.flush>
641 request or setting C<NBDKIT_FLAG_FUA> on a request must be visible
642 across all connections to the plugin before the plugin replies to that
645 Properly working clients should send the same export name for each of
648 If you use Linux L<nbd-client(8)> option S<I<-C num>> with
649 S<num E<gt> 1> then Linux checks this flag and will refuse to connect
650 if C<.can_multi_conn> is false.
652 If there is an error, C<.can_multi_conn> should call C<nbdkit_error>
653 with an error message and return C<-1>.
655 This callback is not required. If omitted, then we return false.
659 int can_cache (void *handle);
661 This is called during the option negotiation phase to find out if the
662 plugin supports a cache operation. The nature of the caching is
663 unspecified (including whether there are limits on how much can be
664 cached at once, and whether writes to a cached region have
665 write-through or write-back semantics), but the command exists to let
666 clients issue a hint to the server that they will be accessing that
667 region of the export.
669 If this returns C<NBDKIT_CACHE_NONE>, cache support is not advertised
670 to the client; if this returns C<NBDKIT_CACHE_EMULATE>, caching is
671 emulated by the server calling C<.pread> and ignoring the results; if
672 this returns C<NBDKIT_CACHE_NATIVE>, then the C<.cache> callback will
673 be used. If there is an error, C<.can_cache> should call
674 C<nbdkit_error> with an error message and return C<-1>.
676 This callback is not required. If omitted, then we return
677 C<NBDKIT_CACHE_NONE> if the C<.cache> callback is missing, or
678 C<NBDKIT_CACHE_NATIVE> if it is defined.
682 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
685 During the data serving phase, nbdkit calls this callback to read data
686 from the backing store. C<count> bytes starting at C<offset> in the
687 backing store should be read and copied into C<buf>. nbdkit takes
688 care of all bounds- and sanity-checking, so the plugin does not need
691 The parameter C<flags> exists in case of future NBD protocol
692 extensions; at this time, it will be 0 on input.
694 The callback must read the whole C<count> bytes if it can. The NBD
695 protocol doesn't allow partial reads (instead, these would be errors).
696 If the whole C<count> bytes was read, the callback should return C<0>
697 to indicate there was I<no> error.
699 If there is an error (including a short read which couldn't be
700 recovered from), C<.pread> should call C<nbdkit_error> with an error
701 message, and C<nbdkit_set_error> to record an appropriate error
702 (unless C<errno> is sufficient), then return C<-1>.
706 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
709 During the data serving phase, nbdkit calls this callback to write
710 data to the backing store. C<count> bytes starting at C<offset> in
711 the backing store should be written using the data in C<buf>. nbdkit
712 takes care of all bounds- and sanity-checking, so the plugin does not
713 need to worry about that.
715 This function will not be called if C<.can_write> returned false. The
716 parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based on
717 the result of C<.can_fua>.
719 The callback must write the whole C<count> bytes if it can. The NBD
720 protocol doesn't allow partial writes (instead, these would be
721 errors). If the whole C<count> bytes was written successfully, the
722 callback should return C<0> to indicate there was I<no> error.
724 If there is an error (including a short write which couldn't be
725 recovered from), C<.pwrite> should call C<nbdkit_error> with an error
726 message, and C<nbdkit_set_error> to record an appropriate error
727 (unless C<errno> is sufficient), then return C<-1>.
731 int flush (void *handle, uint32_t flags);
733 During the data serving phase, this callback is used to
734 L<fdatasync(2)> the backing store, ie. to ensure it has been
735 completely written to a permanent medium. If that is not possible
736 then you can omit this callback.
738 This function will not be called directly by the client if
739 C<.can_flush> returned false; however, it may still be called by
740 nbdkit if C<.can_fua> returned C<NBDKIT_FUA_EMULATE>. The parameter
741 C<flags> exists in case of future NBD protocol extensions; at this
742 time, it will be 0 on input.
744 If there is an error, C<.flush> should call C<nbdkit_error> with an
745 error message, and C<nbdkit_set_error> to record an appropriate error
746 (unless C<errno> is sufficient), then return C<-1>.
750 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
752 During the data serving phase, this callback is used to "punch holes"
753 in the backing store. If that is not possible then you can omit this
756 This function will not be called if C<.can_trim> returned false. The
757 parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based on
758 the result of C<.can_fua>.
760 If there is an error, C<.trim> should call C<nbdkit_error> with an
761 error message, and C<nbdkit_set_error> to record an appropriate error
762 (unless C<errno> is sufficient), then return C<-1>.
766 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
768 During the data serving phase, this callback is used to write C<count>
769 bytes of zeroes at C<offset> in the backing store.
771 This function will not be called if C<.can_zero> returned false. On
772 input, the parameter C<flags> may include C<NBDKIT_FLAG_MAY_TRIM>
773 unconditionally, C<NBDKIT_FLAG_FUA> based on the result of
774 C<.can_fua>, and C<NBDKIT_FLAG_FAST_ZERO> based on the result of
777 If C<NBDKIT_FLAG_MAY_TRIM> is requested, the operation can punch a
778 hole instead of writing actual zero bytes, but only if subsequent
779 reads from the hole read as zeroes.
781 If C<NBDKIT_FLAG_FAST_ZERO> is requested, the plugin must decide up
782 front if the implementation is likely to be faster than a
783 corresponding C<.pwrite>; if not, then it must immediately fail with
784 C<ENOTSUP> or C<EOPNOTSUPP> (whether by C<nbdkit_set_error> or
785 C<errno>) and preferably without modifying the exported image. It is
786 acceptable to always fail a fast zero request (as a fast failure is
787 better than attempting the write only to find out after the fact that
788 it was not fast after all). Note that on Linux, support for
789 C<ioctl(BLKZEROOUT)> is insufficient for determining whether a zero
790 request to a block device will be fast (because the kernel will
791 perform a slow fallback when needed).
793 The callback must write the whole C<count> bytes if it can. The NBD
794 protocol doesn't allow partial writes (instead, these would be
795 errors). If the whole C<count> bytes was written successfully, the
796 callback should return C<0> to indicate there was I<no> error.
798 If there is an error, C<.zero> should call C<nbdkit_error> with an
799 error message, and C<nbdkit_set_error> to record an appropriate error
800 (unless C<errno> is sufficient), then return C<-1>.
802 If this callback is omitted, or if it fails with C<ENOTSUP> or
803 C<EOPNOTSUPP> (whether by C<nbdkit_set_error> or C<errno>), then
804 C<.pwrite> will be used as an automatic fallback except when the
805 client requested a fast zero.
809 int extents (void *handle, uint32_t count, uint64_t offset,
810 uint32_t flags, struct nbdkit_extents *extents);
812 During the data serving phase, this callback is used to detect
813 allocated, sparse and zeroed regions of the disk.
815 This function will not be called if C<.can_extents> returned false.
816 nbdkit's default behaviour in this case is to treat the whole virtual
817 disk as if it was allocated. Also, this function will not be called
818 by a client that does not request structured replies (the I<--no-sr>
819 option of nbdkit can be used to test behavior when C<.extents> is
820 unavailable to the client).
822 The callback should detect and return the list of extents overlapping
823 the range C<[offset...offset+count-1]>. The C<extents> parameter
824 points to an opaque object which the callback should fill in by
825 calling C<nbdkit_add_extent>. See L</Extents list> below.
827 If there is an error, C<.extents> should call C<nbdkit_error> with an
828 error message, and C<nbdkit_set_error> to record an appropriate error
829 (unless C<errno> is sufficient), then return C<-1>.
833 The plugin C<extents> callback is passed an opaque pointer C<struct
834 nbdkit_extents *extents>. This structure represents a list of
835 L<filesystem extents|https://en.wikipedia.org/wiki/Extent_(file_systems)>
836 describing which areas of the disk are allocated, which are sparse
837 (“holes”), and, if supported, which are zeroes.
839 The C<extents> callback should scan the disk starting at C<offset> and
840 call C<nbdkit_add_extent> for each extent found.
842 Extents overlapping the range C<[offset...offset+count-1]> should be
843 returned if possible. However nbdkit ignores extents E<lt> offset so
844 the plugin may, if it is easier to implement, return all extent
845 information for the whole disk. The plugin may return extents beyond
846 the end of the range. It may also return extent information for less
847 than the whole range, but it must return at least one extent
848 overlapping C<offset>.
850 The extents B<must> be added in ascending order, and B<must> be
853 The C<flags> parameter of the C<.extents> callback may contain the
854 flag C<NBDKIT_FLAG_REQ_ONE>. This means that the client is only
855 requesting information about the extent overlapping C<offset>. The
856 plugin may ignore this flag, or as an optimization it may return just
857 a single extent for C<offset>.
859 int nbdkit_add_extent (struct nbdkit_extents *extents,
860 uint64_t offset, uint64_t length, uint32_t type);
862 Add an extent covering C<[offset...offset+length-1]> of one of
863 the following four types:
869 A normal, allocated data extent.
871 =item C<type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO>
873 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
874 This is the normal type of hole applicable to most disks.
876 =item C<type = NBDKIT_EXTENT_ZERO>
878 An allocated extent which is known to contain only zeroes.
880 =item C<type = NBDKIT_EXTENT_HOLE>
882 An unallocated extent (hole) which does not read back as zeroes. Note
883 this should only be used in specialized circumstances such as when
884 writing a plugin for (or to emulate) certain SCSI drives which do not
885 guarantee that trimmed blocks read back as zeroes.
889 C<nbdkit_extent_add> returns C<0> on success or C<-1> on failure. On
890 failure C<nbdkit_error> and/or C<nbdkit_set_error> has already been
891 called. C<errno> will be set to a suitable value.
895 int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
897 During the data serving phase, this callback is used to give the
898 plugin a hint that the client intends to make further accesses to the
899 given region of the export. The nature of caching is not specified
900 further by the NBD specification (for example, a server may place
901 limits on how much may be cached at once, and there is no way to
902 control if writes to a cached area have write-through or write-back
903 semantics). In fact, the cache command can always fail and still be
904 compliant, and success might not guarantee a performance gain. If
905 this callback is omitted, then the results of C<.can_cache> determine
906 whether nbdkit will reject cache requests, treat them as instant
907 success, or emulate caching by calling C<.pread> over the same region
908 and ignoring the results.
910 This function will not be called if C<.can_cache> did not return
911 C<NBDKIT_CACHE_NATIVE>. The parameter C<flags> exists in case of
912 future NBD protocol extensions; at this time, it will be 0 on input. A
913 plugin must fail this function if C<flags> includes an unrecognized
914 flag, as that may indicate a requirement that the plugin comply must
915 with a specific caching semantic.
917 If there is an error, C<.cache> should call C<nbdkit_error> with an
918 error message, and C<nbdkit_set_error> to record an appropriate error
919 (unless C<errno> is sufficient), then return C<-1>.
923 The plugin struct also contains an integer field used as a
924 boolean in C code, but unlikely to be exposed in other language
929 =item C<.errno_is_preserved>
931 This defaults to 0; if non-zero, nbdkit can reliably use the value of
932 C<errno> when a callback reports failure, rather than the plugin
933 having to call C<nbdkit_set_error>.
939 Each nbdkit plugin must declare its maximum thread safety model by
940 defining the C<THREAD_MODEL> macro. (This macro is used by
941 C<NBDKIT_REGISTER_PLUGIN>). Additionally, a plugin may implement the
942 C<.thread_model> callback, called right after C<.config_complete> to
943 make a runtime decision on which thread model to use. The nbdkit
944 server chooses the most restrictive model between the plugin's
945 C<THREAD_MODEL>, the C<.thread_model> if present, any restrictions
946 requested by filters, and any limitations imposed by the system (for
947 example, a system without atomic C<FD_CLOEXEC> will serialize all
948 requests, so as to avoid nbdkit leaking a new file descriptor from one
949 thread into a child process created by another thread).
951 In C<nbdkit --dump-plugin PLUGIN> output, the C<max_thread_model> line
952 matches the C<THREAD_MODEL> macro, and the C<thread_model> line
953 matches what the system finally settled on after applying all
956 The possible settings for C<THREAD_MODEL> are defined below.
960 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS>
962 Only a single handle can be open at any time, and all requests happen
965 Note this means only one client can connect to the server at any time.
966 If a second client tries to connect it will block waiting for the
967 first client to close the connection.
969 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>
971 I<This is a safe default for most plugins>.
973 Multiple handles can be open at the same time, but requests are
974 serialized so that for the plugin as a whole only one
975 open/read/write/close (etc) request will be in progress at any time.
977 This is a useful setting if the library you are using is not
978 thread-safe. However performance may not be good.
980 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS>
982 Multiple handles can be open and multiple data requests can happen in
983 parallel. However only one request will happen per handle at a time
984 (but requests on different handles might happen concurrently).
986 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL>
988 Multiple handles can be open and multiple data requests can happen in
989 parallel (even on the same handle). The server may reorder replies,
990 answering a later request before an earlier one.
992 All the libraries you use must be thread-safe and reentrant, and any
993 code that creates a file descriptor should atomically set
994 C<FD_CLOEXEC> if you do not want it accidentally leaked to another
995 thread's child process. You may also need to provide mutexes for
996 fields in your connection handle.
1000 If none of the above thread models are suitable, then use
1001 C<NBDKIT_THREAD_MODEL_PARALLEL> and implement your own locking using
1002 C<pthread_mutex_t> etc.
1006 When nbdkit receives certain signals it will shut down (see
1007 L<nbdkit(1)/SIGNALS>). The server will wait for any currently running
1008 plugin callbacks to finish and also call the C<.unload> callback
1009 before unloading the plugin.
1011 Note that it's not guaranteed this can always happen (eg. the server
1012 might be killed by C<SIGKILL> or segfault).
1014 =head1 PARSING COMMAND LINE PARAMETERS
1016 =head2 Parsing numbers
1018 There are several functions for parsing numbers. These all deal
1019 correctly with overflow, out of range and parse errors, and you should
1020 use them instead of unsafe functions like L<sscanf(3)>, L<atoi(3)> and
1023 int nbdkit_parse_int (const char *what, const char *str, int *r);
1024 int nbdkit_parse_unsigned (const char *what,
1025 const char *str, unsigned *r);
1026 int nbdkit_parse_int8_t (const char *what,
1027 const char *str, int8_t *r);
1028 int nbdkit_parse_uint8_t (const char *what,
1029 const char *str, uint8_t *r);
1030 int nbdkit_parse_int16_t (const char *what,
1031 const char *str, int16_t *r);
1032 int nbdkit_parse_uint16_t (const char *what,
1033 const char *str, uint16_t *r);
1034 int nbdkit_parse_int32_t (const char *what,
1035 const char *str, int32_t *r);
1036 int nbdkit_parse_uint32_t (const char *what,
1037 const char *str, uint32_t *r);
1038 int nbdkit_parse_int64_t (const char *what,
1039 const char *str, int64_t *r);
1040 int nbdkit_parse_uint64_t (const char *what,
1041 const char *str, uint64_t *r);
1043 Parse string C<str> into an integer of various types. These functions
1044 parse a decimal, hexadecimal (C<"0x...">) or octal (C<"0...">) number.
1046 On success the functions return C<0> and set C<*r> to the parsed value
1047 (unless C<*r == NULL> in which case the result is discarded). On
1048 error, C<nbdkit_error> is called and the functions return C<-1>. On
1049 error C<*r> is always unchanged.
1051 The C<what> parameter is printed in error messages to provide context.
1052 It should usually be a short descriptive string of what you are trying
1055 if (nbdkit_parse_int ("random seed", argv[1], &seed) == -1)
1058 might print an error:
1060 random seed: could not parse number: "lalala"
1062 =head2 Parsing sizes
1064 Use the C<nbdkit_parse_size> utility function to parse human-readable
1065 size strings such as "100M" into the size in bytes.
1067 int64_t nbdkit_parse_size (const char *str);
1069 C<str> can be a string in a number of common formats. The function
1070 returns the size in bytes. If there was an error, it returns C<-1>.
1072 =head2 Parsing booleans
1074 Use the C<nbdkit_parse_bool> utility function to parse human-readable
1075 strings such as "on" into a boolean value.
1077 int nbdkit_parse_bool (const char *str);
1079 C<str> can be a string containing a case-insensitive form of various
1080 common toggle values. The function returns 0 or 1 if the parse was
1081 successful. If there was an error, it returns C<-1>.
1083 =head2 Reading passwords
1085 The C<nbdkit_read_password> utility function can be used to read
1086 passwords from config parameters:
1088 int nbdkit_read_password (const char *value, char **password);
1092 char *password = NULL;
1095 myplugin_config (const char *key, const char *value)
1098 if (strcmp (key, "password") == 0) {
1100 if (nbdkit_read_password (value, &password) == -1)
1106 The C<password> result string is allocated by malloc, and so you may
1109 This function recognizes several password formats. A password may be
1110 used directly on the command line, eg:
1112 nbdkit myplugin password=mostsecret
1114 But more securely this function can also read a password
1117 nbdkit myplugin password=-
1121 nbdkit myplugin password=+/tmp/secret
1123 or from a file descriptor inherited by nbdkit:
1125 nbdkit myplugin password=-99
1127 (If the password begins with a C<-> or C<+> character then it must be
1130 =head1 FILENAMES AND PATHS
1132 The server usually (not always) changes directory to C</> before it
1133 starts serving connections. This means that any relative paths passed
1134 during configuration will not work when the server is running
1135 (example: S<C<nbdkit plugin.so disk.img>>).
1137 To avoid problems, prepend relative paths with the current directory
1138 before storing them in the handle. Or open files and store the file
1141 =head2 C<nbdkit_absolute_path>
1143 char *nbdkit_absolute_path (const char *filename);
1145 The utility function C<nbdkit_absolute_path> converts any path to an
1146 absolute path: if it is relative, then all this function does is
1147 prepend the current working directory to the path, with no extra
1150 Note that this function works I<only> when used in the C<.config>, and
1151 C<.config_complete> callbacks.
1153 If conversion was not possible, this calls C<nbdkit_error> and returns
1154 C<NULL>. Note that this function does not check that the file exists.
1156 The returned string must be freed by the caller.
1158 =head2 C<nbdkit_realpath>
1160 char *nbdkit_realpath (const char *filename);
1162 The utility function C<nbdkit_realpath> converts any path to an
1163 absolute path, resolving symlinks. Under the hood it uses the
1164 C<realpath> function, and thus it fails if the path does not exist,
1165 or it is not possible to access to any of the components of the path.
1167 Note that this function works I<only> when used in the C<.config>, and
1168 C<.config_complete> callbacks.
1170 If the path resolution was not possible, this calls C<nbdkit_error>
1171 and returns C<NULL>.
1173 The returned string must be freed by the caller.
1177 All plugins will see a L<umask(2)> of C<0022>.
1181 A plugin that needs to sleep may call L<sleep(2)>, L<nanosleep(2)> and
1182 similar. However that can cause nbdkit to delay excessively when
1183 shutting down (since it must wait for any plugin or filter which is
1184 sleeping). To avoid this there is a special wrapper around nanosleep
1185 which plugins and filters should use instead.
1187 =head2 C<nbdkit_nanosleep>
1189 int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1191 The utility function C<nbdkit_nanosleep> suspends the current thread,
1192 and returns 0 if it slept at least as many seconds and nanoseconds as
1193 requested, or -1 after calling C<nbdkit_error> if there is no point in
1194 continuing the current command. Attempts to sleep more than
1195 C<INT_MAX> seconds are treated as an error.
1199 If the client negotiated an NBD export name with nbdkit then plugins
1200 may read this from any connected callbacks. Nbdkit's normal behaviour
1201 is to accept any export name passed by the client, log it in debug
1202 output, but otherwise ignore it. By using C<nbdkit_export_name>
1203 plugins may choose to filter by export name or serve different
1206 =head2 C<nbdkit_export_name>
1208 const char *nbdkit_export_name (void);
1210 Return the optional NBD export name if one was negotiated with the
1211 current client (this uses thread-local magic so no parameter is
1212 required). The returned string is only valid while the client is
1213 connected, so if you need to store it in the plugin you must copy it.
1215 The export name is a free-form text string, it is not necessarily a
1216 path or filename and it does not need to begin with a C<'/'>
1217 character. The NBD protocol describes the empty string (C<"">) as a
1218 representing a "default export" or to be used in cases where the
1219 export name does not make sense. B<The export name is untrusted
1220 client data, be cautious when parsing it.>
1222 On error, C<nbdkit_error> is called and the call returns C<NULL>.
1226 It is possible to get the address of the client when you are running
1227 in any connected callback.
1229 =head2 C<nbdkit_peer_name>
1231 int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1233 Return the peer (client) address, if available. The C<addr> and
1234 C<addrlen> parameters behave like L<getpeername(2)>. In particular
1235 you must initialize C<addrlen> with the size of the buffer pointed to
1236 by C<addr>, and if C<addr> is not large enough then the address will
1239 In some cases this is not available or the address returned will be
1240 meaningless (eg. if there is a proxy between the client and nbdkit).
1241 This call uses thread-local magic so no parameter is required to
1242 specify the current connection.
1244 On success this returns C<0>. On error, C<nbdkit_error> is called and
1245 this call returns C<-1>.
1249 Run the server with I<-f> and I<-v> options so it doesn't fork and you
1250 can see debugging information:
1252 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1254 To print debugging information from within the plugin, call
1255 C<nbdkit_debug>, which has the following prototype and works like
1258 void nbdkit_debug (const char *fs, ...);
1259 void nbdkit_vdebug (const char *fs, va_list args);
1261 For convenience, C<nbdkit_debug> preserves the value of C<errno>, and
1262 also supports the glibc extension of a single C<%m> in a format string
1263 expanding to C<strerror(errno)>, even on platforms that don't support
1264 that natively. Note that C<nbdkit_debug> only prints things when the
1265 server is in verbose mode (I<-v> option).
1269 The I<-v> option switches general debugging on or off, and this
1270 debugging should be used for messages which are useful for all users
1273 In cases where you want to enable specific extra debugging to track
1274 down bugs in plugins or filters — mainly for use by the plugin/filter
1275 developers themselves — you can define Debug Flags. These are global
1276 ints called C<myplugin_debug_*>:
1278 int myplugin_debug_foo;
1279 int myplugin_debug_bar;
1281 if (myplugin_debug_foo) {
1282 nbdkit_debug ("lots of extra debugging about foo: ...");
1285 Debug Flags can be controlled on the command line using the I<-D> (or
1288 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1290 Note C<myplugin> is the name passed to C<.name> in the C<struct
1293 You should only use this feature for debug settings. For general
1294 settings use ordinary plugin parameters. Debug Flags can only be C
1295 ints. They are not supported by non-C language plugins.
1297 =head1 INSTALLING THE PLUGIN
1299 The plugin is a C<*.so> file and possibly a manual page. You can of
1300 course install the plugin C<*.so> file wherever you want, and users
1301 will be able to use it by running:
1303 nbdkit /path/to/plugin.so [args]
1305 However B<if> the shared library has a name of the form
1306 C<nbdkit-I<name>-plugin.so> B<and if> the library is installed in the
1307 C<$plugindir> directory, then users can be run it by only typing:
1311 The location of the C<$plugindir> directory is set when nbdkit is
1312 compiled and can be found by doing:
1314 nbdkit --dump-config
1316 If using the pkg-config/pkgconf system then you can also find the
1317 plugin directory at compile time by doing:
1319 pkgconf nbdkit --variable=plugindir
1321 =head1 PKG-CONFIG/PKGCONF
1323 nbdkit provides a pkg-config/pkgconf file called C<nbdkit.pc> which
1324 should be installed on the correct path when the nbdkit plugin
1325 development environment is installed. You can use this in autoconf
1326 F<configure.ac> scripts to test for the development environment:
1328 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1330 The above will fail unless nbdkit E<ge> 1.2.3 and the header file is
1331 installed, and will set C<NBDKIT_CFLAGS> and C<NBDKIT_LIBS>
1332 appropriately for compiling plugins.
1334 You can also run pkg-config/pkgconf directly, for example:
1336 if ! pkgconf nbdkit --exists; then
1337 echo "you must install the nbdkit plugin development environment"
1341 You can also substitute the plugindir variable by doing:
1343 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1345 which defines C<$(NBDKIT_PLUGINDIR)> in automake-generated Makefiles.
1347 =head1 WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES
1349 You can also write nbdkit plugins in Lua, OCaml, Perl, Python, Ruby,
1350 Rust, shell script or Tcl. Other programming languages may be offered
1353 For more information see:
1354 __LANG_PLUGIN_LINKS__.
1356 Plugins written in scripting languages may also be installed in
1357 C<$plugindir>. These must be called C<nbdkit-I<name>-plugin> without
1358 any extension. They must be executable, and they must use the shebang
1359 header (see L<nbdkit(1)/Shebang scripts>). For example a plugin
1360 written in Perl called C<foo.pl> might be installed like this:
1363 #!/usr/sbin/nbdkit perl
1365 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1367 and then users will be able to run it like this:
1369 $ nbdkit foo [args ...]
1374 L<nbdkit-nozero-filter(3)>,
1375 L<nbdkit-filter(3)>.
1377 Standard plugins provided by nbdkit:
1391 Copyright (C) 2013-2018 Red Hat Inc.