nbdkit-filter(3)

📦
version 1.48.1 · 14 versions
, in fedora 44

🌸 nbdkit-filter 🌸

okay bestie, this is the nbdkit-filter(3) manual page and it's literally all about how to write nbdkit filters 💅

✨ NAME ✨

nbdkit-filter — how to write nbdkit filters

🎀 SYNOPSIS 🎀

#include <nbdkit-filter.h>

static int
myfilter_config (nbdkit_next_config *next, void *nxdata,
                 const char *key, const char *value)
{
  if (strcmp (key, "myparameter") == 0) {
    // ...
    return 0;
  }
  else {
    // pass through to next filter or plugin
    return next (nxdata, key, value);
  }
}

static struct nbdkit_filter filter = {
  .name              = "filter",
  .config            = myfilter_config,
  /* etc */
};

NBDKIT_REGISTER_FILTER(filter)

When this has been compiled to a shared library, do:

nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]

When debugging, use the -fv options:

nbdkit -fv --filter=./myfilter.so plugin [key=value ...]

🦋 DESCRIPTION 🦋

One or more nbdkit filters can be placed in front of an nbdkit plugin to modify the behaviour of the plugin. This manual page describes how to create an nbdkit filter. slay

Filters can be used for example to limit requests to an offset/limit, add copy-on-write support, or inject delays or errors (for testing). ✨

Different filters can be stacked:

     NBD     ┌─────────┐    ┌─────────┐          ┌────────┐
  client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
 request     └─────────┘    └─────────┘          └────────┘

Each filter intercepts plugin functions (see nbdkit-plugin(3)) and can call the next filter or plugin in the chain, modifying parameters, calling before the filter function, in the middle or after. Filters may even short-cut the chain. As an example, to process its own parameters the filter can intercept the .config method:

static int
myfilter_config (nbdkit_next_config *next, void *nxdata,
                 const char *key, const char *value)
{
  if (strcmp (key, "myparameter") == 0) {
    // ...
    // here you would handle this key, value
    // ...
    return 0;
  }
  else {
    // pass through to next filter or plugin
    return next (nxdata, key, value);
  }
}

static struct nbdkit_filter filter = {
  // ...
  .config            = myfilter_config,
  // ...
};

The call to next (nxdata, ...) calls the .config method of the next filter or plugin in the chain. In the example above any instances of myparameter=... on the command line would not be seen by the plugin. 👀

To see example filters: https://gitlab.com/nbdkit/nbdkit/tree/master/filters

Filters must be written in C. periodt.

Unlike plugins, where we provide a stable ABI guarantee that permits operation across version differences, filters can only be run with the same version of nbdkit that they were compiled with. The reason for this is two-fold: the filter API includes access to struct nbdkit_next_ops that is likely to change if new callbacks are added (old nbdkit cannot safely run new filters that access new methods); and if we added new methods then an old filter would not see them and so they would be passed unmodified through the filter, and in some cases that leads to data corruption (new nbdkit cannot safely run old filters unaware of new methods). Therefore, unlike plugins, you should not expect to distribute filters separately from nbdkit. 💀

lowkey important: this ABI thing is not a vibe, it's a whole rule. don't ship your filter separately from nbdkit, fr fr.

💖 #include <nbdkit-filter.h> 💖

All filters should start by including this header file. no exceptions bestie 🫶

👑 struct nbdkit_filter 👑

All filters must define and register one struct nbdkit_filter, which contains the name of the filter and pointers to plugin methods that the filter wants to intercept.

static struct nbdkit_filter filter = {
  .name              = "filter",
  .longname          = "My Filter",
  .description       = "This is my great filter for nbdkit",
  .config            = myfilter_config,
  /* etc */
};

NBDKIT_REGISTER_FILTER(filter)

The .name field is the name of the filter. This is the only field which is required. ⭐

🌈 NEXT PLUGIN 🌈

Okay bestie, so nbdkit-filter.h defines a whole little friend group of function types — specifically nbdkit_next_config, nbdkit_next_config_complete, nbdkit_next_preconnect, nbdkit_next_list_exports, nbdkit_next_default_export, and nbdkit_next_open — plus a struct called struct nbdkit_next_ops. What are they for? They abstract the next plugin or filter in the chain 💫. There's also an opaque pointer — backend, context or nxdata — that you must pass along when you call these functions. The value of backend is stable between .after_fork, .preconnect, .list_exports, and .default_export, and you can also grab it with nbdkit_context_get_backend on the context parameter to .open. Obsessed with the consistency honestly.

