nbdkit-plugin(3)

📦
version 1.48.1 · 14 versions
, in fedora 44

🎀 nbdkit-plugin(3) 🎀

bestie, this is the nbdkit-plugin(3) manual page, and it's literally the blueprint for writing your own nbdkit plugin. we're doing it in C. it's giving main character energy, no cap.

✨ NAME ✨

nbdkit-plugin — how to write nbdkit plugins

💅 SYNOPSIS 💅

okay so first you gotta include the header and define your API version, like so:

#define NBDKIT_API_VERSION 2
#include <nbdkit-plugin.h>

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

static void *
myplugin_open (void)
{
  /* create a handle ... */
  return handle;
}

static struct nbdkit_plugin plugin = {
  .name              = "myplugin",
  .open              = myplugin_open,
  .get_size          = myplugin_get_size,
  .pread             = myplugin_pread,
  .pwrite            = myplugin_pwrite,
  /* etc */
};
NBDKIT_REGISTER_PLUGIN(plugin)

then compile that plugin as a shared library:

gcc -fPIC -shared myplugin.c -o myplugin.so

and load it into nbdkit:

nbdkit [--args ...] ./myplugin.so [key=value ...]

when you're debugging, use the -fv options:

nbdkit -fv ./myplugin.so [key=value ...]

💖 DESCRIPTION 💖

an nbdkit plugin is a new source device which can be served using the Network Block Device (NBD) protocol. this manual page describes how to create an nbdkit plugin in C. periodt.

to see example plugins: https://gitlab.com/nbdkit/nbdkit/tree/master/plugins

to write plugins in other languages, see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

🌈 API and ABI guarantee for C plugins 🌈

plugins written in C have an ABI guarantee: a plugin compiled against an older version of nbdkit will still work correctly when loaded with a newer nbdkit. we also try (but cannot guarantee) to support plugins compiled against a newer version of nbdkit when loaded with an older nbdkit, although the plugin may have reduced functionality if it depends on features only provided by newer nbdkit. iykyk.

for plugins written in C, we also provide an API guarantee: a plugin written against an older header will still compile unmodified with a newer nbdkit.

the API guarantee does not always apply to plugins written in other (non-C) languages which may have to adapt to changes when recompiled against a newer nbdkit. so like, be aware bestie.

👑 WRITING AN NBDKIT PLUGIN 👑

🌟 #define NBDKIT_API_VERSION 2 🌟

plugins must choose which API version they want to use, by defining NBDKIT_API_VERSION before including <nbdkit-plugin.h> (or any other nbdkit header).

if omitted, the default version is 1 for backwards-compatibility with nbdkit v1.1.26 and earlier; however, it is recommended that new plugins be written to the maximum version (currently 2) as it enables more features and better interaction with nbdkit filters.

the rest of this document only covers the version 2 interface. a newer nbdkit will always support plugins written in C which use any prior API version. slay.

🌸 #include <nbdkit-plugin.h> 🌸

all plugins should start by including this header file (after optionally choosing an API version).

🦋 #define THREAD_MODEL ... 🦋

all plugins must define a thread model. see "Threads" below for details. it is generally safe to use:

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

💜 struct nbdkit_plugin 💜

all plugins must define and register one struct nbdkit_plugin, which contains the name of the plugin and pointers to callback functions, and use the NBDKIT_REGISTER_PLUGIN(plugin) macro:

static struct nbdkit_plugin plugin = {
  .name              = "myplugin",
  .longname          = "My Plugin",
  .description       = "This is my great plugin for nbdkit",
  .open              = myplugin_open,
  .get_size          = myplugin_get_size,
  .pread             = myplugin_pread,
  .pwrite            = myplugin_pwrite,
  /* etc */
};
NBDKIT_REGISTER_PLUGIN(plugin)

the .name field is the name of the plugin.

the callbacks are described below (see "CALLBACKS"). only .name, .open, .get_size and .pread are required. all other callbacks can be omitted, although typical plugins need to use more. no pressure tho.

🦄 Callback lifecycle 🦄

callbacks are called in the following order over the lifecycle of the plugin:

                ┌──────────────────┐
                │ load             │
                └─────────┬────────┘
                          │           configuration phase starts     ─┐
                ┌─────────┴────────┐                                  ┆
                │ config           │  config is called once per       ┆
                └─────────┬────────┘↺ key=value on the command line   ┆
                ┌─────────┴────────┐                                  ┆
                │ config_complete  │                                  ┆
                └─────────┬────────┘                                  ┆
                ┌─────────┴────────┐                                  ┆
                │ thread_model     │                                  ┆
                └─────────┬────────┘  configuration phase ends       ─┘
                ┌─────────┴────────┐
                │ get_ready        │
                └─────────┬────────┘
                          │           nbdkit forks into the background
                ┌─────────┴────────┐
                │ after_fork       │
                └─────────┬────────┘
                          │           nbdkit starts serving clients
                          │
               ┌──────────┴─────────────┬─ ─ ─ ─ ─ ─ ─ ─ ─
        ┌──────┴─────┐ client #1        │
        │ preconnect │                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐                  │
        │list_exports│                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐                  │
        │ open       │                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐  NBD option      │
        │ can_write  │  negotiation     │
        └──────┬─────┘                  │
        ┌──────┴─────┐           ┌──────┴─────┐ client #2
        │ get_size   │           │ preconnect │
        └──────┬─────┘           └──────┬─────┘
        ┌──────┴─────┐ data
        │ pread      │ serving
        └──────┬─────┘↺                ...
        ┌──────┴─────┐
        │ pwrite     │
        └──────┬─────┘↺          ┌──────┴─────┐
        ┌──────┴─────┐           │ close      │
        │ close      │           └────────────┘
        └────────────┘

                          │           before nbdkit exits
                          │
                ┌─────────┴────────┐
                │ cleanup          │
                └─────────┬────────┘
                ┌─────────┴────────┐
                │ unload           │
                └──────────────────┘

📝 Notes 📝

  • nbdkit --dump-plugin — the order of calls when the user queries the plugin is slightly different: .config is called once for each parameter. .config_complete is not called. .thread_model is called after .config.
  • .get_ready — this is the last chance to do any global preparation that is needed to serve connections. in particular, error messages here will be visible to the user, but they might not be in .after_fork (see below).

plugins should not create background threads here. use .after_fork instead. bestie, i'm serious.

  • .after_fork — .after_fork is called after the server has forked into the background and changed UID and directory. if a plugin needs to create background threads (or uses an external library that creates threads) it should do so here, because background threads are invalidated by fork.

because the server may have forked into the background, error messages and failures from .after_fork cannot be seen by the user unless they look through syslog. an error in .after_fork can appear to the user as if nbdkit “just died”. so in almost all cases it is better to use .get_ready instead of this callback, or to do as much preparation work as possible in .get_ready and only start background threads here. 😭

