Provided by: nbdkit-plugin-dev_1.32.5-1ubuntu2_amd64 
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.
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.
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.
"#include <nbdkit-filter.h>"
All filters should start by including this header file.
"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
nbdkit-filter.h defines some function types ("nbdkit_next_config",
"nbdkit_next_config_complete", "nbdkit_next_preconnect", "nbdkit_next_list_exports",
"nbdkit_next_default_export", "nbdkit_next_open") and a structure called "struct
nbdkit_next_ops". These abstract the next plugin or filter in the chain. There is also
an opaque pointer "backend", "context" or "nxdata" which must be passed along when calling
these functions. The value of "backend" is stable between ".after_fork", ".preconnect",
".list_exports", and ".default_export", and can also be obtained by using
"nbdkit_context_get_backend" on the "context" parameter to ".open".
Meanwhile, if the filter does not use "nbdkit_context_set_next", the value of "next"
passed to ".prepare" has a stable lifetime that lasts to the corresponding ".finalize",
with all intermediate functions (such as ".pread") receiving the same value for
convenience. Functions where "nxdata" is not reused are ".config", ".config_complete",
and ".get_ready", which are all called during initialization outside any connections. The
value of "backend" passed to ".after_fork" also occurs without connections, but is shared
with ".preconnect", ".list_exports", and ".default_export", and can also be obtained from
the "context" passed to ".open", and has 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".
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").
The filter’s ".close" method is called when an old connection closed, and this has no
"next" parameter because it cannot be short-circuited.
"nbdkit_next"
The filter generally needs to call into the underlying plugin, which is done via a pointer
to "struct nbdkit_next_ops", also available 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 will be 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 using automatic registration, the "next" parameter is stable between
".prepare" and ".finalize", and nbdkit automatically prepares, finalizes, and closes the
next context at the right point in the filter connection lifecycle.
Alternatively, the filter can manage plugin contexts manually, whether to multiplex
multiple client connections through a single context into the plugin, or to open multiple
plugin contexts to perform 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, where 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.
"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".
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". The filter should be careful to not violate any threading
model restrictions of the plugin if it opens more than one context.
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()
will depend solely whether --tls=require was on the command line, the lifetime of interned
strings (via "nbdkit_strdup_intern" 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.
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.
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.
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.
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.
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" or setting "errno"), whereas "next->pread" exposes this via an explicit
parameter, allowing a filter to learn or modify this error if desired.
Use of "next->prepare" and "next->finalize" is only needed when manually managing the
plugin context lifetime.
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" helpful for avoiding a
memory leak while still obeying lifecycle constraints.
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.
CALLBACKS
"struct nbdkit_filter" has some static fields describing the filter and optional callback
functions which can be used to intercept plugin methods.
".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.
".longname"
const char *longname;
An optional free text name of the filter. This field is used in error messages.
".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.
".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).
".config"
int (*config) (nbdkit_next_config *next, void *nxdata,
const char *key, const char *value);
This intercepts the plugin ".config" method and can be used by the filter to parse its own
command line parameters. You should try to make sure that command line parameter keys
that the filter uses do not conflict with ones that could be used by a plugin.
If there is an error, ".config" should call "nbdkit_error" with an error message and
return "-1".
".config_complete"
int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
This intercepts the plugin ".config_complete" method and can be used to ensure that all
parameters needed by the filter were supplied on the command line.
If there is an error, ".config_complete" should call "nbdkit_error" 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".
If the filter doesn't take any config parameters you should probably omit this.
".thread_model"
int (*thread_model) (void);
Filters may tighten (but not relax) the thread model of the plugin, by defining this
callback. Note that while plugins use a compile-time definition of "THREAD_MODEL",
filters do not need to declare a model at compile time; instead, this callback is called
after ".config_complete" and before any connections are created. See "THREADS" in
nbdkit-plugin(3) for a discussion of thread models.
The final thread model used by nbdkit is the smallest (ie. most serialized) out of all the
filters and the plugin, and applies for all connections. Requests for a model larger than
permitted by the plugin are silently ignored. It is acceptable for decisions made during
".config" and ".config_complete" to determine which model to request.
This callback is optional; if it is 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
ensures the filter doesn't slow down other filters or plugins.
If there is an error, ".thread_model" should call "nbdkit_error" with an error message and
return "-1".
".get_ready"
int (*get_ready) (int thread_model);
This optional callback is reached if the plugin ".get_ready" method succeeded (if the
plugin failed, nbdkit has already exited), and can be used by the filter to get ready to
serve requests.
The "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".
If there is an error, ".get_ready" should call "nbdkit_error" with an error message and
return "-1".
".after_fork"
int (*after_fork) (nbdkit_backend *backend);
This optional callback is reached after the plugin ".after_fork" method has succeeded (if
the plugin failed, nbdkit has already exited), and can be used by the filter to start
background threads. The "backend" parameter is valid until ".cleanup", for creating
manual contexts into the backend with "nbdkit_next_context_open".
If there is an error, ".after_fork" should call "nbdkit_error" 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 ".cleanup" or any ".unload" callbacks. It can be used by the
filter to gracefully close any background threads created during ".after_fork", as well as
close any manual contexts into "backend" 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).
".preconnect"
int (*preconnect) (nbdkit_next_preconnect *next, nbdkit_backend *nxdata,
int readonly);
This intercepts the plugin ".preconnect" method and can be used to filter access to the
server.
If there is an error, ".preconnect" should call "nbdkit_error" 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 ".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 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 is an error, ".list_exports" should call "nbdkit_error" 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" as
required. "errno" will be set to a suitable value.
void nbdkit_exports_free (struct nbdkit_exports *);
Frees an existing exports list.
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 ".default_export" method and can be used to alter the canonical
export name used in place of the default "".
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 can be used to allocate any per-
connection data structures needed by the filter. 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.
If there is an error, ".open" should call "nbdkit_error" 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.
The "exportname" string is only guaranteed to be available during the call (different than
the lifetime for the return of "nbdkit_export_name" 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" 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" and "nbdkit_is_tls".
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);
This is called when the client closes the connection. It should clean up any per-
connection resources used by the filter. It is called beginning with the outermost filter
and ending with the plugin (the opposite order of ".open" if all filters call "next"
first), although this order technically does not matter since the callback cannot report
failures or access the underlying plugin.
".prepare"
".finalize"
int (*prepare) (nbdkit_next *next, void *handle, int readonly);
int (*finalize) (nbdkit_next *next, void *handle);
These two methods can be used to perform any necessary operations just after opening the
connection (".prepare") or just before closing the connection (".finalize").
For example if you need to scan the underlying disk to check for a partition table, you
could do it in your ".prepare" method (calling the plugin's ".get_size" and ".pread"
methods via "next"). Or if you need to cleanly update superblock data in the image on
close you can do it in your ".finalize" method (calling the plugin's ".pwrite" method).
Doing these things in the filter's ".open" or ".close" method is not possible without
using manual context lifecycle management.
For ".prepare", the value of "readonly" is the same as was passed to ".open", declaring
how this filter will be used.
Note that 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 (to ensure the read requests are in
bounds), 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".
While there are "next->prepare" and "next->finalize" functions, these are different from
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 are only used during manual lifecycle
management. Prepare methods are 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 are 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.
If there is an error, both callbacks should call "nbdkit_error" with an error message and
return "-1". 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 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 is an error, ".get_size" should call
"nbdkit_error" 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.
".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 feature bits advertised to
the client.
Of note, the semantics of ".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 (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 that 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").
If there is an error, the callback should call "nbdkit_error" 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.
".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 is an error (including a short read which couldn't be recovered from), ".pread"
should call "nbdkit_error" 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 is an error (including a short write which couldn't be recovered from), ".pwrite"
should call "nbdkit_error" 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.
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 is an error, ".flush" should call "nbdkit_error" 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 is an error, ".trim" should call "nbdkit_error" 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.
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, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM" unconditionally,
"NBDKIT_FLAG_FUA" based on the result of ".can_fua", and "NBDKIT_FLAG_FAST_ZERO" based on
the result of ".can_fast_zero". In turn, the filter may pass "NBDKIT_FLAG_MAY_TRIM"
unconditionally, but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
"next->zero" if the corresponding "next->can_fua" or "next->can_fast_zero" returned a
positive value.
Note that unlike the plugin ".zero" which is permitted to fail with "ENOTSUP" or
"EOPNOTSUPP" to force a fallback to ".pwrite", the function "next->zero" will not fail
with "err" set to "ENOTSUP" or "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used,
because otherwise the fallback has already taken place.
If there is an error, ".zero" should call "nbdkit_error" with an error message and return
-1 with "err" set to the positive errno value to return to the client. The filter should
not fail with "ENOTSUP" or "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO"
(while plugins have automatic fallback to ".pwrite", filters do not).
".extents"
int (*extents) (nbdkit_next *next,
void *handle, uint32_t count, uint64_t offset, uint32_t flags,
struct nbdkit_extents *extents,
int *err);
This intercepts the plugin ".extents" method and can be used to modify extent requests.
This function will not be called if ".can_extents" returned false; in turn, 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" 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 would pass in "offset" as the start and the size of the plugin as
the end, but for filters which adjust offsets, they should pass in the adjusted offset.
On error this function can return "NULL". In this case it calls "nbdkit_error" and/or
"nbdkit_set_error" as required. "errno" will be set to a suitable value.
void nbdkit_extents_free (struct nbdkit_extents *);
Frees an existing extents list.
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 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 (this is usually what
you want).
On error this function can return "NULL". In this case it calls "nbdkit_error" and/or
"nbdkit_set_error" 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,
uint32_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. It is an
error to call this function with "count" or "offset" that is not already aligned.
".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"; 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".
If there is an error, ".cache" should call "nbdkit_error" 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" 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".
"nbdkit_error" has the following prototype and works like printf(3):
void nbdkit_error (const char *fs, ...);
void nbdkit_verror (const char *fs, va_list args);
For convenience, "nbdkit_error" preserves the value of "errno", and also supports the
glibc extension of a single %m in a format string expanding to "strerror(errno)", even on
platforms that don't support that natively.
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", which has the
following prototype and works like printf(3):
void nbdkit_debug (const char *fs, ...);
void nbdkit_vdebug (const char *fs, va_list args);
For convenience, "nbdkit_debug" preserves the value of "errno", and also supports the
glibc extension of a single %m in a format string expanding to "strerror(errno)", even on
platforms that don't support that natively. Note that "nbdkit_debug" only prints things
when the server is in verbose mode (-v option).
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.
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
nbdkit(1), nbdkit-plugin(3).
Standard filters provided by nbdkit:
nbdkit-blocksize-filter(1), nbdkit-blocksize-policy-filter(1), nbdkit-cache-filter(1),
nbdkit-cacheextents-filter(1), nbdkit-checkwrite-filter(1), nbdkit-cow-filter(1),
nbdkit-ddrescue-filter(1), nbdkit-delay-filter(1), nbdkit-error-filter(1),
nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1), nbdkit-exportname-filter(1),
nbdkit-ext2-filter(1), nbdkit-extentlist-filter(1), nbdkit-fua-filter(1),
nbdkit-gzip-filter(1), nbdkit-ip-filter(1), nbdkit-limit-filter(1), nbdkit-log-filter(1),
nbdkit-luks-filter(1), nbdkit-multi-conn-filter(1), nbdkit-nocache-filter(1),
nbdkit-noextents-filter(1), nbdkit-nofilter-filter(1), nbdkit-noparallel-filter(1),
nbdkit-nozero-filter(1), nbdkit-offset-filter(1), nbdkit-partition-filter(1),
nbdkit-pause-filter(1), nbdkit-protect-filter(1), nbdkit-rate-filter(1),
nbdkit-readahead-filter(1), nbdkit-retry-filter(1), nbdkit-retry-request-filter(1),
nbdkit-scan-filter(1), nbdkit-stats-filter(1), nbdkit-swab-filter(1),
nbdkit-tar-filter(1), nbdkit-tls-fallback-filter(1), nbdkit-truncate-filter(1),
nbdkit-xz-filter(1) .
AUTHORS
Eric Blake
Richard W.M. Jones
COPYRIGHT
Copyright (C) 2013-2020 Red Hat Inc.
LICENSE
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.