Meanwhile, if the filter doesn't use nbdkit_context_set_next, the value of next passed to .prepare has a stable lifetime that lasts all the way to the corresponding .finalize, with every intermediate function (like .pread) receiving the same value for convenience. So cute of nbdkit. The functions where nxdata is not reused are .config, .config_complete, and .get_ready — those all get called during initialization, outside any connections. And the value of backend passed to .after_fork also happens without connections, but it's shared with .preconnect, .list_exports, and .default_export, and can also be obtained from the context passed to .open, with a lifetime that lasts to .cleanup for use by nbdkit_next_context_open. In turn, the value of context passed to .open has a lifetime that lasts until the matching .close, for use by nbdkit_context_get_backend and nbdkit_context_set_next. Bestie it's giving ✨memory management✨ but in a slay way.

🎀 Next config, open and close 🎀

The filter's .config, .config_complete, .get_ready, .after_fork, .preconnect, .list_exports, .default_export and .open methods may only call the next .config, .config_complete, .get_ready, .after_fork, .preconnect, .list_exports, .default_export and .open method in the chain (optionally, for .config and .open). One per one, no skipping the line 💅.

The filter's .close method gets called when an old connection closed, and this one has no next parameter, because it can't be short-circuited. It's just... closing time. Periodt.

💜 nbdkit_next 💜

The filter generally needs to call into the underlying plugin, and it does that via a pointer to struct nbdkit_next_ops, which you can also refer to as the typedef nbdkit_next. The most common behavior is to create a next context per connection by calling the next_open parameter during .open, at which point the next context gets automatically provided to the filter's other methods like .prepare, .get_size, .pread etc. The nbdkit_next struct contains a comparable set of accessors to plugin methods that can be called during a connection. When you're using automatic registration, the next parameter is stable between .prepare and .finalize, and nbdkit automatically prepares, finalizes, and closes the next context at exactly the right point in the filter connection lifecycle. She's doing the work for you, no cap 🫶.

Alternatively — plot twist — the filter can manage plugin contexts manually, whether that's to multiplex multiple client connections through a single context into the plugin, or to open multiple plugin contexts to do retries or otherwise service a single client connection more efficiently. In this mode of operation, the filter uses nbdkit_next_context_open to open a plugin context using the backend parameter passed to .after_fork, .preconnect, .list_exports, .default_export, or obtained from using nbdkit_context_get_backend on the context parameter to .open. The resulting next context has a lifecycle under manual control — meaning the filter must use next->prepare (next) before using any other function pointers within the next context, and must reclaim the memory using next->finalize (next) and nbdkit_next_context_close when done. A filter using manual lifecycle management may use nbdkit_context_set_next to associate the next context into the current connection, which lets nbdkit then pass that context as the next parameter to future connection-related functions like .pread, and take over lifecycle responsibility. So it can literally hand off the keys 😭.

nbdkit_context_get_backend

nbdkit_next_context_open

nbdkit_next_context_close

nbdkit_context_set_next

 nbdkit_backend *nbdkit_context_get_backend (nbdkit_context *context);

Obtains the backend pointer from the context parameter to .open, matching the backend pointer available to .after_fork, .preconnect, .list_exports, and .default_export. This backend pointer has a stable lifetime from the time of .after_fork until .cleanup. Immaculate.

 nbdkit_next *nbdkit_next_context_open (nbdkit_backend *backend,
                                        int readonly, const char *exportname,
                                        int shared);

This function attempts to open a new context into the plugin in relation to the filter's current backend. The readonly and exportname parameters behave the same as documented in .open. The resulting context will be under the filter's manual lifecycle control unless the filter associates it into the connection with nbdkit_context_set_next. And bestie, be careful: the filter should not violate any threading model restrictions of the plugin if it opens more than one context. Mind the rules 🧚.

If shared is false, this function must be called while servicing an existing client connection, and the new context will share the same connection details (export name, tls status, and shorter interned string lifetimes) as the current connection, and thus should not be used after the client connection ends. Conversely, if shared is true, this function may be called outside of a current client connection (such as during .after_fork), and the resulting context may be freely shared among multiple client connections. In shared mode, it will not be possible for the plugin to differentiate content based on the client export name, the result of the plugin calling nbdkit_is_tls(3) will depend solely whether --tls=require was on the command line, the lifetime of interned strings (via nbdkit_strdup_intern(3) and friends) lasts for the life of the filter, and the filter must take care to not expose potentially-secure information from the backend to an insecure client. 🚨 That last bit is a big deal, do not play with it.

 void nbdkit_next_context_close (nbdkit_next *next);

This function closes a context into the plugin. If the context has previously been prepared, it should first be finalized before using this function. This function does not need to be called for a plugin context that has been associated with the filter connection via nbdkit_context_set_next prior to the .close callback. Nice, one less thing.

 nbdkit_next *nbdkit_context_set_next (nbdkit_context *context,
                                       nbdkit_next *next);

