Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
751 lines (545 sloc) 26.3 KB

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://github.com/libguestfs/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 three function types (nbdkit_next_config, nbdkit_next_config_complete, 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 nxdata which must be passed along when calling these functions.

The filter’s .config, .config_complete and .open methods may only call the next .config, .config_complete and .open method in the chain (optionally for .config).

The filter’s .close method is called when an old connection closed, and this has no next parameter because it cannot be short-circuited.

The filter’s other methods like .prepare, .get_size, .pread etc ― always called in the context of a connection ― are passed a pointer to struct nbdkit_next_ops which contains a comparable set of accessors to plugin methods that can be called during a connection. It is possible for a filter to issue (for example) extra read calls in response to a single .pwrite call. 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_ops->pread exposes this via an explicit parameter, allowing a filter to learn or modify this error if desired.

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.

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.

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 and be unique amongst all filters.

.version

const char *version;

Filters may optionally set a version string which is displayed in help and debugging output.

.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.

.open

void * (*open) (nbdkit_next_open *next, void *nxdata,
                int readonly);

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.

.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.

.prepare

.finalize

int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
                void *handle);
int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
                 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 .pread method via next_ops). 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.

There is no next_ops->prepare or next_ops->finalize. Unlike other filter methods, prepare and finalize are not chained through the next_ops structure. Instead the core nbdkit server calls the prepare and finalize methods of all filters. Prepare methods are called starting with the filter closest to the plugin and proceeding outwards. Finalize methods are called in the reverse order of prepare methods.

If there is an error, both callbacks should call nbdkit_error with an error message and return -1.

.get_size

int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
                     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. If this function is called more than once for the same connection, it should return the same value; similarly, the filter may cache next_ops->get_size for a given connection rather than repeating calls.

.can_write

.can_flush

.is_rotational

.can_trim

.can_zero

.can_extents

.can_fua

.can_multi_conn

.can_cache

int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
                  void *handle);
int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
                  void *handle);
int (*is_rotational) (struct nbdkit_next_ops *next_ops,
                      void *nxdata,
                      void *handle);
int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
                 void *handle);
int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
                 void *handle);
int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
                    void *handle);
int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
                void *handle);
int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
                       void *handle);
int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
                  void *handle);

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

Of note, the .can_zero callback in the filter controls whether the server advertises zero support to the client, which is slightly different semantics than the plugin; that is, next_ops->can_zero always returns true for a plugin, even when the plugin's own .can_zero callback returned false, because nbdkit implements a fallback to .pwrite at the plugin layer.

Remember that most of the feature check functions return merely a boolean success value, while .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_ops->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_ops->flush).

If there is an error, the callback should call nbdkit_error with an error message and return -1. If these functions are called more than once for the same connection, they should return the same value; similarly, the filter may cache the results of each counterpart in next_ops for a given connection rather than repeating calls.

.pread

int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
              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_ops->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) (struct nbdkit_next_ops *next_ops, void *nxdata,
               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_ops->pwrite if next_ops->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_ops->pwrite if next_ops->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) (struct nbdkit_next_ops *next_ops, void *nxdata,
              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_ops->flush if next_ops->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_ops->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) (struct nbdkit_next_ops *next_ops, void *nxdata,
             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_ops->trim if next_ops->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_ops->trim if next_ops->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) (struct nbdkit_next_ops *next_ops, void *nxdata,
             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 false; in turn, the filter should not call next_ops->zero if next_ops->can_zero did not return true.

On input, the parameter flags may include NBDKIT_FLAG_MAY_TRIM unconditionally, and NBDKIT_FLAG_FUA based on the result of .can_fua. In turn, the filter may pass NBDKIT_FLAG_MAY_TRIM unconditionally, but should only pass NBDKIT_FLAG_FUA on to next_ops->zero if next_ops->can_fua returned a positive value.

Note that unlike the plugin .zero which is permitted to fail with EOPNOTSUPP to force a fallback to .pwrite, the function next_ops->zero will never fail with err set to EOPNOTSUPP because 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 never fail with EOPNOTSUPP (while plugins have automatic fallback to .pwrite, filters do not).

.extents

int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
                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_ops->extents if next_ops->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_ops->get_size (nxdata);
  extents2 = nbdkit_extents_new (offset + shift, size - shift);
  next_ops->extents (nxdata, 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.

.cache

int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
              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_ops->cache unless next_ops->can_cache returned NBDKIT_CACHE_NATIVE.

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_ops->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:

pkgconf 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 ! pkgconf 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.

SEE ALSO

nbdkit(1), nbdkit-plugin(3).

Standard filters provided by nbdkit:

__FILTER_LINKS__.

AUTHORS

Eric Blake

Richard W.M. Jones

COPYRIGHT

Copyright (C) 2013-2019 Red Hat Inc.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 50:

Non-ASCII character seen before =encoding in '┌─────────┐'. Assuming UTF-8

You can’t perform that action at this time.