1nbdkit-plugin(3) nbdkit nbdkit-plugin(3)
2
6 nbdkit-plugin - How to write nbdkit plugins
7
9 #include <nbdkit-plugin.h>
10 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
12 static void *
14 myplugin_open (void)
15 {
16 /* create a handle ... */
17 return handle;
18 }
19 static struct nbdkit_plugin plugin = {
21 .name = "myplugin",
22 .open = myplugin_open,
23 .get_size = myplugin_get_size,
24 .pread = myplugin_pread,
25 .pwrite = myplugin_pwrite,
26 /* etc */
27 };
28 NBDKIT_REGISTER_PLUGIN(plugin)
30 When this has been compiled to a shared library, do:
32 nbdkit [--args ...] ./myplugin.so [key=value ...]
34 When debugging, use the -fv options:
36 nbdkit -fv ./myplugin.so [key=value ...]
38
40 An nbdkit plugin is a new source device which can be served using the
41 Network Block Device (NBD) protocol. This manual page describes how to
42 create an nbdkit plugin in C.
43 For example plugins, take a look at the source of nbdkit, in the
45 "plugins" directory.
46 To write plugins in other languages, see: nbdkit-ocaml-plugin(3),
48 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3).
49
51 All plugins should start by including this header file:
52 #include <nbdkit-plugin.h>
54
56 All plugins must define a thread model. See "THREADS" below for
57 details. It is generally safe to use:
58 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
60
62 All plugins must define and register one "struct nbdkit_plugin", which
63 contains the name of the plugin and pointers to callback functions.
64 static struct nbdkit_plugin plugin = {
66 .name = "myplugin",
67 .longname = "My Plugin",
68 .description = "This is my great plugin for nbdkit",
69 .open = myplugin_open,
70 .get_size = myplugin_get_size,
71 .pread = myplugin_pread,
72 .pwrite = myplugin_pwrite,
73 /* etc */
74 };
75 NBDKIT_REGISTER_PLUGIN(plugin)
77 The ".name" field is the name of the plugin.
79 The callbacks are described below (see "CALLBACKS"). Only ".name",
81 ".open", ".get_size" and ".pread" are required. All other callbacks
82 can be omitted. However almost all plugins should have a ".close"
83 callback. Most real-world plugins will also want to declare some of
84 the other callbacks.
85 The nbdkit server calls the callbacks in the following order over the
87 lifetime of the plugin:
88 ".load"
90 is called once just after the plugin is loaded into memory.
91 ".config" and ".config_complete"
93 ".config" is called zero or more times during command line parsing.
94 ".config_complete" is called once after all configuration
95 information has been passed to the plugin.
96 Both are called after loading the plugin but before any connections
98 are accepted.
99 ".open"
101 A new client has connected.
102 ".can_write", ".get_size" and other option negotiation callbacks
104 These are called during option negotiation with the client, but
105 before any data is served.
106 ".pread", ".pwrite" and other data serving callbacks
108 After option negotiation has finished, these may be called to serve
109 data. Depending on the thread model chosen, they might be called
110 in parallel from multiple threads.
111 ".close"
113 The client has disconnected.
114 ".open" ... ".close"
116 The sequence ".open" ... ".close" can be called repeatedly over the
117 lifetime of the plugin, and can be called in parallel (depending on
118 the thread model).
119 ".unload"
121 is called once just before the plugin is unloaded from memory.
122
124 If there is an error in the plugin, the plugin should call
125 "nbdkit_error" to report an error message; additionally, if the
126 callback is involved in serving data, the plugin should call
127 "nbdkit_set_error" to influence the error code that will be sent to the
128 client. These two functions can be called in either order. Then, the
129 callback should return the appropriate error indication, eg. "NULL" or
130 "-1".
131 If the call to "nbdkit_set_error" is omitted while serving data, then
133 the global variable "errno" may be used. For plugins which have
134 ".errno_is_preserved == 1" the core code will use "errno". In plugins
135 written in non-C languages, we usually cannot trust that "errno" will
136 not be overwritten when returning from that language to C. In that
137 case, either the plugin must call "nbdkit_set_error" or hard-coded
138 "EIO" is used.
139 "nbdkit_error" has the following prototype and works like printf(3):
141 void nbdkit_error (const char *fs, ...);
143 void nbdkit_verror (const char *fs, va_list args);
144 For convenience, "nbdkit_error" preserves the value of "errno".
146 "nbdkit_set_error" can be called at any time, but only has an impact
148 during callbacks for serving data, and only when the callback returns
149 an indication of failure. It has the following prototype:
150 void nbdkit_set_error (int err);
152
154 The server usually (not always) changes directory to "/" before it
155 starts serving connections. This means that any relative paths passed
156 during configuration will not work when the server is running (example:
157 "nbdkit plugin.so file=disk.img").
158 To avoid problems, prepend relative paths with the current directory
160 before storing them in the handle. Or open files and store the file
161 descriptor.
162 "nbdkit_absolute_path"
164 char *nbdkit_absolute_path (const char *filename);
165 The utility function "nbdkit_absolute_path" converts any path to an
167 absolute path: if it is relative, then all this function does is
168 prepend the current working directory to the path, with no extra
169 checks.
170 Note that this function works only when used in the ".config", and
172 ".config_complete" callbacks.
173 If conversion was not possible, this calls "nbdkit_error" and returns
175 "NULL". Note that this function does not check that the file exists.
176 The returned string must be freed by the caller.
178
180 ".name"
181 const char *name;
182 This field (a string) is required, and must contain only ASCII
184 alphanumeric characters and be unique amongst all plugins.
185 ".version"
187 const char *version;
188 Plugins may optionally set a version string which is displayed in help
190 and debugging output.
191 ".longname"
193 const char *longname;
194 An optional free text name of the plugin. This field is used in error
196 messages.
197 ".description"
199 const char *description;
200 An optional multi-line description of the plugin.
202 ".load"
204 void load (void);
205 This is called once just after the plugin is loaded into memory. You
207 can use this to perform any global initialization needed by the plugin.
208 ".unload"
210 void unload (void);
211 This may be called once just before the plugin is unloaded from memory.
213 Note that it's not guaranteed that ".unload" will always be called (eg.
214 the server might be killed or segfault), so you should try to make the
215 plugin as robust as possible by not requiring cleanup. See also
216 "SHUTDOWN" below.
217 ".dump_plugin"
219 void dump_plugin (void);
220 This optional callback is called when the "nbdkit plugin --dump-plugin"
222 command is used. It should print any additional informative
223 "key=value" fields to stdout as needed. Prefixing the keys with the
224 name of the plugin will avoid conflicts.
225 ".config"
227 int config (const char *key, const char *value);
228 On the nbdkit command line, after the plugin filename, come an optional
230 list of "key=value" arguments. These are passed to the plugin through
231 this callback when the plugin is first loaded and before any
232 connections are accepted.
233 This callback may be called zero or more times. Both "key" and "value"
235 parameters will be non-NULL, but it is possible for either to be empty
236 strings. The strings are owned by nbdkit but will remain valid for the
237 lifetime of the plugin, so the plugin does not need to copy them.
238 The format of the "key" accepted by plugins is up to the plugin, but
240 you should probably look at other plugins and follow the same
241 conventions.
242 If the value is a relative path, then note that the server changes
244 directory when it starts up. See "FILENAMES AND PATHS" above.
245 If the ".config" callback is not provided by the plugin, and the user
247 tries to specify any "key=value" arguments, then nbdkit will exit with
248 an error.
249 If there is an error, ".config" should call "nbdkit_error" with an
251 error message and return "-1".
252 ".config_complete"
254 int config_complete (void);
255 This optional callback is called after all the configuration has been
257 passed to the plugin. It is a good place to do checks, for example
258 that the user has passed the required parameters to the plugin.
259 If there is an error, ".config_complete" should call "nbdkit_error"
261 with an error message and return "-1".
262 ".config_help"
264 const char *config_help;
265 This optional multi-line help message should summarize any "key=value"
267 parameters that it takes. It does not need to repeat what already
268 appears in ".description".
269 If the plugin doesn't take any config parameters you should probably
271 omit this.
272 ".open"
274 void *open (int readonly);
275 This is called when a new client connects to the nbdkit server. The
277 callback should allocate a handle and return it. This handle is passed
278 back to other callbacks and could be freed in the ".close" callback.
279 Note that the handle is completely opaque to nbdkit, but it must not be
281 NULL.
282 The "readonly" flag informs the plugin that the user requested a read-
284 only connection using the -r flag on the command line. Note that the
285 plugin may additionally force the connection to be readonly (even if
286 this flag is false) by returning false from the ".can_write" callback.
287 So if your plugin can only serve read-only, you can ignore this
288 parameter.
289 If there is an error, ".open" should call "nbdkit_error" with an error
291 message and return "NULL".
292 ".close"
294 void close (void *handle);
295 This is called when the client closes the connection. It should clean
297 up any per-connection resources.
298 Note there is no way in the NBD protocol to communicate close errors
300 back to the client, for example if your plugin calls close(2) and you
301 are checking for errors (as you should do). Therefore the best you can
302 do is to log the error on the server. Well-behaved NBD clients should
303 try to flush the connection before it is closed and check for errors,
304 but obviously this is outside the scope of nbdkit.
305 ".get_size"
307 int64_t get_size (void *handle);
308 This is called during the option negotiation phase of the protocol to
310 get the size (in bytes) of the block device being exported.
311 The returned size must be ≥ 0. If there is an error, ".get_size"
313 should call "nbdkit_error" with an error message and return "-1".
314 ".can_write"
316 int can_write (void *handle);
317 This is called during the option negotiation phase to find out if the
319 handle supports writes.
320 If there is an error, ".can_write" should call "nbdkit_error" with an
322 error message and return "-1".
323 This callback is not required. If omitted, then we return true iff a
325 ".pwrite" callback has been defined.
326 ".can_flush"
328 int can_flush (void *handle);
329 This is called during the option negotiation phase to find out if the
331 handle supports the flush-to-disk operation.
332 If there is an error, ".can_flush" should call "nbdkit_error" with an
334 error message and return "-1".
335 This callback is not required. If omitted, then we return true iff a
337 ".flush" callback has been defined.
338 ".is_rotational"
340 int is_rotational (void *handle);
341 This is called during the option negotiation phase to find out if the
343 backing disk is a rotational medium (like a traditional hard disk) or
344 not (like an SSD). If true, this may cause the client to reorder
345 requests to make them more efficient for a slow rotating disk.
346 If there is an error, ".is_rotational" should call "nbdkit_error" with
348 an error message and return "-1".
349 This callback is not required. If omitted, then we return false.
351 ".can_trim"
353 int can_trim (void *handle);
354 This is called during the option negotiation phase to find out if the
356 plugin supports the trim/discard operation for punching holes in the
357 backing storage.
358 If there is an error, ".can_trim" should call "nbdkit_error" with an
360 error message and return "-1".
361 This callback is not required. If omitted, then we return true iff a
363 ".trim" callback has been defined.
364 ".pread"
366 int pread (void *handle, void *buf, uint32_t count, uint64_t offset);
367 During the data serving phase, nbdkit calls this callback to read data
369 from the backing store. "count" bytes starting at "offset" in the
370 backing store should be read and copied into "buf". nbdkit takes care
371 of all bounds- and sanity-checking, so the plugin does not need to
372 worry about that.
373 The callback must read the whole "count" bytes if it can. The NBD
375 protocol doesn't allow partial reads (instead, these would be errors).
376 If the whole "count" bytes was read, the callback should return 0 to
377 indicate there was no error.
378 If there is an error (including a short read which couldn't be
380 recovered from), ".pread" should call "nbdkit_error" with an error
381 message, and "nbdkit_set_error" to record an appropriate error (unless
382 "errno" is sufficient), then return "-1".
383 ".pwrite"
385 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset);
386 During the data serving phase, nbdkit calls this callback to write data
388 to the backing store. "count" bytes starting at "offset" in the
389 backing store should be written using the data in "buf". nbdkit takes
390 care of all bounds- and sanity-checking, so the plugin does not need to
391 worry about that.
392 The callback must write the whole "count" bytes if it can. The NBD
394 protocol doesn't allow partial writes (instead, these would be errors).
395 If the whole "count" bytes was written successfully, the callback
396 should return 0 to indicate there was no error.
397 If there is an error (including a short write which couldn't be
399 recovered from), ".pwrite" should call "nbdkit_error" with an error
400 message, and "nbdkit_set_error" to record an appropriate error (unless
401 "errno" is sufficient), then return "-1".
402 ".flush"
404 int flush (void *handle);
405 During the data serving phase, this callback is used to fdatasync(2)
407 the backing store, ie. to ensure it has been completely written to a
408 permanent medium. If that is not possible then you can omit this
409 callback.
410 If there is an error, ".flush" should call "nbdkit_error" with an error
412 message, and "nbdkit_set_error" to record an appropriate error (unless
413 "errno" is sufficient), then return "-1".
414 ".trim"
416 int trim (void *handle, uint32_t count, uint64_t offset);
417 During the data serving phase, this callback is used to "punch holes"
419 in the backing store. If that is not possible then you can omit this
420 callback.
421 If there is an error, ".trim" should call "nbdkit_error" with an error
423 message, and "nbdkit_set_error" to record an appropriate error (unless
424 "errno" is sufficient), then return "-1".
425 ".zero"
427 int zero (void *handle, uint32_t count, uint64_t offset, int may_trim);
428 During the data serving phase, this callback is used to write "count"
430 bytes of zeroes at "offset" in the backing store. If "may_trim" is
431 non-zero, the operation can punch a hole instead of writing actual zero
432 bytes, but only if subsequent reads from the hole read as zeroes. If
433 this callback is omitted, or if it fails with "EOPNOTSUPP" (whether by
434 "nbdkit_set_error" or "errno"), then ".pwrite" will be used instead.
435 The callback must write the whole "count" bytes if it can. The NBD
437 protocol doesn't allow partial writes (instead, these would be errors).
438 If the whole "count" bytes was written successfully, the callback
439 should return 0 to indicate there was no error.
440 If there is an error, ".zero" should call "nbdkit_error" with an error
442 message, and "nbdkit_set_error" to record an appropriate error (unless
443 "errno" is sufficient), then return "-1".
444
446 Each nbdkit plugin must declare its thread safety model by defining the
447 "THREAD_MODEL" macro. (This macro is used by
448 "NBDKIT_REGISTER_PLUGIN").
449 The possible settings for "THREAD_MODEL" are defined below.
451 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
453 Only a single handle can be open at any time, and all requests
454 happen from one thread.
455 Note this means only one client can connect to the server at any
457 time. If a second client tries to connect it will block waiting
458 for the first client to close the connection.
459 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
461 This is a safe default for most plugins.
462 Multiple handles can be open at the same time, but requests are
464 serialized so that for the plugin as a whole only one
465 open/read/write/close (etc) request will be in progress at any
466 time.
467 This is a useful setting if the library you are using is not
469 thread-safe. However performance may not be good.
470 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
472 Multiple handles can be open and multiple data requests can happen
473 in parallel. However only one request will happen per handle at a
474 time (but requests on different handles might happen concurrently).
475 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
477 Multiple handles can be open and multiple data requests can happen
478 in parallel (even on the same handle).
479 All the libraries you use must be thread-safe and reentrant. You
481 may also need to provide mutexes for fields in your connection
482 handle.
483 If none of the above thread models are suitable, then use
485 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
486 "pthread_mutex_t" etc.
487
489 When nbdkit receives certain signals it will shut down (see "SIGNALS"
490 in nbdkit(1)). The server will wait for any currently running plugin
491 callbacks to finish and also call the ".unload" callback before
492 unloading the plugin.
493 Note that it's not guaranteed this can always happen (eg. the server
495 might be killed by "SIGKILL" or segfault).
496
498 Use the "nbdkit_parse_size" utility function to parse human-readable
499 size strings such as "100M" into the size in bytes.
500 int64_t nbdkit_parse_size (const char *str);
502 "str" can be a string in a number of common formats. The function
504 returns the size in bytes. If there was an error, it returns "-1".
505
507 The "nbdkit_read_password" utility function can be used to read
508 passwords from config parameters:
509 int nbdkit_read_password (const char *value, char **password);
511 For example:
513 char *password = NULL;
515 static int
517 myplugin_config (const char *key, const char *value)
518 {
519 ..
520 if (strcmp (key, "password") == 0) {
521 free (password);
522 if (nbdkit_read_password (value, &password) == -1)
523 return -1;
524 }
525 ..
526 }
527 The "password" result string is allocated by malloc, and so you may
529 need to free it.
530 This function recognizes several password formats. A password may be
532 used directly on the command line, eg:
533 nbdkit myplugin password=mostsecret
535 But more securely this function can also read a password interactively:
537 nbdkit myplugin password=-
539 or from a file:
541 nbdkit myplugin password=+/tmp/secret
543 (If the password begins with a "-" or "+" character then it must be
545 passed in a file).
546
548 Run the server with -f and -v options so it doesn't fork and you can
549 see debugging information:
550 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
552 To print debugging information from within the plugin, call
554 "nbdkit_debug", which has the following prototype and works like
555 printf(3):
556 void nbdkit_debug (const char *fs, ...);
558 void nbdkit_vdebug (const char *fs, va_list args);
559 For convenience, "nbdkit_debug" preserves the value of "errno". Note
561 that "nbdkit_debug" only prints things when the server is in verbose
562 mode (-v option).
563
565 The plugin is a "*.so" file and possibly a manual page. You can of
566 course install the plugin "*.so" file wherever you want, and users will
567 be able to use it by running:
568 nbdkit /path/to/plugin.so [args]
570 However if the shared library has a name of the form
572 "nbdkit-name-plugin.so" and if the library is installed in the
573 $plugindir directory, then users can be run it by only typing:
574 nbdkit name [args]
576 The location of the $plugindir directory is set when nbdkit is compiled
578 and can be found by doing:
579 nbdkit --dump-config
581 If using the pkg-config/pkgconf system then you can also find the
583 plugin directory at compile time by doing:
584 pkgconf nbdkit --variable=plugindir
586
588 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
589 should be installed on the correct path when the nbdkit plugin
590 development environment is installed. You can use this in autoconf
591 configure.ac scripts to test for the development environment:
592 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
594 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
596 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
597 for compiling plugins.
598 You can also run pkg-config/pkgconf directly, for example:
600 if ! pkgconf nbdkit --exists; then
602 echo "you must install the nbdkit plugin development environment"
603 exit 1
604 fi
605 You can also substitute the plugindir variable by doing:
607 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
609 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
611
613 You can also write nbdkit plugins in OCaml, Perl, Python or Ruby.
614 Other programming languages may be offered in future.
615 For more information see: nbdkit-ocaml-plugin(3),
617 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3).
618 Plugins written in scripting languages may also be installed in
620 $plugindir. These must be called "nbdkit-name-plugin" without any
621 extension. They must be executable, and they must use the shebang
622 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
623 written in Perl called "foo.pl" might be installed like this:
624 $ head -1 foo.pl
626 #!/usr/sbin/nbdkit perl
627 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
629 and then users will be able to run it like this:
631 $ nbdkit foo [args ...]
633
635 nbdkit(1), nbdkit-filter(3), nbdkit-example1-plugin(1),
636 nbdkit-example2-plugin(1), nbdkit-example3-plugin(1),
637 nbdkit-example4-plugin(1), nbdkit-ocaml-plugin(3),
638 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3).
639
641 Eric Blake
642 Richard W.M. Jones
644 Pino Toscano
646
648 Copyright (C) 2013-2018 Red Hat Inc.
649
651 Redistribution and use in source and binary forms, with or without
652 modification, are permitted provided that the following conditions are
653 met:
654 · Redistributions of source code must retain the above copyright
656 notice, this list of conditions and the following disclaimer.
657 · Redistributions in binary form must reproduce the above copyright
659 notice, this list of conditions and the following disclaimer in the
660 documentation and/or other materials provided with the
661 distribution.
662 · Neither the name of Red Hat nor the names of its contributors may
664 be used to endorse or promote products derived from this software
665 without specific prior written permission.
666 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
668 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
669 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
670 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
671 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
672 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
673 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
674 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
675 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
676 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
677 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
678nbdkit 2018-06-12 nbdkit-plugin(3)