This function associates a plugin context with the filter's current connection context, given by the context parameter to .open. Once associated, this plugin context will be given as the next parameter to all other connection-specific callbacks. If associated during .open, nbdkit will take care of preparing the context prior to .prepare; if still associated before .finalize, nbdkit will take care of finalizing the context, and also for closing it. A filter may also pass NULL for next, to remove any association; if no plugin context is associated with the connection, then filter callbacks such as .pread will receive NULL for their next parameter. She said "no context, no problem" 💀.

This function returns the previous context that had been associated with the connection prior to switching the association to next; this result will be NULL if there was no previous association. The filter assumes manual responsibility for any remaining lifecycle functions that must be called on the returned context. Don't forget about her 🥺.

🦋 Using nbdkit_next 🦋

Regardless of whether the plugin context is managed automatically or manually, it is possible for a filter to issue (for example) extra next->pread calls in response to a single .pwrite call. Extra reads? On my watch? It's more likely than you think.

The next parameter serves two purposes: it serves as the struct to access the pointers to all the plugin connection functions, and it serves as the opaque data that must be passed as the first parameter to those functions. For example, calling the plugin's can_flush functionality would be done via

 next->can_flush (next)

Note that the semantics of the functions in struct nbdkit_next_ops are slightly different from what a plugin implements: for example, when a plugin's .pread returns -1 on error, the error value to advertise to the client is implicit (via the plugin calling nbdkit_set_error(3) or setting errno), whereas next->pread exposes this via an explicit parameter, allowing a filter to learn or modify this error if desired. Sneaky little detail but so useful.

Use of next->prepare and next->finalize is only needed when manually managing the plugin context lifetime. Auto mode besties, you're off the hook ✨.

🌸 Other considerations 🌸

You can modify parameters when you call the next function. However — be careful when modifying strings, because for some methods (eg. .config) the plugin may save the string pointer that you pass along. So you may have to ensure that the string is not freed for the lifetime of the server; you may find nbdkit_strdup_intern(3) helpful for avoiding a memory leak while still obeying lifecycle constraints. That's your get-out-of-jail card, use it 🎀.

Note that if your filter registers a callback but in that callback it doesn't call the next function, then the corresponding method in the plugin will never be called. In particular, your .open method, if you have one, must call the next method if you want the underlying plugin to be available to all further nbdkit_next use. The way that skipping next silently cuts the whole chain off... not the vibe, bestie 😭.

👑 CALLBACKS 👑

struct nbdkit_filter has some static fields describing the filter and optional callback functions which can be used to intercept plugin methods. Slay, let's meet them all one by one 💖.

.name

 const char *name;

This field (a string) is required, and must contain only ASCII alphanumeric characters or non-leading dashes, and be unique amongst all filters. Only one of her, she's the main character 🔥.

.longname

 const char *longname;

An optional free text name of the filter. This field is used in error messages. Like a government name, for formal occasions.

.description

 const char *description;

An optional multi-line description of the filter.

.load

 void load (void);

This is called once just after the filter is loaded into memory. You can use this to perform any global initialization needed by the filter. Get ready, get set, it's loading ⭐.

.unload

 void unload (void);

This may be called once just before the filter 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 filter as robust as possible by not requiring cleanup. See also "SHUTDOWN" in nbdkit-plugin(3). So like, don't build your whole life around .unload showing up 💀.

.config

 int (*config) (nbdkit_next_config *next, void *nxdata,
                const char *key, const char *value);

.config

int (*config) (nbdkit_next_config *next, void *nxdata,
               const char *key, const char *value);

Okay so this one intercepts the plugin's .config method, and bestie it's literally your filter's moment to parse its own command line parameters 💅 You should lowkey try to make sure that the command line parameter keys your filter uses don't clash with ones a plugin could be using — conflicting keys are giving awkward family dinner energy 🫠

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

.config_complete

int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);

This intercepts the plugin's .config_complete method, and it's your chance to double-check that every parameter your filter needed actually showed up on the command line. Vibe check on your own requirements, fr fr ✨

If there's 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 it takes. It does not need to repeat what already shows up in .description — no need to say the same thing twice, that's not the move 🙈

If your filter doesn't take any config parameters you should probably just omit this one entirely. Simple as.

.thread_model

int (*thread_model) (int next_thread_model);

Filters may tighten (but not relax) the thread model of the plugin, by defining this callback. The next_thread_model parameter passed in is the thread model of the underlying layer — for a plugin it's its thread model, for a filter it's whatever it returned from .thread_model.

See THREADS in nbdkit-plugin(3) for the whole discussion of thread models, iykyk 📚

