"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(3) 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(3) with an error message and return -1.
".config_help"
const char *config_help;
This optional multi-line help message should summarize any "key=value" parameters that it takes. It does
not need to repeat what already appears in ".description".
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.
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(3) with an error message and return -1.
".dump_plugin"
void (*dump_plugin) (void);
This optional callback is called when the "nbdkit null --filter=filtername --dump-plugin" command is
used. It should print any additional informative "key=value" fields to stdout as needed. Prefixing the
keys with the name of the filter will avoid conflicts.
".get_ready"
int (*get_ready) (int final_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 "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".
If there is 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 ".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(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 ".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(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 ".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(3) with an error message and return -1.
Allocatingandfreeingnbdkit_exportslist
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.
Iteratingovernbdkit_exportslist
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(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.
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);
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(3) 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(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.
".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(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.
".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(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 is 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.
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(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 is 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.
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(3) 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(3) with an error message and return -1 with
"err" set to the positive errno value to return to the client.
Allocatingandfreeingnbdkit_extentslist
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(3) and/or
nbdkit_set_error(3) as required. "errno" will be set to a suitable value.
void nbdkit_extents_free (struct nbdkit_extents *);
Frees an existing extents list.
Iteratingovernbdkit_extentslist
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.
Readingthefullextentsfromtheplugin
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(3) and/or
nbdkit_set_error(3) as required. *err will be set to a suitable value.
Enforcingalignmentofannbdkit_extentslist
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(3) with an error message and return -1 with "err"
set to the positive errno value to return to the client.
Install Now
PNG Icons