the server doesn't always fork (eg. if the -f flag is used), but even so this callback will be called. if you want to find out if the server forked between .get_ready and .after_fork use getpid(2).

  • .preconnect and .open — .preconnect is called when a TCP connection has been made to the server. this happens early, before NBD or TLS negotiation.

.open is called when a new client has connected and finished the NBD handshake. TLS negotiation (if used) has been completed successfully.

  • .can_write, .get_size and other option negotiation callbacks — these are called during option negotiation with the client, but before any data is served. these callbacks may return different values across different .open calls, but within a single connection, they are called at most once and cached by nbdkit for that connection.
  • .pread, .pwrite and other data serving callbacks — after option negotiation has finished, these may be called to serve data. depending on the thread model chosen, they might be called in parallel from multiple threads. the data serving callbacks include a flags argument; the results of the negotiation callbacks influence whether particular flags will ever be passed to a data callback.
  • .cleanup and .unload — the difference between these two methods is that .cleanup is called before any filter has been removed from memory with dlclose(3). when .unload is called, nbdkit is in the middle of calling dlclose(3). most plugins do not need to worry about this difference.

🌈 Flags 🌈

okay so nbdkit itself defines these lil flags, and they show up in various data-serving callbacks like little vibe-checks from the server. Here's the whole roster, no gatekeeping:

NBDKIT_FLAG_MAY_TRIM

This one is used by the .zero callback 💅 and bestie, there is no way to disable it. But it's chill — if your plugin doesn't support trims as a way to write zeroes, you can just ignore the flag and you're not breaking any expected semantics. Iconic behaviour honestly.

NBDKIT_FLAG_FUA

FUA stands for Forced Unit Access and it's giving "no really, make sure it's actually on disk". It's used by the .pwrite, .zero, and .trim callbacks to say the plugin must not return a result until the action has landed in persistent storage. Huge deal, don't fumble it.

Heads up bestie: this flag will not be sent to your plugin unless .can_fua is provided and it returns NBDKIT_FUA_NATIVE. No .can_fua, no FUA flag. Periodt.

Now these next defines are the valid successful return values for .can_fua:

NBDKIT_FUA_NONE

Forced Unit Access is just not supported, sorry babe. The client has to manually request a flush after its writes complete. The NBDKIT_FLAG_FUA flag will not be passed to the plugin's write callbacks.

NBDKIT_FUA_EMULATE

The client may request Forced Unit Access, but it's implemented by emulation — nbdkit calls .flush after a write operation. It's semantically correct ✨ but it can hurt performance, because it tends to flush more data than just what the client actually asked for. It's giving "close enough, but extra". The NBDKIT_FLAG_FUA flag will not be passed to the plugin's write callbacks.

NBDKIT_FUA_NATIVE

The client may request Forced Unit Access, and this results in the NBDKIT_FLAG_FUA flag actually being passed to the plugin's write callbacks (.pwrite, .trim, and .zero). When that flag is set, these callbacks must not return success until the client's request has landed in persistent storage. The real deal, no shortcuts. 🔥

And these defines are the valid successful return values for .can_cache:

NBDKIT_CACHE_NONE

The server does not advertise caching support at all, and rejects any client-requested caching. Any .cache callback is just ignored 🫶.

NBDKIT_CACHE_EMULATE

The nbdkit server advertises cache support to the client, and the client may request that the server cache a region of the export to potentially speed up future read and/or write operations on that region. The nbdkit server implements the caching by calling .pread and ignoring the results (lmao, fake it till you make it). This option exists to ease the implementation of a common form of caching; any .cache callback is ignored.

NBDKIT_CACHE_NATIVE

The nbdkit server advertises cache support to the client, and the client may request that the server cache a region of the export to potentially speed up future read and/or write operations on that region. The nbdkit server calls the .cache callback to do the actual caching; if that callback is missing, the client's cache request succeeds without doing anything. Slay, it just vibes through. 💜

🧵 Threads 🧵

Every nbdkit plugin has to declare its maximum thread safety model by defining the THREAD_MODEL macro. (This macro is used by NBDKIT_REGISTER_PLUGIN, fyi.) On top of that, a plugin may implement the .thread_model callback — it gets called right after .config_complete so you can make a runtime decision about which thread model to use. The nbdkit server then chooses the most restrictive model out of all of these:

  • the plugin's THREAD_MODEL,
  • the .thread_model if present,
  • any restrictions requested by filters,
  • and any limitations imposed by the operating system.

In nbdkit --dump-plugin PLUGIN output, the max_thread_model line matches the THREAD_MODEL macro, and the thread_model line matches what the system finally settled on after applying all the restrictions. Two lines, two truths. 👑

The possible settings for THREAD_MODEL are defined below.

Serialize connections

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS

Only a single handle can be open at any time, and all requests happen from one thread.

Note this means only one client can connect to the server at any time. If a second client tries to connect it will block, waiting for the first client to close the connection. Not a queue, just a line. 😭

Serialize all requests

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

This is a safe default for most plugins. 🎀

Multiple handles can be open at the same time, but requests are serialized so that for the plugin as a whole only one open/read/write/close (etc) request will be in progress at any time.

This is a useful setting if the library you are using is not thread-safe. However, performance may not be good. You win some, you lose some.

Serialize requests

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS

Multiple handles can be open and multiple data requests can happen in parallel. However, only one request will happen per handle at a time (but requests on different handles might happen concurrently). It's giving "everyone gets their own lane". 🦋

Parallel

#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL

Multiple handles can be open and multiple data requests can happen in parallel — even on the same handle. The server may reorder replies, answering a later request before an earlier one. Chaos mode, but make it valid.

All the libraries you use must be thread-safe and reentrant, and any code that creates a file descriptor should atomically set FD_CLOEXEC if you do not want it accidentally leaked to another thread's child process. You may also need to provide mutexes for fields in your connection handle.

If none of the above thread models are suitable, use NBDKIT_THREAD_MODEL_PARALLEL and implement your own locking using pthread_mutex_t etc. DIY era. 💅

🚨 Error handling 🚨

If there is an error in the plugin, the plugin should call nbdkit_error(3) to report an error message. Then, the callback should return the appropriate error indication, eg. NULL or -1. That's the whole ritual, bestie.

More information about these functions and nbdkit_verror(3) can be found in the separate manual page about them. (Yes, they get their own page. Main character energy.)

If your plugin does not overwrite global errno when returning from system call failures — usually true for plugins written in C, often false for plugins written in high level scripting languages — then you can set .errno_is_preserved = 1 in the plugin struct. Little flag, big difference. 🌟

✨ CALLBACKS ✨

okay so this is the part everyone actually came for. Here's every callback, one by one, no skips, no "you get the idea". Buckle up. 🎀

.name

const char *name;

This field (a string) is required 🔥, and must contain only ASCII alphanumeric characters or non-leading dashes, and it has to be unique amongst all plugins. No duplicates, no weird characters. It's the plugin's whole identity, so pick something cute and legal.

.version

const char *version;

Plugins may optionally set a version string which is displayed in help and debugging output. (See also VERSION below.) Optional but slay. 💖