The final thread model nbdkit uses is the smallest (ie. most serialized) out of all the filters and the plugin, and it applies for all connections. Requests for a model larger than what the plugin permits are silently ignored — no drama, just quietly not happening 💀 It's totally acceptable for decisions made during .config and .config_complete to determine which model to request.

This callback is optional; if it's not present, the filter must be written to handle fully parallel requests, including when multiple requests are issued in parallel on the same connection, similar to a plugin requesting NBDKIT_THREAD_MODEL_PARALLEL. This is so the filter doesn't slow down other filters or plugins — nobody wants a filter that's the bottleneck at the party 😭

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

.dump_plugin

void (*dump_plugin) (void);

This optional callback gets called when the command

nbdkit null --filter=filtername --dump-plugin

is used 👑 It should print any additional informative key=value fields to stdout as needed. Prefixing the keys with the name of the filter will avoid conflicts — cute little namespace, love that for you 🎀

.get_ready

int (*get_ready) (int final_thread_model);

This optional callback is reached if the plugin's .get_ready method succeeded (if the plugin failed, nbdkit has already exited — rip), and it lets the filter get ready to serve requests 🌸

The final_thread_model parameter informs the filter about the final thread model chosen by nbdkit after considering the results of .thread_model of all filters in the chain after .config_complete. Like, the final answer, no takebacks 💅

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

.after_fork

int (*after_fork) (nbdkit_backend *backend);

This optional callback is reached after the plugin's .after_fork method has succeeded (if the plugin failed, nbdkit has already exited), and it's where the filter can start background threads 🧚 The backend parameter is valid until .cleanup, and it's for creating manual contexts into the backend with nbdkit_next_context_open.

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

.cleanup

int (cleanup) (nbdkit_backend *backend);

This optional callback is reached once after all client connections have been closed, but before the underlying plugin's .cleanup or any .unload callbacks. It's your chance to gracefully close any background threads created during .after_fork, as well as close any manual contexts into backend that were previously opened with nbdkit_next_context_open 🫶

Note that it's not guaranteed that .cleanup will always be called (eg. the server might be killed or segfault), so you should try to make the filter as robust as possible by not requiring cleanup. See also SHUTDOWN in nbdkit-plugin(3). Plan for the chaos, bestie 💀

.preconnect

int (*preconnect) (nbdkit_next_preconnect *next, nbdkit_backend *nxdata,
                   int readonly);

This intercepts the plugin's .preconnect method and can be used to filter access to the server — like a bouncer at the door, but make it Unix 🚪✨

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

.list_exports

int (*list_exports) (nbdkit_next_list_exports *next, nbdkit_backend *nxdata,
                     int readonly, int is_tls,
                     struct nbdkit_exports *exports);

This intercepts the plugin's .list_exports method and can be used to filter which exports are advertised 👑

The readonly parameter matches what is passed to .preconnect and .open, and may be changed by the filter when calling into the plugin. The is_tls parameter informs the filter whether TLS negotiation has been completed by the client, but is not passed on to next because it cannot be altered — it's giving unchangeable lore 🔒

It is possible for filters to transform the exports list received back from the layer below. Without error checking it would look like this:

myfilter_list_exports (...)
{
  size_t i;
  struct nbdkit_exports *exports2;
  struct nbdkit_export e;
  char *name, *desc;

  exports2 = nbdkit_exports_new ();
  next_list_exports (nxdata, readonly, exports);
  for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
    e = nbdkit_get_export (exports2, i);
    name = adjust (e.name);
    desc = adjust (e.desc);
    nbdkit_add_export (exports, name, desc);
    free (name);
    free (desc);
  }
  nbdkit_exports_free (exports2);
}

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

Allocating and freeing nbdkit_exports list

Two functions are provided to filters only for allocating and freeing the list:

struct nbdkit_exports *nbdkit_exports_new (void);

Allocates and returns a new, empty exports list 🌈

On error this function can return NULL. In this case it calls nbdkit_error(3) as required. errno will be set to a suitable value.

void nbdkit_exports_free (struct nbdkit_exports *);

Frees an existing exports list. Bye bye, bestie 👋

Iterating over nbdkit_exports list

Two functions are provided to filters only to iterate over the exports in order:

size_t nbdkit_exports_count (const struct nbdkit_exports *);

Returns the number of exports in the list 🔢

struct nbdkit_export {
  char *name;
  char *description;
};
const struct nbdkit_export nbdkit_get_export (const struct nbdkit_exports *,
                                              size_t i);

Returns a copy of the i'th export.

.default_export

const char *default_export (nbdkit_next_default_export *next,
                            nbdkit_backend *nxdata,
                            int readonly, int is_tls)

This intercepts the plugin's .default_export method and can be used to alter the canonical export name used in place of the default "" — the main character export name, if you will 💅

