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 Notes
182 "nbdkit --dump-plugin"
184 The order of calls when the user queries the plugin is slightly
185 different: ".config" is called once for each parameter.
186 ".config_complete" is not called. ".thread_model" is called after
187 ".config".
188 ".get_ready"
190 This is the last chance to do any global preparation that is needed
191 to serve connections. In particular, error messages here will be
192 visible to the user, but they might not be in ".after_fork" (see
193 below).
194 Plugins should not create background threads here. Use
196 ".after_fork" instead.
197 ".after_fork"
199 ".after_fork" is called after the server has forked into the
200 background and changed UID and directory. If a plugin needs to
201 create background threads (or uses an external library that creates
202 threads) it should do so here, because background threads are
203 invalidated by fork.
204 Because the server may have forked into the background, error
206 messages and failures from ".after_fork" cannot be seen by the user
207 unless they look through syslog. An error in ".after_fork" can
208 appear to the user as if nbdkit “just died”. So in almost all
209 cases it is better to use ".get_ready" instead of this callback, or
210 to do as much preparation work as possible in ".get_ready" and only
211 start background threads here.
212 The server doesn't always fork (eg. if the -f flag is used), but
214 even so this callback will be called. If you want to find out if
215 the server forked between ".get_ready" and ".after_fork" use
216 getpid(2).
217 ".preconnect" and ".open"
219 ".preconnect" is called when a TCP connection has been made to the
220 server. This happens early, before NBD or TLS negotiation.
221 ".open" is called when a new client has connected and finished the
223 NBD handshake. TLS negotiation (if used) has been completed
224 successfully.
225 ".can_write", ".get_size" and other option negotiation callbacks
227 These are called during option negotiation with the client, but
228 before any data is served. These callbacks may return different
229 values across different ".open" calls, but within a single
230 connection, they are called at most once and cached by nbdkit for
231 that connection.
232 ".pread", ".pwrite" and other data serving callbacks
234 After option negotiation has finished, these may be called to serve
235 data. Depending on the thread model chosen, they might be called
236 in parallel from multiple threads. The data serving callbacks
237 include a flags argument; the results of the negotiation callbacks
238 influence whether particular flags will ever be passed to a data
239 callback.
240 ".cleanup" and ".unload"
242 The difference between these two methods is that ".cleanup" is
243 called before any filter has been removed from memory with
244 dlclose(3). When ".unload" is called, nbdkit is in the middle of
245 calling dlclose(3). Most plugins do not need to worry about this
246 difference.
247 Flags
249 The following flags are defined by nbdkit, and used in various data
250 serving callbacks as follows:
251 "NBDKIT_FLAG_MAY_TRIM"
253 This flag is used by the ".zero" callback; there is no way to
254 disable this flag, although a plugin that does not support trims as
255 a way to write zeroes may ignore the flag without violating
256 expected semantics.
257 "NBDKIT_FLAG_FUA"
259 This flag represents Forced Unit Access semantics. It is used by
260 the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
261 plugin must not return a result until the action has landed in
262 persistent storage. This flag will not be sent to the plugin
263 unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
264 The following defines are valid as successful return values for
266 ".can_fua":
267 "NBDKIT_FUA_NONE"
269 Forced Unit Access is not supported; the client must manually
270 request a flush after writes have completed. The "NBDKIT_FLAG_FUA"
271 flag will not be passed to the plugin's write callbacks.
272 "NBDKIT_FUA_EMULATE"
274 The client may request Forced Unit Access, but it is implemented by
275 emulation, where nbdkit calls ".flush" after a write operation;
276 this is semantically correct, but may hurt performance as it tends
277 to flush more data than just what the client requested. The
278 "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
279 callbacks.
280 "NBDKIT_FUA_NATIVE"
282 The client may request Forced Unit Access, which results in the
283 "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
284 (".pwrite", ".trim", and ".zero"). When the flag is set, these
285 callbacks must not return success until the client's request has
286 landed in persistent storage.
287 The following defines are valid as successful return values for
289 ".can_cache":
290 "NBDKIT_CACHE_NONE"
292 The server does not advertise caching support, and rejects any
293 client-requested caching. Any ".cache" callback is ignored.
294 "NBDKIT_CACHE_EMULATE"
296 The nbdkit server advertises cache support to the client, where the
297 client may request that the server cache a region of the export to
298 potentially speed up future read and/or write operations on that
299 region. The nbdkit server implements the caching by calling
300 ".pread" and ignoring the results. This option exists to ease the
301 implementation of a common form of caching; any ".cache" callback
302 is ignored.
303 "NBDKIT_CACHE_NATIVE"
305 The nbdkit server advertises cache support to the client, where the
306 client may request that the server cache a region of the export to
307 potentially speed up future read and/or write operations on that
308 region. The nbdkit server calls the ".cache" callback to perform
309 the caching; if that callback is missing, the client's cache
310 request succeeds without doing anything.
311 Threads
313 Each nbdkit plugin must declare its maximum thread safety model by
314 defining the "THREAD_MODEL" macro. (This macro is used by
315 "NBDKIT_REGISTER_PLUGIN"). Additionally, a plugin may implement the
316 ".thread_model" callback, called right after ".config_complete" to make
317 a runtime decision on which thread model to use. The nbdkit server
318 chooses the most restrictive model between the plugin's "THREAD_MODEL",
319 the ".thread_model" if present, any restrictions requested by filters,
320 and any limitations imposed by the operating system.
321 In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line
323 matches the "THREAD_MODEL" macro, and the "thread_model" line matches
324 what the system finally settled on after applying all restrictions.
325 The possible settings for "THREAD_MODEL" are defined below.
327 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
329 Only a single handle can be open at any time, and all requests
330 happen from one thread.
331 Note this means only one client can connect to the server at any
333 time. If a second client tries to connect it will block waiting
334 for the first client to close the connection.
335 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
337 This is a safe default for most plugins.
338 Multiple handles can be open at the same time, but requests are
340 serialized so that for the plugin as a whole only one
341 open/read/write/close (etc) request will be in progress at any
342 time.
343 This is a useful setting if the library you are using is not
345 thread-safe. However performance may not be good.
346 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
348 Multiple handles can be open and multiple data requests can happen
349 in parallel. However only one request will happen per handle at a
350 time (but requests on different handles might happen concurrently).
351 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
353 Multiple handles can be open and multiple data requests can happen
354 in parallel (even on the same handle). The server may reorder
355 replies, answering a later request before an earlier one.
356 All the libraries you use must be thread-safe and reentrant, and
358 any code that creates a file descriptor should atomically set
359 "FD_CLOEXEC" if you do not want it accidentally leaked to another
360 thread's child process. You may also need to provide mutexes for
361 fields in your connection handle.
362 If none of the above thread models are suitable, use
364 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
365 "pthread_mutex_t" etc.
366 Error handling
368 If there is an error in the plugin, the plugin should call
369 "nbdkit_error" to report an error message; additionally, if the
370 callback is involved in serving data, the plugin should call
371 "nbdkit_set_error" to influence the error code that will be sent to the
372 client. These two functions can be called in either order. Then, the
373 callback should return the appropriate error indication, eg. "NULL" or
374 -1.
375 If the call to "nbdkit_set_error" is omitted while serving data, then
377 the global variable "errno" may be used. For plugins which have
378 ".errno_is_preserved != 0" the core code will use "errno". In plugins
379 written in non-C languages, we usually cannot trust that "errno" will
380 not be overwritten when returning from that language to C. In that
381 case, either the plugin must call "nbdkit_set_error" or hard-coded
382 "EIO" is used.
383 "nbdkit_error" has the following prototype and works like printf(3):
385 void nbdkit_error (const char *fs, ...);
387 void nbdkit_verror (const char *fs, va_list args);
388 For convenience, "nbdkit_error" preserves the value of "errno", and
390 also supports the glibc extension of a single %m in a format string
391 expanding to strerror(errno), even on platforms that don't support that
392 natively.
393 "nbdkit_set_error" can be called at any time, but only has an impact
395 during callbacks for serving data, and only when the callback returns
396 an indication of failure. It has the following prototype:
397 void nbdkit_set_error (int err);
399
401 ".name"
402 const char *name;
403 This field (a string) is required, and must contain only ASCII
405 alphanumeric characters or non-leading dashes, and be unique amongst
406 all plugins.
407 ".version"
409 const char *version;
410 Plugins may optionally set a version string which is displayed in help
412 and debugging output. (See also "VERSION" below)
413 ".longname"
415 const char *longname;
416 An optional free text name of the plugin. This field is used in error
418 messages.
419 ".description"
421 const char *description;
422 An optional multi-line description of the plugin.
424 ".load"
426 void load (void);
427 This is called once just after the plugin is loaded into memory. You
429 can use this to perform any global initialization needed by the plugin.
430 ".unload"
432 void unload (void);
433 This may be called once just before the plugin is unloaded from memory.
435 Note that it's not guaranteed that ".unload" will always be called (eg.
436 the server might be killed or segfault), so you should try to make the
437 plugin as robust as possible by not requiring cleanup. See also
438 "SHUTDOWN" below.
439 ".dump_plugin"
441 void dump_plugin (void);
442 This optional callback is called when the "nbdkit plugin --dump-plugin"
444 command is used. It should print any additional informative
445 "key=value" fields to stdout as needed. Prefixing the keys with the
446 name of the plugin will avoid conflicts.
447 ".config"
449 int config (const char *key, const char *value);
450 On the nbdkit command line, after the plugin filename, come an optional
452 list of "key=value" arguments. These are passed to the plugin through
453 this callback when the plugin is first loaded and before any
454 connections are accepted.
455 This callback may be called zero or more times.
457 Both "key" and "value" parameters will be non-NULL. The strings are
459 owned by nbdkit but will remain valid for the lifetime of the plugin,
460 so the plugin does not need to copy them.
461 The key will be a non-empty string beginning with an ASCII alphabetic
463 character ("A-Z" "a-z"). The rest of the key must contain only ASCII
464 alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
465 "0-9" "." "_" "-"). The value may be an arbitrary string, including an
466 empty string.
467 The names of "key"s accepted by plugins is up to the plugin, but you
469 should probably look at other plugins and follow the same conventions.
470 If the value is a relative path, then note that the server changes
472 directory when it starts up. See "FILENAMES AND PATHS" above.
473 If "nbdkit_stdio_safe" returns 1, the value of the configuration
475 parameter may be used to trigger reading additional data through stdin
476 (such as a password or inline script).
477 If the ".config" callback is not provided by the plugin, and the user
479 tries to specify any "key=value" arguments, then nbdkit will exit with
480 an error.
481 If there is an error, ".config" should call "nbdkit_error" with an
483 error message and return -1.
484 ".magic_config_key"
486 const char *magic_config_key;
487 This optional string can be used to set a "magic" key used when parsing
489 plugin parameters. It affects how "bare parameters" (those which do
490 not contain an "=" character) are parsed on the command line.
491 If "magic_config_key != NULL" then any bare parameters are passed to
493 the ".config" method as: "config (magic_config_key, argv[i]);".
494 If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
496 the first parameter on the command line is bare then it is passed to
497 the ".config" method as: "config ("script", value);". Any other bare
498 parameters give errors.
499 ".config_complete"
501 int config_complete (void);
502 This optional callback is called after all the configuration has been
504 passed to the plugin. It is a good place to do checks, for example
505 that the user has passed the required parameters to the plugin.
506 If there is an error, ".config_complete" should call "nbdkit_error"
508 with an error message and return -1.
509 ".config_help"
511 const char *config_help;
512 This optional multi-line help message should summarize any "key=value"
514 parameters that it takes. It does not need to repeat what already
515 appears in ".description".
516 If the plugin doesn't take any config parameters you should probably
518 omit this.
519 ".thread_model"
521 int thread_model (void)
522 This optional callback is called after all the configuration has been
524 passed to the plugin. It can be used to force a stricter thread model
525 based on configuration, compared to "THREAD_MODEL". See "Threads"
526 above for details. Attempts to request a looser (more parallel) model
527 are silently ignored.
528 If there is an error, ".thread_model" should call "nbdkit_error" with
530 an error message and return -1.
531 ".get_ready"
533 int get_ready (void);
534 This optional callback is called before the server starts serving. It
536 is called before the server forks or changes directory. It is
537 ordinarily the last chance to do any global preparation that is needed
538 to serve connections.
539 If there is an error, ".get_ready" should call "nbdkit_error" with an
541 error message and return -1.
542 ".after_fork"
544 int after_fork (void);
545 This optional callback is called before the server starts serving. It
547 is called after the server forks and changes directory. If a plugin
548 needs to create background threads (or uses an external library that
549 creates threads) it should do so here, because background threads are
550 killed by fork. However you should try to do as little as possible
551 here because error reporting is difficult. See "Callback lifecycle"
552 above.
553 If there is an error, ".after_fork" should call "nbdkit_error" with an
555 error message and return -1.
556 ".cleanup"
558 void cleanup (void);
559 This optional callback is called after the server has closed all
561 connections and is preparing to unload. It is only reached in the same
562 cases that the ".after_fork" callback was used, making it a good place
563 to clean up any background threads. However, it is not guaranteed that
564 this callback will be reached, so you should try to make the plugin as
565 robust as possible by not requiring cleanup. See also "SHUTDOWN"
566 below.
567 ".preconnect"
569 int preconnect (int readonly);
570 This optional callback is called when a TCP connection has been made to
572 the server. This happens early, before NBD or TLS negotiation. If TLS
573 authentication is required to access the server, then it has not been
574 negotiated at this point.
575 For security reasons (to avoid denial of service attacks) this callback
577 should be written to be as fast and take as few resources as possible.
578 If you use this callback, only use it to do basic access control, such
579 as checking "nbdkit_peer_name", "nbdkit_peer_pid", "nbdkit_peer_uid",
580 "nbdkit_peer_gid" against a list of permitted source addresses (see
581 "PEER NAME" and nbdkit-ip-filter(1)). It may be better to do access
582 control outside the server, for example using TCP wrappers or a
583 firewall.
584 The "readonly" flag informs the plugin that the server was started with
586 the -r flag on the command line.
587 Returning 0 will allow the connection to continue. If there is an
589 error or you want to deny the connection, call "nbdkit_error" with an
590 error message and return -1.
591 ".list_exports"
593 int list_exports (int readonly, int is_tls,
594 struct nbdkit_exports *exports);
595 This optional callback is called if the client tries to list the
597 exports served by the plugin (using "NBD_OPT_LIST"). If the plugin
598 does not supply this callback then the result of ".default_export" is
599 advertised as the lone export. The NBD protocol defines "" as the
600 default export, so this is suitable for plugins which ignore the export
601 name and always serve the same content. See also "EXPORT NAME" below.
602 The "readonly" flag informs the plugin that the server was started with
604 the -r flag on the command line, which is the same value passed to
605 ".preconnect" and ".open". However, the NBD protocol does not yet have
606 a way to let the client advertise an intent to be read-only even when
607 the server allows writes, so this parameter may not be as useful as it
608 appears.
609 The "is_tls" flag informs the plugin whether this listing was requested
611 after the client has completed TLS negotiation. When running the
612 server in a mode that permits but does not require TLS, be careful that
613 any exports listed when "is_tls" is "false" do not leak unintended
614 information.
615 The "exports" parameter is an opaque object for collecting the list of
617 exports. Call "nbdkit_add_export" as needed to add specific exports to
618 the list.
619 int nbdkit_add_export (struct nbdkit_export *exports,
621 const char *name, const char *description);
622 The "name" must be a non-NULL, UTF-8 string between 0 and 4096 bytes in
624 length. Export names must be unique. "description" is an optional
625 description of the export which some clients can display but which is
626 otherwise unused (if you don't want a description, you can pass this
627 parameter as "NULL"). The string(s) are copied into the exports list
628 so you may free them immediately after calling this function.
629 "nbdkit_add_export" returns 0 on success or -1 on failure; on failure
630 "nbdkit_error" has already been called, with "errno" set to a suitable
631 value.
632 There are also situations where a plugin may wish to duplicate the
634 nbdkit default behavior of supplying an export list containing only the
635 result of ".default_export" when ".list_exports" is missing; this is
636 most common in a language binding where it is not known at compile time
637 whether the language script will be providing an implementation for
638 ".list_exports", and is done by calling "nbdkit_use_default_export".
639 int nbdkit_use_default_export (struct nbdkit_export *exports);
641 "nbdkit_use_default_export" returns 0 on success or -1 on failure; on
643 failure "nbdkit_error" has already been called, with "errno" set to a
644 suitable value.
645 The plugin may also leave the export list empty, by not calling either
647 helper. Once the plugin is happy with the list contents, returning 0
648 will send the list of exports back to the client. If there is an
649 error, ".list_exports" should call "nbdkit_error" with an error message
650 and return -1.
651 ".default_export"
653 const char *default_export (int readonly, int is_tls);
654 This optional callback is called if the client tries to connect to the
656 default export "", where the plugin provides a UTF-8 string between 0
657 and 4096 bytes. If the plugin does not supply this callback, the
658 connection continues with the empty name; if the plugin returns a valid
659 string, nbdkit behaves as if the client had passed that string instead
660 of an empty name, and returns that name to clients that support it (see
661 the "NBD_INFO_NAME" response to "NBD_OPT_GO"). Similarly, if the
662 plugin does not supply a ".list_exports" callback, the result of this
663 callback determines what export name to advertise to a client
664 requesting an export list.
665 The "readonly" flag informs the plugin that the server was started with
667 the -r flag on the command line, which is the same value passed to
668 ".preconnect" and ".open". However, the NBD protocol does not yet have
669 a way to let the client advertise an intent to be read-only even when
670 the server allows writes, so this parameter may not be as useful as it
671 appears.
672 The "is_tls" flag informs the plugin whether the canonical name for the
674 default export is being requested after the client has completed TLS
675 negotiation. When running the server in a mode that permits but does
676 not require TLS, be careful that a default export name does not leak
677 unintended information.
678 If the plugin returns "NULL" or an invalid string (such as longer than
680 4096 bytes), the client is not permitted to connect to the default
681 export. However, this is not an error in the protocol, so it is not
682 necessary to call "nbdkit_error".
683 ".open"
685 void *open (int readonly);
686 This is called when a new client connects to the nbdkit server. The
688 callback should allocate a handle and return it. This handle is passed
689 back to other callbacks and could be freed in the ".close" callback.
690 Note that the handle is completely opaque to nbdkit, but it must not be
692 NULL. If you don't need to use a handle, return
693 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
694 The "readonly" flag informs the plugin that the server was started with
696 the -r flag on the command line which forces connections to be read-
697 only. Note that the plugin may additionally force the connection to be
698 readonly (even if this flag is false) by returning false from the
699 ".can_write" callback. So if your plugin can only serve read-only, you
700 can ignore this parameter.
701 If the plugin wants to differentiate the content it serves based on
703 client input, then this is the spot to use nbdkit_export_name() to
704 determine which export the client requested. See also "EXPORT NAME"
705 below.
706 This callback is called after the NBD handshake has completed; if the
708 server requires TLS authentication, then that has occurred as well.
709 But if the server is set up to have optional TLS authentication, you
710 may check "nbdkit_is_tls" to learn whether the client has completed TLS
711 authentication. When running the server in a mode that permits but
712 does not require TLS, be careful that you do not allow unauthenticated
713 clients to cause a denial of service against authentication.
714 If there is an error, ".open" should call "nbdkit_error" with an error
716 message and return "NULL".
717 ".close"
719 void close (void *handle);
720 This is called when the client closes the connection. It should clean
722 up any per-connection resources.
723 Note there is no way in the NBD protocol to communicate close errors
725 back to the client, for example if your plugin calls close(2) and you
726 are checking for errors (as you should do). Therefore the best you can
727 do is to log the error on the server. Well-behaved NBD clients should
728 try to flush the connection before it is closed and check for errors,
729 but obviously this is outside the scope of nbdkit.
730 ".get_size"
732 int64_t get_size (void *handle);
733 This is called during the option negotiation phase of the protocol to
735 get the size (in bytes) of the block device being exported.
736 The returned size must be ≥ 0. If there is an error, ".get_size"
738 should call "nbdkit_error" with an error message and return -1.
739 ".export_description"
741 const char *export_description (void *handle);
742 This is called during the option negotiation phase only if the client
744 specifically requested an export description (see the
745 "NBD_INFO_DESCRIPTION" response to "NBD_OPT_GO"). Any description
746 provided must be human-readable UTF-8, no longer than 4096 bytes.
747 Ideally, this description should match any description set during
748 ".list_exports", but that is not enforced.
749 If the plugin returns "NULL" or an invalid string (such as longer than
751 4096 bytes), or if this callback is omitted, no description is offered
752 to the client. As this is not an error in the protocol, it is not
753 necessary to call "nbdkit_error". If the callback will not be
754 returning a compile-time constant string, you may find
755 "nbdkit_strdup_intern" helpful for returning a value that avoids a
756 memory leak.
757 ".block_size"
759 int block_size (void *handle, uint32_t *minimum,
760 uint32_t *preferred, uint32_t *maximum);
761 This is called during the option negotiation phase of the protocol to
763 get the minimum, preferred and maximum block size (all in bytes) of the
764 block device. The client should obey these constraints by not making
765 requests which are smaller than the minimum size or larger than the
766 maximum size, and usually making requests of a multiple of the
767 preferred size. Furthermore requests should be aligned to at least the
768 minimum block size, and usually the preferred block size.
769 "Preferred" block size in the NBD specification can be misinterpreted.
771 It means the I/O size which does not have a penalty for read-modify-
772 write.
773 Even if the plugin implements this callback, this does not mean that
775 all client requests will obey the constraints. A client could still
776 ignore the constraints. nbdkit passes all requests through to the
777 plugin, because what the plugin does depends on the plugin's policy.
778 It might decide to serve the requests correctly anyway, or reject them
779 with an error. Plugins can avoid this complexity by using
780 nbdkit-blocksize-policy-filter(1) which allows both setting/adjusting
781 the constraints, and selecting an error policy.
782 The minimum block size must be ≥ 1. The maximum block size must be ≤
784 0xffff_ffff. minimum ≤ preferred ≤ maximum.
785 As a special case, the plugin may return minimum == preferred ==
787 maximum == 0, meaning no information.
788 If this callback is not used, then the NBD protocol assumes by default
790 minimum = 1, preferred = 4096. (Maximum block size depends on various
791 factors, see the NBD protocol specification, section "Block size
792 constraints").
793 ".can_write"
795 int can_write (void *handle);
796 This is called during the option negotiation phase to find out if the
798 handle supports writes.
799 If there is an error, ".can_write" should call "nbdkit_error" with an
801 error message and return -1.
802 This callback is not required. If omitted, then we return true iff a
804 ".pwrite" callback has been defined.
805 ".can_flush"
807 int can_flush (void *handle);
808 This is called during the option negotiation phase to find out if the
810 handle supports the flush-to-disk operation.
811 If there is an error, ".can_flush" should call "nbdkit_error" with an
813 error message and return -1.
814 This callback is not required. If omitted, then we return true iff a
816 ".flush" callback has been defined.
817 ".is_rotational"
819 int is_rotational (void *handle);
820 This is called during the option negotiation phase to find out if the
822 backing disk is a rotational medium (like a traditional hard disk) or
823 not (like an SSD). If true, this may cause the client to reorder
824 requests to make them more efficient for a slow rotating disk.
825 If there is an error, ".is_rotational" should call "nbdkit_error" with
827 an error message and return -1.
828 This callback is not required. If omitted, then we return false.
830 ".can_trim"
832 int can_trim (void *handle);
833 This is called during the option negotiation phase to find out if the
835 plugin supports the trim/discard operation for punching holes in the
836 backing storage.
837 If there is an error, ".can_trim" should call "nbdkit_error" with an
839 error message and return -1.
840 This callback is not required. If omitted, then we return true iff a
842 ".trim" callback has been defined.
843 ".can_zero"
845 int can_zero (void *handle);
846 This is called during the option negotiation phase to find out if the
848 plugin wants the ".zero" callback to be utilized. Support for writing
849 zeroes is still advertised to the client (unless the
850 nbdkit-nozero-filter(1) is also used), so returning false merely serves
851 as a way to avoid complicating the ".zero" callback to have to fail
852 with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
853 be more efficient than using ".pwrite" up front.
854 If there is an error, ".can_zero" should call "nbdkit_error" with an
856 error message and return -1.
857 This callback is not required. If omitted, then for a normal zero
859 request, nbdkit always tries ".zero" first if it is present, and
860 gracefully falls back to ".pwrite" if ".zero" was absent or failed with
861 "ENOTSUP" or "EOPNOTSUPP".
862 ".can_fast_zero"
864 int can_fast_zero (void *handle);
865 This is called during the option negotiation phase to find out if the
867 plugin wants to advertise support for fast zero requests. If this
868 support is not advertised, a client cannot attempt fast zero requests,
869 and has no way to tell if writing zeroes offers any speedups compared
870 to using ".pwrite" (other than compressed network traffic). If support
871 is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when
872 the client has requested a fast zero, in which case the plugin must
873 fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
874 offer any benefits over ".pwrite". Advertising support for fast zero
875 requests does not require that writing zeroes be fast, only that the
876 result (whether success or failure) is fast, so this should be
877 advertised when feasible.
878 If there is an error, ".can_fast_zero" should call "nbdkit_error" with
880 an error message and return -1.
881 This callback is not required. If omitted, then nbdkit returns true if
883 ".zero" is absent or ".can_zero" returns false (in those cases, nbdkit
884 fails all fast zero requests, as its fallback to ".pwrite" is not
885 inherently faster), otherwise false (since it cannot be determined in
886 advance if the plugin's ".zero" will properly honor the semantics of
887 "NBDKIT_FLAG_FAST_ZERO").
888 ".can_extents"
890 int can_extents (void *handle);
891 This is called during the option negotiation phase to find out if the
893 plugin supports detecting allocated (non-sparse) regions of the disk
894 with the ".extents" callback.
895 If there is an error, ".can_extents" should call "nbdkit_error" with an
897 error message and return -1.
898 This callback is not required. If omitted, then we return true iff a
900 ".extents" callback has been defined.
901 ".can_fua"
903 int can_fua (void *handle);
904 This is called during the option negotiation phase to find out if the
906 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
907 trim requests. If this returns "NBDKIT_FUA_NONE", FUA support is not
908 advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
909 ".flush" callback must work (even if ".can_flush" returns false), and
910 FUA support is emulated by calling ".flush" after any write operation;
911 if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
912 ".trim" callbacks (if implemented) must handle the flag
913 "NBDKIT_FLAG_FUA", by not returning until that action has landed in
914 persistent storage.
915 If there is an error, ".can_fua" should call "nbdkit_error" with an
917 error message and return -1.
918 This callback is not required unless a plugin wants to specifically
920 handle FUA requests. If omitted, nbdkit checks whether ".flush"
921 exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
922 "NBDKIT_FUA_EMULATE" as appropriate.
923 ".can_multi_conn"
925 int can_multi_conn (void *handle);
926 This is called during the option negotiation phase to find out if the
928 plugin is prepared to handle multiple connections from a single client.
929 If the plugin sets this to true then a client may try to open multiple
930 connections to the nbdkit server and spread requests across all
931 connections to maximize parallelism. If the plugin sets it to false
932 (which is the default) then well-behaved clients should only open a
933 single connection, although we cannot control what clients do in
934 practice.
935 Specifically it means that either the plugin does not cache requests at
937 all. Or if it does cache them then the effects of a ".flush" request
938 or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
939 connections to the plugin before the plugin replies to that request.
940 Properly working clients should send the same export name for each of
942 these connections.
943 If you use Linux nbd-client(8) option -C num with num > 1 then Linux
945 checks this flag and will refuse to connect if ".can_multi_conn" is
946 false.
947 If there is an error, ".can_multi_conn" should call "nbdkit_error" with
949 an error message and return -1.
950 This callback is not required. If omitted, then we return false.
952 ".can_cache"
954 int can_cache (void *handle);
955 This is called during the option negotiation phase to find out if the
957 plugin supports a cache or prefetch operation.
958 This can return:
960 "NBDKIT_CACHE_NONE"
962 Cache support is not advertised to the client.
963 "NBDKIT_CACHE_EMULATE"
965 Caching is emulated by the server calling ".pread" and discarding
966 the result.
967 "NBDKIT_CACHE_NATIVE"
969 Cache support is advertised to the client. The ".cache" callback
970 will be called if it exists, otherwise all cache requests instantly
971 succeed.
972 If there is an error, ".can_cache" should call "nbdkit_error" with an
974 error message and return -1.
975 This callback is not required. If omitted, then we return
977 "NBDKIT_CACHE_NONE" if the ".cache" callback is missing, or
978 "NBDKIT_CACHE_NATIVE" if it is defined.
979 ".pread"
981 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
982 uint32_t flags);
983 During the data serving phase, nbdkit calls this callback to read data
985 from the backing store. "count" bytes starting at "offset" in the
986 backing store should be read and copied into "buf". nbdkit takes care
987 of all bounds- and sanity-checking, so the plugin does not need to
988 worry about that.
989 The parameter "flags" exists in case of future NBD protocol extensions;
991 at this time, it will be 0 on input.
992 The callback must read the whole "count" bytes if it can. The NBD
994 protocol doesn't allow partial reads (instead, these would be errors).
995 If the whole "count" bytes was read, the callback should return 0 to
996 indicate there was no error.
997 If there is an error (including a short read which couldn't be
999 recovered from), ".pread" should call "nbdkit_error" with an error
1000 message, and "nbdkit_set_error" to record an appropriate error (unless
1001 "errno" is sufficient), then return -1.
1002 ".pwrite"
1004 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
1005 uint32_t flags);
1006 During the data serving phase, nbdkit calls this callback to write data
1008 to the backing store. "count" bytes starting at "offset" in the
1009 backing store should be written using the data in "buf". nbdkit takes
1010 care of all bounds- and sanity-checking, so the plugin does not need to
1011 worry about that.
1012 This function will not be called if ".can_write" returned false. The
1014 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1015 result of ".can_fua".
1016 The callback must write the whole "count" bytes if it can. The NBD
1018 protocol doesn't allow partial writes (instead, these would be errors).
1019 If the whole "count" bytes was written successfully, the callback
1020 should return 0 to indicate there was no error.
1021 If there is an error (including a short write which couldn't be
1023 recovered from), ".pwrite" should call "nbdkit_error" with an error
1024 message, and "nbdkit_set_error" to record an appropriate error (unless
1025 "errno" is sufficient), then return -1.
1026 ".flush"
1028 int flush (void *handle, uint32_t flags);
1029 During the data serving phase, this callback is used to fdatasync(2)
1031 the backing store, ie. to ensure it has been completely written to a
1032 permanent medium. If that is not possible then you can omit this
1033 callback.
1034 This function will not be called directly by the client if ".can_flush"
1036 returned false; however, it may still be called by nbdkit if ".can_fua"
1037 returned "NBDKIT_FUA_EMULATE". The parameter "flags" exists in case of
1038 future NBD protocol extensions; at this time, it will be 0 on input.
1039 If there is an error, ".flush" should call "nbdkit_error" with an error
1041 message, and "nbdkit_set_error" to record an appropriate error (unless
1042 "errno" is sufficient), then return -1.
1043 ".trim"
1045 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1046 During the data serving phase, this callback is used to "punch holes"
1048 in the backing store. If that is not possible then you can omit this
1049 callback.
1050 This function will not be called if ".can_trim" returned false. The
1052 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1053 result of ".can_fua".
1054 If there is an error, ".trim" should call "nbdkit_error" with an error
1056 message, and "nbdkit_set_error" to record an appropriate error (unless
1057 "errno" is sufficient), then return -1.
1058 ".zero"
1060 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1061 During the data serving phase, this callback is used to write "count"
1063 bytes of zeroes at "offset" in the backing store.
1064 This function will not be called if ".can_zero" returned false. On
1066 input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
1067 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
1068 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
1069 If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
1071 instead of writing actual zero bytes, but only if subsequent reads from
1072 the hole read as zeroes.
1073 If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up
1075 front if the implementation is likely to be faster than a corresponding
1076 ".pwrite"; if not, then it must immediately fail with "ENOTSUP" or
1077 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno") and preferably
1078 without modifying the exported image. It is acceptable to always fail
1079 a fast zero request (as a fast failure is better than attempting the
1080 write only to find out after the fact that it was not fast after all).
1081 Note that on Linux, support for ioctl(BLKZEROOUT) is insufficient for
1082 determining whether a zero request to a block device will be fast
1083 (because the kernel will perform a slow fallback when needed).
1084 The callback must write the whole "count" bytes if it can. The NBD
1086 protocol doesn't allow partial writes (instead, these would be errors).
1087 If the whole "count" bytes was written successfully, the callback
1088 should return 0 to indicate there was no error.
1089 If there is an error, ".zero" should call "nbdkit_error" with an error
1091 message, and "nbdkit_set_error" to record an appropriate error (unless
1092 "errno" is sufficient), then return -1.
1093 If this callback is omitted, or if it fails with "ENOTSUP" or
1095 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then ".pwrite"
1096 will be used as an automatic fallback except when the client requested
1097 a fast zero.
1098 ".extents"
1100 int extents (void *handle, uint32_t count, uint64_t offset,
1101 uint32_t flags, struct nbdkit_extents *extents);
1102 During the data serving phase, this callback is used to detect
1104 allocated, sparse and zeroed regions of the disk.
1105 This function will not be called if ".can_extents" returned false.
1107 nbdkit's default behaviour in this case is to treat the whole virtual
1108 disk as if it was allocated. Also, this function will not be called by
1109 a client that does not request structured replies (the --no-sr option
1110 of nbdkit can be used to test behavior when ".extents" is unavailable
1111 to the client).
1112 The callback should detect and return the list of extents overlapping
1114 the range "[offset...offset+count-1]". The "extents" parameter points
1115 to an opaque object which the callback should fill in by calling
1116 "nbdkit_add_extent". See "Extents list" below.
1117 If there is an error, ".extents" should call "nbdkit_error" with an
1119 error message, and "nbdkit_set_error" to record an appropriate error
1120 (unless "errno" is sufficient), then return -1.
1121 Extents list
1123 The plugin "extents" callback is passed an opaque pointer "struct
1125 nbdkit_extents *extents". This structure represents a list of
1126 filesystem extents describing which areas of the disk are allocated,
1127 which are sparse (“holes”), and, if supported, which are zeroes.
1128 The "extents" callback should scan the disk starting at "offset" and
1130 call "nbdkit_add_extent" for each extent found.
1131 Extents overlapping the range "[offset...offset+count-1]" should be
1133 returned if possible. However nbdkit ignores extents < offset so the
1134 plugin may, if it is easier to implement, return all extent information
1135 for the whole disk. The plugin may return extents beyond the end of
1136 the range. It may also return extent information for less than the
1137 whole range, but it must return at least one extent overlapping
1138 "offset".
1139 The extents must be added in ascending order, and must be contiguous.
1141 The "flags" parameter of the ".extents" callback may contain the flag
1143 "NBDKIT_FLAG_REQ_ONE". This means that the client is only requesting
1144 information about the extent overlapping "offset". The plugin may
1145 ignore this flag, or as an optimization it may return just a single
1146 extent for "offset".
1147 int nbdkit_add_extent (struct nbdkit_extents *extents,
1149 uint64_t offset, uint64_t length, uint32_t type);
1150 Add an extent covering "[offset...offset+length-1]" of one of the
1152 following four types:
1153 "type = 0"
1155 A normal, allocated data extent.
1156 "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
1158 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
1159 This is the normal type of hole applicable to most disks.
1160 "type = NBDKIT_EXTENT_ZERO"
1162 An allocated extent which is known to contain only zeroes.
1163 "type = NBDKIT_EXTENT_HOLE"
1165 An unallocated extent (hole) which does not read back as zeroes.
1166 Note this should only be used in specialized circumstances such as
1167 when writing a plugin for (or to emulate) certain SCSI drives which
1168 do not guarantee that trimmed blocks read back as zeroes.
1169 "nbdkit_add_extent" returns 0 on success or -1 on failure. On failure
1171 "nbdkit_error" and/or "nbdkit_set_error" has already been called.
1172 "errno" will be set to a suitable value.
1173 ".cache"
1175 int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1176 During the data serving phase, this callback is used to give the plugin
1178 a hint that the client intends to make further accesses to the given
1179 region of the export.
1180 The nature of caching/prefetching is not specified further by the NBD
1182 specification. For example, a server may place limits on how much may
1183 be cached at once, and there is no way to control if writes to a cached
1184 area have write-through or write-back semantics. In fact, the cache
1185 command can always fail and still be compliant, and success might not
1186 guarantee a performance gain.
1187 If this callback is omitted, then the results of ".can_cache" determine
1189 whether nbdkit will reject cache requests, treat them as instant
1190 success, or emulate caching by calling ".pread" over the same region
1191 and ignoring the results.
1192 This function will not be called if ".can_cache" did not return
1194 "NBDKIT_CACHE_NATIVE".
1195 The "flags" parameter exists in case of future NBD protocol extensions;
1197 at this time, it will be 0 on input. A plugin must fail this function
1198 if "flags" includes an unrecognized flag, as that may indicate a
1199 requirement that the plugin must comply with to provide a specific
1200 caching semantic.
1201 If there is an error, ".cache" should call "nbdkit_error" with an error
1203 message, and "nbdkit_set_error" to record an appropriate error (unless
1204 "errno" is sufficient), then return -1.
1205 ".errno_is_preserved"
1207 This field defaults to 0; if non-zero, nbdkit can reliably use the
1208 value of "errno" when a callback reports failure, rather than the
1209 plugin having to call "nbdkit_set_error".
1210
1212 When nbdkit receives certain signals it will shut down (see "SIGNALS"
1213 in nbdkit(1)). The server will wait for any currently running plugin
1214 callbacks to finish, call ".close" on those connections, then call the
1215 ".cleanup" and ".unload" callbacks before unloading the plugin.
1216 Note that it's not guaranteed this can always happen (eg. the server
1218 might be killed by "SIGKILL" or segfault).
1219 Requesting asynchronous shutdown
1221 Plugins and filters can call exit(3) in the configuration phase (before
1222 and including ".get_ready", but not in connected callbacks).
1223 Once nbdkit has started serving connections, plugins and filters should
1225 not call exit(3). However they may instruct nbdkit to shut down by
1226 calling "nbdkit_shutdown", or to disconnect a single client by calling
1227 "nbdkit_disconnect":
1228 void nbdkit_shutdown (void);
1230 This function requests an asynchronous shutdown and returns (note that
1232 it does not exit the process immediately). It ensures that the plugin
1233 and all filters are unloaded cleanly which may take some time. Further
1234 callbacks from nbdkit into the plugin or filter may occur after you
1235 have called this.
1236 void nbdkit_disconnect (int force);
1238 This function requests that the current connection be disconnected
1240 (note that it does not affect other connections, and the client may try
1241 to reconnect). It is only useful from connected callbacks (that is,
1242 after ".open" and before ".close"). If "force" is true, nbdkit will
1243 disconnect the client immediately, and the client will not receive any
1244 response to the current command or any other commands in flight in
1245 parallel threads; otherwise, nbdkit will not accept any new commands
1246 from the client (failing all commands other than "NBD_CMD_DISC" with
1247 "ESHUTDOWN"), but will allow existing commands to complete gracefully.
1248 Either way, the next callback for the current connection should be
1249 ".close".
1250
1252 Parsing numbers
1253 There are several functions for parsing numbers. These all deal
1254 correctly with overflow, out of range and parse errors, and you should
1255 use them instead of unsafe functions like sscanf(3), atoi(3) and
1256 similar.
1257 int nbdkit_parse_int (const char *what, const char *str, int *r);
1259 int nbdkit_parse_unsigned (const char *what,
1260 const char *str, unsigned *r);
1261 int nbdkit_parse_int8_t (const char *what,
1262 const char *str, int8_t *r);
1263 int nbdkit_parse_uint8_t (const char *what,
1264 const char *str, uint8_t *r);
1265 int nbdkit_parse_int16_t (const char *what,
1266 const char *str, int16_t *r);
1267 int nbdkit_parse_uint16_t (const char *what,
1268 const char *str, uint16_t *r);
1269 int nbdkit_parse_int32_t (const char *what,
1270 const char *str, int32_t *r);
1271 int nbdkit_parse_uint32_t (const char *what,
1272 const char *str, uint32_t *r);
1273 int nbdkit_parse_int64_t (const char *what,
1274 const char *str, int64_t *r);
1275 int nbdkit_parse_uint64_t (const char *what,
1276 const char *str, uint64_t *r);
1277 Parse string "str" into an integer of various types. These functions
1279 parse a decimal, hexadecimal ("0x...") or octal ("0...") number.
1280 On success the functions return 0 and set *r to the parsed value
1282 (unless "*r == NULL" in which case the result is discarded). On error,
1283 "nbdkit_error" is called and the functions return -1. On error *r is
1284 always unchanged.
1285 The "what" parameter is printed in error messages to provide context.
1287 It should usually be a short descriptive string of what you are trying
1288 to parse, eg:
1289 if (nbdkit_parse_int ("random seed", value, &seed) == -1)
1291 return -1;
1292 might print an error:
1294 random seed: could not parse number: "lalala"
1296 Parsing sizes
1298 Use the "nbdkit_parse_size" utility function to parse human-readable
1299 size strings such as "100M" into the size in bytes.
1300 int64_t nbdkit_parse_size (const char *str);
1302 "str" can be a string in a number of common formats. The function
1304 returns the size in bytes. If there was an error, it returns -1.
1305 Parsing booleans
1307 Use the "nbdkit_parse_bool" utility function to parse human-readable
1308 strings such as "on" into a boolean value.
1309 int nbdkit_parse_bool (const char *str);
1311 "str" can be a string containing a case-insensitive form of various
1313 common toggle values. The function returns 0 or 1 if the parse was
1314 successful. If there was an error, it returns -1.
1315 Parsing probabilities
1317 Use the "nbdkit_parse_probability" utility function to parse
1318 probabilities. Common formats understood include: "0.1", "1e-1",
1319 "10%", "1:10" or "1/10", which all mean a probability of 1 in 10.
1320 int nbdkit_parse_probability (const char *what, const char *str,
1322 double *ret);
1323 The "what" parameter is printed in error messages to provide context.
1325 The "str" parameter is the probability string.
1326 On success the function returns 0 and sets *ret. The probability is
1328 always a finite number ≥ 0.0, but note the result may be larger than
1329 1.0 (for example if "str == "200%"" then the function will set
1330 "*ret = 2.0"). If you want to clamp the upper bound the caller must do
1331 that.
1332 On error, nbdkit_error is called and -1 is returned.
1334 Reading passwords
1336 The "nbdkit_read_password" utility function can be used to read
1337 passwords from config parameters:
1338 int nbdkit_read_password (const char *value, char **password);
1340 For example:
1342 char *password = NULL;
1344 static int
1346 myplugin_config (const char *key, const char *value)
1347 {
1348 ..
1349 if (strcmp (key, "password") == 0) {
1350 free (password);
1351 if (nbdkit_read_password (value, &password) == -1)
1352 return -1;
1353 }
1354 ..
1355 }
1356 The "password" result string is allocated by malloc, and so you may
1358 need to free it.
1359 This function recognizes several password formats. A password may be
1361 used directly on the command line, eg:
1362 nbdkit myplugin password=mostsecret
1364 But more securely this function can also read a password interactively:
1366 nbdkit myplugin password=-
1368 or from a file:
1370 nbdkit myplugin password=+/tmp/secret
1372 or from a file descriptor inherited by nbdkit:
1374 nbdkit myplugin password=-99
1376 Notes on reading passwords
1378 If the password begins with a "-" or "+" character then it must be
1380 passed in a file.
1381 "password=-" can only be used when stdin is a terminal.
1383 "password=-FD" cannot be used with stdin, stdout or stderr (ie. -0, -1
1385 or -2). The reason is that after reading the password the file
1386 descriptor is closed, which causes bad stuff to happen.
1387 Safely interacting with stdin and stdout
1389 int nbdkit_stdio_safe (void);
1390 The "nbdkit_stdio_safe" utility function returns 1 if it is safe to
1392 interact with stdin and stdout during the configuration phase, and 0
1393 otherwise. This is because when the nbdkit -s option is used the
1394 plugin must not directly interact with stdin, because that would
1395 interfere with the client.
1396 The result of this function only matters in callbacks up to
1398 ".config_complete". Once nbdkit reaches ".get_ready", the plugin
1399 should assume that nbdkit may have closed the original stdin and stdout
1400 in order to become a daemon.
1401 nbdkit-sh-plugin(3) uses this function to determine whether it is safe
1403 to support "script=-" to read a script from stdin. Also constructs
1404 like "password=-" (see "Reading passwords" above) are disabled when
1405 reading from stdio is not safe.
1406
1408 The server usually (not always) changes directory to "/" before it
1409 starts serving connections. This means that any relative paths passed
1410 during configuration will not work when the server is running (example:
1411 "nbdkit plugin.so disk.img").
1412 To avoid problems, prepend relative paths with the current directory
1414 before storing them in the handle. Or open files and store the file
1415 descriptor.
1416 "nbdkit_absolute_path"
1418 char *nbdkit_absolute_path (const char *filename);
1419 The utility function "nbdkit_absolute_path" converts any path to an
1421 absolute path: if it is relative, then all this function does is
1422 prepend the current working directory to the path, with no extra
1423 checks.
1424 Note that this function works only when used in the ".config",
1426 ".config_complete" and ".get_ready" callbacks.
1427 If conversion was not possible, this calls "nbdkit_error" and returns
1429 "NULL". Note that this function does not check that the file exists.
1430 The returned string must be freed by the caller.
1432 "nbdkit_realpath"
1434 char *nbdkit_realpath (const char *filename);
1435 The utility function "nbdkit_realpath" converts any path to an absolute
1437 path, resolving symlinks. Under the hood it uses the "realpath"
1438 function, and thus it fails if the path does not exist, or it is not
1439 possible to access to any of the components of the path.
1440 Note that this function works only when used in the ".config",
1442 ".config_complete" and ".get_ready" callbacks.
1443 If the path resolution was not possible, this calls "nbdkit_error" and
1445 returns "NULL".
1446 The returned string must be freed by the caller.
1448 umask
1450 All plugins will see a umask(2) of 0022.
1451
1453 A plugin that needs to sleep may call sleep(2), nanosleep(2) and
1454 similar. However that can cause nbdkit to delay excessively when
1455 shutting down (since it must wait for any plugin or filter which is
1456 sleeping). To avoid this there is a special wrapper around nanosleep
1457 which plugins and filters should use instead.
1458 "nbdkit_nanosleep"
1460 int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1461 The utility function "nbdkit_nanosleep" suspends the current thread,
1463 and returns 0 if it slept at least as many seconds and nanoseconds as
1464 requested, or -1 after calling "nbdkit_error" if there is no point in
1465 continuing the current command. Attempts to sleep more than "INT_MAX"
1466 seconds are treated as an error.
1467
1469 If the client negotiated an NBD export name with nbdkit then plugins
1470 may read this from any connected callbacks. Nbdkit's normal behaviour
1471 is to accept any export name passed by the client, log it in debug
1472 output, but otherwise ignore it. By using "nbdkit_export_name" plugins
1473 may choose to filter by export name or serve different content.
1474 "nbdkit_export_name"
1476 const char *nbdkit_export_name (void);
1477 Return the optional NBD export name if one was negotiated with the
1479 current client (this uses thread-local magic so no parameter is
1480 required). The returned string is valid at least through the ".close"
1481 of the current connection, but if you need to store it in the plugin
1482 for use by more than one client you must copy it.
1483 The export name is a free-form text string, it is not necessarily a
1485 path or filename and it does not need to begin with a '/' character.
1486 The NBD protocol describes the empty string ("") as a representing a
1487 "default export" or to be used in cases where the export name does not
1488 make sense. The export name is untrusted client data, be cautious when
1489 parsing it.
1490 On error, "nbdkit_error" is called and the call returns "NULL".
1492
1494 Some callbacks are specified to return "const char *", even when a
1495 plugin may not have a suitable compile-time constant to return.
1496 Returning dynamically-allocated memory for such a callback would induce
1497 a memory leak or otherwise complicate the plugin to perform additional
1498 bookkeeping. For these cases, nbdkit provides several convenience
1499 functions for creating a copy of a string for better lifetime
1500 management.
1501 "nbdkit_strdup_intern"
1503 "nbdkit_strndup_intern"
1504 const char *nbdkit_strdup_intern (const char *str);
1505 const char *nbdkit_strndup_intern (const char *str, size_t n);
1506 Returns a copy of "str", possibly limited to a maximum of "n" bytes, so
1508 that the caller may reclaim str and use the copy in its place. If the
1509 copy is created outside the scope of a connection (such as during
1510 ".load" or ".config"), the lifetime of the copy will last at least
1511 through ".unload". If the copy is created after a client has triggered
1512 a connection (such as during ".preconnect" or ".open"), the lifetime
1513 will last at least through ".close", but the copy is not safe to share
1514 with other connections.
1515 On error, "nbdkit_error" is called and the call returns "NULL".
1517 "nbdkit_printf_intern"
1519 "nbdkit_vprintf_intern"
1520 const char *nbdkit_printf_intern (const char *fmt, ...);
1521 const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);
1522 Return a string created from a format template, with a lifetime longer
1524 than the current connection. Shorthand for passing "fmt" to
1525 asprintf(3) on a temporary string, then passing that result to
1526 "nbdkit_strdup_intern".
1527 On error, "nbdkit_error" is called and the call returns "NULL".
1529
1531 A server may use "nbdkit_is_tls" to limit which export names work until
1532 after a client has completed TLS authentication. See nbdkit-tls(1).
1533 It is also possible to use nbdkit-tls-fallback-filter(1) to
1534 automatically ensure that the plugin is only used with authentication.
1535 "nbdkit_is_tls"
1537 int nbdkit_is_tls (void);
1538 Return true if the client has completed TLS authentication, or false if
1540 the connection is still plaintext.
1541 On error (such as calling this function outside of the context of
1543 ".open"), "nbdkit_error" is called and the call returns -1.
1544
1546 It is possible to get the source address of the client when you are
1547 running in any connected callback.
1548 "nbdkit_peer_name"
1550 int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1551 Return the peer (client) address, if available. The "addr" and
1553 "addrlen" parameters behave like getpeername(2). In particular you
1554 must initialize "addrlen" with the size of the buffer pointed to by
1555 "addr", and if "addr" is not large enough then the address will be
1556 truncated.
1557 In some cases this is not available or the address returned will be
1559 meaningless (eg. if there is a proxy between the client and nbdkit).
1560 This call uses thread-local magic so no parameter is required to
1561 specify the current connection.
1562 On success this returns 0. On error, "nbdkit_error" is called and this
1564 call returns -1.
1565 "nbdkit_peer_pid"
1567 (nbdkit ≥ 1.24, Linux only)
1568 int64_t nbdkit_peer_pid (void);
1570 Return the peer process ID. This is only available when the client
1572 connected over a Unix domain socket.
1573 On success this returns the peer process ID. On error, "nbdkit_error"
1575 is called and this call returns -1.
1576 "nbdkit_peer_uid"
1578 (nbdkit ≥ 1.24)
1579 int64_t nbdkit_peer_uid (void);
1581 Return the peer user ID. This is only available when the client
1583 connected over a Unix domain socket.
1584 On success this returns the user ID. On error, "nbdkit_error" is
1586 called and this call returns -1.
1587 "nbdkit_peer_gid"
1589 (nbdkit ≥ 1.24)
1590 int64_t nbdkit_peer_gid (void);
1592 Return the peer group ID. This is only available when the client
1594 connected over a Unix domain socket.
1595 On success this returns the user ID. On error, "nbdkit_error" is
1597 called and this call returns -1.
1598 "nbdkit_peer_security_context"
1600 (nbdkit ≥ 1.36, not Windows)
1601 char *nbdkit_peer_security_context (void);
1603 Return the peer security context (usually the SELinux label, IPSEC
1605 label or NetLabel, see the description of "SO_PEERSEC" in unix(7) and
1606 ip(7).
1607 On success this returns the security context as a string. The caller
1609 must free the string. On error (which can include missing label or
1610 unsupported protocol), "nbdkit_error" is called and this call returns
1611 "NULL".
1612
1614 Compile-time version of nbdkit
1615 The macros "NBDKIT_VERSION_MAJOR", "NBDKIT_VERSION_MINOR" and
1616 "NBDKIT_VERSION_MICRO" expand to integers containing the version of the
1617 nbdkit headers that you are compiling against.
1618 "NBDKIT_VERSION_MAJOR" is always 1. "NBDKIT_VERSION_MINOR" is even for
1620 stable releases of nbdkit and odd for development releases.
1621 The macro "NBDKIT_VERSION_STRING" expands to the same version as a
1623 string.
1624 Run-time version of nbdkit
1626 When the plugin is loaded into nbdkit, it may not be the same version
1627 that it was compiled against. nbdkit guarantees backwards
1628 compatibility of the API and ABI, so provided that nbdkit is the same
1629 version or newer, the plugin will still work. There is no way to get
1630 the version of nbdkit from the plugin.
1631 Version of the plugin
1633 The plugin itself can use any versioning scheme you want, and put any
1634 string into the ".version" field of the plugin struct (or leave the
1635 field NULL).
1636 API version
1638 See "WRITING AN NBDKIT PLUGIN" above.
1639
1641 Run the server with -f and -v options so it doesn't fork and you can
1642 see debugging information:
1643 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1645 To print debugging information from within the plugin, call
1647 "nbdkit_debug", which has the following prototype and works like
1648 printf(3):
1649 void nbdkit_debug (const char *fs, ...);
1651 void nbdkit_vdebug (const char *fs, va_list args);
1652 For convenience, "nbdkit_debug" preserves the value of "errno", and
1654 also supports the glibc extension of a single %m in a format string
1655 expanding to strerror(errno), even on platforms that don't support that
1656 natively. Note that "nbdkit_debug" only prints things when the server
1657 is in verbose mode (-v option).
1658 Debug Flags
1660 The -v option switches general debugging on or off, and this debugging
1661 should be used for messages which are useful for all users of your
1662 plugin.
1663 In cases where you want to enable specific extra debugging to track
1665 down bugs in plugins or filters — mainly for use by the plugin/filter
1666 developers themselves — you can define Debug Flags. These are global
1667 ints called "myplugin_debug_*":
1668 int myplugin_debug_foo;
1670 int myplugin_debug_bar;
1671 ...
1672 if (myplugin_debug_foo) {
1673 nbdkit_debug ("lots of extra debugging about foo: ...");
1674 }
1675 Debug Flags can be controlled on the command line using the -D (or
1677 --debug) option:
1678 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1680 Note "myplugin" is the name passed to ".name" in the "struct
1682 nbdkit_plugin".
1683 You should only use this feature for debug settings. For general
1685 settings use ordinary plugin parameters. Debug Flags can only be C
1686 ints. They are not supported by non-C language plugins.
1687 For convenience '.' characters are replaced with '_' characters in the
1689 variable name, so both of these parameters:
1690 -D myplugin.foo_bar=1
1692 -D myplugin.foo.bar=1
1693 correspond to the plugin variable "myplugin_debug_foo_bar".
1695
1697 Plugins should be compiled as shared libraries. There are various ways
1698 to achieve this, but most Linux compilers support a -shared option to
1699 create the shared library directly, for example:
1700 gcc -fPIC -shared myplugin.c -o myplugin.so
1702 Note that the shared library will have undefined symbols for functions
1704 that you call like "nbdkit_parse_int" or "nbdkit_error". These will be
1705 resolved by the server binary when nbdkit dlopens the plugin.
1706 PKG-CONFIG/PKGCONF
1708 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
1709 should be installed on the correct path when the nbdkit plugin
1710 development environment is installed. You can use this in autoconf
1711 configure.ac scripts to test for the development environment:
1712 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1714 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
1716 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
1717 for compiling plugins.
1718 You can also run pkg-config/pkgconf directly, for example:
1720 if ! pkg-config nbdkit --exists; then
1722 echo "you must install the nbdkit plugin development environment"
1723 exit 1
1724 fi
1725 You can also substitute the plugindir variable by doing:
1727 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1729 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
1731 If nbdkit development headers are installed in a non-standard location
1733 then you may need to compile plugins using:
1734 gcc -fPIC -shared myplugin.c -o myplugin.so \
1736 `pkg-config nbdkit --cflags --libs`
1737
1739 The plugin is a "*.so" file and possibly a manual page. You can of
1740 course install the plugin "*.so" file wherever you want, and users will
1741 be able to use it by running:
1742 nbdkit /path/to/plugin.so [args]
1744 However if the shared library has a name of the form
1746 "nbdkit-name-plugin.so" and if the library is installed in the
1747 $plugindir directory, then users can be run it by only typing:
1748 nbdkit name [args]
1750 The location of the $plugindir directory is set when nbdkit is compiled
1752 and can be found by doing:
1753 nbdkit --dump-config
1755 If using the pkg-config/pkgconf system then you can also find the
1757 plugin directory at compile time by doing:
1758 pkg-config nbdkit --variable=plugindir
1760
1762 Plugins in C++ work almost exactly like those in C, but the way you
1763 define the "nbdkit_plugin" struct is slightly different:
1764 namespace {
1766 nbdkit_plugin create_plugin() {
1767 nbdkit_plugin plugin = nbdkit_plugin ();
1768 plugin.name = "myplugin";
1769 plugin.open = myplugin_open;
1770 plugin.get_size = myplugin_get_size;
1771 plugin.pread = myplugin_pread;
1772 plugin.pwrite = myplugin_pwrite;
1773 return plugin;
1774 }
1775 }
1776 static struct nbdkit_plugin plugin = create_plugin ();
1777 NBDKIT_REGISTER_PLUGIN(plugin)
1778
1780 You can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python,
1781 Ruby, Rust, shell script or Tcl. Other programming languages may be
1782 offered in future.
1783 For more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
1785 nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
1786 nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
1787 nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1788 Plugins written in scripting languages may also be installed in
1790 $plugindir. These must be called "nbdkit-name-plugin" without any
1791 extension. They must be executable, and they must use the shebang
1792 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
1793 written in Perl called "foo.pl" might be installed like this:
1794 $ head -1 foo.pl
1796 #!/usr/sbin/nbdkit perl
1797 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1799 and then users will be able to run it like this:
1801 $ nbdkit foo [args ...]
1803
1805 nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1),
1806 nbdkit-filter(3).
1807 Standard plugins provided by nbdkit:
1809 nbdkit-blkio-plugin(1), nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1),
1811 nbdkit-data-plugin(1), nbdkit-eval-plugin(1),
1812 nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
1813 nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
1814 nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-full-plugin(1),
1815 nbdkit-guestfs-plugin(1), nbdkit-info-plugin(1), nbdkit-iso-plugin(1),
1816 nbdkit-libvirt-plugin(1), nbdkit-linuxdisk-plugin(1),
1817 nbdkit-memory-plugin(1), nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
1818 nbdkit-ondemand-plugin(1), nbdkit-ones-plugin(1),
1819 nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
1820 nbdkit-random-plugin(1), nbdkit-S3-plugin(1),
1821 nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1),
1822 nbdkit-ssh-plugin(1), nbdkit-tmpdisk-plugin(1),
1823 nbdkit-torrent-plugin(1), nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1)
1824 ; nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3),
1825 nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
1826 nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
1827 nbdkit-tcl-plugin(3) .
1828
1830 Eric Blake
1831 Richard W.M. Jones
1833 Pino Toscano
1835
1837 Copyright Red Hat
1838
1840 Redistribution and use in source and binary forms, with or without
1841 modification, are permitted provided that the following conditions are
1842 met:
1843 • Redistributions of source code must retain the above copyright
1845 notice, this list of conditions and the following disclaimer.
1846 • Redistributions in binary form must reproduce the above copyright
1848 notice, this list of conditions and the following disclaimer in the
1849 documentation and/or other materials provided with the
1850 distribution.
1851 • Neither the name of Red Hat nor the names of its contributors may
1853 be used to endorse or promote products derived from this software
1854 without specific prior written permission.
1855 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1857 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1858 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1859 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1860 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1861 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1862 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1863 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1864 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1865 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1866 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1867nbdkit-1.36.2 2023-11-26 nbdkit-plugin(3)