.longname

const char *longname;

An optional free text name of the plugin. This field is used in error messages — so when something goes wrong, this is the name that shows up. Make it readable, bestie.

.description

const char *description;

An optional multi-line description of the plugin. Go off, describe yourself. 🌸

.load

void load (void);

This is called once, just after the plugin is loaded into memory. You can use this to perform any global initialization needed by the plugin. One shot, make it count. ✨

.unload

void unload (void);

This may be called once just before the plugin is unloaded from memory.

Note that it's not guaranteed that .unload will always be called (eg. the server might be killed or segfault 😭), so you should try to make the plugin as robust as possible by not requiring cleanup.

See also SHUTDOWN below.

.dump_plugin

void dump_plugin (void);

This optional callback is called when the nbdkit plugin --dump-plugin command is used. It should print any additional informative key=value fields to stdout as needed. Prefixing the keys with the name of the plugin will avoid conflicts — do that, it's the polite move. 🫶

.config

int config (const char *key, const char *value);

On the nbdkit command line, after the plugin filename, come an optional list of key=value arguments. These are passed to the plugin through this callback when the plugin is first loaded and before any connections are accepted.

This callback may be called zero or more times.

Both key and value parameters will be non-NULL. The strings are owned by nbdkit but will remain valid for the lifetime of the plugin, so the plugin does not need to copy them. No need to hoard them, they're yours for the whole relationship. 💅

The key will be a non-empty string beginning with an ASCII alphabetic character (A-Z a-z). The rest of the key must contain only ASCII alphanumeric plus period, underscore or dash characters (A-Z a-z 0-9 . _ -). The value may be an arbitrary string, including an empty string.

The names of keys accepted by plugins is up to the plugin, but you should probably look at other plugins and follow the same conventions. Copying your friends' homework is encouraged here.

If the value is a relative path, then note that the server changes directory when it starts up. See nbdkit_realpath(3).

If nbdkit_stdio_safe(3) returns 1, the value of the configuration parameter may be used to trigger reading additional data through stdin (such as a password or inline script). 👀

If the .config callback is not provided by the plugin, and the user tries to specify any key=value arguments, then nbdkit will exit with an error.

If there is an error, .config should call nbdkit_error(3) with an error message and return -1.

.magic_config_key

const char *magic_config_key;

This optional string can be used to set a "magic" key used when parsing plugin parameters. It affects how bare parameters (those which do not contain an = character) are parsed on the command line. Magic, literally. 🪄

If magic_config_key != NULL then any bare parameters are passed to the .config method as:

config (magic_config_key, argv[i]);

If magic_config_key is not set then we behave as in nbdkit < 1.7: if the first parameter on the command line is bare then it is passed to the .config method as:

config ("script", value);

Any other bare parameters give errors. Old-school rules, bestie.

.config_complete

int config_complete (void);

This optional callback is called after all the configuration has been passed to the plugin. It is a good place to do checks, for example that the user has passed the required parameters to the plugin. Vibe check before the party starts. 🎀

If there is an error, .config_complete should call nbdkit_error(3) with an error message and return -1.

.config_help

const char *config_help;

This optional multi-line help message should summarize any key=value parameters that it takes. It does not need to repeat what already appears in .description. Don't be redundant, it's not cute.

If the plugin doesn't take any config parameters you should probably omit this.

.thread_model

int thread_model (void)

This optional callback is called after all the configuration has been passed to the plugin. It can be used to force a stricter thread model based on configuration, compared to THREAD_MODEL. See Threads above for details. Attempts to request a looser (more parallel) model are silently ignored 🙈 — so don't bother asking.

If there is an error, .thread_model should call nbdkit_error(3) with an error message and return -1.

.get_ready

int get_ready (void);

✨ and that's where this part wraps — bestie, keep scrolling, the rest of the callbacks are waiting for you in the next bit 💜✨

✨ .get_ready ✨

This optional callback fires up before the server starts serving anything. It runs before the server forks or changes directory, so bestie, this is literally your last chance to do any global prep you need to serve connections. Last call, no cap.

If something goes wrong, .get_ready should call nbdkit_error(3) with an error message and return -1.

🌸 .after_fork 🌸

int after_fork (void);

Also optional, also called before the server starts serving — but this one comes after the server forks and changes directory. If your plugin needs to create background threads (or leans on an external library that spawns threads), this is the spot, because background threads get absolutely obliterated by fork. 💀

That said, try to do as little as possible here, because error reporting is genuinely difficult at this point. See "Callback lifecycle" above for the whole vibe.

If there's an error, .after_fork should call nbdkit_error(3) with an error message and return -1.

🧹 .cleanup 🧹

void cleanup (void);

Optional callback, called after the server has closed all connections and is getting ready to unload. It's only reached in the same cases where the .after_fork callback was used, which honestly makes it a great little spot to clean up any background threads you spawned earlier.

BUT — and this is the important part — it is not guaranteed that this callback will be reached. So make your plugin as robust as you possibly can by not requiring cleanup at all. See also "SHUTDOWN" below.

🔒 .preconnect 🔒

int preconnect (int readonly);

Optional callback, called when a TCP connection has been made to the server. This happens early — before NBD or TLS negotiation. So if TLS authentication is required to access the server, it has not been negotiated yet at this point.

For security reasons (to avoid denial of service attacks), this callback should be written to be as fast as possible and to take as few resources as possible. 💅

If you use this callback, only use it for basic access control, like checking nbdkit_peer_name(3), nbdkit_peer_pid(3), nbdkit_peer_uid(3), nbdkit_peer_gid(3) against a list of permitted source addresses (see "PEER NAME" and nbdkit-ip-filter(1)). Honestly it may be better to do your access control outside the server, like with TCP wrappers or a firewall. Just saying.

The readonly flag tells the plugin that the server was started with the -r flag on the command line.

Returning 0 lets the connection continue. If there's an error, or you want to deny the connection, call nbdkit_error(3) with an error message and return -1.

📋 .list_exports 📋

int list_exports (int readonly, int is_tls,
                  struct nbdkit_exports *exports);

Optional callback, called when the client tries to list the exports served by the plugin (using NBD_OPT_LIST). If the plugin doesn't supply this callback, then the result of .default_export gets advertised as the lone export. The NBD protocol defines "" as the default export, so this works great for plugins that ignore the export name and always serve the same content. See also "EXPORT NAME" below.

The readonly flag tells the plugin that the server was started with the -r flag on the command line — same value that gets passed to .preconnect and .open. However! The NBD protocol doesn't yet have a way for the client to advertise an intent to be read-only even when the server allows writes, so this parameter may not be as useful as it appears. 🙈

The is_tls flag tells the plugin whether this listing was requested after the client has completed TLS negotiation. When you're running the server in a mode that permits but doesn't require TLS, be careful that any exports listed when is_tls is false don't leak unintended information.