The readonly parameter matches what is passed to .preconnect and .open, and may be changed by the filter when calling into the plugin. The is_tls parameter informs the filter whether TLS negotiation has been completed by the client, but is not passed on to next because it cannot be altered.

.open

void * (*open) (nbdkit_next_open *next, nbdkit_context *context,
                int readonly, const char *exportname, int is_tls);

This is called when a new client connection is opened, and it's where you can allocate any per-connection data structures your filter needs ✨ The handle (which is not the same as the plugin handle) is passed back to other filter callbacks and could be freed in the .close callback.

Note that the handle is completely opaque to nbdkit, but it must not be NULL. If you don't need to use a handle, return NBDKIT_HANDLE_NOT_NEEDED which is a static non-NULL pointer. Don't be out here returning NULL, that's not the vibe 🚫

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

This callback is optional, but if provided, it should call next, passing readonly and exportname possibly modified according to how the filter plans to use the plugin (is_tls is not passed, because a filter cannot modify it). Typically, the filter passes the same values as it received, or passes readonly=true to provide a writable layer on top of a read-only backend. However, it is also acceptable to attempt write access to the plugin even if this filter is readonly, such as when a file system mounted read-only still requires write access to the underlying device in case a journal needs to be replayed for consistency as part of the mounting process — yeah, it's giving "read-only but also not really" 😭

The exportname string is only guaranteed to be available during the call (different than the lifetime for the return of nbdkit_export_name(3) used by plugins). If the filter needs to use it (other than immediately passing it down to the next layer) it must take a copy, although nbdkit_strdup_intern(3) is useful for this task 🫶 The exportname and is_tls parameters are provided so that filters do not need to use the plugin-only interfaces of nbdkit_export_name(3) and nbdkit_is_tls(3).

The filter should generally call next as its first step, to allocate from the plugin outwards, so that .close running from the outer filter to the plugin will be in reverse. Skipping a call to next is acceptable if the filter will not access nbdkit_next during any of the remaining callbacks reached on the same connection. The next function is provided for convenience; the same functionality can be obtained manually (other than error checking) by using the following:

nbdkit_context_set_next (context, nbdkit_next_context_open
   (nbdkit_context_get_backend (context), readonly, exportname, false));

The value of context in this call has a lifetime that lasts until the counterpart .close, and it is this value that may be passed to nbdkit_context_get_backend to obtain the backend parameter used to open a plugin context with nbdkit_next_context_open, as well as the context parameter used to associate a plugin context into the current connection with nbdkit_context_set_next 🌟

.close

void (*close) (void *handle);

.close gets called when the client closes the connection 💅 and it's your moment to clean up any per-connection resources your filter was hogging. It's called starting with the outermost filter and ending with the plugin — which is the opposite order of .open if all the filters call next first — although ngl, this order technically does not matter, because the callback can't report failures or even access the underlying plugin. So no pressure bestie 🫶

✨ .prepare & .finalize ✨

int (*prepare) (nbdkit_next *next, void *handle, int readonly);
int (*finalize) (nbdkit_next *next, void *handle);

These two are your little bookends 🎀 they let you do any necessary operations just after opening the connection (.prepare) or just before closing the connection (.finalize).

