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>
11 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
13 static void *
15 myplugin_open (void)
16 {
17 /* create a handle ... */
18 return handle;
19 }
20 static struct nbdkit_plugin plugin = {
22 .name = "myplugin",
23 .open = myplugin_open,
24 .get_size = myplugin_get_size,
25 .pread = myplugin_pread,
26 .pwrite = myplugin_pwrite,
27 /* etc */
28 };
29 NBDKIT_REGISTER_PLUGIN(plugin)
30 Compile the plugin as a shared library:
32 gcc -fPIC -shared myplugin.c -o myplugin.so
34 and load it into nbdkit:
36 nbdkit [--args ...] ./myplugin.so [key=value ...]
38 When debugging, use the -fv options:
40 nbdkit -fv ./myplugin.so [key=value ...]
42
44 An nbdkit plugin is a new source device which can be served using the
45 Network Block Device (NBD) protocol. This manual page describes how to
46 create an nbdkit plugin in C.
47 To see example plugins:
49 https://gitlab.com/nbdkit/nbdkit/tree/master/plugins
50 To write plugins in other languages, see: nbdkit-cc-plugin(3),
52 nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
53 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
54 nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
55 API and ABI guarantee for C plugins
57 Plugins written in C have an ABI guarantee: a plugin compiled against
58 an older version of nbdkit will still work correctly when loaded with a
59 newer nbdkit. We also try (but cannot guarantee) to support plugins
60 compiled against a newer version of nbdkit when loaded with an older
61 nbdkit, although the plugin may have reduced functionality if it
62 depends on features only provided by newer nbdkit.
63 For plugins written in C, we also provide an API guarantee: a plugin
65 written against an older header will still compile unmodified with a
66 newer nbdkit.
67 The API guarantee does not always apply to plugins written in other
69 (non-C) languages which may have to adapt to changes when recompiled
70 against a newer nbdkit.
71
73 "#define NBDKIT_API_VERSION 2"
74 Plugins must choose which API version they want to use, by defining
75 NBDKIT_API_VERSION before including "<nbdkit-plugin.h>" (or any other
76 nbdkit header).
77 If omitted, the default version is 1 for backwards-compatibility with
79 nbdkit v1.1.26 and earlier; however, it is recommended that new plugins
80 be written to the maximum version (currently 2) as it enables more
81 features and better interaction with nbdkit filters.
82 The rest of this document only covers the version 2 interface. A newer
84 nbdkit will always support plugins written in C which use any prior API
85 version.
86 "#include <nbdkit-plugin.h>"
88 All plugins should start by including this header file (after
89 optionally choosing an API version).
90 "#define THREAD_MODEL ..."
92 All plugins must define a thread model. See "Threads" below for
93 details. It is generally safe to use:
94 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
96 "struct nbdkit_plugin"
98 All plugins must define and register one "struct nbdkit_plugin", which
99 contains the name of the plugin and pointers to callback functions, and
100 use the "NBDKIT_REGISTER_PLUGIN(plugin)" macro:
101 static struct nbdkit_plugin plugin = {
103 .name = "myplugin",
104 .longname = "My Plugin",
105 .description = "This is my great plugin for nbdkit",
106 .open = myplugin_open,
107 .get_size = myplugin_get_size,
108 .pread = myplugin_pread,
109 .pwrite = myplugin_pwrite,
110 /* etc */
111 };
112 NBDKIT_REGISTER_PLUGIN(plugin)
113 The ".name" field is the name of the plugin.
115 The callbacks are described below (see "CALLBACKS"). Only ".name",
117 ".open", ".get_size" and ".pread" are required. All other callbacks
118 can be omitted, although typical plugins need to use more.
119 Callback lifecycle
121 Callbacks are called in the following order over the lifecycle of the
122 plugin:
123 ┌──────────────────┐
125 │ load │
126 └─────────┬────────┘
127 │ configuration phase starts ─┐
128 ┌─────────┴────────┐ ┆
129 │ config │ config is called once per ┆
130 └─────────┬────────┘↺ key=value on the command line ┆
131 ┌─────────┴────────┐ ┆
132 │ config_complete │ ┆
133 └─────────┬────────┘ ┆
134 ┌─────────┴────────┐ ┆
135 │ thread_model │ ┆
136 └─────────┬────────┘ configuration phase ends ─┘
137 ┌─────────┴────────┐
138 │ get_ready │
139 └─────────┬────────┘
140 │ nbdkit forks into the background
141 ┌─────────┴────────┐
142 │ after_fork │
143 └─────────┬────────┘
144 │ nbdkit starts serving clients
145 │
146 ┌──────────┴─────────────┬─ ─ ─ ─ ─ ─ ─ ─ ─
147 ┌──────┴─────┐ client #1 │
148 │ preconnect │ │
149 └──────┬─────┘ │
150 ┌──────┴─────┐ │
151 │list_exports│ │
152 └──────┬─────┘ │
153 ┌──────┴─────┐ │
154 │ open │ │
155 └──────┬─────┘ │
156 ┌──────┴─────┐ NBD option │
157 │ can_write │ negotiation │
158 └──────┬─────┘ │
159 ┌──────┴─────┐ ┌──────┴─────┐ client #2
160 │ get_size │ │ preconnect │
161 └──────┬─────┘ └──────┬─────┘
162 ┌──────┴─────┐ data
163 │ pread │ serving
164 └──────┬─────┘↺ ...
165 ┌──────┴─────┐
166 │ pwrite │
167 └──────┬─────┘↺ ┌──────┴─────┐
168 ┌──────┴─────┐ │ close │
169 │ close │ └────────────┘
170 └────────────┘
171 │ before nbdkit exits
173 │
174 ┌─────────┴────────┐
175 │ cleanup │
176 └─────────┬────────┘
177 ┌─────────┴────────┐
178 │ unload │
179 └──────────────────┘
180 ".load"
182 is called once just after the plugin is loaded into memory.
183 ".config" and ".config_complete"
185 ".config" is called zero or more times during command line parsing.
186 ".config_complete" is called once after all configuration
187 information has been passed to the plugin (but not during "nbdkit
188 --dump-plugin").
189 Both are called after loading the plugin but before any connections
191 are accepted.
192 ".thread_model"
194 In normal operation, ".thread_model" is called once after
195 ".config_complete" has validated all configuration information, and
196 before any connections are accepted. However, during "nbdkit
197 --dump-plugin", it is called after any ".config" calls but without
198 ".config_complete" (so a plugin which determines the results from a
199 script must be prepared for a missing script).
200 ".get_ready"
202 In normal operation, ".get_ready" is called before the server
203 starts serving. It is called before the server forks or changes
204 directory. It is normally the last chance to do any global
205 preparation that is needed to serve connections.
206 Plugins should not create background threads here. Use
208 ".after_fork" instead.
209 ".after_fork"
211 In normal operation, ".after_fork" is called after the server has
212 forked into the background and changed UID and directory. If a
213 plugin needs to create background threads (or uses an external
214 library that creates threads) it should do so here, because
215 background threads are invalidated by fork.
216 Because the server may have forked into the background, error
218 messages and failures from ".after_fork" cannot be seen by the user
219 unless they look through syslog. An error in ".after_fork" can
220 appear to the user as if nbdkit “just died”. So in almost all
221 cases it is better to use ".get_ready" instead of this callback, or
222 to do as much preparation work as possible in ".get_ready" and only
223 start background threads here.
224 The server doesn't always fork (eg. if the -f flag is used), but
226 even so this callback will be called. If you want to find out if
227 the server forked between ".get_ready" and ".after_fork" use
228 getpid(2).
229 ".preconnect"
231 Called when a TCP connection has been made to the server. This
232 happens early, before NBD or TLS negotiation.
233 ".list_exports"
235 Early in option negotiation the client may try to list the exports
236 served by the plugin, and plugins can optionally implement this
237 callback to answer the client. See "EXPORT NAME" below.
238 ".default_export"
240 During option negotiation, if the client requests the default
241 export name (""), this optional callback provides a canonical name
242 to use in its place prior to calling ".open".
243 ".open"
245 A new client has connected and finished the NBD handshake. TLS
246 negotiation (if required) has been completed successfully.
247 ".can_write", ".get_size" and other option negotiation callbacks
249 These are called during option negotiation with the client, but
250 before any data is served. These callbacks may return different
251 values across different ".open" calls, but within a single
252 connection, they are called at most once and cached by nbdkit for
253 that connection.
254 ".pread", ".pwrite" and other data serving callbacks
256 After option negotiation has finished, these may be called to serve
257 data. Depending on the thread model chosen, they might be called
258 in parallel from multiple threads. The data serving callbacks
259 include a flags argument; the results of the negotiation callbacks
260 influence whether particular flags will ever be passed to a data
261 callback.
262 ".close"
264 The client has disconnected.
265 ".preconnect", ".open" ... ".close"
267 The sequence ".preconnect", ".open" ... ".close" can be called
268 repeatedly over the lifetime of the plugin, and can be called in
269 parallel (depending on the thread model).
270 ".cleanup"
272 is called once after all connections have been closed, prior to
273 unloading the plugin from memory. This is only called if
274 ".after_fork" succeeded earlier (even in cases where nbdkit did not
275 fork but is running in the foreground), which makes it a good place
276 to gracefully end any background threads.
277 ".unload"
279 is called once just before the plugin is unloaded from memory.
280 This is called even when nbdkit did not need to use ".after_fork"
281 (such as when using --dump-plugin to display documentation about
282 the plugin).
283 Flags
285 The following flags are defined by nbdkit, and used in various data
286 serving callbacks as follows:
287 "NBDKIT_FLAG_MAY_TRIM"
289 This flag is used by the ".zero" callback; there is no way to
290 disable this flag, although a plugin that does not support trims as
291 a way to write zeroes may ignore the flag without violating
292 expected semantics.
293 "NBDKIT_FLAG_FUA"
295 This flag represents Forced Unit Access semantics. It is used by
296 the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
297 plugin must not return a result until the action has landed in
298 persistent storage. This flag will not be sent to the plugin
299 unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
300 The following defines are valid as successful return values for
302 ".can_fua":
303 "NBDKIT_FUA_NONE"
305 Forced Unit Access is not supported; the client must manually
306 request a flush after writes have completed. The "NBDKIT_FLAG_FUA"
307 flag will not be passed to the plugin's write callbacks.
308 "NBDKIT_FUA_EMULATE"
310 The client may request Forced Unit Access, but it is implemented by
311 emulation, where nbdkit calls ".flush" after a write operation;
312 this is semantically correct, but may hurt performance as it tends
313 to flush more data than just what the client requested. The
314 "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
315 callbacks.
316 "NBDKIT_FUA_NATIVE"
318 The client may request Forced Unit Access, which results in the
319 "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
320 (".pwrite", ".trim", and ".zero"). When the flag is set, these
321 callbacks must not return success until the client's request has
322 landed in persistent storage.
323 The following defines are valid as successful return values for
325 ".can_cache":
326 "NBDKIT_CACHE_NONE"
328 The server does not advertise caching support, and rejects any
329 client-requested caching. Any ".cache" callback is ignored.
330 "NBDKIT_CACHE_EMULATE"
332 The nbdkit server advertises cache support to the client, where the
333 client may request that the server cache a region of the export to
334 potentially speed up future read and/or write operations on that
335 region. The nbdkit server implements the caching by calling
336 ".pread" and ignoring the results. This option exists to ease the
337 implementation of a common form of caching; any ".cache" callback
338 is ignored.
339 "NBDKIT_CACHE_NATIVE"
341 The nbdkit server advertises cache support to the client, where the
342 client may request that the server cache a region of the export to
343 potentially speed up future read and/or write operations on that
344 region. The nbdkit server calls the ".cache" callback to perform
345 the caching; if that callback is missing, the client's cache
346 request succeeds without doing anything.
347 Threads
349 Each nbdkit plugin must declare its maximum thread safety model by
350 defining the "THREAD_MODEL" macro. (This macro is used by
351 "NBDKIT_REGISTER_PLUGIN"). Additionally, a plugin may implement the
352 ".thread_model" callback, called right after ".config_complete" to make
353 a runtime decision on which thread model to use. The nbdkit server
354 chooses the most restrictive model between the plugin's "THREAD_MODEL",
355 the ".thread_model" if present, any restrictions requested by filters,
356 and any limitations imposed by the operating system.
357 In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line
359 matches the "THREAD_MODEL" macro, and the "thread_model" line matches
360 what the system finally settled on after applying all restrictions.
361 The possible settings for "THREAD_MODEL" are defined below.
363 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
365 Only a single handle can be open at any time, and all requests
366 happen from one thread.
367 Note this means only one client can connect to the server at any
369 time. If a second client tries to connect it will block waiting
370 for the first client to close the connection.
371 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
373 This is a safe default for most plugins.
374 Multiple handles can be open at the same time, but requests are
376 serialized so that for the plugin as a whole only one
377 open/read/write/close (etc) request will be in progress at any
378 time.
379 This is a useful setting if the library you are using is not
381 thread-safe. However performance may not be good.
382 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
384 Multiple handles can be open and multiple data requests can happen
385 in parallel. However only one request will happen per handle at a
386 time (but requests on different handles might happen concurrently).
387 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
389 Multiple handles can be open and multiple data requests can happen
390 in parallel (even on the same handle). The server may reorder
391 replies, answering a later request before an earlier one.
392 All the libraries you use must be thread-safe and reentrant, and
394 any code that creates a file descriptor should atomically set
395 "FD_CLOEXEC" if you do not want it accidentally leaked to another
396 thread's child process. You may also need to provide mutexes for
397 fields in your connection handle.
398 If none of the above thread models are suitable, use
400 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
401 "pthread_mutex_t" etc.
402 Error handling
404 If there is an error in the plugin, the plugin should call
405 "nbdkit_error" to report an error message; additionally, if the
406 callback is involved in serving data, the plugin should call
407 "nbdkit_set_error" to influence the error code that will be sent to the
408 client. These two functions can be called in either order. Then, the
409 callback should return the appropriate error indication, eg. "NULL" or
410 "-1".
411 If the call to "nbdkit_set_error" is omitted while serving data, then
413 the global variable "errno" may be used. For plugins which have
414 ".errno_is_preserved != 0" the core code will use "errno". In plugins
415 written in non-C languages, we usually cannot trust that "errno" will
416 not be overwritten when returning from that language to C. In that
417 case, either the plugin must call "nbdkit_set_error" or hard-coded
418 "EIO" is used.
419 "nbdkit_error" has the following prototype and works like printf(3):
421 void nbdkit_error (const char *fs, ...);
423 void nbdkit_verror (const char *fs, va_list args);
424 For convenience, "nbdkit_error" preserves the value of "errno", and
426 also supports the glibc extension of a single %m in a format string
427 expanding to "strerror(errno)", even on platforms that don't support
428 that natively.
429 "nbdkit_set_error" can be called at any time, but only has an impact
431 during callbacks for serving data, and only when the callback returns
432 an indication of failure. It has the following prototype:
433 void nbdkit_set_error (int err);
435
437 ".name"
438 const char *name;
439 This field (a string) is required, and must contain only ASCII
441 alphanumeric characters or non-leading dashes, and be unique amongst
442 all plugins.
443 ".version"
445 const char *version;
446 Plugins may optionally set a version string which is displayed in help
448 and debugging output. (See also "VERSION" below)
449 ".longname"
451 const char *longname;
452 An optional free text name of the plugin. This field is used in error
454 messages.
455 ".description"
457 const char *description;
458 An optional multi-line description of the plugin.
460 ".load"
462 void load (void);
463 This is called once just after the plugin is loaded into memory. You
465 can use this to perform any global initialization needed by the plugin.
466 ".unload"
468 void unload (void);
469 This may be called once just before the plugin is unloaded from memory.
471 Note that it's not guaranteed that ".unload" will always be called (eg.
472 the server might be killed or segfault), so you should try to make the
473 plugin as robust as possible by not requiring cleanup. See also
474 "SHUTDOWN" below.
475 ".dump_plugin"
477 void dump_plugin (void);
478 This optional callback is called when the "nbdkit plugin --dump-plugin"
480 command is used. It should print any additional informative
481 "key=value" fields to stdout as needed. Prefixing the keys with the
482 name of the plugin will avoid conflicts.
483 ".config"
485 int config (const char *key, const char *value);
486 On the nbdkit command line, after the plugin filename, come an optional
488 list of "key=value" arguments. These are passed to the plugin through
489 this callback when the plugin is first loaded and before any
490 connections are accepted.
491 This callback may be called zero or more times.
493 Both "key" and "value" parameters will be non-NULL. The strings are
495 owned by nbdkit but will remain valid for the lifetime of the plugin,
496 so the plugin does not need to copy them.
497 The key will be a non-empty string beginning with an ASCII alphabetic
499 character ("A-Z" "a-z"). The rest of the key must contain only ASCII
500 alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
501 "0-9" "." "_" "-"). The value may be an arbitrary string, including an
502 empty string.
503 The names of "key"s accepted by plugins is up to the plugin, but you
505 should probably look at other plugins and follow the same conventions.
506 If the value is a relative path, then note that the server changes
508 directory when it starts up. See "FILENAMES AND PATHS" above.
509 If "nbdkit_stdio_safe" returns 1, the value of the configuration
511 parameter may be used to trigger reading additional data through stdin
512 (such as a password or inline script).
513 If the ".config" callback is not provided by the plugin, and the user
515 tries to specify any "key=value" arguments, then nbdkit will exit with
516 an error.
517 If there is an error, ".config" should call "nbdkit_error" with an
519 error message and return "-1".
520 ".magic_config_key"
522 const char *magic_config_key;
523 This optional string can be used to set a "magic" key used when parsing
525 plugin parameters. It affects how "bare parameters" (those which do
526 not contain an "=" character) are parsed on the command line.
527 If "magic_config_key != NULL" then any bare parameters are passed to
529 the ".config" method as: "config (magic_config_key, argv[i]);".
530 If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
532 the first parameter on the command line is bare then it is passed to
533 the ".config" method as: "config ("script", value);". Any other bare
534 parameters give errors.
535 ".config_complete"
537 int config_complete (void);
538 This optional callback is called after all the configuration has been
540 passed to the plugin. It is a good place to do checks, for example
541 that the user has passed the required parameters to the plugin.
542 If there is an error, ".config_complete" should call "nbdkit_error"
544 with an error message and return "-1".
545 ".config_help"
547 const char *config_help;
548 This optional multi-line help message should summarize any "key=value"
550 parameters that it takes. It does not need to repeat what already
551 appears in ".description".
552 If the plugin doesn't take any config parameters you should probably
554 omit this.
555 ".thread_model"
557 int thread_model (void)
558 This optional callback is called after all the configuration has been
560 passed to the plugin. It can be used to force a stricter thread model
561 based on configuration, compared to "THREAD_MODEL". See "Threads"
562 above for details. Attempts to request a looser (more parallel) model
563 are silently ignored.
564 If there is an error, ".thread_model" should call "nbdkit_error" with
566 an error message and return "-1".
567 ".get_ready"
569 int get_ready (void);
570 This optional callback is called before the server starts serving. It
572 is called before the server forks or changes directory. It is
573 ordinarily the last chance to do any global preparation that is needed
574 to serve connections.
575 If there is an error, ".get_ready" should call "nbdkit_error" with an
577 error message and return "-1".
578 ".after_fork"
580 int after_fork (void);
581 This optional callback is called before the server starts serving. It
583 is called after the server forks and changes directory. If a plugin
584 needs to create background threads (or uses an external library that
585 creates threads) it should do so here, because background threads are
586 killed by fork. However you should try to do as little as possible
587 here because error reporting is difficult. See "Callback lifecycle"
588 above.
589 If there is an error, ".after_fork" should call "nbdkit_error" with an
591 error message and return "-1".
592 ".cleanup"
594 void cleanup (void);
595 This optional callback is called after the server has closed all
597 connections and is preparing to unload. It is only reached in the same
598 cases that the ".after_fork" callback was used, making it a good place
599 to clean up any background threads. However, it is not guaranteed that
600 this callback will be reached, so you should try to make the plugin as
601 robust as possible by not requiring cleanup. See also "SHUTDOWN"
602 below.
603 ".preconnect"
605 int preconnect (int readonly);
606 This optional callback is called when a TCP connection has been made to
608 the server. This happens early, before NBD or TLS negotiation. If TLS
609 authentication is required to access the server, then it has not been
610 negotiated at this point.
611 For security reasons (to avoid denial of service attacks) this callback
613 should be written to be as fast and take as few resources as possible.
614 If you use this callback, only use it to do basic access control, such
615 as checking "nbdkit_peer_name", "nbdkit_peer_pid", "nbdkit_peer_uid",
616 "nbdkit_peer_gid" against a list of permitted source addresses (see
617 "PEER NAME" and nbdkit-ip-filter(1)). It may be better to do access
618 control outside the server, for example using TCP wrappers or a
619 firewall.
620 The "readonly" flag informs the plugin that the server was started with
622 the -r flag on the command line.
623 Returning 0 will allow the connection to continue. If there is an
625 error or you want to deny the connection, call "nbdkit_error" with an
626 error message and return "-1".
627 ".list_exports"
629 int list_exports (int readonly, int is_tls,
630 struct nbdkit_exports *exports);
631 This optional callback is called if the client tries to list the
633 exports served by the plugin (using "NBD_OPT_LIST"). If the plugin
634 does not supply this callback then the result of ".default_export" is
635 advertised as the lone export. The NBD protocol defines "" as the
636 default export, so this is suitable for plugins which ignore the export
637 name and always serve the same content. See also "EXPORT NAME" below.
638 The "readonly" flag informs the plugin that the server was started with
640 the -r flag on the command line, which is the same value passed to
641 ".preconnect" and ".open". However, the NBD protocol does not yet have
642 a way to let the client advertise an intent to be read-only even when
643 the server allows writes, so this parameter may not be as useful as it
644 appears.
645 The "is_tls" flag informs the plugin whether this listing was requested
647 after the client has completed TLS negotiation. When running the
648 server in a mode that permits but does not require TLS, be careful that
649 any exports listed when "is_tls" is "false" do not leak unintended
650 information.
651 The "exports" parameter is an opaque object for collecting the list of
653 exports. Call "nbdkit_add_export" as needed to add specific exports to
654 the list.
655 int nbdkit_add_export (struct nbdkit_export *exports,
657 const char *name, const char *description);
658 The "name" must be a non-NULL, UTF-8 string between 0 and 4096 bytes in
660 length. Export names must be unique. "description" is an optional
661 description of the export which some clients can display but which is
662 otherwise unused (if you don't want a description, you can pass this
663 parameter as "NULL"). The string(s) are copied into the exports list
664 so you may free them immediately after calling this function.
665 "nbdkit_add_export" returns 0 on success or "-1" on failure; on failure
666 "nbdkit_error" has already been called, with "errno" set to a suitable
667 value.
668 There are also situations where a plugin may wish to duplicate the
670 nbdkit default behavior of supplying an export list containing only the
671 result of ".default_export" when ".list_exports" is missing; this is
672 most common in a language binding where it is not known at compile time
673 whether the language script will be providing an implementation for
674 ".list_exports", and is done by calling "nbdkit_use_default_export".
675 int nbdkit_use_default_export (struct nbdkit_export *exports);
677 "nbdkit_use_default_export" returns 0 on success or "-1" on failure; on
679 failure "nbdkit_error" has already been called, with "errno" set to a
680 suitable value.
681 The plugin may also leave the export list empty, by not calling either
683 helper. Once the plugin is happy with the list contents, returning 0
684 will send the list of exports back to the client. If there is an
685 error, ".list_exports" should call "nbdkit_error" with an error message
686 and return "-1".
687 ".default_export"
689 const char *default_export (int readonly, int is_tls);
690 This optional callback is called if the client tries to connect to the
692 default export "", where the plugin provides a UTF-8 string between 0
693 and 4096 bytes. If the plugin does not supply this callback, the
694 connection continues with the empty name; if the plugin returns a valid
695 string, nbdkit behaves as if the client had passed that string instead
696 of an empty name, and returns that name to clients that support it (see
697 the "NBD_INFO_NAME" response to "NBD_OPT_GO"). Similarly, if the
698 plugin does not supply a ".list_exports" callback, the result of this
699 callback determines what export name to advertise to a client
700 requesting an export list.
701 The "readonly" flag informs the plugin that the server was started with
703 the -r flag on the command line, which is the same value passed to
704 ".preconnect" and ".open". However, the NBD protocol does not yet have
705 a way to let the client advertise an intent to be read-only even when
706 the server allows writes, so this parameter may not be as useful as it
707 appears.
708 The "is_tls" flag informs the plugin whether the canonical name for the
710 default export is being requested after the client has completed TLS
711 negotiation. When running the server in a mode that permits but does
712 not require TLS, be careful that a default export name does not leak
713 unintended information.
714 If the plugin returns "NULL" or an invalid string (such as longer than
716 4096 bytes), the client is not permitted to connect to the default
717 export. However, this is not an error in the protocol, so it is not
718 necessary to call "nbdkit_error".
719 ".open"
721 void *open (int readonly);
722 This is called when a new client connects to the nbdkit server. The
724 callback should allocate a handle and return it. This handle is passed
725 back to other callbacks and could be freed in the ".close" callback.
726 Note that the handle is completely opaque to nbdkit, but it must not be
728 NULL. If you don't need to use a handle, return
729 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
730 The "readonly" flag informs the plugin that the server was started with
732 the -r flag on the command line which forces connections to be read-
733 only. Note that the plugin may additionally force the connection to be
734 readonly (even if this flag is false) by returning false from the
735 ".can_write" callback. So if your plugin can only serve read-only, you
736 can ignore this parameter.
737 If the plugin wants to differentiate the content it serves based on
739 client input, then this is the spot to use "nbdkit_export_name()" to
740 determine which export the client requested. See also "EXPORT NAME"
741 below.
742 This callback is called after the NBD handshake has completed; if the
744 server requires TLS authentication, then that has occurred as well.
745 But if the server is set up to have optional TLS authentication, you
746 may check "nbdkit_is_tls" to learn whether the client has completed TLS
747 authentication. When running the server in a mode that permits but
748 does not require TLS, be careful that you do not allow unauthenticated
749 clients to cause a denial of service against authentication.
750 If there is an error, ".open" should call "nbdkit_error" with an error
752 message and return "NULL".
753 ".close"
755 void close (void *handle);
756 This is called when the client closes the connection. It should clean
758 up any per-connection resources.
759 Note there is no way in the NBD protocol to communicate close errors
761 back to the client, for example if your plugin calls close(2) and you
762 are checking for errors (as you should do). Therefore the best you can
763 do is to log the error on the server. Well-behaved NBD clients should
764 try to flush the connection before it is closed and check for errors,
765 but obviously this is outside the scope of nbdkit.
766 ".get_size"
768 int64_t get_size (void *handle);
769 This is called during the option negotiation phase of the protocol to
771 get the size (in bytes) of the block device being exported.
772 The returned size must be ≥ 0. If there is an error, ".get_size"
774 should call "nbdkit_error" with an error message and return "-1".
775 ".export_description"
777 const char *export_description (void *handle);
778 This is called during the option negotiation phase only if the client
780 specifically requested an export description (see the
781 "NBD_INFO_DESCRIPTION" response to "NBD_OPT_GO"). Any description
782 provided must be human-readable UTF-8, no longer than 4096 bytes.
783 Ideally, this description should match any description set during
784 ".list_exports", but that is not enforced.
785 If the plugin returns "NULL" or an invalid string (such as longer than
787 4096 bytes), or if this callback is omitted, no description is offered
788 to the client. As this is not an error in the protocol, it is not
789 necessary to call "nbdkit_error". If the callback will not be
790 returning a compile-time constant string, you may find
791 "nbdkit_strdup_intern" helpful for returning a value that avoids a
792 memory leak.
793 ".block_size"
795 int block_size (void *handle, uint32_t *minimum,
796 uint32_t *preferred, uint32_t *maximum);
797 This is called during the option negotiation phase of the protocol to
799 get the minimum, preferred and maximum block size (all in bytes) of the
800 block device. The client should obey these constraints by not making
801 requests which are smaller than the minimum size or larger than the
802 maximum size, and usually making requests of a multiple of the
803 preferred size. Furthermore requests should be aligned to at least the
804 minimum block size, and usually the preferred block size.
805 "Preferred" block size in the NBD specification can be misinterpreted.
807 It means the I/O size which does not have a penalty for read-modify-
808 write.
809 Even if the plugin implements this callback, this does not mean that
811 all client requests will obey the constraints. A client could still
812 ignore the constraints. nbdkit passes all requests through to the
813 plugin, because what the plugin does depends on the plugin's policy.
814 It might decide to serve the requests correctly anyway, or reject them
815 with an error. Plugins can avoid this complexity by using
816 nbdkit-blocksize-policy-filter(1) which allows both setting/adjusting
817 the constraints, and selecting an error policy.
818 The minimum block size must be ≥ 1. The maximum block size must be ≤
820 0xffff_ffff. minimum ≤ preferred ≤ maximum.
821 As a special case, the plugin may return minimum == preferred ==
823 maximum == 0, meaning no information.
824 If this callback is not used, then the NBD protocol assumes by default
826 minimum = 1, preferred = 4096. (Maximum block size depends on various
827 factors, see the NBD protocol specification, section "Block size
828 constraints").
829 ".can_write"
831 int can_write (void *handle);
832 This is called during the option negotiation phase to find out if the
834 handle supports writes.
835 If there is an error, ".can_write" should call "nbdkit_error" with an
837 error message and return "-1".
838 This callback is not required. If omitted, then we return true iff a
840 ".pwrite" callback has been defined.
841 ".can_flush"
843 int can_flush (void *handle);
844 This is called during the option negotiation phase to find out if the
846 handle supports the flush-to-disk operation.
847 If there is an error, ".can_flush" should call "nbdkit_error" with an
849 error message and return "-1".
850 This callback is not required. If omitted, then we return true iff a
852 ".flush" callback has been defined.
853 ".is_rotational"
855 int is_rotational (void *handle);
856 This is called during the option negotiation phase to find out if the
858 backing disk is a rotational medium (like a traditional hard disk) or
859 not (like an SSD). If true, this may cause the client to reorder
860 requests to make them more efficient for a slow rotating disk.
861 If there is an error, ".is_rotational" should call "nbdkit_error" with
863 an error message and return "-1".
864 This callback is not required. If omitted, then we return false.
866 ".can_trim"
868 int can_trim (void *handle);
869 This is called during the option negotiation phase to find out if the
871 plugin supports the trim/discard operation for punching holes in the
872 backing storage.
873 If there is an error, ".can_trim" should call "nbdkit_error" with an
875 error message and return "-1".
876 This callback is not required. If omitted, then we return true iff a
878 ".trim" callback has been defined.
879 ".can_zero"
881 int can_zero (void *handle);
882 This is called during the option negotiation phase to find out if the
884 plugin wants the ".zero" callback to be utilized. Support for writing
885 zeroes is still advertised to the client (unless the
886 nbdkit-nozero-filter(1) is also used), so returning false merely serves
887 as a way to avoid complicating the ".zero" callback to have to fail
888 with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
889 be more efficient than using ".pwrite" up front.
890 If there is an error, ".can_zero" should call "nbdkit_error" with an
892 error message and return "-1".
893 This callback is not required. If omitted, then for a normal zero
895 request, nbdkit always tries ".zero" first if it is present, and
896 gracefully falls back to ".pwrite" if ".zero" was absent or failed with
897 "ENOTSUP" or "EOPNOTSUPP".
898 ".can_fast_zero"
900 int can_fast_zero (void *handle);
901 This is called during the option negotiation phase to find out if the
903 plugin wants to advertise support for fast zero requests. If this
904 support is not advertised, a client cannot attempt fast zero requests,
905 and has no way to tell if writing zeroes offers any speedups compared
906 to using ".pwrite" (other than compressed network traffic). If support
907 is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when
908 the client has requested a fast zero, in which case the plugin must
909 fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
910 offer any benefits over ".pwrite". Advertising support for fast zero
911 requests does not require that writing zeroes be fast, only that the
912 result (whether success or failure) is fast, so this should be
913 advertised when feasible.
914 If there is an error, ".can_fast_zero" should call "nbdkit_error" with
916 an error message and return "-1".
917 This callback is not required. If omitted, then nbdkit returns true if
919 ".zero" is absent or ".can_zero" returns false (in those cases, nbdkit
920 fails all fast zero requests, as its fallback to ".pwrite" is not
921 inherently faster), otherwise false (since it cannot be determined in
922 advance if the plugin's ".zero" will properly honor the semantics of
923 "NBDKIT_FLAG_FAST_ZERO").
924 ".can_extents"
926 int can_extents (void *handle);
927 This is called during the option negotiation phase to find out if the
929 plugin supports detecting allocated (non-sparse) regions of the disk
930 with the ".extents" callback.
931 If there is an error, ".can_extents" should call "nbdkit_error" with an
933 error message and return "-1".
934 This callback is not required. If omitted, then we return true iff a
936 ".extents" callback has been defined.
937 ".can_fua"
939 int can_fua (void *handle);
940 This is called during the option negotiation phase to find out if the
942 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
943 trim requests. If this returns "NBDKIT_FUA_NONE", FUA support is not
944 advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
945 ".flush" callback must work (even if ".can_flush" returns false), and
946 FUA support is emulated by calling ".flush" after any write operation;
947 if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
948 ".trim" callbacks (if implemented) must handle the flag
949 "NBDKIT_FLAG_FUA", by not returning until that action has landed in
950 persistent storage.
951 If there is an error, ".can_fua" should call "nbdkit_error" with an
953 error message and return "-1".
954 This callback is not required unless a plugin wants to specifically
956 handle FUA requests. If omitted, nbdkit checks whether ".flush"
957 exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
958 "NBDKIT_FUA_EMULATE" as appropriate.
959 ".can_multi_conn"
961 int can_multi_conn (void *handle);
962 This is called during the option negotiation phase to find out if the
964 plugin is prepared to handle multiple connections from a single client.
965 If the plugin sets this to true then a client may try to open multiple
966 connections to the nbdkit server and spread requests across all
967 connections to maximize parallelism. If the plugin sets it to false
968 (which is the default) then well-behaved clients should only open a
969 single connection, although we cannot control what clients do in
970 practice.
971 Specifically it means that either the plugin does not cache requests at
973 all. Or if it does cache them then the effects of a ".flush" request
974 or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
975 connections to the plugin before the plugin replies to that request.
976 Properly working clients should send the same export name for each of
978 these connections.
979 If you use Linux nbd-client(8) option -C num with num > 1 then Linux
981 checks this flag and will refuse to connect if ".can_multi_conn" is
982 false.
983 If there is an error, ".can_multi_conn" should call "nbdkit_error" with
985 an error message and return "-1".
986 This callback is not required. If omitted, then we return false.
988 ".can_cache"
990 int can_cache (void *handle);
991 This is called during the option negotiation phase to find out if the
993 plugin supports a cache or prefetch operation.
994 This can return:
996 "NBDKIT_CACHE_NONE"
998 Cache support is not advertised to the client.
999 "NBDKIT_CACHE_EMULATE"
1001 Caching is emulated by the server calling ".pread" and discarding
1002 the result.
1003 "NBDKIT_CACHE_NATIVE"
1005 Cache support is advertised to the client. The ".cache" callback
1006 will be called if it exists, otherwise all cache requests instantly
1007 succeed.
1008 If there is an error, ".can_cache" should call "nbdkit_error" with an
1010 error message and return "-1".
1011 This callback is not required. If omitted, then we return
1013 "NBDKIT_CACHE_NONE" if the ".cache" callback is missing, or
1014 "NBDKIT_CACHE_NATIVE" if it is defined.
1015 ".pread"
1017 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
1018 uint32_t flags);
1019 During the data serving phase, nbdkit calls this callback to read data
1021 from the backing store. "count" bytes starting at "offset" in the
1022 backing store should be read and copied into "buf". nbdkit takes care
1023 of all bounds- and sanity-checking, so the plugin does not need to
1024 worry about that.
1025 The parameter "flags" exists in case of future NBD protocol extensions;
1027 at this time, it will be 0 on input.
1028 The callback must read the whole "count" bytes if it can. The NBD
1030 protocol doesn't allow partial reads (instead, these would be errors).
1031 If the whole "count" bytes was read, the callback should return 0 to
1032 indicate there was no error.
1033 If there is an error (including a short read which couldn't be
1035 recovered from), ".pread" should call "nbdkit_error" with an error
1036 message, and "nbdkit_set_error" to record an appropriate error (unless
1037 "errno" is sufficient), then return "-1".
1038 ".pwrite"
1040 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
1041 uint32_t flags);
1042 During the data serving phase, nbdkit calls this callback to write data
1044 to the backing store. "count" bytes starting at "offset" in the
1045 backing store should be written using the data in "buf". nbdkit takes
1046 care of all bounds- and sanity-checking, so the plugin does not need to
1047 worry about that.
1048 This function will not be called if ".can_write" returned false. The
1050 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1051 result of ".can_fua".
1052 The callback must write the whole "count" bytes if it can. The NBD
1054 protocol doesn't allow partial writes (instead, these would be errors).
1055 If the whole "count" bytes was written successfully, the callback
1056 should return 0 to indicate there was no error.
1057 If there is an error (including a short write which couldn't be
1059 recovered from), ".pwrite" should call "nbdkit_error" with an error
1060 message, and "nbdkit_set_error" to record an appropriate error (unless
1061 "errno" is sufficient), then return "-1".
1062 ".flush"
1064 int flush (void *handle, uint32_t flags);
1065 During the data serving phase, this callback is used to fdatasync(2)
1067 the backing store, ie. to ensure it has been completely written to a
1068 permanent medium. If that is not possible then you can omit this
1069 callback.
1070 This function will not be called directly by the client if ".can_flush"
1072 returned false; however, it may still be called by nbdkit if ".can_fua"
1073 returned "NBDKIT_FUA_EMULATE". The parameter "flags" exists in case of
1074 future NBD protocol extensions; at this time, it will be 0 on input.
1075 If there is an error, ".flush" should call "nbdkit_error" with an error
1077 message, and "nbdkit_set_error" to record an appropriate error (unless
1078 "errno" is sufficient), then return "-1".
1079 ".trim"
1081 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1082 During the data serving phase, this callback is used to "punch holes"
1084 in the backing store. If that is not possible then you can omit this
1085 callback.
1086 This function will not be called if ".can_trim" returned false. The
1088 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1089 result of ".can_fua".
1090 If there is an error, ".trim" should call "nbdkit_error" with an error
1092 message, and "nbdkit_set_error" to record an appropriate error (unless
1093 "errno" is sufficient), then return "-1".
1094 ".zero"
1096 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1097 During the data serving phase, this callback is used to write "count"
1099 bytes of zeroes at "offset" in the backing store.
1100 This function will not be called if ".can_zero" returned false. On
1102 input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
1103 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
1104 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
1105 If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
1107 instead of writing actual zero bytes, but only if subsequent reads from
1108 the hole read as zeroes.
1109 If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up
1111 front if the implementation is likely to be faster than a corresponding
1112 ".pwrite"; if not, then it must immediately fail with "ENOTSUP" or
1113 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno") and preferably
1114 without modifying the exported image. It is acceptable to always fail
1115 a fast zero request (as a fast failure is better than attempting the
1116 write only to find out after the fact that it was not fast after all).
1117 Note that on Linux, support for "ioctl(BLKZEROOUT)" is insufficient for
1118 determining whether a zero request to a block device will be fast
1119 (because the kernel will perform a slow fallback when needed).
1120 The callback must write the whole "count" bytes if it can. The NBD
1122 protocol doesn't allow partial writes (instead, these would be errors).
1123 If the whole "count" bytes was written successfully, the callback
1124 should return 0 to indicate there was no error.
1125 If there is an error, ".zero" should call "nbdkit_error" with an error
1127 message, and "nbdkit_set_error" to record an appropriate error (unless
1128 "errno" is sufficient), then return "-1".
1129 If this callback is omitted, or if it fails with "ENOTSUP" or
1131 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then ".pwrite"
1132 will be used as an automatic fallback except when the client requested
1133 a fast zero.
1134 ".extents"
1136 int extents (void *handle, uint32_t count, uint64_t offset,
1137 uint32_t flags, struct nbdkit_extents *extents);
1138 During the data serving phase, this callback is used to detect
1140 allocated, sparse and zeroed regions of the disk.
1141 This function will not be called if ".can_extents" returned false.
1143 nbdkit's default behaviour in this case is to treat the whole virtual
1144 disk as if it was allocated. Also, this function will not be called by
1145 a client that does not request structured replies (the --no-sr option
1146 of nbdkit can be used to test behavior when ".extents" is unavailable
1147 to the client).
1148 The callback should detect and return the list of extents overlapping
1150 the range "[offset...offset+count-1]". The "extents" parameter points
1151 to an opaque object which the callback should fill in by calling
1152 "nbdkit_add_extent". See "Extents list" below.
1153 If there is an error, ".extents" should call "nbdkit_error" with an
1155 error message, and "nbdkit_set_error" to record an appropriate error
1156 (unless "errno" is sufficient), then return "-1".
1157 Extents list
1159 The plugin "extents" callback is passed an opaque pointer "struct
1161 nbdkit_extents *extents". This structure represents a list of
1162 filesystem extents describing which areas of the disk are allocated,
1163 which are sparse (“holes”), and, if supported, which are zeroes.
1164 The "extents" callback should scan the disk starting at "offset" and
1166 call "nbdkit_add_extent" for each extent found.
1167 Extents overlapping the range "[offset...offset+count-1]" should be
1169 returned if possible. However nbdkit ignores extents < offset so the
1170 plugin may, if it is easier to implement, return all extent information
1171 for the whole disk. The plugin may return extents beyond the end of
1172 the range. It may also return extent information for less than the
1173 whole range, but it must return at least one extent overlapping
1174 "offset".
1175 The extents must be added in ascending order, and must be contiguous.
1177 The "flags" parameter of the ".extents" callback may contain the flag
1179 "NBDKIT_FLAG_REQ_ONE". This means that the client is only requesting
1180 information about the extent overlapping "offset". The plugin may
1181 ignore this flag, or as an optimization it may return just a single
1182 extent for "offset".
1183 int nbdkit_add_extent (struct nbdkit_extents *extents,
1185 uint64_t offset, uint64_t length, uint32_t type);
1186 Add an extent covering "[offset...offset+length-1]" of one of the
1188 following four types:
1189 "type = 0"
1191 A normal, allocated data extent.
1192 "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
1194 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
1195 This is the normal type of hole applicable to most disks.
1196 "type = NBDKIT_EXTENT_ZERO"
1198 An allocated extent which is known to contain only zeroes.
1199 "type = NBDKIT_EXTENT_HOLE"
1201 An unallocated extent (hole) which does not read back as zeroes.
1202 Note this should only be used in specialized circumstances such as
1203 when writing a plugin for (or to emulate) certain SCSI drives which
1204 do not guarantee that trimmed blocks read back as zeroes.
1205 "nbdkit_add_extent" returns 0 on success or "-1" on failure. On
1207 failure "nbdkit_error" and/or "nbdkit_set_error" has already been
1208 called. "errno" will be set to a suitable value.
1209 ".cache"
1211 int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1212 During the data serving phase, this callback is used to give the plugin
1214 a hint that the client intends to make further accesses to the given
1215 region of the export.
1216 The nature of caching/prefetching is not specified further by the NBD
1218 specification. For example, a server may place limits on how much may
1219 be cached at once, and there is no way to control if writes to a cached
1220 area have write-through or write-back semantics. In fact, the cache
1221 command can always fail and still be compliant, and success might not
1222 guarantee a performance gain.
1223 If this callback is omitted, then the results of ".can_cache" determine
1225 whether nbdkit will reject cache requests, treat them as instant
1226 success, or emulate caching by calling ".pread" over the same region
1227 and ignoring the results.
1228 This function will not be called if ".can_cache" did not return
1230 "NBDKIT_CACHE_NATIVE".
1231 The "flags" parameter exists in case of future NBD protocol extensions;
1233 at this time, it will be 0 on input. A plugin must fail this function
1234 if "flags" includes an unrecognized flag, as that may indicate a
1235 requirement that the plugin must comply with to provide a specific
1236 caching semantic.
1237 If there is an error, ".cache" should call "nbdkit_error" with an error
1239 message, and "nbdkit_set_error" to record an appropriate error (unless
1240 "errno" is sufficient), then return "-1".
1241 ".errno_is_preserved"
1243 This field defaults to 0; if non-zero, nbdkit can reliably use the
1244 value of "errno" when a callback reports failure, rather than the
1245 plugin having to call "nbdkit_set_error".
1246
1248 When nbdkit receives certain signals it will shut down (see "SIGNALS"
1249 in nbdkit(1)). The server will wait for any currently running plugin
1250 callbacks to finish, call ".close" on those connections, then call the
1251 ".cleanup" and ".unload" callbacks before unloading the plugin.
1252 Note that it's not guaranteed this can always happen (eg. the server
1254 might be killed by "SIGKILL" or segfault).
1255 Requesting asynchronous shutdown
1257 Plugins and filters can call exit(3) in the configuration phase (before
1258 and including ".get_ready", but not in connected callbacks).
1259 Once nbdkit has started serving connections, plugins and filters should
1261 not call exit(3). However they may instruct nbdkit to shut down by
1262 calling "nbdkit_shutdown":
1263 void nbdkit_shutdown (void);
1265 This function requests an asynchronous shutdown and returns (note that
1267 it does not exit the process immediately). It ensures that the plugin
1268 and all filters are unloaded cleanly which may take some time. Further
1269 callbacks from nbdkit into the plugin or filter may occur after you
1270 have called this.
1271
1273 Parsing numbers
1274 There are several functions for parsing numbers. These all deal
1275 correctly with overflow, out of range and parse errors, and you should
1276 use them instead of unsafe functions like sscanf(3), atoi(3) and
1277 similar.
1278 int nbdkit_parse_int (const char *what, const char *str, int *r);
1280 int nbdkit_parse_unsigned (const char *what,
1281 const char *str, unsigned *r);
1282 int nbdkit_parse_int8_t (const char *what,
1283 const char *str, int8_t *r);
1284 int nbdkit_parse_uint8_t (const char *what,
1285 const char *str, uint8_t *r);
1286 int nbdkit_parse_int16_t (const char *what,
1287 const char *str, int16_t *r);
1288 int nbdkit_parse_uint16_t (const char *what,
1289 const char *str, uint16_t *r);
1290 int nbdkit_parse_int32_t (const char *what,
1291 const char *str, int32_t *r);
1292 int nbdkit_parse_uint32_t (const char *what,
1293 const char *str, uint32_t *r);
1294 int nbdkit_parse_int64_t (const char *what,
1295 const char *str, int64_t *r);
1296 int nbdkit_parse_uint64_t (const char *what,
1297 const char *str, uint64_t *r);
1298 Parse string "str" into an integer of various types. These functions
1300 parse a decimal, hexadecimal ("0x...") or octal ("0...") number.
1301 On success the functions return 0 and set *r to the parsed value
1303 (unless "*r == NULL" in which case the result is discarded). On error,
1304 "nbdkit_error" is called and the functions return "-1". On error *r is
1305 always unchanged.
1306 The "what" parameter is printed in error messages to provide context.
1308 It should usually be a short descriptive string of what you are trying
1309 to parse, eg:
1310 if (nbdkit_parse_int ("random seed", argv[1], &seed) == -1)
1312 return -1;
1313 might print an error:
1315 random seed: could not parse number: "lalala"
1317 Parsing sizes
1319 Use the "nbdkit_parse_size" utility function to parse human-readable
1320 size strings such as "100M" into the size in bytes.
1321 int64_t nbdkit_parse_size (const char *str);
1323 "str" can be a string in a number of common formats. The function
1325 returns the size in bytes. If there was an error, it returns "-1".
1326 Parsing booleans
1328 Use the "nbdkit_parse_bool" utility function to parse human-readable
1329 strings such as "on" into a boolean value.
1330 int nbdkit_parse_bool (const char *str);
1332 "str" can be a string containing a case-insensitive form of various
1334 common toggle values. The function returns 0 or 1 if the parse was
1335 successful. If there was an error, it returns "-1".
1336 Reading passwords
1338 The "nbdkit_read_password" utility function can be used to read
1339 passwords from config parameters:
1340 int nbdkit_read_password (const char *value, char **password);
1342 For example:
1344 char *password = NULL;
1346 static int
1348 myplugin_config (const char *key, const char *value)
1349 {
1350 ..
1351 if (strcmp (key, "password") == 0) {
1352 free (password);
1353 if (nbdkit_read_password (value, &password) == -1)
1354 return -1;
1355 }
1356 ..
1357 }
1358 The "password" result string is allocated by malloc, and so you may
1360 need to free it.
1361 This function recognizes several password formats. A password may be
1363 used directly on the command line, eg:
1364 nbdkit myplugin password=mostsecret
1366 But more securely this function can also read a password interactively:
1368 nbdkit myplugin password=-
1370 or from a file:
1372 nbdkit myplugin password=+/tmp/secret
1374 or from a file descriptor inherited by nbdkit:
1376 nbdkit myplugin password=-99
1378 Notes on reading passwords
1380 If the password begins with a "-" or "+" character then it must be
1382 passed in a file.
1383 "password=-" can only be used when stdin is a terminal.
1385 "password=-FD" cannot be used with stdin, stdout or stderr (ie. "-0",
1387 "-1" or "-2"). The reason is that after reading the password the file
1388 descriptor is closed, which causes bad stuff to happen.
1389 Safely interacting with stdin and stdout
1391 int nbdkit_stdio_safe (void);
1392 The "nbdkit_stdio_safe" utility function returns 1 if it is safe to
1394 interact with stdin and stdout during the configuration phase, and 0
1395 otherwise. This is because when the nbdkit -s option is used the
1396 plugin must not directly interact with stdin, because that would
1397 interfere with the client.
1398 The result of this function only matters in callbacks up to
1400 ".config_complete". Once nbdkit reaches ".get_ready", the plugin
1401 should assume that nbdkit may have closed the original stdin and stdout
1402 in order to become a daemon.
1403 nbdkit-sh-plugin(3) uses this function to determine whether it is safe
1405 to support "script=-" to read a script from stdin. Also constructs
1406 like "password=-" (see "Reading passwords" above) are disabled when
1407 reading from stdio is not safe.
1408
1410 The server usually (not always) changes directory to "/" before it
1411 starts serving connections. This means that any relative paths passed
1412 during configuration will not work when the server is running (example:
1413 "nbdkit plugin.so disk.img").
1414 To avoid problems, prepend relative paths with the current directory
1416 before storing them in the handle. Or open files and store the file
1417 descriptor.
1418 "nbdkit_absolute_path"
1420 char *nbdkit_absolute_path (const char *filename);
1421 The utility function "nbdkit_absolute_path" converts any path to an
1423 absolute path: if it is relative, then all this function does is
1424 prepend the current working directory to the path, with no extra
1425 checks.
1426 Note that this function works only when used in the ".config",
1428 ".config_complete" and ".get_ready" callbacks.
1429 If conversion was not possible, this calls "nbdkit_error" and returns
1431 "NULL". Note that this function does not check that the file exists.
1432 The returned string must be freed by the caller.
1434 "nbdkit_realpath"
1436 char *nbdkit_realpath (const char *filename);
1437 The utility function "nbdkit_realpath" converts any path to an absolute
1439 path, resolving symlinks. Under the hood it uses the "realpath"
1440 function, and thus it fails if the path does not exist, or it is not
1441 possible to access to any of the components of the path.
1442 Note that this function works only when used in the ".config",
1444 ".config_complete" and ".get_ready" callbacks.
1445 If the path resolution was not possible, this calls "nbdkit_error" and
1447 returns "NULL".
1448 The returned string must be freed by the caller.
1450 umask
1452 All plugins will see a umask(2) of 0022.
1453
1455 A plugin that needs to sleep may call sleep(2), nanosleep(2) and
1456 similar. However that can cause nbdkit to delay excessively when
1457 shutting down (since it must wait for any plugin or filter which is
1458 sleeping). To avoid this there is a special wrapper around nanosleep
1459 which plugins and filters should use instead.
1460 "nbdkit_nanosleep"
1462 int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1463 The utility function "nbdkit_nanosleep" suspends the current thread,
1465 and returns 0 if it slept at least as many seconds and nanoseconds as
1466 requested, or -1 after calling "nbdkit_error" if there is no point in
1467 continuing the current command. Attempts to sleep more than "INT_MAX"
1468 seconds are treated as an error.
1469
1471 If the client negotiated an NBD export name with nbdkit then plugins
1472 may read this from any connected callbacks. Nbdkit's normal behaviour
1473 is to accept any export name passed by the client, log it in debug
1474 output, but otherwise ignore it. By using "nbdkit_export_name" plugins
1475 may choose to filter by export name or serve different content.
1476 "nbdkit_export_name"
1478 const char *nbdkit_export_name (void);
1479 Return the optional NBD export name if one was negotiated with the
1481 current client (this uses thread-local magic so no parameter is
1482 required). The returned string is valid at least through the ".close"
1483 of the current connection, but if you need to store it in the plugin
1484 for use by more than one client you must copy it.
1485 The export name is a free-form text string, it is not necessarily a
1487 path or filename and it does not need to begin with a '/' character.
1488 The NBD protocol describes the empty string ("") as a representing a
1489 "default export" or to be used in cases where the export name does not
1490 make sense. The export name is untrusted client data, be cautious when
1491 parsing it.
1492 On error, "nbdkit_error" is called and the call returns "NULL".
1494
1496 Some callbacks are specified to return "const char *", even when a
1497 plugin may not have a suitable compile-time constant to return.
1498 Returning dynamically-allocated memory for such a callback would induce
1499 a memory leak or otherwise complicate the plugin to perform additional
1500 bookkeeping. For these cases, nbdkit provides several convenience
1501 functions for creating a copy of a string for better lifetime
1502 management.
1503 "nbdkit_strdup_intern"
1505 "nbdkit_strndup_intern"
1506 const char *nbdkit_strdup_intern (const char *str);
1507 const char *nbdkit_strndup_intern (const char *str, size_t n);
1508 Returns a copy of "str", possibly limited to a maximum of "n" bytes, so
1510 that the caller may reclaim str and use the copy in its place. If the
1511 copy is created outside the scope of a connection (such as during
1512 ".load" or ".config"), the lifetime of the copy will last at least
1513 through ".unload". If the copy is created after a client has triggered
1514 a connection (such as during ".preconnect" or ".open"), the lifetime
1515 will last at least through ".close", but the copy is not safe to share
1516 with other connections.
1517 On error, "nbdkit_error" is called and the call returns "NULL".
1519 "nbdkit_printf_intern"
1521 "nbdkit_vprintf_intern"
1522 const char *nbdkit_printf_intern (const char *fmt, ...);
1523 const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);
1524 Return a string created from a format template, with a lifetime longer
1526 than the current connection. Shorthand for passing "fmt" to
1527 asprintf(3) on a temporary string, then passing that result to
1528 "nbdkit_strdup_intern".
1529 On error, "nbdkit_error" is called and the call returns "NULL".
1531
1533 A server may use "nbdkit_is_tls" to limit which export names work until
1534 after a client has completed TLS authentication. See nbdkit-tls(1).
1535 It is also possible to use nbdkit-tls-fallback-filter(1) to
1536 automatically ensure that the plugin is only used with authentication.
1537 "nbdkit_is_tls"
1539 int nbdkit_is_tls (void);
1540 Return true if the client has completed TLS authentication, or false if
1542 the connection is still plaintext.
1543 On error (such as calling this function outside of the context of
1545 ".open"), "nbdkit_error" is called and the call returns "-1".
1546
1548 It is possible to get the source address of the client when you are
1549 running in any connected callback.
1550 "nbdkit_peer_name"
1552 int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1553 Return the peer (client) address, if available. The "addr" and
1555 "addrlen" parameters behave like getpeername(2). In particular you
1556 must initialize "addrlen" with the size of the buffer pointed to by
1557 "addr", and if "addr" is not large enough then the address will be
1558 truncated.
1559 In some cases this is not available or the address returned will be
1561 meaningless (eg. if there is a proxy between the client and nbdkit).
1562 This call uses thread-local magic so no parameter is required to
1563 specify the current connection.
1564 On success this returns 0. On error, "nbdkit_error" is called and this
1566 call returns "-1".
1567 "nbdkit_peer_pid"
1569 (nbdkit ≥ 1.24, Linux only)
1570 int64_t nbdkit_peer_pid (void);
1572 Return the peer process ID. This is only available when the client
1574 connected over a Unix domain socket.
1575 On success this returns the peer process ID. On error, "nbdkit_error"
1577 is called and this call returns "-1".
1578 "nbdkit_peer_uid"
1580 (nbdkit ≥ 1.24)
1581 int64_t nbdkit_peer_uid (void);
1583 Return the peer user ID. This is only available when the client
1585 connected over a Unix domain socket.
1586 On success this returns the user ID. On error, "nbdkit_error" is
1588 called and this call returns "-1".
1589 "nbdkit_peer_gid"
1591 (nbdkit ≥ 1.24)
1592 int64_t nbdkit_peer_gid (void);
1594 Return the peer group ID. This is only available when the client
1596 connected over a Unix domain socket.
1597 On success this returns the user ID. On error, "nbdkit_error" is
1599 called and this call returns "-1".
1600
1602 Compile-time version of nbdkit
1603 The macros "NBDKIT_VERSION_MAJOR", "NBDKIT_VERSION_MINOR" and
1604 "NBDKIT_VERSION_MICRO" expand to integers containing the version of the
1605 nbdkit headers that you are compiling against.
1606 "NBDKIT_VERSION_MAJOR" is always 1. "NBDKIT_VERSION_MINOR" is even for
1608 stable releases of nbdkit and odd for development releases.
1609 The macro "NBDKIT_VERSION_STRING" expands to the same version as a
1611 string.
1612 Run-time version of nbdkit
1614 When the plugin is loaded into nbdkit, it may not be the same version
1615 that it was compiled against. nbdkit guarantees backwards
1616 compatibility of the API and ABI, so provided that nbdkit is the same
1617 version or newer, the plugin will still work. There is no way to get
1618 the version of nbdkit from the plugin.
1619 Version of the plugin
1621 The plugin itself can use any versioning scheme you want, and put any
1622 string into the ".version" field of the plugin struct (or leave the
1623 field NULL).
1624 API version
1626 See "WRITING AN NBDKIT PLUGIN" above.
1627
1629 Run the server with -f and -v options so it doesn't fork and you can
1630 see debugging information:
1631 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1633 To print debugging information from within the plugin, call
1635 "nbdkit_debug", which has the following prototype and works like
1636 printf(3):
1637 void nbdkit_debug (const char *fs, ...);
1639 void nbdkit_vdebug (const char *fs, va_list args);
1640 For convenience, "nbdkit_debug" preserves the value of "errno", and
1642 also supports the glibc extension of a single %m in a format string
1643 expanding to "strerror(errno)", even on platforms that don't support
1644 that natively. Note that "nbdkit_debug" only prints things when the
1645 server is in verbose mode (-v option).
1646 Debug Flags
1648 The -v option switches general debugging on or off, and this debugging
1649 should be used for messages which are useful for all users of your
1650 plugin.
1651 In cases where you want to enable specific extra debugging to track
1653 down bugs in plugins or filters — mainly for use by the plugin/filter
1654 developers themselves — you can define Debug Flags. These are global
1655 ints called "myplugin_debug_*":
1656 int myplugin_debug_foo;
1658 int myplugin_debug_bar;
1659 ...
1660 if (myplugin_debug_foo) {
1661 nbdkit_debug ("lots of extra debugging about foo: ...");
1662 }
1663 Debug Flags can be controlled on the command line using the -D (or
1665 --debug) option:
1666 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1668 Note "myplugin" is the name passed to ".name" in the "struct
1670 nbdkit_plugin".
1671 You should only use this feature for debug settings. For general
1673 settings use ordinary plugin parameters. Debug Flags can only be C
1674 ints. They are not supported by non-C language plugins.
1675 For convenience '.' characters are replaced with '_' characters in the
1677 variable name, so both of these parameters:
1678 -D myplugin.foo_bar=1
1680 -D myplugin.foo.bar=1
1681 correspond to the plugin variable "myplugin_debug_foo_bar".
1683
1685 Plugins should be compiled as shared libraries. There are various ways
1686 to achieve this, but most Linux compilers support a -shared option to
1687 create the shared library directly, for example:
1688 gcc -fPIC -shared myplugin.c -o myplugin.so
1690 Note that the shared library will have undefined symbols for functions
1692 that you call like "nbdkit_parse_int" or "nbdkit_error". These will be
1693 resolved by the server binary when nbdkit dlopens the plugin.
1694 PKG-CONFIG/PKGCONF
1696 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
1697 should be installed on the correct path when the nbdkit plugin
1698 development environment is installed. You can use this in autoconf
1699 configure.ac scripts to test for the development environment:
1700 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1702 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
1704 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
1705 for compiling plugins.
1706 You can also run pkg-config/pkgconf directly, for example:
1708 if ! pkg-config nbdkit --exists; then
1710 echo "you must install the nbdkit plugin development environment"
1711 exit 1
1712 fi
1713 You can also substitute the plugindir variable by doing:
1715 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1717 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
1719 If nbdkit development headers are installed in a non-standard location
1721 then you may need to compile plugins using:
1722 gcc -fPIC -shared myplugin.c -o myplugin.so \
1724 `pkg-config nbdkit --cflags --libs`
1725
1727 The plugin is a "*.so" file and possibly a manual page. You can of
1728 course install the plugin "*.so" file wherever you want, and users will
1729 be able to use it by running:
1730 nbdkit /path/to/plugin.so [args]
1732 However if the shared library has a name of the form
1734 "nbdkit-name-plugin.so" and if the library is installed in the
1735 $plugindir directory, then users can be run it by only typing:
1736 nbdkit name [args]
1738 The location of the $plugindir directory is set when nbdkit is compiled
1740 and can be found by doing:
1741 nbdkit --dump-config
1743 If using the pkg-config/pkgconf system then you can also find the
1745 plugin directory at compile time by doing:
1746 pkg-config nbdkit --variable=plugindir
1748
1750 Plugins in C++ work almost exactly like those in C, but the way you
1751 define the "nbdkit_plugin" struct is slightly different:
1752 namespace {
1754 nbdkit_plugin create_plugin() {
1755 nbdkit_plugin plugin = nbdkit_plugin ();
1756 plugin.name = "myplugin";
1757 plugin.open = myplugin_open;
1758 plugin.get_size = myplugin_get_size;
1759 plugin.pread = myplugin_pread;
1760 plugin.pwrite = myplugin_pwrite;
1761 return plugin;
1762 }
1763 }
1764 static struct nbdkit_plugin plugin = create_plugin ();
1765 NBDKIT_REGISTER_PLUGIN(plugin)
1766
1768 You can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python,
1769 Ruby, Rust, shell script or Tcl. Other programming languages may be
1770 offered in future.
1771 For more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
1773 nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
1774 nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
1775 nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1776 Plugins written in scripting languages may also be installed in
1778 $plugindir. These must be called "nbdkit-name-plugin" without any
1779 extension. They must be executable, and they must use the shebang
1780 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
1781 written in Perl called "foo.pl" might be installed like this:
1782 $ head -1 foo.pl
1784 #!/usr/sbin/nbdkit perl
1785 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1787 and then users will be able to run it like this:
1789 $ nbdkit foo [args ...]
1791
1793 nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1),
1794 nbdkit-filter(3).
1795 Standard plugins provided by nbdkit:
1797 nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1), nbdkit-data-plugin(1),
1799 nbdkit-eval-plugin(1), nbdkit-example1-plugin(1),
1800 nbdkit-example2-plugin(1), nbdkit-example3-plugin(1),
1801 nbdkit-example4-plugin(1), nbdkit-file-plugin(1),
1802 nbdkit-floppy-plugin(1), nbdkit-full-plugin(1),
1803 nbdkit-guestfs-plugin(1), nbdkit-info-plugin(1), nbdkit-iso-plugin(1),
1804 nbdkit-libvirt-plugin(1), nbdkit-linuxdisk-plugin(1),
1805 nbdkit-memory-plugin(1), nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
1806 nbdkit-ondemand-plugin(1), nbdkit-partitioning-plugin(1),
1807 nbdkit-pattern-plugin(1), nbdkit-random-plugin(1), nbdkit-S3-plugin(1),
1808 nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1),
1809 nbdkit-ssh-plugin(1), nbdkit-tmpdisk-plugin(1),
1810 nbdkit-torrent-plugin(1), nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1)
1811 ; nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3),
1812 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
1813 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
1814 nbdkit-tcl-plugin(3) .
1815
1817 Eric Blake
1818 Richard W.M. Jones
1820 Pino Toscano
1822
1824 Copyright (C) 2013-2020 Red Hat Inc.
1825
1827 Redistribution and use in source and binary forms, with or without
1828 modification, are permitted provided that the following conditions are
1829 met:
1830 • Redistributions of source code must retain the above copyright
1832 notice, this list of conditions and the following disclaimer.
1833 • Redistributions in binary form must reproduce the above copyright
1835 notice, this list of conditions and the following disclaimer in the
1836 documentation and/or other materials provided with the
1837 distribution.
1838 • Neither the name of Red Hat nor the names of its contributors may
1840 be used to endorse or promote products derived from this software
1841 without specific prior written permission.
1842 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1844 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1845 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1846 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1847 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1848 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1849 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1850 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1851 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1852 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1853 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1854nbdkit-1.30.7 2022-07-10 nbdkit-plugin(3)