1nbdkit-plugin(3) NBDKIT nbdkit-plugin(3)
2
6 nbdkit-plugin - how to write nbdkit plugins
7
9 #define NBDKIT_API_VERSION 2
10 #include <nbdkit-plugin.h>
12 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
14 static void *
16 myplugin_open (void)
17 {
18 /* create a handle ... */
19 return handle;
20 }
21 static struct nbdkit_plugin plugin = {
23 .name = "myplugin",
24 .open = myplugin_open,
25 .get_size = myplugin_get_size,
26 .pread = myplugin_pread,
27 .pwrite = myplugin_pwrite,
28 /* etc */
29 };
30 NBDKIT_REGISTER_PLUGIN(plugin)
32 When this has been compiled to a shared library, do:
34 nbdkit [--args ...] ./myplugin.so [key=value ...]
36 When debugging, use the -fv options:
38 nbdkit -fv ./myplugin.so [key=value ...]
40
42 An nbdkit plugin is a new source device which can be served using the
43 Network Block Device (NBD) protocol. This manual page describes how to
44 create an nbdkit plugin in C.
45 To see example plugins:
47 https://github.com/libguestfs/nbdkit/tree/master/plugins
48 Plugins written in C have an ABI guarantee: a plugin compiled against
50 an older version of nbdkit will still work correctly when loaded with a
51 newer nbdkit. We also try (but cannot guarantee) to support plugins
52 compiled against a newer version of nbdkit when loaded with an older
53 nbdkit, although the plugin may have reduced functionality if it
54 depends on features only provided by newer nbdkit.
55 For plugins written in C, we also provide an API guarantee: a plugin
57 written against an older header will still compile unmodified with a
58 newer nbdkit.
59 The API guarantee does not always apply to plugins written in other
61 (non-C) languages which may have to adapt to changes when recompiled
62 against a newer nbdkit.
63 To write plugins in other languages, see: nbdkit-lua-plugin(3),
65 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
66 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
67 nbdkit-tcl-plugin(3) .
68
70 Plugins must choose which API version they want to use, by defining
71 NBDKIT_API_VERSION to a positive integer prior to including
72 "nbdkit-plugin.h" (or any other nbdkit header). The default version is
73 1 for backwards-compatibility with nbdkit v1.1.26 and earlier; however,
74 it is recommended that new plugins be written to the maximum version
75 (currently 2) as it enables more features and better interaction with
76 nbdkit filters. Therefore, the rest of this document only covers the
77 version 2 interface. A newer nbdkit will always support plugins
78 written in C which were compiled against any prior API version.
79
81 All plugins should start by including this header file, after
82 optionally choosing an API version.
83
85 All plugins must define a thread model. See "THREADS" below for
86 details. It is generally safe to use:
87 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
89
91 All plugins must define and register one "struct nbdkit_plugin", which
92 contains the name of the plugin and pointers to callback functions.
93 static struct nbdkit_plugin plugin = {
95 .name = "myplugin",
96 .longname = "My Plugin",
97 .description = "This is my great plugin for nbdkit",
98 .open = myplugin_open,
99 .get_size = myplugin_get_size,
100 .pread = myplugin_pread,
101 .pwrite = myplugin_pwrite,
102 /* etc */
103 };
104 NBDKIT_REGISTER_PLUGIN(plugin)
106 The ".name" field is the name of the plugin.
108 The callbacks are described below (see "CALLBACKS"). Only ".name",
110 ".open", ".get_size" and ".pread" are required. All other callbacks
111 can be omitted. However almost all plugins should have a ".close"
112 callback. Most real-world plugins will also want to declare some of
113 the other callbacks.
114 The nbdkit server calls the callbacks in the following order over the
116 lifetime of the plugin:
117 ".load"
119 is called once just after the plugin is loaded into memory.
120 ".config" and ".config_complete"
122 ".config" is called zero or more times during command line parsing.
123 ".config_complete" is called once after all configuration
124 information has been passed to the plugin (but not during "nbdkit
125 --dump-plugin").
126 Both are called after loading the plugin but before any connections
128 are accepted.
129 ".thread_model"
131 In normal operation, ".thread_model" is called once after
132 ".config_complete" has validated all configuration information, and
133 before any connections are accepted. However, during "nbdkit
134 --dump-plugin", it is called after any ".config" calls but without
135 ".config_complete" (so a plugin which determines the results from a
136 script must be prepared for a missing script).
137 ".preconnect"
139 Called when a TCP connection has been made to the server. This
140 happens early, before NBD or TLS negotiation.
141 ".open"
143 A new client has connected and finished the NBD handshake. TLS
144 negotiation (if required) has been completed successfully.
145 ".can_write", ".get_size" and other option negotiation callbacks
147 These are called during option negotiation with the client, but
148 before any data is served. These callbacks may return different
149 values across different ".open" calls, but within a single
150 connection, they are called at most once and cached by nbdkit for
151 that connection.
152 ".pread", ".pwrite" and other data serving callbacks
154 After option negotiation has finished, these may be called to serve
155 data. Depending on the thread model chosen, they might be called
156 in parallel from multiple threads. The data serving callbacks
157 include a flags argument; the results of the negotiation callbacks
158 influence whether particular flags will ever be passed to a data
159 callback.
160 ".close"
162 The client has disconnected.
163 ".preconnect", ".open" ... ".close"
165 The sequence ".preconnect", ".open" ... ".close" can be called
166 repeatedly over the lifetime of the plugin, and can be called in
167 parallel (depending on the thread model).
168 ".unload"
170 is called once just before the plugin is unloaded from memory.
171
173 The following flags are defined by nbdkit, and used in various data
174 serving callbacks as follows:
175 "NBDKIT_FLAG_MAY_TRIM"
177 This flag is used by the ".zero" callback; there is no way to
178 disable this flag, although a plugin that does not support trims as
179 a way to write zeroes may ignore the flag without violating
180 expected semantics.
181 "NBDKIT_FLAG_FUA"
183 This flag represents Forced Unit Access semantics. It is used by
184 the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
185 plugin must not return a result until the action has landed in
186 persistent storage. This flag will not be sent to the plugin
187 unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
188 The following defines are valid as successful return values for
190 ".can_fua":
191 "NBDKIT_FUA_NONE"
193 Forced Unit Access is not supported; the client must manually
194 request a flush after writes have completed. The "NBDKIT_FLAG_FUA"
195 flag will not be passed to the plugin's write callbacks.
196 "NBDKIT_FUA_EMULATE"
198 The client may request Forced Unit Access, but it is implemented by
199 emulation, where nbdkit calls ".flush" after a write operation;
200 this is semantically correct, but may hurt performance as it tends
201 to flush more data than just what the client requested. The
202 "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
203 callbacks.
204 "NBDKIT_FUA_NATIVE"
206 The client may request Forced Unit Access, which results in the
207 "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
208 (".pwrite", ".trim", and ".zero"). When the flag is set, these
209 callbacks must not return success until the client's request has
210 landed in persistent storage.
211 The following defines are valid as successful return values for
213 ".can_cache":
214 "NBDKIT_CACHE_NONE"
216 The server does not advertise caching support, and rejects any
217 client-requested caching. Any ".cache" callback is ignored.
218 "NBDKIT_CACHE_EMULATE"
220 The nbdkit server advertises cache support to the client, where the
221 client may request that the server cache a region of the export to
222 potentially speed up future read and/or write operations on that
223 region. The nbdkit server implements the caching by calling
224 ".pread" and ignoring the results. This option exists to ease the
225 implementation of a common form of caching; any ".cache" callback
226 is ignored.
227 "NBDKIT_CACHE_NATIVE"
229 The nbdkit server advertises cache support to the client, where the
230 client may request that the server cache a region of the export to
231 potentially speed up future read and/or write operations on that
232 region. The nbdkit server calls the ".cache" callback to perform
233 the caching; if that callback is missing, the client's cache
234 request succeeds without doing anything.
235
237 If there is an error in the plugin, the plugin should call
238 "nbdkit_error" to report an error message; additionally, if the
239 callback is involved in serving data, the plugin should call
240 "nbdkit_set_error" to influence the error code that will be sent to the
241 client. These two functions can be called in either order. Then, the
242 callback should return the appropriate error indication, eg. "NULL" or
243 "-1".
244 If the call to "nbdkit_set_error" is omitted while serving data, then
246 the global variable "errno" may be used. For plugins which have
247 ".errno_is_preserved != 0" the core code will use "errno". In plugins
248 written in non-C languages, we usually cannot trust that "errno" will
249 not be overwritten when returning from that language to C. In that
250 case, either the plugin must call "nbdkit_set_error" or hard-coded
251 "EIO" is used.
252 "nbdkit_error" has the following prototype and works like printf(3):
254 void nbdkit_error (const char *fs, ...);
256 void nbdkit_verror (const char *fs, va_list args);
257 For convenience, "nbdkit_error" preserves the value of "errno", and
259 also supports the glibc extension of a single %m in a format string
260 expanding to "strerror(errno)", even on platforms that don't support
261 that natively.
262 "nbdkit_set_error" can be called at any time, but only has an impact
264 during callbacks for serving data, and only when the callback returns
265 an indication of failure. It has the following prototype:
266 void nbdkit_set_error (int err);
268
270 ".name"
271 const char *name;
272 This field (a string) is required, and must contain only ASCII
274 alphanumeric characters and be unique amongst all plugins.
275 ".version"
277 const char *version;
278 Plugins may optionally set a version string which is displayed in help
280 and debugging output.
281 ".longname"
283 const char *longname;
284 An optional free text name of the plugin. This field is used in error
286 messages.
287 ".description"
289 const char *description;
290 An optional multi-line description of the plugin.
292 ".load"
294 void load (void);
295 This is called once just after the plugin is loaded into memory. You
297 can use this to perform any global initialization needed by the plugin.
298 ".unload"
300 void unload (void);
301 This may be called once just before the plugin is unloaded from memory.
303 Note that it's not guaranteed that ".unload" will always be called (eg.
304 the server might be killed or segfault), so you should try to make the
305 plugin as robust as possible by not requiring cleanup. See also
306 "SHUTDOWN" below.
307 ".dump_plugin"
309 void dump_plugin (void);
310 This optional callback is called when the "nbdkit plugin --dump-plugin"
312 command is used. It should print any additional informative
313 "key=value" fields to stdout as needed. Prefixing the keys with the
314 name of the plugin will avoid conflicts.
315 ".config"
317 int config (const char *key, const char *value);
318 On the nbdkit command line, after the plugin filename, come an optional
320 list of "key=value" arguments. These are passed to the plugin through
321 this callback when the plugin is first loaded and before any
322 connections are accepted.
323 This callback may be called zero or more times.
325 Both "key" and "value" parameters will be non-NULL. The strings are
327 owned by nbdkit but will remain valid for the lifetime of the plugin,
328 so the plugin does not need to copy them.
329 The key will be a non-empty string beginning with an ASCII alphabetic
331 character ("A-Z" "a-z"). The rest of the key must contain only ASCII
332 alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
333 "0-9" "." "_" "-"). The value may be an arbitrary string, including an
334 empty string.
335 The names of "key"s accepted by plugins is up to the plugin, but you
337 should probably look at other plugins and follow the same conventions.
338 If the value is a relative path, then note that the server changes
340 directory when it starts up. See "FILENAMES AND PATHS" above.
341 If the ".config" callback is not provided by the plugin, and the user
343 tries to specify any "key=value" arguments, then nbdkit will exit with
344 an error.
345 If there is an error, ".config" should call "nbdkit_error" with an
347 error message and return "-1".
348 ".magic_config_key"
350 const char *magic_config_key;
351 This optional string can be used to set a "magic" key used when parsing
353 plugin parameters. It affects how "bare parameters" (those which do
354 not contain an "=" character) are parsed on the command line.
355 If "magic_config_key != NULL" then any bare parameters are passed to
357 the ".config" method as: "config (magic_config_key, argv[i]);".
358 If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
360 the first parameter on the command line is bare then it is passed to
361 the ".config" method as: "config ("script", value);". Any other bare
362 parameters give errors.
363 ".config_complete"
365 int config_complete (void);
366 This optional callback is called after all the configuration has been
368 passed to the plugin. It is a good place to do checks, for example
369 that the user has passed the required parameters to the plugin.
370 If there is an error, ".config_complete" should call "nbdkit_error"
372 with an error message and return "-1".
373 ".config_help"
375 const char *config_help;
376 This optional multi-line help message should summarize any "key=value"
378 parameters that it takes. It does not need to repeat what already
379 appears in ".description".
380 If the plugin doesn't take any config parameters you should probably
382 omit this.
383 ".thread_model"
385 int thread_model (void)
386 This optional callback is called after all the configuration has been
388 passed to the plugin. It can be used to force a stricter thread model
389 based on configuration, compared to "THREAD_MODEL". See "THREADS"
390 below for details. Attempts to request a looser (more parallel) model
391 are silently ignored.
392 If there is an error, ".thread_model" should call "nbdkit_error" with
394 an error message and return "-1".
395 ".get_ready"
397 int get_ready (void);
398 This optional callback is called before the server starts serving. It
400 is called before the server forks or changes directory. It is the last
401 chance to do any global preparation that is needed to serve
402 connections.
403 If there is an error, ".get_ready" should call "nbdkit_error" with an
405 error message and return "-1".
406 ".preconnect"
408 int preconnect (int readonly);
409 This optional callback is called when a TCP connection has been made to
411 the server. This happens early, before NBD or TLS negotiation. If TLS
412 authentication is required to access the server, then it has not been
413 negotiated at this point.
414 For security reasons (to avoid denial of service attacks) this callback
416 should be written to be as fast and take as few resources as possible.
417 If you use this callback, only use it to do basic access control, such
418 as checking "nbdkit_peer_name" against a whitelist (see "PEER NAME" and
419 nbdkit-ip-filter(1)). It may be better to do access control outside
420 the server, for example using TCP wrappers or a firewall.
421 The "readonly" flag informs the plugin that the server was started with
423 the -r flag on the command line.
424 Returning 0 will allow the connection to continue. If there is an
426 error or you want to deny the connection, call "nbdkit_error" with an
427 error message and return "-1".
428 ".open"
430 void *open (int readonly);
431 This is called when a new client connects to the nbdkit server. The
433 callback should allocate a handle and return it. This handle is passed
434 back to other callbacks and could be freed in the ".close" callback.
435 Note that the handle is completely opaque to nbdkit, but it must not be
437 NULL. If you don't need to use a handle, return
438 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
439 The "readonly" flag informs the plugin that the server was started with
441 the -r flag on the command line which forces connections to be read-
442 only. Note that the plugin may additionally force the connection to be
443 readonly (even if this flag is false) by returning false from the
444 ".can_write" callback. So if your plugin can only serve read-only, you
445 can ignore this parameter.
446 This callback is called after the NBD handshake has completed, which
448 includes TLS authentication (if required). If the plugin defines a
449 ".preconnect" callback, then it must be called and return with success
450 before ".open" is called.
451 If there is an error, ".open" should call "nbdkit_error" with an error
453 message and return "NULL".
454 ".close"
456 void close (void *handle);
457 This is called when the client closes the connection. It should clean
459 up any per-connection resources.
460 Note there is no way in the NBD protocol to communicate close errors
462 back to the client, for example if your plugin calls close(2) and you
463 are checking for errors (as you should do). Therefore the best you can
464 do is to log the error on the server. Well-behaved NBD clients should
465 try to flush the connection before it is closed and check for errors,
466 but obviously this is outside the scope of nbdkit.
467 ".get_size"
469 int64_t get_size (void *handle);
470 This is called during the option negotiation phase of the protocol to
472 get the size (in bytes) of the block device being exported.
473 The returned size must be ≥ 0. If there is an error, ".get_size"
475 should call "nbdkit_error" with an error message and return "-1".
476 ".can_write"
478 int can_write (void *handle);
479 This is called during the option negotiation phase to find out if the
481 handle supports writes.
482 If there is an error, ".can_write" should call "nbdkit_error" with an
484 error message and return "-1".
485 This callback is not required. If omitted, then we return true iff a
487 ".pwrite" callback has been defined.
488 ".can_flush"
490 int can_flush (void *handle);
491 This is called during the option negotiation phase to find out if the
493 handle supports the flush-to-disk operation.
494 If there is an error, ".can_flush" should call "nbdkit_error" with an
496 error message and return "-1".
497 This callback is not required. If omitted, then we return true iff a
499 ".flush" callback has been defined.
500 ".is_rotational"
502 int is_rotational (void *handle);
503 This is called during the option negotiation phase to find out if the
505 backing disk is a rotational medium (like a traditional hard disk) or
506 not (like an SSD). If true, this may cause the client to reorder
507 requests to make them more efficient for a slow rotating disk.
508 If there is an error, ".is_rotational" should call "nbdkit_error" with
510 an error message and return "-1".
511 This callback is not required. If omitted, then we return false.
513 ".can_trim"
515 int can_trim (void *handle);
516 This is called during the option negotiation phase to find out if the
518 plugin supports the trim/discard operation for punching holes in the
519 backing storage.
520 If there is an error, ".can_trim" should call "nbdkit_error" with an
522 error message and return "-1".
523 This callback is not required. If omitted, then we return true iff a
525 ".trim" callback has been defined.
526 ".can_zero"
528 int can_zero (void *handle);
529 This is called during the option negotiation phase to find out if the
531 plugin wants the ".zero" callback to be utilized. Support for writing
532 zeroes is still advertised to the client (unless the
533 nbdkit-nozero-filter(1) is also used), so returning false merely serves
534 as a way to avoid complicating the ".zero" callback to have to fail
535 with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
536 be more efficient than using ".pwrite" up front.
537 If there is an error, ".can_zero" should call "nbdkit_error" with an
539 error message and return "-1".
540 This callback is not required. If omitted, then for a normal zero
542 request, nbdkit always tries ".zero" first if it is present, and
543 gracefully falls back to ".pwrite" if ".zero" was absent or failed with
544 "ENOTSUP" or "EOPNOTSUPP".
545 ".can_fast_zero"
547 int can_fast_zero (void *handle);
548 This is called during the option negotiation phase to find out if the
550 plugin wants to advertise support for fast zero requests. If this
551 support is not advertised, a client cannot attempt fast zero requests,
552 and has no way to tell if writing zeroes offers any speedups compared
553 to using ".pwrite" (other than compressed network traffic). If support
554 is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when
555 the client has requested a fast zero, in which case the plugin must
556 fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
557 offer any benefits over ".pwrite". Advertising support for fast zero
558 requests does not require that writing zeroes be fast, only that the
559 result (whether success or failure) is fast, so this should be
560 advertised when feasible.
561 If there is an error, ".can_fast_zero" should call "nbdkit_error" with
563 an error message and return "-1".
564 This callback is not required. If omitted, then nbdkit returns true if
566 ".zero" is absent or ".can_zero" returns false (in those cases, nbdkit
567 fails all fast zero requests, as its fallback to ".pwrite" is not
568 inherently faster), otherwise false (since it cannot be determined in
569 advance if the plugin's ".zero" will properly honor the semantics of
570 "NBDKIT_FLAG_FAST_ZERO").
571 ".can_extents"
573 int can_extents (void *handle);
574 This is called during the option negotiation phase to find out if the
576 plugin supports detecting allocated (non-sparse) regions of the disk
577 with the ".extents" callback.
578 If there is an error, ".can_extents" should call "nbdkit_error" with an
580 error message and return "-1".
581 This callback is not required. If omitted, then we return true iff a
583 ".extents" callback has been defined.
584 ".can_fua"
586 int can_fua (void *handle);
587 This is called during the option negotiation phase to find out if the
589 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
590 trim requests. If this returns "NBDKIT_FUA_NONE", FUA support is not
591 advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
592 ".flush" callback must work (even if ".can_flush" returns false), and
593 FUA support is emulated by calling ".flush" after any write operation;
594 if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
595 ".trim" callbacks (if implemented) must handle the flag
596 "NBDKIT_FLAG_FUA", by not returning until that action has landed in
597 persistent storage.
598 If there is an error, ".can_fua" should call "nbdkit_error" with an
600 error message and return "-1".
601 This callback is not required unless a plugin wants to specifically
603 handle FUA requests. If omitted, nbdkit checks whether ".flush"
604 exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
605 "NBDKIT_FUA_EMULATE" as appropriate.
606 ".can_multi_conn"
608 int can_multi_conn (void *handle);
609 This is called during the option negotiation phase to find out if the
611 plugin is prepared to handle multiple connections from a single client.
612 If the plugin sets this to true then a client may try to open multiple
613 connections to the nbdkit server and spread requests across all
614 connections to maximize parallelism. If the plugin sets it to false
615 (which is the default) then well-behaved clients should only open a
616 single connection, although we cannot control what clients do in
617 practice.
618 Specifically it means that either the plugin does not cache requests at
620 all. Or if it does cache them then the effects of a ".flush" request
621 or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
622 connections to the plugin before the plugin replies to that request.
623 Properly working clients should send the same export name for each of
625 these connections.
626 If you use Linux nbd-client(8) option -C num with num > 1 then Linux
628 checks this flag and will refuse to connect if ".can_multi_conn" is
629 false.
630 If there is an error, ".can_multi_conn" should call "nbdkit_error" with
632 an error message and return "-1".
633 This callback is not required. If omitted, then we return false.
635 ".can_cache"
637 int can_cache (void *handle);
638 This is called during the option negotiation phase to find out if the
640 plugin supports a cache operation. The nature of the caching is
641 unspecified (including whether there are limits on how much can be
642 cached at once, and whether writes to a cached region have write-
643 through or write-back semantics), but the command exists to let clients
644 issue a hint to the server that they will be accessing that region of
645 the export.
646 If this returns "NBDKIT_CACHE_NONE", cache support is not advertised to
648 the client; if this returns "NBDKIT_CACHE_EMULATE", caching is emulated
649 by the server calling ".pread" and ignoring the results; if this
650 returns "NBDKIT_CACHE_NATIVE", then the ".cache" callback will be used.
651 If there is an error, ".can_cache" should call "nbdkit_error" with an
652 error message and return "-1".
653 This callback is not required. If omitted, then we return
655 "NBDKIT_CACHE_NONE" if the ".cache" callback is missing, or
656 "NBDKIT_CACHE_NATIVE" if it is defined.
657 ".pread"
659 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
660 uint32_t flags);
661 During the data serving phase, nbdkit calls this callback to read data
663 from the backing store. "count" bytes starting at "offset" in the
664 backing store should be read and copied into "buf". nbdkit takes care
665 of all bounds- and sanity-checking, so the plugin does not need to
666 worry about that.
667 The parameter "flags" exists in case of future NBD protocol extensions;
669 at this time, it will be 0 on input.
670 The callback must read the whole "count" bytes if it can. The NBD
672 protocol doesn't allow partial reads (instead, these would be errors).
673 If the whole "count" bytes was read, the callback should return 0 to
674 indicate there was no error.
675 If there is an error (including a short read which couldn't be
677 recovered from), ".pread" should call "nbdkit_error" with an error
678 message, and "nbdkit_set_error" to record an appropriate error (unless
679 "errno" is sufficient), then return "-1".
680 ".pwrite"
682 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
683 uint32_t flags);
684 During the data serving phase, nbdkit calls this callback to write data
686 to the backing store. "count" bytes starting at "offset" in the
687 backing store should be written using the data in "buf". nbdkit takes
688 care of all bounds- and sanity-checking, so the plugin does not need to
689 worry about that.
690 This function will not be called if ".can_write" returned false. The
692 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
693 result of ".can_fua".
694 The callback must write the whole "count" bytes if it can. The NBD
696 protocol doesn't allow partial writes (instead, these would be errors).
697 If the whole "count" bytes was written successfully, the callback
698 should return 0 to indicate there was no error.
699 If there is an error (including a short write which couldn't be
701 recovered from), ".pwrite" should call "nbdkit_error" with an error
702 message, and "nbdkit_set_error" to record an appropriate error (unless
703 "errno" is sufficient), then return "-1".
704 ".flush"
706 int flush (void *handle, uint32_t flags);
707 During the data serving phase, this callback is used to fdatasync(2)
709 the backing store, ie. to ensure it has been completely written to a
710 permanent medium. If that is not possible then you can omit this
711 callback.
712 This function will not be called directly by the client if ".can_flush"
714 returned false; however, it may still be called by nbdkit if ".can_fua"
715 returned "NBDKIT_FUA_EMULATE". The parameter "flags" exists in case of
716 future NBD protocol extensions; at this time, it will be 0 on input.
717 If there is an error, ".flush" should call "nbdkit_error" with an error
719 message, and "nbdkit_set_error" to record an appropriate error (unless
720 "errno" is sufficient), then return "-1".
721 ".trim"
723 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
724 During the data serving phase, this callback is used to "punch holes"
726 in the backing store. If that is not possible then you can omit this
727 callback.
728 This function will not be called if ".can_trim" returned false. The
730 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
731 result of ".can_fua".
732 If there is an error, ".trim" should call "nbdkit_error" with an error
734 message, and "nbdkit_set_error" to record an appropriate error (unless
735 "errno" is sufficient), then return "-1".
736 ".zero"
738 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
739 During the data serving phase, this callback is used to write "count"
741 bytes of zeroes at "offset" in the backing store.
742 This function will not be called if ".can_zero" returned false. On
744 input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
745 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
746 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
747 If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
749 instead of writing actual zero bytes, but only if subsequent reads from
750 the hole read as zeroes.
751 If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up
753 front if the implementation is likely to be faster than a corresponding
754 ".pwrite"; if not, then it must immediately fail with "ENOTSUP" or
755 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno") and preferably
756 without modifying the exported image. It is acceptable to always fail
757 a fast zero request (as a fast failure is better than attempting the
758 write only to find out after the fact that it was not fast after all).
759 Note that on Linux, support for "ioctl(BLKZEROOUT)" is insufficient for
760 determining whether a zero request to a block device will be fast
761 (because the kernel will perform a slow fallback when needed).
762 The callback must write the whole "count" bytes if it can. The NBD
764 protocol doesn't allow partial writes (instead, these would be errors).
765 If the whole "count" bytes was written successfully, the callback
766 should return 0 to indicate there was no error.
767 If there is an error, ".zero" should call "nbdkit_error" with an error
769 message, and "nbdkit_set_error" to record an appropriate error (unless
770 "errno" is sufficient), then return "-1".
771 If this callback is omitted, or if it fails with "ENOTSUP" or
773 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then ".pwrite"
774 will be used as an automatic fallback except when the client requested
775 a fast zero.
776 ".extents"
778 int extents (void *handle, uint32_t count, uint64_t offset,
779 uint32_t flags, struct nbdkit_extents *extents);
780 During the data serving phase, this callback is used to detect
782 allocated, sparse and zeroed regions of the disk.
783 This function will not be called if ".can_extents" returned false.
785 nbdkit's default behaviour in this case is to treat the whole virtual
786 disk as if it was allocated. Also, this function will not be called by
787 a client that does not request structured replies (the --no-sr option
788 of nbdkit can be used to test behavior when ".extents" is unavailable
789 to the client).
790 The callback should detect and return the list of extents overlapping
792 the range "[offset...offset+count-1]". The "extents" parameter points
793 to an opaque object which the callback should fill in by calling
794 "nbdkit_add_extent". See "Extents list" below.
795 If there is an error, ".extents" should call "nbdkit_error" with an
797 error message, and "nbdkit_set_error" to record an appropriate error
798 (unless "errno" is sufficient), then return "-1".
799 Extents list
801 The plugin "extents" callback is passed an opaque pointer "struct
803 nbdkit_extents *extents". This structure represents a list of
804 filesystem extents describing which areas of the disk are allocated,
805 which are sparse (“holes”), and, if supported, which are zeroes.
806 The "extents" callback should scan the disk starting at "offset" and
808 call "nbdkit_add_extent" for each extent found.
809 Extents overlapping the range "[offset...offset+count-1]" should be
811 returned if possible. However nbdkit ignores extents < offset so the
812 plugin may, if it is easier to implement, return all extent information
813 for the whole disk. The plugin may return extents beyond the end of
814 the range. It may also return extent information for less than the
815 whole range, but it must return at least one extent overlapping
816 "offset".
817 The extents must be added in ascending order, and must be contiguous.
819 The "flags" parameter of the ".extents" callback may contain the flag
821 "NBDKIT_FLAG_REQ_ONE". This means that the client is only requesting
822 information about the extent overlapping "offset". The plugin may
823 ignore this flag, or as an optimization it may return just a single
824 extent for "offset".
825 int nbdkit_add_extent (struct nbdkit_extents *extents,
827 uint64_t offset, uint64_t length, uint32_t type);
828 Add an extent covering "[offset...offset+length-1]" of one of the
830 following four types:
831 "type = 0"
833 A normal, allocated data extent.
834 "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
836 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
837 This is the normal type of hole applicable to most disks.
838 "type = NBDKIT_EXTENT_ZERO"
840 An allocated extent which is known to contain only zeroes.
841 "type = NBDKIT_EXTENT_HOLE"
843 An unallocated extent (hole) which does not read back as zeroes.
844 Note this should only be used in specialized circumstances such as
845 when writing a plugin for (or to emulate) certain SCSI drives which
846 do not guarantee that trimmed blocks read back as zeroes.
847 "nbdkit_add_extent" returns 0 on success or "-1" on failure. On
849 failure "nbdkit_error" and/or "nbdkit_set_error" has already been
850 called. "errno" will be set to a suitable value.
851 ".cache"
853 int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
854 During the data serving phase, this callback is used to give the plugin
856 a hint that the client intends to make further accesses to the given
857 region of the export. The nature of caching is not specified further
858 by the NBD specification (for example, a server may place limits on how
859 much may be cached at once, and there is no way to control if writes to
860 a cached area have write-through or write-back semantics). In fact,
861 the cache command can always fail and still be compliant, and success
862 might not guarantee a performance gain. If this callback is omitted,
863 then the results of ".can_cache" determine whether nbdkit will reject
864 cache requests, treat them as instant success, or emulate caching by
865 calling ".pread" over the same region and ignoring the results.
866 This function will not be called if ".can_cache" did not return
868 "NBDKIT_CACHE_NATIVE". The parameter "flags" exists in case of future
869 NBD protocol extensions; at this time, it will be 0 on input. A plugin
870 must fail this function if "flags" includes an unrecognized flag, as
871 that may indicate a requirement that the plugin comply must with a
872 specific caching semantic.
873 If there is an error, ".cache" should call "nbdkit_error" with an error
875 message, and "nbdkit_set_error" to record an appropriate error (unless
876 "errno" is sufficient), then return "-1".
877
879 The plugin struct also contains an integer field used as a boolean in C
880 code, but unlikely to be exposed in other language bindings:
881 ".errno_is_preserved"
883 This defaults to 0; if non-zero, nbdkit can reliably use the value
884 of "errno" when a callback reports failure, rather than the plugin
885 having to call "nbdkit_set_error".
886
888 Each nbdkit plugin must declare its maximum thread safety model by
889 defining the "THREAD_MODEL" macro. (This macro is used by
890 "NBDKIT_REGISTER_PLUGIN"). Additionally, a plugin may implement the
891 ".thread_model" callback, called right after ".config_complete" to make
892 a runtime decision on which thread model to use. The nbdkit server
893 chooses the most restrictive model between the plugin's "THREAD_MODEL",
894 the ".thread_model" if present, any restrictions requested by filters,
895 and any limitations imposed by the system (for example, a system
896 without atomic "FD_CLOEXEC" will serialize all requests, so as to avoid
897 nbdkit leaking a new file descriptor from one thread into a child
898 process created by another thread).
899 In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line
901 matches the "THREAD_MODEL" macro, and the "thread_model" line matches
902 what the system finally settled on after applying all restrictions.
903 The possible settings for "THREAD_MODEL" are defined below.
905 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
907 Only a single handle can be open at any time, and all requests
908 happen from one thread.
909 Note this means only one client can connect to the server at any
911 time. If a second client tries to connect it will block waiting
912 for the first client to close the connection.
913 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
915 This is a safe default for most plugins.
916 Multiple handles can be open at the same time, but requests are
918 serialized so that for the plugin as a whole only one
919 open/read/write/close (etc) request will be in progress at any
920 time.
921 This is a useful setting if the library you are using is not
923 thread-safe. However performance may not be good.
924 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
926 Multiple handles can be open and multiple data requests can happen
927 in parallel. However only one request will happen per handle at a
928 time (but requests on different handles might happen concurrently).
929 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
931 Multiple handles can be open and multiple data requests can happen
932 in parallel (even on the same handle). The server may reorder
933 replies, answering a later request before an earlier one.
934 All the libraries you use must be thread-safe and reentrant, and
936 any code that creates a file descriptor should atomically set
937 "FD_CLOEXEC" if you do not want it accidentally leaked to another
938 thread's child process. You may also need to provide mutexes for
939 fields in your connection handle.
940 If none of the above thread models are suitable, then use
942 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
943 "pthread_mutex_t" etc.
944
946 When nbdkit receives certain signals it will shut down (see "SIGNALS"
947 in nbdkit(1)). The server will wait for any currently running plugin
948 callbacks to finish and also call the ".unload" callback before
949 unloading the plugin.
950 Note that it's not guaranteed this can always happen (eg. the server
952 might be killed by "SIGKILL" or segfault).
953
955 Parsing numbers
956 There are several functions for parsing numbers. These all deal
957 correctly with overflow, out of range and parse errors, and you should
958 use them instead of unsafe functions like sscanf(3), atoi(3) and
959 similar.
960 int nbdkit_parse_int (const char *what, const char *str, int *r);
962 int nbdkit_parse_unsigned (const char *what,
963 const char *str, unsigned *r);
964 int nbdkit_parse_int8_t (const char *what,
965 const char *str, int8_t *r);
966 int nbdkit_parse_uint8_t (const char *what,
967 const char *str, uint8_t *r);
968 int nbdkit_parse_int16_t (const char *what,
969 const char *str, int16_t *r);
970 int nbdkit_parse_uint16_t (const char *what,
971 const char *str, uint16_t *r);
972 int nbdkit_parse_int32_t (const char *what,
973 const char *str, int32_t *r);
974 int nbdkit_parse_uint32_t (const char *what,
975 const char *str, uint32_t *r);
976 int nbdkit_parse_int64_t (const char *what,
977 const char *str, int64_t *r);
978 int nbdkit_parse_uint64_t (const char *what,
979 const char *str, uint64_t *r);
980 Parse string "str" into an integer of various types. These functions
982 parse a decimal, hexadecimal ("0x...") or octal ("0...") number.
983 On success the functions return 0 and set *r to the parsed value
985 (unless "*r == NULL" in which case the result is discarded). On error,
986 "nbdkit_error" is called and the functions return "-1". On error *r is
987 always unchanged.
988 The "what" parameter is printed in error messages to provide context.
990 It should usually be a short descriptive string of what you are trying
991 to parse, eg:
992 if (nbdkit_parse_int ("random seed", argv[1], &seed) == -1)
994 return -1;
995 might print an error:
997 random seed: could not parse number: "lalala"
999 Parsing sizes
1001 Use the "nbdkit_parse_size" utility function to parse human-readable
1002 size strings such as "100M" into the size in bytes.
1003 int64_t nbdkit_parse_size (const char *str);
1005 "str" can be a string in a number of common formats. The function
1007 returns the size in bytes. If there was an error, it returns "-1".
1008 Parsing booleans
1010 Use the "nbdkit_parse_bool" utility function to parse human-readable
1011 strings such as "on" into a boolean value.
1012 int nbdkit_parse_bool (const char *str);
1014 "str" can be a string containing a case-insensitive form of various
1016 common toggle values. The function returns 0 or 1 if the parse was
1017 successful. If there was an error, it returns "-1".
1018 Reading passwords
1020 The "nbdkit_read_password" utility function can be used to read
1021 passwords from config parameters:
1022 int nbdkit_read_password (const char *value, char **password);
1024 For example:
1026 char *password = NULL;
1028 static int
1030 myplugin_config (const char *key, const char *value)
1031 {
1032 ..
1033 if (strcmp (key, "password") == 0) {
1034 free (password);
1035 if (nbdkit_read_password (value, &password) == -1)
1036 return -1;
1037 }
1038 ..
1039 }
1040 The "password" result string is allocated by malloc, and so you may
1042 need to free it.
1043 This function recognizes several password formats. A password may be
1045 used directly on the command line, eg:
1046 nbdkit myplugin password=mostsecret
1048 But more securely this function can also read a password interactively:
1050 nbdkit myplugin password=-
1052 or from a file:
1054 nbdkit myplugin password=+/tmp/secret
1056 or from a file descriptor inherited by nbdkit:
1058 nbdkit myplugin password=-99
1060 (If the password begins with a "-" or "+" character then it must be
1062 passed in a file).
1063
1065 The server usually (not always) changes directory to "/" before it
1066 starts serving connections. This means that any relative paths passed
1067 during configuration will not work when the server is running (example:
1068 "nbdkit plugin.so disk.img").
1069 To avoid problems, prepend relative paths with the current directory
1071 before storing them in the handle. Or open files and store the file
1072 descriptor.
1073 "nbdkit_absolute_path"
1075 char *nbdkit_absolute_path (const char *filename);
1076 The utility function "nbdkit_absolute_path" converts any path to an
1078 absolute path: if it is relative, then all this function does is
1079 prepend the current working directory to the path, with no extra
1080 checks.
1081 Note that this function works only when used in the ".config",
1083 ".config_complete" and ".get_ready" callbacks.
1084 If conversion was not possible, this calls "nbdkit_error" and returns
1086 "NULL". Note that this function does not check that the file exists.
1087 The returned string must be freed by the caller.
1089 "nbdkit_realpath"
1091 char *nbdkit_realpath (const char *filename);
1092 The utility function "nbdkit_realpath" converts any path to an absolute
1094 path, resolving symlinks. Under the hood it uses the "realpath"
1095 function, and thus it fails if the path does not exist, or it is not
1096 possible to access to any of the components of the path.
1097 Note that this function works only when used in the ".config",
1099 ".config_complete" and ".get_ready" callbacks.
1100 If the path resolution was not possible, this calls "nbdkit_error" and
1102 returns "NULL".
1103 The returned string must be freed by the caller.
1105 umask
1107 All plugins will see a umask(2) of 0022.
1108
1110 A plugin that needs to sleep may call sleep(2), nanosleep(2) and
1111 similar. However that can cause nbdkit to delay excessively when
1112 shutting down (since it must wait for any plugin or filter which is
1113 sleeping). To avoid this there is a special wrapper around nanosleep
1114 which plugins and filters should use instead.
1115 "nbdkit_nanosleep"
1117 int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1118 The utility function "nbdkit_nanosleep" suspends the current thread,
1120 and returns 0 if it slept at least as many seconds and nanoseconds as
1121 requested, or -1 after calling "nbdkit_error" if there is no point in
1122 continuing the current command. Attempts to sleep more than "INT_MAX"
1123 seconds are treated as an error.
1124
1126 If the client negotiated an NBD export name with nbdkit then plugins
1127 may read this from any connected callbacks. Nbdkit's normal behaviour
1128 is to accept any export name passed by the client, log it in debug
1129 output, but otherwise ignore it. By using "nbdkit_export_name" plugins
1130 may choose to filter by export name or serve different content.
1131 "nbdkit_export_name"
1133 const char *nbdkit_export_name (void);
1134 Return the optional NBD export name if one was negotiated with the
1136 current client (this uses thread-local magic so no parameter is
1137 required). The returned string is only valid while the client is
1138 connected, so if you need to store it in the plugin you must copy it.
1139 The export name is a free-form text string, it is not necessarily a
1141 path or filename and it does not need to begin with a '/' character.
1142 The NBD protocol describes the empty string ("") as a representing a
1143 "default export" or to be used in cases where the export name does not
1144 make sense. The export name is untrusted client data, be cautious when
1145 parsing it.
1146 On error, "nbdkit_error" is called and the call returns "NULL".
1148
1150 It is possible to get the address of the client when you are running in
1151 any connected callback.
1152 "nbdkit_peer_name"
1154 int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1155 Return the peer (client) address, if available. The "addr" and
1157 "addrlen" parameters behave like getpeername(2). In particular you
1158 must initialize "addrlen" with the size of the buffer pointed to by
1159 "addr", and if "addr" is not large enough then the address will be
1160 truncated.
1161 In some cases this is not available or the address returned will be
1163 meaningless (eg. if there is a proxy between the client and nbdkit).
1164 This call uses thread-local magic so no parameter is required to
1165 specify the current connection.
1166 On success this returns 0. On error, "nbdkit_error" is called and this
1168 call returns "-1".
1169
1171 Run the server with -f and -v options so it doesn't fork and you can
1172 see debugging information:
1173 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1175 To print debugging information from within the plugin, call
1177 "nbdkit_debug", which has the following prototype and works like
1178 printf(3):
1179 void nbdkit_debug (const char *fs, ...);
1181 void nbdkit_vdebug (const char *fs, va_list args);
1182 For convenience, "nbdkit_debug" preserves the value of "errno", and
1184 also supports the glibc extension of a single %m in a format string
1185 expanding to "strerror(errno)", even on platforms that don't support
1186 that natively. Note that "nbdkit_debug" only prints things when the
1187 server is in verbose mode (-v option).
1188 Debug Flags
1190 The -v option switches general debugging on or off, and this debugging
1191 should be used for messages which are useful for all users of your
1192 plugin.
1193 In cases where you want to enable specific extra debugging to track
1195 down bugs in plugins or filters — mainly for use by the plugin/filter
1196 developers themselves — you can define Debug Flags. These are global
1197 ints called "myplugin_debug_*":
1198 int myplugin_debug_foo;
1200 int myplugin_debug_bar;
1201 ...
1202 if (myplugin_debug_foo) {
1203 nbdkit_debug ("lots of extra debugging about foo: ...");
1204 }
1205 Debug Flags can be controlled on the command line using the -D (or
1207 --debug) option:
1208 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1210 Note "myplugin" is the name passed to ".name" in the "struct
1212 nbdkit_plugin".
1213 You should only use this feature for debug settings. For general
1215 settings use ordinary plugin parameters. Debug Flags can only be C
1216 ints. They are not supported by non-C language plugins.
1217 For convenience '.' characters are replaced with '_' characters in the
1219 variable name, so both of these parameters:
1220 -D myplugin.foo_bar=1
1222 -D myplugin.foo.bar=1
1223 correspond to the plugin variable "myplugin_debug_foo_bar".
1225
1227 The plugin is a "*.so" file and possibly a manual page. You can of
1228 course install the plugin "*.so" file wherever you want, and users will
1229 be able to use it by running:
1230 nbdkit /path/to/plugin.so [args]
1232 However if the shared library has a name of the form
1234 "nbdkit-name-plugin.so" and if the library is installed in the
1235 $plugindir directory, then users can be run it by only typing:
1236 nbdkit name [args]
1238 The location of the $plugindir directory is set when nbdkit is compiled
1240 and can be found by doing:
1241 nbdkit --dump-config
1243 If using the pkg-config/pkgconf system then you can also find the
1245 plugin directory at compile time by doing:
1246 pkg-config nbdkit --variable=plugindir
1248
1250 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
1251 should be installed on the correct path when the nbdkit plugin
1252 development environment is installed. You can use this in autoconf
1253 configure.ac scripts to test for the development environment:
1254 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1256 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
1258 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
1259 for compiling plugins.
1260 You can also run pkg-config/pkgconf directly, for example:
1262 if ! pkg-config nbdkit --exists; then
1264 echo "you must install the nbdkit plugin development environment"
1265 exit 1
1266 fi
1267 You can also substitute the plugindir variable by doing:
1269 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1271 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
1273
1275 You can also write nbdkit plugins in Lua, OCaml, Perl, Python, Ruby,
1276 Rust, shell script or Tcl. Other programming languages may be offered
1277 in future.
1278 For more information see: nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
1280 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
1281 nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1282 Plugins written in scripting languages may also be installed in
1284 $plugindir. These must be called "nbdkit-name-plugin" without any
1285 extension. They must be executable, and they must use the shebang
1286 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
1287 written in Perl called "foo.pl" might be installed like this:
1288 $ head -1 foo.pl
1290 #!/usr/sbin/nbdkit perl
1291 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1293 and then users will be able to run it like this:
1295 $ nbdkit foo [args ...]
1297
1299 nbdkit(1), nbdkit-nozero-filter(3), nbdkit-filter(3).
1300 Standard plugins provided by nbdkit:
1302 nbdkit-curl-plugin(1), nbdkit-data-plugin(1), nbdkit-eval-plugin(1),
1304 nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
1305 nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
1306 nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
1307 nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1), nbdkit-gzip-plugin(1),
1308 nbdkit-info-plugin(1), nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
1309 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
1310 nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
1311 nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
1312 nbdkit-random-plugin(1), nbdkit-split-plugin(1), nbdkit-ssh-plugin(1),
1313 nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
1314 nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-lua-plugin(3),
1315 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
1316 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
1317 nbdkit-tcl-plugin(3) .
1318
1320 Eric Blake
1321 Richard W.M. Jones
1323 Pino Toscano
1325
1327 Copyright (C) 2013-2018 Red Hat Inc.
1328
1330 Redistribution and use in source and binary forms, with or without
1331 modification, are permitted provided that the following conditions are
1332 met:
1333 · Redistributions of source code must retain the above copyright
1335 notice, this list of conditions and the following disclaimer.
1336 · Redistributions in binary form must reproduce the above copyright
1338 notice, this list of conditions and the following disclaimer in the
1339 documentation and/or other materials provided with the
1340 distribution.
1341 · Neither the name of Red Hat nor the names of its contributors may
1343 be used to endorse or promote products derived from this software
1344 without specific prior written permission.
1345 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1347 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1348 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1349 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1350 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1351 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1352 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1353 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1354 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1355 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1356 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1357nbdkit-1.18.4 2020-04-16 nbdkit-plugin(3)