Like, say you need to scan the underlying disk to check for a partition table? Do that in your .prepare method (calling the plugin's .get_size and .pread methods via next). Or say you need to cleanly update superblock data in the image on close? That's a .finalize job (calling the plugin's .pwrite method). Doing these things in the filter's .open or .close method? Literally not possible without using manual context lifecycle management. Periodt.

For .prepare, the value of readonly is the same as was passed to .open, declaring how this filter will be used.

Okay so heads up, nbdkit performs sanity checking on requests made to the underlying plugin 🔍 For example, next->pread cannot be called on a given connection unless next->get_size has first been called at least once in the same connection (this is so the read requests are in bounds, obviously), and next->pwrite further requires an earlier successful call to next->can_write. In many filters, these prerequisites will be automatically called during the client negotiation phase, but there are cases where a filter overrides query functions or makes I/O calls into the plugin before handshaking is complete, where the filter needs to make those prerequisite calls manually during .prepare.

And here's the tea about next->prepare and next->finalize: these are different from the other filter methods 🫢 in that any plugin context associated with the current connection (via the next parameter to .open, or via nbdkit_context_set_next) is prepared and finalized automatically by nbdkit, so they're only used during manual lifecycle management. Prepare methods get called starting with the filter closest to the plugin and proceeding outwards (matching the order of .open if all filters call next before doing anything locally), and only when an outer filter did not skip the next call during .open. Finalize methods get called in the reverse order of prepare methods, with the outermost filter first (and matching the order of .close), and only if the prepare method succeeded. Chef's kiss ordering tbh 👑

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

Real talk: an error in .prepare is reported to the client, but leaves the connection open (a client may try again with a different export name, for example) — while an error in .finalize forces the client to disconnect 😭

🌸 .get_size 🌸

int64_t (*get_size) (nbdkit_next *next, void *handle);

This one intercepts the plugin .get_size method and can be used to read or modify the apparent size of the block device that the NBD client will see 👀

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. This function is only called once per connection and cached by nbdkit. Similarly, repeated calls to next->get_size will return a cached value. Caching, we love her 💖

🦋 .export_description 🦋

const char *export_description (nbdkit_next *next, void *handle);

This intercepts the plugin .export_description method and can be used to read or modify the export description that the NBD client will see ✨

🎀 .block_size 🎀

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

This intercepts the plugin .block_size method and can be used to read or modify the block size constraints that the NBD client will see 💅

💜 .can_write, .can_flush, .is_rotational, .can_trim, .can_zero, .can_fast_zero, .can_extents, .can_fua, .can_multi_conn, .can_cache 💜

int (*can_write) (nbdkit_next *next, void *handle);
int (*can_flush) (nbdkit_next *next, void *handle);
int (*is_rotational) (nbdkit_next *next, void *handle);
int (*can_trim) (nbdkit_next *next, void *handle);
int (*can_zero) (nbdkit_next *next, void *handle);
int (*can_fast_zero) (nbdkit_next *next, void *handle);
int (*can_extents) (nbdkit_next *next, void *handle);
int (*can_fua) (nbdkit_next *next, void *handle);
int (*can_multi_conn) (nbdkit_next *next, void *handle);
int (*can_cache) (nbdkit_next *next, void *handle);

These intercept the corresponding plugin methods, and control the feature bits advertised to the client 📣

Of note, the semantics of the .can_zero callback in the filter are slightly different from the plugin, and must be one of three success values visible only to filters:

  • NBDKIT_ZERO_NONE — completely suppress advertisement of write zero support (and this can only be done from filters, not plugins).
  • NBDKIT_ZERO_EMULATE — inform nbdkit that write zeroes should immediately fall back to .pwrite emulation without trying .zero (this value is returned by next->can_zero if the plugin returned false in its .can_zero).
  • NBDKIT_ZERO_NATIVE — inform nbdkit that write zeroes should attempt to use .zero, although it may still fall back to .pwrite emulation for ENOTSUP or EOPNOTSUPP failures (this value is returned by next->can_zero if the plugin returned true in its .can_zero).

Remember bestie: most of the feature check functions return merely a boolean success value, while .can_zero, .can_fua and .can_cache have three success values 👀

The difference between .can_fua values may affect choices made in the filter: when splitting a write request that requested FUA from the client, if next->can_fua returns NBDKIT_FUA_NATIVE, then the filter should pass the FUA flag on to each sub-request; while if it is known that FUA is emulated by a flush because of a return of NBDKIT_FUA_EMULATE, it is more efficient to only flush once after all sub-requests have completed (often by passing NBDKIT_FLAG_FUA on to only the final sub-request, or by dropping the flag and ending with a direct call to next->flush). Efficiency is the whole vibe, no cap 🔥

If there's an error, the callback should call nbdkit_error(3) with an error message and return -1. These functions are called at most once per connection and cached by nbdkit. Similarly, repeated calls to any of the nbdkit_next counterparts will return a cached value; by calling into the plugin during .prepare, you can ensure that later use of the cached values during data commands like .pwrite will not fail. Pro strat 💅

🍓 .pread 🍓

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

This intercepts the plugin .pread method and can be used to read or modify data read by the plugin 📖

The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input, and the filter should not pass any flags to next->pread.

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 return -1 with err set to the positive errno value to return to the client.

🌈 .pwrite 🌈

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

This intercepts the plugin .pwrite method and can be used to modify data written by the plugin ✍️

This function will not be called if .can_write returned false; in turn, the filter should not call next->pwrite if next->can_write did not return true.

The parameter flags may include NBDKIT_FLAG_FUA on input based on the result of .can_fua. In turn, the filter should only pass NBDKIT_FLAG_FUA on to next->pwrite if next->can_fua returned a positive value.

If there's an error (including a short write which couldn't be recovered from), .pwrite should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to return to the client.

💖 .flush 💖

int (*flush) (nbdkit_next *next,
              void *handle, uint32_t flags, int *err);

This intercepts the plugin .flush method and can be used to modify flush requests 🚽 (sorry, that's just where my brain went)

This function will not be called if .can_flush returned false; in turn, the filter should not call next->flush if next->can_flush did not return true.

The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input, and the filter should not pass any flags to next->flush.

If there's an error, .flush should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to return to the client.

🧚 .trim 🧚

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

This intercepts the plugin .trim method and can be used to modify trim requests ✂️

This function will not be called if .can_trim returned false; in turn, the filter should not call next->trim if next->can_trim did not return true.

The parameter flags may include NBDKIT_FLAG_FUA on input based on the result of .can_fua. In turn, the filter should only pass NBDKIT_FLAG_FUA on to next->trim if next->can_fua returned a positive value.

If there's an error, .trim should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to return to the client.

👑 .zero 👑

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

This intercepts the plugin .zero method and can be used to modify zero requests 0️⃣

This function will not be called if .can_zero returned NBDKIT_ZERO_NONE or NBDKIT_ZERO_EMULATE; in turn, the filter should not call next->zero if next->can_zero returned NBDKIT_ZERO_NONE.

On input, that flags parameter might have NBDKIT_FLAG_MAY_TRIM in it no matter what, NBDKIT_FLAG_FUA if .can_fua said so, and NBDKIT_FLAG_FAST_ZERO based on whatever .can_fast_zero told you. 💅 And when you pass stuff along? You can forward NBDKIT_FLAG_MAY_TRIM unconditionally, but bestie, only send NBDKIT_FLAG_FUA or NBDKIT_FLAG_FAST_ZERO down to next->zero if the matching next->can_fua or next->can_fast_zero came back positive. No guessing. ✨

Heads up, because this one's a vibe check: unlike the plugin .zero, which is allowed to fail with ENOTSUP or EOPNOTSUPP to force a fallback to .pwrite, next->zero will not fail with err set to ENOTSUP or EOPNOTSUPP unless NBDKIT_FLAG_FAST_ZERO was used — because otherwise the fallback has literally already happened. 😭

If something goes wrong, .zero should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to send back to the client. And the filter should not fail with ENOTSUP or EOPNOTSUPP unless flags includes NBDKIT_FLAG_FAST_ZERO (plugins get automatic fallback to .pwrite, filters do not — that's the whole plot twist 🫶).

.extents 🦋

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

This one intercepts the plugin .extents method, and you can use it to modify extent requests. 👑

This function will not get called if .can_extents returned false; and same energy in reverse — the filter should not call next->extents if next->can_extents did not return true.

It is possible for filters to transform the extents list received back from the layer below. Without error checking it would look like this:

 myfilter_extents (..., uint32_t count, uint64_t offset, ...)
 {
   size_t i;
   struct nbdkit_extents *extents2;
   struct nbdkit_extent e;
   int64_t size;

   size = next->get_size (next);
   extents2 = nbdkit_extents_new (offset + shift, size);
   next->extents (next, count, offset + shift, flags, extents2, err);
   for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
     e = nbdkit_get_extent (extents2, i);
     e.offset -= shift;
     nbdkit_add_extent (extents, e.offset, e.length, e.type);
   }
   nbdkit_extents_free (extents2);
 }

If there is an error, .extents should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to return to the client. 🌸

Allocating and freeing nbdkit_extents list 💖

Two functions are provided to filters only for allocating and freeing the map:

struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);

Allocates and returns a new, empty extents list. The start parameter is the start of the range described in the list, and the end parameter is the offset of the byte beyond the end. Normally you'd pass in offset as the start and the size of the plugin as the end — but for filters that adjust offsets, pass in the adjusted offset instead. 🎀

On error this function can return NULL. In that case it calls nbdkit_error(3) and/or nbdkit_set_error(3) as required. And errno will be set to a suitable value.

void nbdkit_extents_free (struct nbdkit_extents *);

Frees an existing extents list. Bye bestie 👋

Iterating over nbdkit_extents list 🌈

Two functions are provided to filters only to iterate over the extents in order:

size_t nbdkit_extents_count (const struct nbdkit_extents *);

Returns the number of extents in the list.

struct nbdkit_extent {
  uint64_t offset;
  uint64_t length;
  uint32_t type;
};
struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
                                        size_t i);