The exports parameter is an opaque object for collecting the list of exports. Call nbdkit_add_export as needed to add specific exports to the list:

 int nbdkit_add_export (struct nbdkit_export *exports,
                        const char *name, const char *description);

The name must be a non-NULL, UTF-8 string between 0 and 4096 bytes in length. Export names must be unique. description is an optional description of the export which some clients can display but which is otherwise unused (if you don't want a description, you can pass this parameter as NULL). The string(s) are copied into the exports list, so you may free them immediately after calling this function. nbdkit_add_export returns 0 on success or -1 on failure; on failure nbdkit_error(3) has already been called, with errno set to a suitable value.

There are also situations where a plugin may wish to duplicate the nbdkit default behavior of supplying an export list containing only the result of .default_export when .list_exports is missing. This is most common in a language binding where it isn't known at compile time whether the language script will be providing an implementation for .list_exports, and it's done by calling nbdkit_use_default_export:

 int nbdkit_use_default_export (struct nbdkit_exports *exports);

nbdkit_use_default_export returns 0 on success or -1 on failure; on failure nbdkit_error(3) has already been called, with errno set to a suitable value.

The plugin may also leave the export list empty, by not calling either helper. Once the plugin is happy with the list contents, returning 0 will send the list of exports back to the client. If there's an error, .list_exports should call nbdkit_error(3) with an error message and return -1.

🏷️ .default_export 🏷️

const char *default_export (int readonly, int is_tls);

Optional callback, called when the client tries to connect to the default export "", where the plugin provides a UTF-8 string between 0 and 4096 bytes. If the plugin doesn't supply this callback, the connection continues with the empty name. If the plugin returns a valid string, nbdkit behaves as if the client had passed that string instead of an empty name, and returns that name to clients that support it (see the NBD_INFO_NAME response to NBD_OPT_GO). Similarly, if the plugin doesn't supply a .list_exports callback, the result of this callback determines what export name gets advertised to a client requesting an export list.

The readonly flag tells the plugin that the server was started with the -r flag on the command line — same value passed to .preconnect and .open. Again though, the NBD protocol doesn't yet have a way for the client to advertise an intent to be read-only even when the server allows writes, so this parameter may not be as useful as it appears.

The is_tls flag tells the plugin whether the canonical name for the default export is being requested after the client has completed TLS negotiation. When running the server in a mode that permits but doesn't require TLS, be careful that a default export name doesn't leak unintended information. 🤫

If the plugin returns NULL or an invalid string (like something longer than 4096 bytes), the client is not permitted to connect to the default export. However, this is not an error in the protocol, so it's not necessary to call nbdkit_error(3).

🚪 .open 🚪

void *open (int readonly);

Called when a new client connects to the nbdkit server. The callback should allocate a handle and return it. That handle gets passed back to other callbacks and could be freed in the .close callback.

Heads up: the handle is completely opaque to nbdkit, but it must not be NULL. If you don't need a handle, return NBDKIT_HANDLE_NOT_NEEDED, which is a static non-NULL pointer. ✨

The readonly flag tells the plugin that the server was started with the -r flag on the command line, which forces connections to be read-only. Note that the plugin may additionally force the connection to be readonly (even if this flag is false) by returning false from the .can_write callback. So if your plugin can only serve read-only, you can just ignore this parameter.

If the plugin wants to differentiate the content it serves based on client input, then this is the spot to use nbdkit_export_name(3) to figure out which export the client requested. See also "EXPORT NAME AND TLS" below.

This callback is called after the NBD handshake has completed; if the server requires TLS authentication, then that's happened too. But if the server is set up with optional TLS authentication, you can check nbdkit_is_tls(3) to learn whether the client has completed TLS authentication. When running the server in a mode that permits but doesn't require TLS, be careful that you don't let unauthenticated clients cause a denial of service against authentication. 🛑

If there's an error, .open should call nbdkit_error(3) with an error message and return NULL.

👋 .close 👋

void close (void *handle);

Called when the client closes the connection. It should clean up any per-connection resources.

Now, there's genuinely no way in the NBD protocol to communicate close errors back to the client — for example, if your plugin calls close(2) and you're checking for errors (which, bestie, you should do). So the best you can do is log the error on the server. Well-behaved NBD clients should try to flush the connection before it's closed and check for errors, but obviously that's outside the scope of nbdkit.

📏 .get_size 📏

int64_t get_size (void *handle);

Called during the option negotiation phase of the protocol to get the size (in bytes) of the block device being exported.

The returned size must be ≥ 0. If there's an error, .get_size should call nbdkit_error(3) with an error message and return -1.

📝 .export_description 📝

const char *export_description (void *handle);

Called during the option negotiation phase, but only if the client specifically requested an export description (see the NBD_INFO_DESCRIPTION response to NBD_OPT_GO). Any description you provide must be human-readable UTF-8, no longer than 4096 bytes. Ideally this description should match any description set during .list_exports, but that's not enforced. 🤷

If the plugin returns NULL or an invalid string (like something longer than 4096 bytes), or if this callback is omitted, no description is offered to the client. Since this isn't an error in the protocol, it's not necessary to call nbdkit_error(3). If the callback won't be returning a compile-time constant string, you may find nbdkit_strdup_intern(3) helpful for returning a value that avoids a memory leak.

🧱 .block_size 🧱

int block_size (void *handle, uint32_t *minimum,
                uint32_t *preferred, uint32_t *maximum);

...and the vibe continues, bestie, because we're still deep in .block_size 💅

This one gets called during the option negotiation phase of the protocol, and its whole job is to hand back the minimum, preferred and maximum block size (all in bytes, no cap) of the block device. The client should be a good little client and obey those constraints — meaning no requests smaller than the minimum, none bigger than the maximum, and usually requests that are a multiple of the preferred size. On top of that, requests should be aligned to at least the minimum block size, and usually to the preferred block size too. ✨

Heads up: "Preferred" block size in the NBD specification can absolutely be misinterpreted. What it actually means is the I/O size that does not have a penalty for read-modify-write. That's the tea. 🍵

And listen — even if your plugin implements this callback, that does NOT mean every client request will play nice and obey the constraints. A client could still just... ignore them. Rude, but real. nbdkit passes all requests straight through to the plugin, because what the plugin does is entirely up to the plugin's own policy. It might decide to serve the requests correctly anyway, or reject them with an error. Plugins can dodge all this complexity by using nbdkit-blocksize-policy-filter(1), which lets you both set/adjust the constraints and pick an error policy. Iconic shortcut behavior honestly. 🎀

The rules, no cap:

  • The minimum block size must be ≥ 1.
  • The maximum block size must be ≤ 0xffff_ffff.
  • minimum ≤ preferred ≤ maximum.

As a special little exception, the plugin may return minimum == preferred == maximum == 0, which means "no information". 🤷

If this callback isn't used at all, then the NBD protocol assumes by default minimum = 1, preferred = 4096. (Maximum block size depends on various factors — go peek at the NBD protocol specification, section "Block size constraints".)

.can_write

int can_write (void *handle);

Called during the option negotiation phase to find out if the handle supports writes. ✍️

If there's an error, .can_write should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return true iff a .pwrite callback has been defined. 💖

.can_flush

int can_flush (void *handle);

Called during the option negotiation phase to find out if the handle supports the flush-to-disk operation. 🚽✨

If there's an error, .can_flush should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return true iff a .flush callback has been defined.

.is_rotational

int is_rotational (void *handle);

Called during the option negotiation phase to find out if the backing disk is a rotational medium (like a traditional hard disk, the old-school spinning kind 🌀) or not (like an SSD, slay 💫). If true, this may cause the client to reorder requests to make them more efficient for a slow rotating disk.

If there's an error, .is_rotational should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return false.

.can_trim

int can_trim (void *handle);

Called during the option negotiation phase to find out if the plugin supports the trim/discard operation for punching holes in the backing storage. 🕳️ (Yes, literally punching holes, it's giving Swiss cheese.)

If there's an error, .can_trim should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return true iff a .trim callback has been defined.

.can_zero

int can_zero (void *handle);

Called during the option negotiation phase to find out if the plugin wants the .zero callback to be utilized. Support for writing zeroes is still advertised to the client (unless the nbdkit-nozero-filter(1) is also used), so returning false merely serves as a way to avoid complicating the .zero callback — you know, so it doesn't have to fail with ENOTSUP or EOPNOTSUPP on the connections where it will never be more efficient than just using .pwrite up front. Lowkey a courtesy move. 🫶

If there's an error, .can_zero should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then for a normal zero request, nbdkit always tries .zero first if it's present, and gracefully falls back to .pwrite if .zero was absent or failed with ENOTSUP or EOPNOTSUPP. Graceful fallback? We love to see it. 💅

.can_fast_zero

int can_fast_zero (void *handle);

Called during the option negotiation phase to find out if the plugin wants to advertise support for fast zero requests. 🏎️💨 If this support isn't advertised, a client cannot attempt fast zero requests, and has no way to tell if writing zeroes offers any speedups compared to using .pwrite (other than compressed network traffic, I guess). If support is advertised, then .zero will have NBDKIT_FLAG_FAST_ZERO set when the client has requested a fast zero — in which case the plugin must fail with ENOTSUP or EOPNOTSUPP up front if the request would not offer any benefits over .pwrite. Advertising support for fast zero requests does not require that writing zeroes be fast — only that the result (whether success or failure) is fast. So yeah, advertise this when feasible, bestie. ✨

If there's an error, .can_fast_zero should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then nbdkit returns true if .zero is absent or .can_zero returns false (in those cases, nbdkit fails all fast zero requests, as its fallback to .pwrite is not inherently faster), otherwise false (since it cannot be determined in advance if the plugin's .zero will properly honor the semantics of NBDKIT_FLAG_FAST_ZERO). Phew, that was a mouthful, but fr fr it matters. 😮‍💨

.can_extents

int can_extents (void *handle);

Called during the option negotiation phase to find out if the plugin supports detecting allocated (non-sparse) regions of the disk with the .extents callback. 🗺️

If there's an error, .can_extents should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return true iff a .extents callback has been defined.

.can_fua

int can_fua (void *handle);

Called during the option negotiation phase to find out if the plugin supports the Forced Unit Access (FUA) flag on write, zero, and trim requests. The returns are giving choices, bestie:

  • If this returns NBDKIT_FUA_NONE, FUA support is not advertised to the client. 🚫
  • If this returns NBDKIT_FUA_EMULATE, the .flush callback must work (even if .can_flush returns false), and FUA support is emulated by calling .flush after any write operation. 🎭
  • If this returns NBDKIT_FUA_NATIVE, then the .pwrite, .zero, and .trim callbacks (if implemented) must handle the flag NBDKIT_FLAG_FUA, by not returning until that action has landed in persistent storage. 💾👑

If there's an error, .can_fua should call nbdkit_error(3) with an error message and return -1.

This callback is not required unless a plugin wants to specifically handle FUA requests. If you omit it, nbdkit checks whether .flush exists, and behaves as if this function returns NBDKIT_FUA_NONE or NBDKIT_FUA_EMULATE as appropriate.

.can_multi_conn

int can_multi_conn (void *handle);

Called during the option negotiation phase to find out if the plugin is prepared to handle multiple connections from a single client. 👯 If the plugin sets this to true, then a client may try to open multiple connections to the nbdkit server and spread requests across all connections to maximize parallelism. If the plugin sets it to false (which is the default), then well-behaved clients should only open a single connection — although, ngl, we cannot control what clients do in practice. 🙈

Specifically it means that either the plugin does not cache requests at all. Or if it does cache them, then the effects of a .flush request or setting NBDKIT_FLAG_FUA on a request must be visible across all connections to the plugin before the plugin replies to that request. No sneaky partial visibility, periodt.

Properly working clients should send the same export name for each of these connections. Consistency is the vibe. 🦋

If you use Linux nbd-client(8) option -C num with num > 1 then Linux checks this flag and will refuse to connect if .can_multi_conn is false.

If there's an error, .can_multi_conn should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return false.

.can_cache

int can_cache (void *handle);

Called during the option negotiation phase to find out if the plugin supports a cache or prefetch operation. 🧠⚡

This can return:

  • NBDKIT_CACHE_NONE — Cache support is not advertised to the client.
  • NBDKIT_CACHE_EMULATE — Caching is emulated by the server calling .pread and discarding the result.
  • NBDKIT_CACHE_NATIVE — Cache support is advertised to the client. The .cache callback will be called if it exists, otherwise all cache requests instantly succeed. ✨

If there's an error, .can_cache should call nbdkit_error(3) with an error message and return -1.

This callback is not required. If you omit it, then we return NBDKIT_CACHE_NONE if the .cache callback is missing, or NBDKIT_CACHE_NATIVE if it is defined.

.pread

int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
           uint32_t flags);

