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://github.com/libguestfs/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 │ unload │
176 └──────────────────┘
177 ".load"
179 is called once just after the plugin is loaded into memory.
180 ".config" and ".config_complete"
182 ".config" is called zero or more times during command line parsing.
183 ".config_complete" is called once after all configuration
184 information has been passed to the plugin (but not during "nbdkit
185 --dump-plugin").
186 Both are called after loading the plugin but before any connections
188 are accepted.
189 ".thread_model"
191 In normal operation, ".thread_model" is called once after
192 ".config_complete" has validated all configuration information, and
193 before any connections are accepted. However, during "nbdkit
194 --dump-plugin", it is called after any ".config" calls but without
195 ".config_complete" (so a plugin which determines the results from a
196 script must be prepared for a missing script).
197 ".get_ready"
199 In normal operation, ".get_ready" is called before the server
200 starts serving. It is called before the server forks or changes
201 directory. It is normally the last chance to do any global
202 preparation that is needed to serve connections.
203 Plugins should not create background threads here. Use
205 ".after_fork" instead.
206 ".after_fork"
208 In normal operation, ".after_fork" is called after the server has
209 forked into the background and changed UID and directory. If a
210 plugin needs to create background threads (or uses an external
211 library that creates threads) it should do so here, because
212 background threads are invalidated by fork.
213 Because the server may have forked into the background, error
215 messages and failures from ".after_fork" cannot be seen by the user
216 unless they look through syslog. An error in ".after_fork" can
217 appear to the user as if nbdkit “just died”. So in almost all
218 cases it is better to use ".get_ready" instead of this callback, or
219 to do as much preparation work as possible in ".get_ready" and only
220 start background threads here.
221 The server doesn't always fork (eg. if the -f flag is used), but
223 even so this callback will be called. If you want to find out if
224 the server forked between ".get_ready" and ".after_fork" use
225 getpid(2).
226 ".preconnect"
228 Called when a TCP connection has been made to the server. This
229 happens early, before NBD or TLS negotiation.
230 ".list_exports"
232 Early in option negotiation the client may try to list the exports
233 served by the plugin, and plugins can optionally implement this
234 callback to answer the client. See "EXPORT NAME" below.
235 ".default_export"
237 During option negotiation, if the client requests the default
238 export name (""), this optional callback provides a canonical name
239 to use in its place prior to calling ".open".
240 ".open"
242 A new client has connected and finished the NBD handshake. TLS
243 negotiation (if required) has been completed successfully.
244 ".can_write", ".get_size" and other option negotiation callbacks
246 These are called during option negotiation with the client, but
247 before any data is served. These callbacks may return different
248 values across different ".open" calls, but within a single
249 connection, they are called at most once and cached by nbdkit for
250 that connection.
251 ".pread", ".pwrite" and other data serving callbacks
253 After option negotiation has finished, these may be called to serve
254 data. Depending on the thread model chosen, they might be called
255 in parallel from multiple threads. The data serving callbacks
256 include a flags argument; the results of the negotiation callbacks
257 influence whether particular flags will ever be passed to a data
258 callback.
259 ".close"
261 The client has disconnected.
262 ".preconnect", ".open" ... ".close"
264 The sequence ".preconnect", ".open" ... ".close" can be called
265 repeatedly over the lifetime of the plugin, and can be called in
266 parallel (depending on the thread model).
267 ".unload"
269 is called once just before the plugin is unloaded from memory.
270 Flags
272 The following flags are defined by nbdkit, and used in various data
273 serving callbacks as follows:
274 "NBDKIT_FLAG_MAY_TRIM"
276 This flag is used by the ".zero" callback; there is no way to
277 disable this flag, although a plugin that does not support trims as
278 a way to write zeroes may ignore the flag without violating
279 expected semantics.
280 "NBDKIT_FLAG_FUA"
282 This flag represents Forced Unit Access semantics. It is used by
283 the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
284 plugin must not return a result until the action has landed in
285 persistent storage. This flag will not be sent to the plugin
286 unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
287 The following defines are valid as successful return values for
289 ".can_fua":
290 "NBDKIT_FUA_NONE"
292 Forced Unit Access is not supported; the client must manually
293 request a flush after writes have completed. The "NBDKIT_FLAG_FUA"
294 flag will not be passed to the plugin's write callbacks.
295 "NBDKIT_FUA_EMULATE"
297 The client may request Forced Unit Access, but it is implemented by
298 emulation, where nbdkit calls ".flush" after a write operation;
299 this is semantically correct, but may hurt performance as it tends
300 to flush more data than just what the client requested. The
301 "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
302 callbacks.
303 "NBDKIT_FUA_NATIVE"
305 The client may request Forced Unit Access, which results in the
306 "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
307 (".pwrite", ".trim", and ".zero"). When the flag is set, these
308 callbacks must not return success until the client's request has
309 landed in persistent storage.
310 The following defines are valid as successful return values for
312 ".can_cache":
313 "NBDKIT_CACHE_NONE"
315 The server does not advertise caching support, and rejects any
316 client-requested caching. Any ".cache" callback is ignored.
317 "NBDKIT_CACHE_EMULATE"
319 The nbdkit server advertises cache support to the client, where the
320 client may request that the server cache a region of the export to
321 potentially speed up future read and/or write operations on that
322 region. The nbdkit server implements the caching by calling
323 ".pread" and ignoring the results. This option exists to ease the
324 implementation of a common form of caching; any ".cache" callback
325 is ignored.
326 "NBDKIT_CACHE_NATIVE"
328 The nbdkit server advertises cache support to the client, where the
329 client may request that the server cache a region of the export to
330 potentially speed up future read and/or write operations on that
331 region. The nbdkit server calls the ".cache" callback to perform
332 the caching; if that callback is missing, the client's cache
333 request succeeds without doing anything.
334 Threads
336 Each nbdkit plugin must declare its maximum thread safety model by
337 defining the "THREAD_MODEL" macro. (This macro is used by
338 "NBDKIT_REGISTER_PLUGIN"). Additionally, a plugin may implement the
339 ".thread_model" callback, called right after ".config_complete" to make
340 a runtime decision on which thread model to use. The nbdkit server
341 chooses the most restrictive model between the plugin's "THREAD_MODEL",
342 the ".thread_model" if present, any restrictions requested by filters,
343 and any limitations imposed by the operating system.
344 In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line
346 matches the "THREAD_MODEL" macro, and the "thread_model" line matches
347 what the system finally settled on after applying all restrictions.
348 The possible settings for "THREAD_MODEL" are defined below.
350 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
352 Only a single handle can be open at any time, and all requests
353 happen from one thread.
354 Note this means only one client can connect to the server at any
356 time. If a second client tries to connect it will block waiting
357 for the first client to close the connection.
358 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
360 This is a safe default for most plugins.
361 Multiple handles can be open at the same time, but requests are
363 serialized so that for the plugin as a whole only one
364 open/read/write/close (etc) request will be in progress at any
365 time.
366 This is a useful setting if the library you are using is not
368 thread-safe. However performance may not be good.
369 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
371 Multiple handles can be open and multiple data requests can happen
372 in parallel. However only one request will happen per handle at a
373 time (but requests on different handles might happen concurrently).
374 "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
376 Multiple handles can be open and multiple data requests can happen
377 in parallel (even on the same handle). The server may reorder
378 replies, answering a later request before an earlier one.
379 All the libraries you use must be thread-safe and reentrant, and
381 any code that creates a file descriptor should atomically set
382 "FD_CLOEXEC" if you do not want it accidentally leaked to another
383 thread's child process. You may also need to provide mutexes for
384 fields in your connection handle.
385 If none of the above thread models are suitable, use
387 "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
388 "pthread_mutex_t" etc.
389 Error handling
391 If there is an error in the plugin, the plugin should call
392 "nbdkit_error" to report an error message; additionally, if the
393 callback is involved in serving data, the plugin should call
394 "nbdkit_set_error" to influence the error code that will be sent to the
395 client. These two functions can be called in either order. Then, the
396 callback should return the appropriate error indication, eg. "NULL" or
397 "-1".
398 If the call to "nbdkit_set_error" is omitted while serving data, then
400 the global variable "errno" may be used. For plugins which have
401 ".errno_is_preserved != 0" the core code will use "errno". In plugins
402 written in non-C languages, we usually cannot trust that "errno" will
403 not be overwritten when returning from that language to C. In that
404 case, either the plugin must call "nbdkit_set_error" or hard-coded
405 "EIO" is used.
406 "nbdkit_error" has the following prototype and works like printf(3):
408 void nbdkit_error (const char *fs, ...);
410 void nbdkit_verror (const char *fs, va_list args);
411 For convenience, "nbdkit_error" preserves the value of "errno", and
413 also supports the glibc extension of a single %m in a format string
414 expanding to "strerror(errno)", even on platforms that don't support
415 that natively.
416 "nbdkit_set_error" can be called at any time, but only has an impact
418 during callbacks for serving data, and only when the callback returns
419 an indication of failure. It has the following prototype:
420 void nbdkit_set_error (int err);
422
424 ".name"
425 const char *name;
426 This field (a string) is required, and must contain only ASCII
428 alphanumeric characters or non-leading dashes, and be unique amongst
429 all plugins.
430 ".version"
432 const char *version;
433 Plugins may optionally set a version string which is displayed in help
435 and debugging output.
436 ".longname"
438 const char *longname;
439 An optional free text name of the plugin. This field is used in error
441 messages.
442 ".description"
444 const char *description;
445 An optional multi-line description of the plugin.
447 ".load"
449 void load (void);
450 This is called once just after the plugin is loaded into memory. You
452 can use this to perform any global initialization needed by the plugin.
453 ".unload"
455 void unload (void);
456 This may be called once just before the plugin is unloaded from memory.
458 Note that it's not guaranteed that ".unload" will always be called (eg.
459 the server might be killed or segfault), so you should try to make the
460 plugin as robust as possible by not requiring cleanup. See also
461 "SHUTDOWN" below.
462 ".dump_plugin"
464 void dump_plugin (void);
465 This optional callback is called when the "nbdkit plugin --dump-plugin"
467 command is used. It should print any additional informative
468 "key=value" fields to stdout as needed. Prefixing the keys with the
469 name of the plugin will avoid conflicts.
470 ".config"
472 int config (const char *key, const char *value);
473 On the nbdkit command line, after the plugin filename, come an optional
475 list of "key=value" arguments. These are passed to the plugin through
476 this callback when the plugin is first loaded and before any
477 connections are accepted.
478 This callback may be called zero or more times.
480 Both "key" and "value" parameters will be non-NULL. The strings are
482 owned by nbdkit but will remain valid for the lifetime of the plugin,
483 so the plugin does not need to copy them.
484 The key will be a non-empty string beginning with an ASCII alphabetic
486 character ("A-Z" "a-z"). The rest of the key must contain only ASCII
487 alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
488 "0-9" "." "_" "-"). The value may be an arbitrary string, including an
489 empty string.
490 The names of "key"s accepted by plugins is up to the plugin, but you
492 should probably look at other plugins and follow the same conventions.
493 If the value is a relative path, then note that the server changes
495 directory when it starts up. See "FILENAMES AND PATHS" above.
496 If "nbdkit_stdio_safe" returns 1, the value of the configuration
498 parameter may be used to trigger reading additional data through stdin
499 (such as a password or inline script).
500 If the ".config" callback is not provided by the plugin, and the user
502 tries to specify any "key=value" arguments, then nbdkit will exit with
503 an error.
504 If there is an error, ".config" should call "nbdkit_error" with an
506 error message and return "-1".
507 ".magic_config_key"
509 const char *magic_config_key;
510 This optional string can be used to set a "magic" key used when parsing
512 plugin parameters. It affects how "bare parameters" (those which do
513 not contain an "=" character) are parsed on the command line.
514 If "magic_config_key != NULL" then any bare parameters are passed to
516 the ".config" method as: "config (magic_config_key, argv[i]);".
517 If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
519 the first parameter on the command line is bare then it is passed to
520 the ".config" method as: "config ("script", value);". Any other bare
521 parameters give errors.
522 ".config_complete"
524 int config_complete (void);
525 This optional callback is called after all the configuration has been
527 passed to the plugin. It is a good place to do checks, for example
528 that the user has passed the required parameters to the plugin.
529 If there is an error, ".config_complete" should call "nbdkit_error"
531 with an error message and return "-1".
532 ".config_help"
534 const char *config_help;
535 This optional multi-line help message should summarize any "key=value"
537 parameters that it takes. It does not need to repeat what already
538 appears in ".description".
539 If the plugin doesn't take any config parameters you should probably
541 omit this.
542 ".thread_model"
544 int thread_model (void)
545 This optional callback is called after all the configuration has been
547 passed to the plugin. It can be used to force a stricter thread model
548 based on configuration, compared to "THREAD_MODEL". See "Threads"
549 above for details. Attempts to request a looser (more parallel) model
550 are silently ignored.
551 If there is an error, ".thread_model" should call "nbdkit_error" with
553 an error message and return "-1".
554 ".get_ready"
556 int get_ready (void);
557 This optional callback is called before the server starts serving. It
559 is called before the server forks or changes directory. It is
560 ordinarily the last chance to do any global preparation that is needed
561 to serve connections.
562 If there is an error, ".get_ready" should call "nbdkit_error" with an
564 error message and return "-1".
565 ".after_fork"
567 int after_fork (void);
568 This optional callback is called before the server starts serving. It
570 is called after the server forks and changes directory. If a plugin
571 needs to create background threads (or uses an external library that
572 creates threads) it should do so here, because background threads are
573 killed by fork. However you should try to do as little as possible
574 here because error reporting is difficult. See "Callback lifecycle"
575 above.
576 If there is an error, ".after_fork" should call "nbdkit_error" with an
578 error message and return "-1".
579 ".preconnect"
581 int preconnect (int readonly);
582 This optional callback is called when a TCP connection has been made to
584 the server. This happens early, before NBD or TLS negotiation. If TLS
585 authentication is required to access the server, then it has not been
586 negotiated at this point.
587 For security reasons (to avoid denial of service attacks) this callback
589 should be written to be as fast and take as few resources as possible.
590 If you use this callback, only use it to do basic access control, such
591 as checking "nbdkit_peer_name", "nbdkit_peer_pid", "nbdkit_peer_uid",
592 "nbdkit_peer_gid" against a list of permitted source addresses (see
593 "PEER NAME" and nbdkit-ip-filter(1)). It may be better to do access
594 control outside the server, for example using TCP wrappers or a
595 firewall.
596 The "readonly" flag informs the plugin that the server was started with
598 the -r flag on the command line.
599 Returning 0 will allow the connection to continue. If there is an
601 error or you want to deny the connection, call "nbdkit_error" with an
602 error message and return "-1".
603 ".list_exports"
605 int list_exports (int readonly, int is_tls,
606 struct nbdkit_exports *exports);
607 This optional callback is called if the client tries to list the
609 exports served by the plugin (using "NBD_OPT_LIST"). If the plugin
610 does not supply this callback then the result of ".default_export" is
611 advertised as the lone export. The NBD protocol defines "" as the
612 default export, so this is suitable for plugins which ignore the export
613 name and always serve the same content. See also "EXPORT NAME" below.
614 The "readonly" flag informs the plugin that the server was started with
616 the -r flag on the command line, which is the same value passed to
617 ".preconnect" and ".open". However, the NBD protocol does not yet have
618 a way to let the client advertise an intent to be read-only even when
619 the server allows writes, so this parameter may not be as useful as it
620 appears.
621 The "is_tls" flag informs the plugin whether this listing was requested
623 after the client has completed TLS negotiation. When running the
624 server in a mode that permits but does not require TLS, be careful that
625 any exports listed when "is_tls" is "false" do not leak unintended
626 information.
627 The "exports" parameter is an opaque object for collecting the list of
629 exports. Call "nbdkit_add_export" as needed to add specific exports to
630 the list.
631 int nbdkit_add_export (struct nbdkit_export *exports,
633 const char *name, const char *description);
634 The "name" must be a non-NULL, UTF-8 string between 0 and 4096 bytes in
636 length. Export names must be unique. "description" is an optional
637 description of the export which some clients can display but which is
638 otherwise unused (if you don't want a description, you can pass this
639 parameter as "NULL"). The string(s) are copied into the exports list
640 so you may free them immediately after calling this function.
641 "nbdkit_add_export" returns 0 on success or "-1" on failure; on failure
642 "nbdkit_error" has already been called, with "errno" set to a suitable
643 value.
644 There are also situations where a plugin may wish to duplicate the
646 nbdkit default behavior of supplying an export list containing only the
647 result of ".default_export" when ".list_exports" is missing; this is
648 most common in a language binding where it is not known at compile time
649 whether the language script will be providing an implementation for
650 ".list_exports", and is done by calling "nbdkit_use_default_export".
651 int nbdkit_use_default_export (struct nbdkit_export *exports);
653 "nbdkit_use_default_export" returns 0 on success or "-1" on failure; on
655 failure "nbdkit_error" has already been called, with "errno" set to a
656 suitable value.
657 The plugin may also leave the export list empty, by not calling either
659 helper. Once the plugin is happy with the list contents, returning 0
660 will send the list of exports back to the client. If there is an
661 error, ".list_exports" should call "nbdkit_error" with an error message
662 and return "-1".
663 ".default_export"
665 const char *default_export (int readonly, int is_tls);
666 This optional callback is called if the client tries to connect to the
668 default export "", where the plugin provides a UTF-8 string between 0
669 and 4096 bytes. If the plugin does not supply this callback, the
670 connection continues with the empty name; if the plugin returns a valid
671 string, nbdkit behaves as if the client had passed that string instead
672 of an empty name, and returns that name to clients that support it (see
673 the "NBD_INFO_NAME" response to "NBD_OPT_GO"). Similarly, if the
674 plugin does not supply a ".list_exports" callback, the result of this
675 callback determines what export name to advertise to a client
676 requesting an export list.
677 The "readonly" flag informs the plugin that the server was started with
679 the -r flag on the command line, which is the same value passed to
680 ".preconnect" and ".open". However, the NBD protocol does not yet have
681 a way to let the client advertise an intent to be read-only even when
682 the server allows writes, so this parameter may not be as useful as it
683 appears.
684 The "is_tls" flag informs the plugin whether the canonical name for the
686 default export is being requested after the client has completed TLS
687 negotiation. When running the server in a mode that permits but does
688 not require TLS, be careful that a default export name does not leak
689 unintended information.
690 If the plugin returns "NULL" or an invalid string (such as longer than
692 4096 bytes), the client is not permitted to connect to the default
693 export. However, this is not an error in the protocol, so it is not
694 necessary to call "nbdkit_error".
695 ".open"
697 void *open (int readonly);
698 This is called when a new client connects to the nbdkit server. The
700 callback should allocate a handle and return it. This handle is passed
701 back to other callbacks and could be freed in the ".close" callback.
702 Note that the handle is completely opaque to nbdkit, but it must not be
704 NULL. If you don't need to use a handle, return
705 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
706 The "readonly" flag informs the plugin that the server was started with
708 the -r flag on the command line which forces connections to be read-
709 only. Note that the plugin may additionally force the connection to be
710 readonly (even if this flag is false) by returning false from the
711 ".can_write" callback. So if your plugin can only serve read-only, you
712 can ignore this parameter.
713 If the plugin wants to differentiate the content it serves based on
715 client input, then this is the spot to use "nbdkit_export_name()" to
716 determine which export the client requested. See also "EXPORT NAME"
717 below.
718 This callback is called after the NBD handshake has completed; if the
720 server requires TLS authentication, then that has occurred as well.
721 But if the server is set up to have optional TLS authentication, you
722 may check "nbdkit_is_tls" to learn whether the client has completed TLS
723 authentication. When running the server in a mode that permits but
724 does not require TLS, be careful that you do not allow unauthenticated
725 clients to cause a denial of service against authentication.
726 If there is an error, ".open" should call "nbdkit_error" with an error
728 message and return "NULL".
729 ".close"
731 void close (void *handle);
732 This is called when the client closes the connection. It should clean
734 up any per-connection resources.
735 Note there is no way in the NBD protocol to communicate close errors
737 back to the client, for example if your plugin calls close(2) and you
738 are checking for errors (as you should do). Therefore the best you can
739 do is to log the error on the server. Well-behaved NBD clients should
740 try to flush the connection before it is closed and check for errors,
741 but obviously this is outside the scope of nbdkit.
742 ".get_size"
744 int64_t get_size (void *handle);
745 This is called during the option negotiation phase of the protocol to
747 get the size (in bytes) of the block device being exported.
748 The returned size must be ≥ 0. If there is an error, ".get_size"
750 should call "nbdkit_error" with an error message and return "-1".
751 ".export_description"
753 const char *export_description (void *handle);
754 This is called during the option negotiation phase only if the client
756 specifically requested an export description (see the
757 "NBD_INFO_DESCRIPTION" response to "NBD_OPT_GO"). Any description
758 provided must be human-readable UTF-8, no longer than 4096 bytes.
759 Ideally, this description should match any description set during
760 ".list_exports", but that is not enforced.
761 If the plugin returns "NULL" or an invalid string (such as longer than
763 4096 bytes), or if this callback is omitted, no description is offered
764 to the client. As this is not an error in the protocol, it is not
765 necessary to call "nbdkit_error". If the callback will not be
766 returning a compile-time constant string, you may find
767 "nbdkit_strdup_intern" helpful for returning a value that avoids a
768 memory leak.
769 ".can_write"
771 int can_write (void *handle);
772 This is called during the option negotiation phase to find out if the
774 handle supports writes.
775 If there is an error, ".can_write" should call "nbdkit_error" with an
777 error message and return "-1".
778 This callback is not required. If omitted, then we return true iff a
780 ".pwrite" callback has been defined.
781 ".can_flush"
783 int can_flush (void *handle);
784 This is called during the option negotiation phase to find out if the
786 handle supports the flush-to-disk operation.
787 If there is an error, ".can_flush" should call "nbdkit_error" with an
789 error message and return "-1".
790 This callback is not required. If omitted, then we return true iff a
792 ".flush" callback has been defined.
793 ".is_rotational"
795 int is_rotational (void *handle);
796 This is called during the option negotiation phase to find out if the
798 backing disk is a rotational medium (like a traditional hard disk) or
799 not (like an SSD). If true, this may cause the client to reorder
800 requests to make them more efficient for a slow rotating disk.
801 If there is an error, ".is_rotational" should call "nbdkit_error" with
803 an error message and return "-1".
804 This callback is not required. If omitted, then we return false.
806 ".can_trim"
808 int can_trim (void *handle);
809 This is called during the option negotiation phase to find out if the
811 plugin supports the trim/discard operation for punching holes in the
812 backing storage.
813 If there is an error, ".can_trim" should call "nbdkit_error" with an
815 error message and return "-1".
816 This callback is not required. If omitted, then we return true iff a
818 ".trim" callback has been defined.
819 ".can_zero"
821 int can_zero (void *handle);
822 This is called during the option negotiation phase to find out if the
824 plugin wants the ".zero" callback to be utilized. Support for writing
825 zeroes is still advertised to the client (unless the
826 nbdkit-nozero-filter(1) is also used), so returning false merely serves
827 as a way to avoid complicating the ".zero" callback to have to fail
828 with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
829 be more efficient than using ".pwrite" up front.
830 If there is an error, ".can_zero" should call "nbdkit_error" with an
832 error message and return "-1".
833 This callback is not required. If omitted, then for a normal zero
835 request, nbdkit always tries ".zero" first if it is present, and
836 gracefully falls back to ".pwrite" if ".zero" was absent or failed with
837 "ENOTSUP" or "EOPNOTSUPP".
838 ".can_fast_zero"
840 int can_fast_zero (void *handle);
841 This is called during the option negotiation phase to find out if the
843 plugin wants to advertise support for fast zero requests. If this
844 support is not advertised, a client cannot attempt fast zero requests,
845 and has no way to tell if writing zeroes offers any speedups compared
846 to using ".pwrite" (other than compressed network traffic). If support
847 is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when
848 the client has requested a fast zero, in which case the plugin must
849 fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
850 offer any benefits over ".pwrite". Advertising support for fast zero
851 requests does not require that writing zeroes be fast, only that the
852 result (whether success or failure) is fast, so this should be
853 advertised when feasible.
854 If there is an error, ".can_fast_zero" should call "nbdkit_error" with
856 an error message and return "-1".
857 This callback is not required. If omitted, then nbdkit returns true if
859 ".zero" is absent or ".can_zero" returns false (in those cases, nbdkit
860 fails all fast zero requests, as its fallback to ".pwrite" is not
861 inherently faster), otherwise false (since it cannot be determined in
862 advance if the plugin's ".zero" will properly honor the semantics of
863 "NBDKIT_FLAG_FAST_ZERO").
864 ".can_extents"
866 int can_extents (void *handle);
867 This is called during the option negotiation phase to find out if the
869 plugin supports detecting allocated (non-sparse) regions of the disk
870 with the ".extents" callback.
871 If there is an error, ".can_extents" should call "nbdkit_error" with an
873 error message and return "-1".
874 This callback is not required. If omitted, then we return true iff a
876 ".extents" callback has been defined.
877 ".can_fua"
879 int can_fua (void *handle);
880 This is called during the option negotiation phase to find out if the
882 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
883 trim requests. If this returns "NBDKIT_FUA_NONE", FUA support is not
884 advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
885 ".flush" callback must work (even if ".can_flush" returns false), and
886 FUA support is emulated by calling ".flush" after any write operation;
887 if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
888 ".trim" callbacks (if implemented) must handle the flag
889 "NBDKIT_FLAG_FUA", by not returning until that action has landed in
890 persistent storage.
891 If there is an error, ".can_fua" should call "nbdkit_error" with an
893 error message and return "-1".
894 This callback is not required unless a plugin wants to specifically
896 handle FUA requests. If omitted, nbdkit checks whether ".flush"
897 exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
898 "NBDKIT_FUA_EMULATE" as appropriate.
899 ".can_multi_conn"
901 int can_multi_conn (void *handle);
902 This is called during the option negotiation phase to find out if the
904 plugin is prepared to handle multiple connections from a single client.
905 If the plugin sets this to true then a client may try to open multiple
906 connections to the nbdkit server and spread requests across all
907 connections to maximize parallelism. If the plugin sets it to false
908 (which is the default) then well-behaved clients should only open a
909 single connection, although we cannot control what clients do in
910 practice.
911 Specifically it means that either the plugin does not cache requests at
913 all. Or if it does cache them then the effects of a ".flush" request
914 or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
915 connections to the plugin before the plugin replies to that request.
916 Properly working clients should send the same export name for each of
918 these connections.
919 If you use Linux nbd-client(8) option -C num with num > 1 then Linux
921 checks this flag and will refuse to connect if ".can_multi_conn" is
922 false.
923 If there is an error, ".can_multi_conn" should call "nbdkit_error" with
925 an error message and return "-1".
926 This callback is not required. If omitted, then we return false.
928 ".can_cache"
930 int can_cache (void *handle);
931 This is called during the option negotiation phase to find out if the
933 plugin supports a cache operation. The nature of the caching is
934 unspecified (including whether there are limits on how much can be
935 cached at once, and whether writes to a cached region have write-
936 through or write-back semantics), but the command exists to let clients
937 issue a hint to the server that they will be accessing that region of
938 the export.
939 If this returns "NBDKIT_CACHE_NONE", cache support is not advertised to
941 the client; if this returns "NBDKIT_CACHE_EMULATE", caching is emulated
942 by the server calling ".pread" and ignoring the results; if this
943 returns "NBDKIT_CACHE_NATIVE", then the ".cache" callback will be used.
944 If there is an error, ".can_cache" should call "nbdkit_error" with an
945 error message and return "-1".
946 This callback is not required. If omitted, then we return
948 "NBDKIT_CACHE_NONE" if the ".cache" callback is missing, or
949 "NBDKIT_CACHE_NATIVE" if it is defined.
950 ".pread"
952 int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
953 uint32_t flags);
954 During the data serving phase, nbdkit calls this callback to read data
956 from the backing store. "count" bytes starting at "offset" in the
957 backing store should be read and copied into "buf". nbdkit takes care
958 of all bounds- and sanity-checking, so the plugin does not need to
959 worry about that.
960 The parameter "flags" exists in case of future NBD protocol extensions;
962 at this time, it will be 0 on input.
963 The callback must read the whole "count" bytes if it can. The NBD
965 protocol doesn't allow partial reads (instead, these would be errors).
966 If the whole "count" bytes was read, the callback should return 0 to
967 indicate there was no error.
968 If there is an error (including a short read which couldn't be
970 recovered from), ".pread" should call "nbdkit_error" with an error
971 message, and "nbdkit_set_error" to record an appropriate error (unless
972 "errno" is sufficient), then return "-1".
973 ".pwrite"
975 int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
976 uint32_t flags);
977 During the data serving phase, nbdkit calls this callback to write data
979 to the backing store. "count" bytes starting at "offset" in the
980 backing store should be written using the data in "buf". nbdkit takes
981 care of all bounds- and sanity-checking, so the plugin does not need to
982 worry about that.
983 This function will not be called if ".can_write" returned false. The
985 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
986 result of ".can_fua".
987 The callback must write the whole "count" bytes if it can. The NBD
989 protocol doesn't allow partial writes (instead, these would be errors).
990 If the whole "count" bytes was written successfully, the callback
991 should return 0 to indicate there was no error.
992 If there is an error (including a short write which couldn't be
994 recovered from), ".pwrite" should call "nbdkit_error" with an error
995 message, and "nbdkit_set_error" to record an appropriate error (unless
996 "errno" is sufficient), then return "-1".
997 ".flush"
999 int flush (void *handle, uint32_t flags);
1000 During the data serving phase, this callback is used to fdatasync(2)
1002 the backing store, ie. to ensure it has been completely written to a
1003 permanent medium. If that is not possible then you can omit this
1004 callback.
1005 This function will not be called directly by the client if ".can_flush"
1007 returned false; however, it may still be called by nbdkit if ".can_fua"
1008 returned "NBDKIT_FUA_EMULATE". The parameter "flags" exists in case of
1009 future NBD protocol extensions; at this time, it will be 0 on input.
1010 If there is an error, ".flush" should call "nbdkit_error" with an error
1012 message, and "nbdkit_set_error" to record an appropriate error (unless
1013 "errno" is sufficient), then return "-1".
1014 ".trim"
1016 int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1017 During the data serving phase, this callback is used to "punch holes"
1019 in the backing store. If that is not possible then you can omit this
1020 callback.
1021 This function will not be called if ".can_trim" returned false. The
1023 parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1024 result of ".can_fua".
1025 If there is an error, ".trim" should call "nbdkit_error" with an error
1027 message, and "nbdkit_set_error" to record an appropriate error (unless
1028 "errno" is sufficient), then return "-1".
1029 ".zero"
1031 int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1032 During the data serving phase, this callback is used to write "count"
1034 bytes of zeroes at "offset" in the backing store.
1035 This function will not be called if ".can_zero" returned false. On
1037 input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
1038 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
1039 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
1040 If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
1042 instead of writing actual zero bytes, but only if subsequent reads from
1043 the hole read as zeroes.
1044 If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up
1046 front if the implementation is likely to be faster than a corresponding
1047 ".pwrite"; if not, then it must immediately fail with "ENOTSUP" or
1048 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno") and preferably
1049 without modifying the exported image. It is acceptable to always fail
1050 a fast zero request (as a fast failure is better than attempting the
1051 write only to find out after the fact that it was not fast after all).
1052 Note that on Linux, support for "ioctl(BLKZEROOUT)" is insufficient for
1053 determining whether a zero request to a block device will be fast
1054 (because the kernel will perform a slow fallback when needed).
1055 The callback must write the whole "count" bytes if it can. The NBD
1057 protocol doesn't allow partial writes (instead, these would be errors).
1058 If the whole "count" bytes was written successfully, the callback
1059 should return 0 to indicate there was no error.
1060 If there is an error, ".zero" should call "nbdkit_error" with an error
1062 message, and "nbdkit_set_error" to record an appropriate error (unless
1063 "errno" is sufficient), then return "-1".
1064 If this callback is omitted, or if it fails with "ENOTSUP" or
1066 "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then ".pwrite"
1067 will be used as an automatic fallback except when the client requested
1068 a fast zero.
1069 ".extents"
1071 int extents (void *handle, uint32_t count, uint64_t offset,
1072 uint32_t flags, struct nbdkit_extents *extents);
1073 During the data serving phase, this callback is used to detect
1075 allocated, sparse and zeroed regions of the disk.
1076 This function will not be called if ".can_extents" returned false.
1078 nbdkit's default behaviour in this case is to treat the whole virtual
1079 disk as if it was allocated. Also, this function will not be called by
1080 a client that does not request structured replies (the --no-sr option
1081 of nbdkit can be used to test behavior when ".extents" is unavailable
1082 to the client).
1083 The callback should detect and return the list of extents overlapping
1085 the range "[offset...offset+count-1]". The "extents" parameter points
1086 to an opaque object which the callback should fill in by calling
1087 "nbdkit_add_extent". See "Extents list" below.
1088 If there is an error, ".extents" should call "nbdkit_error" with an
1090 error message, and "nbdkit_set_error" to record an appropriate error
1091 (unless "errno" is sufficient), then return "-1".
1092 Extents list
1094 The plugin "extents" callback is passed an opaque pointer "struct
1096 nbdkit_extents *extents". This structure represents a list of
1097 filesystem extents describing which areas of the disk are allocated,
1098 which are sparse (“holes”), and, if supported, which are zeroes.
1099 The "extents" callback should scan the disk starting at "offset" and
1101 call "nbdkit_add_extent" for each extent found.
1102 Extents overlapping the range "[offset...offset+count-1]" should be
1104 returned if possible. However nbdkit ignores extents < offset so the
1105 plugin may, if it is easier to implement, return all extent information
1106 for the whole disk. The plugin may return extents beyond the end of
1107 the range. It may also return extent information for less than the
1108 whole range, but it must return at least one extent overlapping
1109 "offset".
1110 The extents must be added in ascending order, and must be contiguous.
1112 The "flags" parameter of the ".extents" callback may contain the flag
1114 "NBDKIT_FLAG_REQ_ONE". This means that the client is only requesting
1115 information about the extent overlapping "offset". The plugin may
1116 ignore this flag, or as an optimization it may return just a single
1117 extent for "offset".
1118 int nbdkit_add_extent (struct nbdkit_extents *extents,
1120 uint64_t offset, uint64_t length, uint32_t type);
1121 Add an extent covering "[offset...offset+length-1]" of one of the
1123 following four types:
1124 "type = 0"
1126 A normal, allocated data extent.
1127 "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
1129 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
1130 This is the normal type of hole applicable to most disks.
1131 "type = NBDKIT_EXTENT_ZERO"
1133 An allocated extent which is known to contain only zeroes.
1134 "type = NBDKIT_EXTENT_HOLE"
1136 An unallocated extent (hole) which does not read back as zeroes.
1137 Note this should only be used in specialized circumstances such as
1138 when writing a plugin for (or to emulate) certain SCSI drives which
1139 do not guarantee that trimmed blocks read back as zeroes.
1140 "nbdkit_add_extent" returns 0 on success or "-1" on failure. On
1142 failure "nbdkit_error" and/or "nbdkit_set_error" has already been
1143 called. "errno" will be set to a suitable value.
1144 ".cache"
1146 int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1147 During the data serving phase, this callback is used to give the plugin
1149 a hint that the client intends to make further accesses to the given
1150 region of the export. The nature of caching is not specified further
1151 by the NBD specification (for example, a server may place limits on how
1152 much may be cached at once, and there is no way to control if writes to
1153 a cached area have write-through or write-back semantics). In fact,
1154 the cache command can always fail and still be compliant, and success
1155 might not guarantee a performance gain. If this callback is omitted,
1156 then the results of ".can_cache" determine whether nbdkit will reject
1157 cache requests, treat them as instant success, or emulate caching by
1158 calling ".pread" over the same region and ignoring the results.
1159 This function will not be called if ".can_cache" did not return
1161 "NBDKIT_CACHE_NATIVE". The parameter "flags" exists in case of future
1162 NBD protocol extensions; at this time, it will be 0 on input. A plugin
1163 must fail this function if "flags" includes an unrecognized flag, as
1164 that may indicate a requirement that the plugin comply must with a
1165 specific caching semantic.
1166 If there is an error, ".cache" should call "nbdkit_error" with an error
1168 message, and "nbdkit_set_error" to record an appropriate error (unless
1169 "errno" is sufficient), then return "-1".
1170 ".errno_is_preserved"
1172 This field defaults to 0; if non-zero, nbdkit can reliably use the
1173 value of "errno" when a callback reports failure, rather than the
1174 plugin having to call "nbdkit_set_error".
1175
1177 When nbdkit receives certain signals it will shut down (see "SIGNALS"
1178 in nbdkit(1)). The server will wait for any currently running plugin
1179 callbacks to finish and also call the ".unload" callback before
1180 unloading the plugin.
1181 Note that it's not guaranteed this can always happen (eg. the server
1183 might be killed by "SIGKILL" or segfault).
1184 Requesting asynchronous shutdown
1186 Plugins and filters can call exit(3) in the configuration phase (before
1187 and including ".get_ready", but not in connected callbacks).
1188 Once nbdkit has started serving connections, plugins and filters should
1190 not call exit(3). However they may instruct nbdkit to shut down by
1191 calling "nbdkit_shutdown":
1192 void nbdkit_shutdown (void);
1194 This function requests an asynchronous shutdown and returns (note that
1196 it does not exit the process immediately). It ensures that the plugin
1197 and all filters are unloaded cleanly which may take some time. Further
1198 callbacks from nbdkit into the plugin or filter may occur after you
1199 have called this.
1200
1202 Parsing numbers
1203 There are several functions for parsing numbers. These all deal
1204 correctly with overflow, out of range and parse errors, and you should
1205 use them instead of unsafe functions like sscanf(3), atoi(3) and
1206 similar.
1207 int nbdkit_parse_int (const char *what, const char *str, int *r);
1209 int nbdkit_parse_unsigned (const char *what,
1210 const char *str, unsigned *r);
1211 int nbdkit_parse_int8_t (const char *what,
1212 const char *str, int8_t *r);
1213 int nbdkit_parse_uint8_t (const char *what,
1214 const char *str, uint8_t *r);
1215 int nbdkit_parse_int16_t (const char *what,
1216 const char *str, int16_t *r);
1217 int nbdkit_parse_uint16_t (const char *what,
1218 const char *str, uint16_t *r);
1219 int nbdkit_parse_int32_t (const char *what,
1220 const char *str, int32_t *r);
1221 int nbdkit_parse_uint32_t (const char *what,
1222 const char *str, uint32_t *r);
1223 int nbdkit_parse_int64_t (const char *what,
1224 const char *str, int64_t *r);
1225 int nbdkit_parse_uint64_t (const char *what,
1226 const char *str, uint64_t *r);
1227 Parse string "str" into an integer of various types. These functions
1229 parse a decimal, hexadecimal ("0x...") or octal ("0...") number.
1230 On success the functions return 0 and set *r to the parsed value
1232 (unless "*r == NULL" in which case the result is discarded). On error,
1233 "nbdkit_error" is called and the functions return "-1". On error *r is
1234 always unchanged.
1235 The "what" parameter is printed in error messages to provide context.
1237 It should usually be a short descriptive string of what you are trying
1238 to parse, eg:
1239 if (nbdkit_parse_int ("random seed", argv[1], &seed) == -1)
1241 return -1;
1242 might print an error:
1244 random seed: could not parse number: "lalala"
1246 Parsing sizes
1248 Use the "nbdkit_parse_size" utility function to parse human-readable
1249 size strings such as "100M" into the size in bytes.
1250 int64_t nbdkit_parse_size (const char *str);
1252 "str" can be a string in a number of common formats. The function
1254 returns the size in bytes. If there was an error, it returns "-1".
1255 Parsing booleans
1257 Use the "nbdkit_parse_bool" utility function to parse human-readable
1258 strings such as "on" into a boolean value.
1259 int nbdkit_parse_bool (const char *str);
1261 "str" can be a string containing a case-insensitive form of various
1263 common toggle values. The function returns 0 or 1 if the parse was
1264 successful. If there was an error, it returns "-1".
1265 Reading passwords
1267 The "nbdkit_read_password" utility function can be used to read
1268 passwords from config parameters:
1269 int nbdkit_read_password (const char *value, char **password);
1271 For example:
1273 char *password = NULL;
1275 static int
1277 myplugin_config (const char *key, const char *value)
1278 {
1279 ..
1280 if (strcmp (key, "password") == 0) {
1281 free (password);
1282 if (nbdkit_read_password (value, &password) == -1)
1283 return -1;
1284 }
1285 ..
1286 }
1287 The "password" result string is allocated by malloc, and so you may
1289 need to free it.
1290 This function recognizes several password formats. A password may be
1292 used directly on the command line, eg:
1293 nbdkit myplugin password=mostsecret
1295 But more securely this function can also read a password interactively:
1297 nbdkit myplugin password=-
1299 or from a file:
1301 nbdkit myplugin password=+/tmp/secret
1303 or from a file descriptor inherited by nbdkit:
1305 nbdkit myplugin password=-99
1307 Notes on reading passwords
1309 If the password begins with a "-" or "+" character then it must be
1311 passed in a file.
1312 "password=-" can only be used when stdin is a terminal.
1314 "password=-FD" cannot be used with stdin, stdout or stderr (ie. "-0",
1316 "-1" or "-2"). The reason is that after reading the password the file
1317 descriptor is closed, which causes bad stuff to happen.
1318 Safely interacting with stdin and stdout
1320 int nbdkit_stdio_safe (void);
1321 The "nbdkit_stdio_safe" utility function returns 1 if it is safe to
1323 interact with stdin and stdout during the configuration phase, and 0
1324 otherwise. This is because when the nbdkit -s option is used the
1325 plugin must not directly interact with stdin, because that would
1326 interfere with the client.
1327 The result of this function only matters in callbacks up to
1329 ".config_complete". Once nbdkit reaches ".get_ready", the plugin
1330 should assume that nbdkit may have closed the original stdin and stdout
1331 in order to become a daemon.
1332 nbdkit-sh-plugin(3) uses this function to determine whether it is safe
1334 to support "script=-" to read a script from stdin. Also constructs
1335 like "password=-" (see "Reading passwords" above) are disabled when
1336 reading from stdio is not safe.
1337
1339 The server usually (not always) changes directory to "/" before it
1340 starts serving connections. This means that any relative paths passed
1341 during configuration will not work when the server is running (example:
1342 "nbdkit plugin.so disk.img").
1343 To avoid problems, prepend relative paths with the current directory
1345 before storing them in the handle. Or open files and store the file
1346 descriptor.
1347 "nbdkit_absolute_path"
1349 char *nbdkit_absolute_path (const char *filename);
1350 The utility function "nbdkit_absolute_path" converts any path to an
1352 absolute path: if it is relative, then all this function does is
1353 prepend the current working directory to the path, with no extra
1354 checks.
1355 Note that this function works only when used in the ".config",
1357 ".config_complete" and ".get_ready" callbacks.
1358 If conversion was not possible, this calls "nbdkit_error" and returns
1360 "NULL". Note that this function does not check that the file exists.
1361 The returned string must be freed by the caller.
1363 "nbdkit_realpath"
1365 char *nbdkit_realpath (const char *filename);
1366 The utility function "nbdkit_realpath" converts any path to an absolute
1368 path, resolving symlinks. Under the hood it uses the "realpath"
1369 function, and thus it fails if the path does not exist, or it is not
1370 possible to access to any of the components of the path.
1371 Note that this function works only when used in the ".config",
1373 ".config_complete" and ".get_ready" callbacks.
1374 If the path resolution was not possible, this calls "nbdkit_error" and
1376 returns "NULL".
1377 The returned string must be freed by the caller.
1379 umask
1381 All plugins will see a umask(2) of 0022.
1382
1384 A plugin that needs to sleep may call sleep(2), nanosleep(2) and
1385 similar. However that can cause nbdkit to delay excessively when
1386 shutting down (since it must wait for any plugin or filter which is
1387 sleeping). To avoid this there is a special wrapper around nanosleep
1388 which plugins and filters should use instead.
1389 "nbdkit_nanosleep"
1391 int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1392 The utility function "nbdkit_nanosleep" suspends the current thread,
1394 and returns 0 if it slept at least as many seconds and nanoseconds as
1395 requested, or -1 after calling "nbdkit_error" if there is no point in
1396 continuing the current command. Attempts to sleep more than "INT_MAX"
1397 seconds are treated as an error.
1398
1400 If the client negotiated an NBD export name with nbdkit then plugins
1401 may read this from any connected callbacks. Nbdkit's normal behaviour
1402 is to accept any export name passed by the client, log it in debug
1403 output, but otherwise ignore it. By using "nbdkit_export_name" plugins
1404 may choose to filter by export name or serve different content.
1405 "nbdkit_export_name"
1407 const char *nbdkit_export_name (void);
1408 Return the optional NBD export name if one was negotiated with the
1410 current client (this uses thread-local magic so no parameter is
1411 required). The returned string is valid at least through the ".close"
1412 of the current connection, but if you need to store it in the plugin
1413 for use by more than one client you must copy it.
1414 The export name is a free-form text string, it is not necessarily a
1416 path or filename and it does not need to begin with a '/' character.
1417 The NBD protocol describes the empty string ("") as a representing a
1418 "default export" or to be used in cases where the export name does not
1419 make sense. The export name is untrusted client data, be cautious when
1420 parsing it.
1421 On error, "nbdkit_error" is called and the call returns "NULL".
1423
1425 Some callbacks are specified to return "const char *", even when a
1426 plugin may not have a suitable compile-time constant to return.
1427 Returning dynamically-allocated memory for such a callback would induce
1428 a memory leak or otherwise complicate the plugin to perform additional
1429 bookkeeping. For these cases, nbdkit provides several convenience
1430 functions for creating a copy of a string for better lifetime
1431 management.
1432 "nbdkit_strdup_intern"
1434 "nbdkit_strndup_intern"
1435 const char *nbdkit_strdup_intern (const char *str);
1436 const char *nbdkit_strndup_intern (const char *str, size_t n);
1437 Returns a copy of "str", possibly limited to a maximum of "n" bytes, so
1439 that the caller may reclaim str and use the copy in its place. If the
1440 copy is created outside the scope of a connection (such as during
1441 ".load" or ".config"), the lifetime of the copy will last at least
1442 through ".unload". If the copy is created after a client has triggered
1443 a connection (such as during ".preconnect" or ".open"), the lifetime
1444 will last at least through ".close", but the copy is not safe to share
1445 with other connections.
1446 On error, "nbdkit_error" is called and the call returns "NULL".
1448 "nbdkit_printf_intern"
1450 "nbdkit_vprintf_intern"
1451 const char *nbdkit_printf_intern (const char *fmt, ...);
1452 const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);
1453 Return a string created from a format template, with a lifetime longer
1455 than the current connection. Shorthand for passing "fmt" to
1456 asprintf(3) on a temporary string, then passing that result to
1457 "nbdkit_strdup_intern".
1458 On error, "nbdkit_error" is called and the call returns "NULL".
1460
1462 A server may use "nbdkit_is_tls" to limit which export names work until
1463 after a client has completed TLS authentication. See nbdkit-tls(1).
1464 It is also possible to use nbdkit-tls-fallback-filter(1) to
1465 automatically ensure that the plugin is only used with authentication.
1466 "nbdkit_is_tls"
1468 int nbdkit_is_tls (void);
1469 Return true if the client has completed TLS authentication, or false if
1471 the connection is still plaintext.
1472 On error (such as calling this function outside of the context of
1474 ".open"), "nbdkit_error" is called and the call returns "-1".
1475
1477 It is possible to get the source address of the client when you are
1478 running in any connected callback.
1479 "nbdkit_peer_name"
1481 int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1482 Return the peer (client) address, if available. The "addr" and
1484 "addrlen" parameters behave like getpeername(2). In particular you
1485 must initialize "addrlen" with the size of the buffer pointed to by
1486 "addr", and if "addr" is not large enough then the address will be
1487 truncated.
1488 In some cases this is not available or the address returned will be
1490 meaningless (eg. if there is a proxy between the client and nbdkit).
1491 This call uses thread-local magic so no parameter is required to
1492 specify the current connection.
1493 On success this returns 0. On error, "nbdkit_error" is called and this
1495 call returns "-1".
1496 "nbdkit_peer_pid"
1498 (nbdkit ≥ 1.24, Linux only)
1499 int64_t nbdkit_peer_pid (void);
1501 Return the peer process ID. This is only available when the client
1503 connected over a Unix domain socket.
1504 On success this returns the peer process ID. On error, "nbdkit_error"
1506 is called and this call returns "-1".
1507 "nbdkit_peer_uid"
1509 (nbdkit ≥ 1.24)
1510 int64_t nbdkit_peer_uid (void);
1512 Return the peer user ID. This is only available when the client
1514 connected over a Unix domain socket.
1515 On success this returns the user ID. On error, "nbdkit_error" is
1517 called and this call returns "-1".
1518 "nbdkit_peer_gid"
1520 (nbdkit ≥ 1.24)
1521 int64_t nbdkit_peer_gid (void);
1523 Return the peer group ID. This is only available when the client
1525 connected over a Unix domain socket.
1526 On success this returns the user ID. On error, "nbdkit_error" is
1528 called and this call returns "-1".
1529
1531 Run the server with -f and -v options so it doesn't fork and you can
1532 see debugging information:
1533 nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1535 To print debugging information from within the plugin, call
1537 "nbdkit_debug", which has the following prototype and works like
1538 printf(3):
1539 void nbdkit_debug (const char *fs, ...);
1541 void nbdkit_vdebug (const char *fs, va_list args);
1542 For convenience, "nbdkit_debug" preserves the value of "errno", and
1544 also supports the glibc extension of a single %m in a format string
1545 expanding to "strerror(errno)", even on platforms that don't support
1546 that natively. Note that "nbdkit_debug" only prints things when the
1547 server is in verbose mode (-v option).
1548 Debug Flags
1550 The -v option switches general debugging on or off, and this debugging
1551 should be used for messages which are useful for all users of your
1552 plugin.
1553 In cases where you want to enable specific extra debugging to track
1555 down bugs in plugins or filters — mainly for use by the plugin/filter
1556 developers themselves — you can define Debug Flags. These are global
1557 ints called "myplugin_debug_*":
1558 int myplugin_debug_foo;
1560 int myplugin_debug_bar;
1561 ...
1562 if (myplugin_debug_foo) {
1563 nbdkit_debug ("lots of extra debugging about foo: ...");
1564 }
1565 Debug Flags can be controlled on the command line using the -D (or
1567 --debug) option:
1568 nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1570 Note "myplugin" is the name passed to ".name" in the "struct
1572 nbdkit_plugin".
1573 You should only use this feature for debug settings. For general
1575 settings use ordinary plugin parameters. Debug Flags can only be C
1576 ints. They are not supported by non-C language plugins.
1577 For convenience '.' characters are replaced with '_' characters in the
1579 variable name, so both of these parameters:
1580 -D myplugin.foo_bar=1
1582 -D myplugin.foo.bar=1
1583 correspond to the plugin variable "myplugin_debug_foo_bar".
1585
1587 Plugins should be compiled as shared libraries. There are various ways
1588 to achieve this, but most Linux compilers support a -shared option to
1589 create the shared library directly, for example:
1590 gcc -fPIC -shared myplugin.c -o myplugin.so
1592 Note that the shared library will have undefined symbols for functions
1594 that you call like "nbdkit_parse_int" or "nbdkit_error". These will be
1595 resolved by the server binary when nbdkit dlopens the plugin.
1596 PKG-CONFIG/PKGCONF
1598 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
1599 should be installed on the correct path when the nbdkit plugin
1600 development environment is installed. You can use this in autoconf
1601 configure.ac scripts to test for the development environment:
1602 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1604 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
1606 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
1607 for compiling plugins.
1608 You can also run pkg-config/pkgconf directly, for example:
1610 if ! pkg-config nbdkit --exists; then
1612 echo "you must install the nbdkit plugin development environment"
1613 exit 1
1614 fi
1615 You can also substitute the plugindir variable by doing:
1617 PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1619 which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
1621 If nbdkit development headers are installed in a non-standard location
1623 then you may need to compile plugins using:
1624 gcc -fPIC -shared myplugin.c -o myplugin.so \
1626 `pkg-config nbdkit --cflags --libs`
1627
1629 The plugin is a "*.so" file and possibly a manual page. You can of
1630 course install the plugin "*.so" file wherever you want, and users will
1631 be able to use it by running:
1632 nbdkit /path/to/plugin.so [args]
1634 However if the shared library has a name of the form
1636 "nbdkit-name-plugin.so" and if the library is installed in the
1637 $plugindir directory, then users can be run it by only typing:
1638 nbdkit name [args]
1640 The location of the $plugindir directory is set when nbdkit is compiled
1642 and can be found by doing:
1643 nbdkit --dump-config
1645 If using the pkg-config/pkgconf system then you can also find the
1647 plugin directory at compile time by doing:
1648 pkg-config nbdkit --variable=plugindir
1650
1652 You can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python,
1653 Ruby, Rust, shell script or Tcl. Other programming languages may be
1654 offered in future.
1655 For more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
1657 nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
1658 nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
1659 nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1660 Plugins written in scripting languages may also be installed in
1662 $plugindir. These must be called "nbdkit-name-plugin" without any
1663 extension. They must be executable, and they must use the shebang
1664 header (see "Shebang scripts" in nbdkit(1)). For example a plugin
1665 written in Perl called "foo.pl" might be installed like this:
1666 $ head -1 foo.pl
1668 #!/usr/sbin/nbdkit perl
1669 $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1671 and then users will be able to run it like this:
1673 $ nbdkit foo [args ...]
1675
1677 nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1),
1678 nbdkit-filter(3).
1679 Standard plugins provided by nbdkit:
1681 nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1), nbdkit-data-plugin(1),
1683 nbdkit-eval-plugin(1), nbdkit-example1-plugin(1),
1684 nbdkit-example2-plugin(1), nbdkit-example3-plugin(1),
1685 nbdkit-example4-plugin(1), nbdkit-file-plugin(1),
1686 nbdkit-floppy-plugin(1), nbdkit-full-plugin(1),
1687 nbdkit-guestfs-plugin(1), nbdkit-gzip-plugin(1), nbdkit-info-plugin(1),
1688 nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
1689 nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
1690 nbdkit-nbd-plugin(1), nbdkit-null-plugin(1), nbdkit-ondemand-plugin(1),
1691 nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
1692 nbdkit-random-plugin(1), nbdkit-S3-plugin(1),
1693 nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1),
1694 nbdkit-ssh-plugin(1), nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
1695 nbdkit-tmpdisk-plugin(1), nbdkit-torrent-plugin(1),
1696 nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-cc-plugin(3),
1697 nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
1698 nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
1699 nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1700
1702 Eric Blake
1703 Richard W.M. Jones
1705 Pino Toscano
1707
1709 Copyright (C) 2013-2020 Red Hat Inc.
1710
1712 Redistribution and use in source and binary forms, with or without
1713 modification, are permitted provided that the following conditions are
1714 met:
1715 · Redistributions of source code must retain the above copyright
1717 notice, this list of conditions and the following disclaimer.
1718 · Redistributions in binary form must reproduce the above copyright
1720 notice, this list of conditions and the following disclaimer in the
1721 documentation and/or other materials provided with the
1722 distribution.
1723 · Neither the name of Red Hat nor the names of its contributors may
1725 be used to endorse or promote products derived from this software
1726 without specific prior written permission.
1727 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1729 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1730 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1731 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1732 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1733 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1734 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1735 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1736 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1737 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1738 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1739nbdkit-1.24.2 2021-03-02 nbdkit-plugin(3)