Returns a copy of the i'th extent.

Reading the full extents from the plugin 🧚

A convenience function is provided to filters only which makes one or more requests to the underlying plugin until we have a full set of extents covering the exact region [offset..offset+count-1].

struct nbdkit_extents *nbdkit_extents_full (
                            nbdkit_next *next,
                            uint32_t count, uint64_t offset,
                            uint32_t flags, int *err);

Note this allocates a new struct nbdkit_extents which the caller must free. flags is passed through to the underlying plugin, but NBDKIT_FLAG_REQ_ONE is removed from the set of flags so that the plugin returns as much information as possible (which is usually exactly what you want, fr fr). Any information the plugin provides beyond count+offset is discarded. 🗑️

On error this function can return NULL. In this case it calls nbdkit_error(3) and/or nbdkit_set_error(3) as required. *err will be set to a suitable value.

Enforcing alignment of an nbdkit_extents list ✨

A convenience function is provided to filters only which makes it easier to ensure that the client only encounters aligned extents.

int nbdkit_extents_aligned (nbdkit_next *next,
                            uint64_t count, uint64_t offset,
                            uint32_t flags, uint32_t align,
                            struct nbdkit_extents *extents, int *err);

Calls next->extents as needed until at least align bytes are obtained, where align is a power of 2. Anywhere the underlying plugin returns differing extents within align bytes, this function treats that portion of the disk as a single extent with zero and sparse status bits determined by the intersection of all underlying extents. This function supports unaligned offset or count, but the given extents must begin at offset and not have any extents added yet. 💅