During the data serving phase, nbdkit calls this callback to read data from the backing store. 📖 count bytes starting at offset in the backing store should be read and copied into buf. nbdkit takes care of all bounds- and sanity-checking, so the plugin does not need to worry about that. Bestie, you're protected. 🫶

The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input.

The callback must read the whole count bytes if it can. The NBD protocol doesn't allow partial reads (instead, these would be errors). If the whole count bytes was read, the callback should return 0 to indicate there was no error. ✅

If there's an error (including a short read which couldn't be recovered from), .pread should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1.

.pwrite

int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
            uint32_t flags);

During the data serving phase, nbdkit calls this callback to write data to the backing store. ✍️💾 count bytes starting at offset in the backing store should be written using the data in buf. nbdkit takes care of all bounds- and sanity-checking, so the plugin does not need to worry about that.

This function will not be called if .can_write returned false. The parameter flags may include NBDKIT_FLAG_FUA on input based on the result of .can_fua. 🔥

So the callback has to write the whole count bytes if it can, bestie — that's not optional. The NBD protocol does not do partial writes (those would be errors, full stop). If the whole count bytes went through successfully, return 0 and we're done, no error, no drama. ✨

If something goes wrong (and yes, that includes a short write that couldn't be recovered from), .pwrite should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient, iykyk), then return -1.

.flush 🚽✨

int flush (void *handle, uint32_t flags);

During the data serving phase, this callback is the one that fdatasync(2)s the backing store — like, it makes sure everything is actually written down to a permanent medium and not just vibing in a cache somewhere. If your backing store can't do that, you can just omit this callback, no biggie.

Real talk though: this function won't be called directly by the client if .can_flush returned false. But it may still get called by nbdkit if .can_fua returned NBDKIT_FUA_EMULATE. Sneaky. The flags parameter is there for future NBD protocol extensions; right now it'll be 0 on input.

If there's an error, .flush should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1. 💅

.trim ✂️

int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

During the data serving phase, this callback is for "punching holes" in the backing store — very demure, very mindful, very sparse. If your backing store can't do that, omit the callback, it's fine.

This function will not be called if .can_trim returned false. The flags parameter may include NBDKIT_FLAG_FUA on input, based on the result of .can_fua.

If there's an error, .trim should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1.

.zero 🫧

int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

During the data serving phase, this callback writes count bytes of zeroes at offset in the backing store. Zeros. So many zeros. Iconic.

This function will not be called if .can_zero returned false. On input, the flags parameter may include:

  • NBDKIT_FLAG_MAY_TRIM — unconditionally
  • NBDKIT_FLAG_FUA — based on the result of .can_fua
  • NBDKIT_FLAG_FAST_ZERO — based on the result of .can_fast_zero

If NBDKIT_FLAG_MAY_TRIM is requested, the operation can punch a hole instead of writing actual zero bytes — but only if subsequent reads from that hole read back as zeroes. Otherwise nope.

If NBDKIT_FLAG_FAST_ZERO is requested, the plugin has to decide up front whether its implementation is likely to be faster than a corresponding .pwrite. If it's not, then it must immediately fail with ENOTSUP or EOPNOTSUPP (whether by nbdkit_set_error(3) or errno), and preferably without modifying the exported image at all. It is acceptable to always fail a fast zero request — a fast failure is genuinely better than attempting the write and only finding out after the fact that it wasn't fast after all. 😭 Also note: on Linux, support for ioctl(BLKZEROOUT) is insufficient for determining whether a zero request to a block device will be fast, because the kernel will perform a slow fallback when needed. Rude, honestly.

The callback must write the whole count bytes if it can. The NBD protocol doesn't allow partial writes (instead, these would be errors). If the whole count bytes was written successfully, the callback should return 0 to indicate there was no error.

If there's an error, .zero should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1.

If this callback is omitted, or if it fails with ENOTSUP or EOPNOTSUPP (whether by nbdkit_set_error(3) or errno), then .pwrite will be used as an automatic fallback — except when the client requested a fast zero. No shortcuts there. 🚫

.extents 🗺️

int extents (void *handle, uint32_t count, uint64_t offset,
             uint32_t flags, struct nbdkit_extents *extents);

During the data serving phase, this callback detects allocated, sparse and zeroed regions of the disk. It's basically the plugin doing a vibe check on which parts of the disk are real and which parts are just holes.

This function will not be called if .can_extents returned false. In that case, nbdkit's default behaviour is to treat the whole virtual disk as if it was allocated. Also, this function will not be called by a client that does not request structured replies — the --no-sr option of nbdkit can be used to test behavior when .extents is unavailable to the client.

The callback should detect and return the list of extents overlapping the range [offset...offset+count-1]. The extents parameter points to an opaque object which the callback should fill in by calling nbdkit_add_extent. See "Extents list" below. 👇

If there's an error, .extents should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1.

Extents list 🧚

The plugin extents callback is passed an opaque pointer struct nbdkit_extents *extents. This structure represents a list of filesystem extents describing which areas of the disk are allocated, which are sparse (“holes”), and, if supported, which are zeroes.

The extents callback should scan the disk starting at offset and call nbdkit_add_extent for each extent found.

Extents overlapping the range [offset...offset+count-1] should be returned if possible. However nbdkit ignores extents < offset, so the plugin may — if it is easier to implement — return all extent information for the whole disk. The plugin may return extents beyond the end of the range. It may also return extent information for less than the whole range, but it must return at least one extent overlapping offset. That's the bare minimum, bestie.

The extents must be added in ascending order, and must be contiguous. No chaotic energy allowed here.

The flags parameter of the .extents callback may contain the flag NBDKIT_FLAG_REQ_ONE. This means the client is only requesting information about the extent overlapping offset. The plugin may ignore this flag, or as an optimization it may return just a single extent for offset.

int nbdkit_add_extent (struct nbdkit_extents *extents,
                       uint64_t offset, uint64_t length, uint32_t type);

Add an extent covering [offset...offset+length-1] of one of the following four types:

  • type = 0 — a normal, allocated data extent. The default, the main character.
  • type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO — an unallocated extent, a.k.a. a “hole”, which reads back as zeroes. This is the normal type of hole applicable to most disks.
  • type = NBDKIT_EXTENT_ZERO — an allocated extent which is known to contain only zeroes. Zeroes but make it official.
  • type = NBDKIT_EXTENT_HOLE — an unallocated extent (hole) which does not read back as zeroes. Note this should only be used in specialized circumstances, such as when writing a plugin for (or to emulate) certain SCSI drives which do not guarantee that trimmed blocks read back as zeroes. Niche. Specialized. For the connoisseurs.

nbdkit_add_extent returns 0 on success or -1 on failure. On failure nbdkit_error(3) and/or nbdkit_set_error(3) has already been called. errno will be set to a suitable value.

.cache 🧠

int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

During the data serving phase, this callback gives the plugin a hint that the client intends to make further accesses to the given region of the export. A little heads-up. A gentle foreshadowing. 🔮

The nature of caching/prefetching is not specified further by the NBD specification. For example, a server may place limits on how much may be cached at once, and there is no way to control if writes to a cached area have write-through or write-back semantics. In fact, the cache command can always fail and still be compliant, and success might not guarantee a performance gain. So like… it's a hint. That's it. That's the whole thing.

If this callback is omitted, then the results of .can_cache determine whether nbdkit will reject cache requests, treat them as instant success, or emulate caching by calling .pread over the same region and ignoring the results.

This function will not be called if .can_cache did not return NBDKIT_CACHE_NATIVE.

The flags parameter exists in case of future NBD protocol extensions; at this time, it will be 0 on input. A plugin must fail this function if flags includes an unrecognized flag, as that may indicate a requirement that the plugin must comply with to provide a specific caching semantic. Don't be brave about unknown flags, okay?

If there's an error, .cache should call nbdkit_error(3) with an error message, and nbdkit_set_error(3) to record an appropriate error (unless errno is sufficient), then return -1.

.errno_is_preserved 🛟

This field defaults to 0; if non-zero, nbdkit can reliably use the value of errno when a callback reports failure, rather than the plugin having to call nbdkit_set_error(3). Basically it's you telling nbdkit "trust me, I kept errno intact" so it can skip a step. Very efficient of you. 💅

UMASK 🌂

All plugins will see a umask(2) of 0022.

PARSING COMMAND LINE PARAMETERS 🔍

nbdkit provides several functions to help plugins and filters to parse command line parameters. These are documented in separate man pages:

SLEEPING 😴

A plugin or filter that needs to sleep may call sleep(2), nanosleep(2) and similar. However that can cause nbdkit to delay excessively when shutting down (since it must wait for any plugin or filter which is sleeping). To avoid this, plugins and filters should call nbdkit_nanosleep(3) instead. Please. For the shutdown experience. 🫶

EXPORT NAME AND TLS 🔐

If the client negotiated an NBD export name with nbdkit then plugins may read this from any connected callback. Nbdkit's normal behaviour is to accept any export name passed by the client, log it in debug output, but otherwise ignore it. By calling nbdkit_export_name(3) plugins may choose to filter by export name or serve different content. Choose your own adventure, honestly.

nbdkit_is_tls(3) can be used to find the status of TLS negotiation on the current connection. 🦋

💖 STRING LIFETIME 💖

okay so some callbacks are like "bestie u gotta return const char *" — even when ur plugin literally does not have a cute little compile-time constant just sitting there ready to hand over. and if u return dynamically-allocated memory from one of those callbacks?? that's a memory leak bestie. or at minimum it makes ur plugin do a whole extra bookkeeping side quest. 💀

for exactly these situations, nbdkit has ur back with some convenience functions that make a copy of a string so the lifetime situation is, like, manageable:

🦋 PEER NAME 🦋

in any connected callback u can grab the source address of the client with nbdkit_peer_name(3). iconic. ✨

and if the client is connected over a Unix domain socket, u might also be able to get the client process ID, user ID, group ID and security context using:

and if the client connected using TLS and actually presented a client certificate, then u can read the Distinguished Name (DN) with nbdkit_peer_tls_dn(3), and the issuer's DN with nbdkit_peer_tls_issuer_dn(3). very main character of them honestly. 💅

🌸 SHUTDOWN 🌸

when nbdkit catches certain signals it's gonna shut down (peep "SIGNALS" in nbdkit(1)). the server waits for any currently running plugin callbacks to finish, calls .close on those connections, then calls the .cleanup and .unload callbacks before it unloads the plugin. so polite of it.

ngl it's not guaranteed this can always happen — like, the server might get SIGKILL'd or segfault. 😭 so don't count on a graceful exit every single time.

if u wanna request server shutdown or client disconnection from inside ur plugin, go look at nbdkit_shutdown(3) and nbdkit_disconnect(3). 🫶

✨ VERSION ✨

Compile-time version of nbdkit

the macros NBDKIT_VERSION_MAJOR, NBDKIT_VERSION_MINOR and NBDKIT_VERSION_MICRO expand to integers containing the version of the nbdkit headers that ur compiling against. 🎀

NBDKIT_VERSION_MAJOR is always 1. and NBDKIT_VERSION_MINOR is even for stable releases of nbdkit and odd for development releases. so if u see an odd minor, congrats u live on the edge bestie. 🔥

the macro NBDKIT_VERSION_STRING expands to that same version, but as a string.

Run-time version of nbdkit

so when ur plugin actually gets loaded into nbdkit, it might not be the same version u compiled against. plot twist. 🙈

but nbdkit guarantees backwards compatibility of the API and ABI, so as long as nbdkit is the same version or newer, ur plugin will still work. periodt.

there is literally no way to get the version of nbdkit from the plugin. none. zero. that's just how it is.

Version of the plugin

the plugin itself can use whatever versioning scheme u want 💖 and put any string into the .version field of the plugin struct (or just leave that field NULL, we don't judge).

API version

see "WRITING AN NBDKIT PLUGIN" above. 👆

🎀 DEBUGGING 🎀

run the server with -f and -v options so it doesn't fork and u can actually see the debugging information:

nbdkit -fv ./myplugin.so [key=value [key=value [...]]]

and if u wanna print debugging info from inside the plugin, call nbdkit_debug(3). heads up tho: nbdkit_debug(3) only prints things when the server is in verbose mode (that's the -v option). 🫶

Debug Flags

the -v option switches general debugging on or off, and u should use this debugging for messages that are useful for all users of ur plugin.

but sometimes u want extra specific debugging to troubleshoot bugs in plugins or filters — mostly for the plugin/filter developers themselves, iykyk — and for that u can define Debug Flags. these are global ints called myplugin_debug_*:

int myplugin_debug_foo;
int myplugin_debug_bar;
...
if (myplugin_debug_foo) {
  nbdkit_debug ("lots of extra debugging about foo: ...");
}

Debug Flags can be controlled on the command line using the -D (or --debug) option:

nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]

note that myplugin is the name passed to .name in the struct nbdkit_plugin. and u don't even have to declare debug flags — they're found automatically using dlsym(3). slay. 💅

only use this feature for debug settings. for general settings, use ordinary plugin parameters. also: Debug Flags can only be C ints, and they are not supported by non-C language plugins.

for convenience, . characters get replaced with _ characters in the variable name, so both of these parameters:

-D myplugin.foo_bar=1
-D myplugin.foo.bar=1

correspond to the plugin variable myplugin_debug_foo_bar. cute right?? 🌸

🧚 COMPILING THE PLUGIN 🧚

plugins should be compiled as shared libraries. there's a bunch of ways to pull this off, but most Linux compilers support a -shared option to create the shared library directly, like:

gcc -fPIC -shared myplugin.c -o myplugin.so

and yeah, the shared library will have undefined symbols for functions that u call like nbdkit_parse_int(3) or nbdkit_error(3). those get resolved by the server binary when nbdkit dlopens the plugin. no stress. ✨

PKG-CONFIG/PKGCONF

nbdkit provides a pkg-config/pkgconf file called nbdkit.pc which should be installed on the correct path when the nbdkit plugin development environment is installed. u can use this in autoconf configure.ac scripts to test for the development environment:

PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])