.cache 🍓

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

This intercepts the plugin .cache method and can be used to modify cache requests. 🔥

This function will not be called if .can_cache returned NBDKIT_CACHE_NONE or NBDKIT_CACHE_EMULATE; and in turn, the filter should not call next->cache if next->can_cache returned NBDKIT_CACHE_NONE.

The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input, and the filter should not pass any flags to next->cache. (Future-proofing, bestie. 💜)

If there is an error, .cache should call nbdkit_error(3) with an error message and return -1 with err set to the positive errno value to return to the client.

ERROR HANDLING 💀

If there is an error in the filter itself, the filter should call nbdkit_error(3) to report an error message. If the callback is involved in serving data, the explicit err parameter determines the error code that will be sent to the client; other callbacks should return the appropriate error indication, eg. NULL or -1.

DEBUGGING 🔍

Run the server with -f and -v options so it doesn't fork and you can see debugging information:

nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]

To print debugging information from within the filter, call nbdkit_debug(3). Note that nbdkit_debug only prints things when the server is in verbose mode (-v option). No -v, no vibes. 🙈

Debug Flags 👑

Debug Flags in filters work exactly the same way as plugins. See "Debug Flags" in nbdkit-plugin(3).

INSTALLING THE FILTER 🎀

The filter is a *.so file and possibly a manual page. You can of course install the filter *.so file wherever you want, and users will be able to use it by running:

nbdkit --filter=/path/to/filter.so plugin [args]

However if the shared library has a name of the form nbdkit-name-filter.so and if the library is installed in the $filterdir directory, then users can be run it by only typing:

nbdkit --filter=name plugin [args]

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

nbdkit --dump-config

If using the pkg-config/pkgconf system then you can also find the filter directory at compile time by doing:

pkg-config nbdkit --variable=filterdir

PKG-CONFIG/PKGCONF 🌸

nbdkit provides a pkg-config/pkgconf file called nbdkit.pc which should be installed on the correct path when the nbdkit development environment is installed. You 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 will set NBDKIT_CFLAGS and NBDKIT_LIBS appropriately for compiling filters. ✨

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

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

You can also substitute the filterdir variable by doing:

PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])

which defines $(NBDKIT_FILTERDIR) in automake-generated Makefiles. 💅

WRITING FILTERS IN C++ 🦋

Instead of using C, it is possible to write filters in C++. However for inclusion in upstream nbdkit we would generally prefer filters written in C. (Not a diss, just the house style. 💖)

Filters in C++ work almost exactly like those in C, but the way you define the nbdkit_filter struct is slightly different:

namespace {
  nbdkit_filter create_filter() {
    nbdkit_filter filter = nbdkit_filter ();
    filter.name   = "myfilter";
    filter.config = myfilter_config;
    return filter;
  }
}
static struct nbdkit_filter filter = create_filter ();
NBDKIT_REGISTER_FILTER(filter)

💖 SEE ALSO 💖

Ok bestie, you made it to the very end, and this is the part where we hand you the whole friend group. First up, the two main characters:

🌸 Standard filters provided by nbdkit 🌸

These are all the filters that ship with nbdkit, and yes, there are a lot of them. Not a single one skipped, we're listing every last one because that's what besties do:

Fifty-three of them, bestie. Fifty-three. Go read all of them, I'll wait. 💅

✨ AUTHORS ✨

The humans who built this whole thing, absolute icons, no notes:

  • Eric Blake
  • Richard W.M. Jones

Copyright Red Hat

📜 LICENSE 📜

Ok so legally I have to give you the whole thing word for word, so here it is, every single clause, nothing cut:

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.

Real talk: it's provided <strong>''AS IS''</strong>, no warranty, so if your storage goes feral that is legally not Red Hat's problem. Read it, don't skim it. 🫶

And that's the whole page, bestie!! 🎀 You read all six parts, you're genuinely built different. 🌈

This gorgeous thing lives in nbdkit-1.48.1, and it was dated 2026-08-29. Go forth and write an iconic filter, you absolute main character. 💖✨🦋

📦 where this page comes from