the above will fail unless nbdkit ≥ 1.2.3 and the header file is installed, and it'll set NBDKIT_CFLAGS and NBDKIT_LIBS appropriately for compiling plugins. 🫶

u can also run pkg-config/pkgconf directly, for example:

if ! pkg-config nbdkit --exists; then
  echo "you must install the nbdkit plugin development environment"
  exit 1
fi

u can also substitute the plugindir variable by doing:

PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])

which defines $(NBDKIT_PLUGINDIR) in automake-generated Makefiles. obsessed. 💖

and if nbdkit development headers are installed in a non-standard location then u may need to compile plugins using:

gcc -fPIC -shared myplugin.c -o myplugin.so \
  `pkg-config nbdkit --cflags --libs`

👑 INSTALLING THE PLUGIN 👑

the plugin is a *.so file and possibly a manual page. u can ofc install the plugin *.so file wherever u want, and users will be able to use it by running:

nbdkit /path/to/plugin.so [args]

but — and this is the glow-up — if the shared library has a name of the form nbdkit-name-plugin.so and if the library is installed in the $plugindir directory, then users can run it by only typing:

nbdkit name [args]

the location of the $plugindir directory is set when nbdkit is compiled and can be found by doing:

nbdkit --dump-config

and if ur using the pkg-config/pkgconf system then u can also find the plugin directory at compile time by doing:

pkg-config nbdkit --variable=plugindir

💜 WRITING PLUGINS IN C++ 💜

plugins in C++ work almost exactly like those in C, but the way u define the nbdkit_plugin struct is slightly different:

namespace {
  nbdkit_plugin create_plugin() {
    nbdkit_plugin plugin = nbdkit_plugin ();
    plugin.name     = "myplugin";
    plugin.open     = myplugin_open;
    plugin.get_size = myplugin_get_size;
    plugin.pread    = myplugin_pread;
    plugin.pwrite   = myplugin_pwrite;
    return plugin;
  }
}
static struct nbdkit_plugin plugin = create_plugin ();
NBDKIT_REGISTER_PLUGIN(plugin)

🌈 WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES 🌈

u can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python, Rust, shell script or Tcl. and other programming languages may be offered in future. the roster keeps growing bestie. 🦋

Ruby plugin support was removed in nbdkit 1.40. rip ruby. 💀

for more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

plugins written in scripting languages may also be installed in $plugindir. these must be called nbdkit-name-plugin without any extension. they must be executable, and they must use the shebang header (see "Shebang scripts" in nbdkit(1)). for example a plugin written in Perl called foo.pl might be installed like this:

$ head -1 foo.pl
#!/usr/sbin/nbdkit perl

$ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin

and then users will be able to run it like this:

$ nbdkit foo [args ...]

ate. no notes. 💅

⭐ SEE ALSO ⭐

nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1), nbdkit-filter(3).

Utility functions provided by nbdkit for plugins and filters to use:

nbdkit_absolute_path(3), nbdkit_debug(3), nbdkit_debug_hexdiff(3), nbdkit_debug_hexdump(3), nbdkit_disconnect(3), nbdkit_error(3), nbdkit_export_name(3), nbdkit_is_tls(3), nbdkit_name(3), nbdkit_nanosleep(3), nbdkit_parse_bool(3), nbdkit_parse_delay(3), nbdkit_parse_int(3), nbdkit_parse_int16_t(3), nbdkit_parse_int32_t(3), nbdkit_parse_int64_t(3), nbdkit_parse_int8_t(3), nbdkit_parse_probability(3), nbdkit_parse_size(3), nbdkit_parse_uint16_t(3), nbdkit_parse_uint32_t(3), nbdkit_parse_uint64_t(3), nbdkit_parse_uint8_t(3), nbdkit_parse_unsigned(3), nbdkit_peer_gid(3), nbdkit_peer_name(3), nbdkit_peer_pid(3), nbdkit_peer_security_context(3), nbdkit_peer_tls_dn(3). nbdkit_peer_tls_issuer_dn(3). nbdkit_peer_uid(3), nbdkit_printf_intern(3), nbdkit_read_password(3), nbdkit_realpath(3), nbdkit_set_error(3), nbdkit_shutdown(3), nbdkit_stdio_safe(3), nbdkit_strdup_intern(3), nbdkit_strndup_intern(3), nbdkit_timestamp(3), nbdkit_vdebug(3), nbdkit_verror(3), nbdkit_vprintf_intern(3).

Standard plugins provided by nbdkit:

nbdkit-blkio-plugin(1), nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1), nbdkit-data-plugin(1), nbdkit-eval-plugin(1), nbdkit-example1-plugin(1), nbdkit-example2-plugin(1), nbdkit-example3-plugin(1), nbdkit-example4-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-full-plugin(1), nbdkit-gcs-plugin(1), nbdkit-guestfs-plugin(1), nbdkit-info-plugin(1), nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1), nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1), nbdkit-nbd-plugin(1), nbdkit-nfs-plugin(1), nbdkit-null-plugin(1), nbdkit-ondemand-plugin(1), nbdkit-ones-plugin(1), nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1), nbdkit-random-plugin(1), nbdkit-S3-plugin(1), nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1), nbdkit-ssh-plugin(1), nbdkit-tmpdisk-plugin(1), nbdkit-torrent-plugin(1), nbdkit-vddk-plugin(1), nbdkit-vram-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

🌸 AUTHORS 🌸

Eric Blake

Richard W.M. Jones

Pino Toscano

Copyright Red Hat

📜 LICENSE 📜

okay bestie, this is the part where we get ✨legal✨ — and no, we are not skipping it, because the vibes are binding and the vibes are, in fact, enforceable 💅. Short version: nbdkit is open source, you can absolutely use it, ship it, remix it, drop it in your little project 🫶 — but there are three (3) rules and one giant ALL-CAPS disclaimer, and the all-caps is doing main character energy on purpose 💀.

Here's the whole thing, word for word, zero edits, no cap:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

•   Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

•   Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

•   Neither the name of Red Hat nor the names of its contributors may be
    used to endorse or promote products derived from this software
    without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

🎀 the three conditions, translated 🎀

  • condition one — the source code receipts — if you redistribute the source code, you keep the copyright notice, you keep this list of conditions, and you keep the disclaimer. that's it, that's the rule. you cannot delete the receipts bestie, they travel with the code 📝.
  • condition two — the binary version — if you redistribute in binary form, you reproduce those same three things — the copyright notice, the list of conditions, the disclaimer — in the documentation and/or the other materials that ship with the distribution. same energy, different delivery method 🌈.
  • condition three — hands off the name — neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. so no slapping their name on your thing as a clout sticker, no "as seen on Red Hat" nonsense. ask first, in writing, or don't. periodt 👑.

💀 the disclaimer 💀

and now the part that is genuinely not a joke: this software is provided by Red Hat and contributors ''AS IS'' — with any express or implied warranties disclaimed, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. zero warranty. none. not implied, not express, not a little bit.

no liability, at all, for any damages — direct, indirect, incidental, special, exemplary or consequential — including but not limited to procurement of substitute goods or services, loss of use, loss of data, loss of profits, or business interruption. and that holds however it happened and under whatever theory: contract, strict liability, or tort (including negligence or otherwise). even if they were literally told this could happen. even then. 😭

the caps lock is not a stylistic choice bestie, it's the legal equivalent of someone screaming it in your face 🗣️ — read it and believe it.

and that's the whole page 🫶 you just made it through all seven parts of nbdkit-plugin(3), from nbdkit-1.48.1, dated 2026-08-29 💖 go write a plugin, go break absolutely nothing, go be the icon you are 🌸✨🦋

📦 where this page comes from