plugins: Expose new FUA callbacks

[nbdkit/ericb.git] / docs / nbdkit-filter.pod

=encoding utf8

=head1 NAME

nbdkit-filter - How to write nbdkit filters

=head1 SYNOPSIS

 #include <nbdkit-filter.h>
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
 
 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 I<-fv> options:

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

=head1 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 L<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 C<.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 C<next (nxdata, ...)> calls the C<.config> method of the
next filter or plugin in the chain.  In the example above any
instances of C<myparameter=...> on the command line would not be seen
by the plugin.

To see example filters, take a look at the source of nbdkit, in the
C<filters> directory.

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.

=head1 C<nbdkit-filter.h>

All filters should start by including this header file:

 #include <nbdkit-filter.h>

=head1 C<#define THREAD_MODEL>

All filters must define a thread model.  See
L<nbdkit-plugin(3)/THREADS> for a discussion of thread models.

The final thread model is the smallest (ie. most serialized) out of
all the filters and the plugin.  Filters cannot alter the thread model
to make it larger (more parallel).

If possible filters should be be written to handle fully parallel
requests (C<NBDKIT_THREAD_MODEL_PARALLEL>, even multiple requests
issued in parallel on the same connection).  This ensures that they
don't slow down other filters or plugins.

=head1 C<struct nbdkit_filter>

All filters must define and register one C<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 C<.name> field is the name of the filter.  This is the only field
which is required.

=head1 NEXT PLUGIN

F<nbdkit-filter.h> defines three function types
(C<nbdkit_next_config>, C<nbdkit_next_config_complete>,
C<nbdkit_next_open>) and a structure called C<struct nbdkit_next_ops>.
These abstract the next plugin or filter in the chain.  There is also
an opaque pointer C<nxdata> which must be passed along when calling
these functions.

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

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

The filter’s other methods like C<.prepare>, C<.get_size>, C<.pread>
etc ― always called in the context of a connection ― are passed a
pointer to C<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 C<.pwrite> call.  Note that the semantics of the
functions in C<struct nbdkit_next_ops> are slightly different from
what a plugin implements: for example, when a plugin's C<.pread>
returns -1 on error, the error value to advertise to the client is
implicit (via the plugin calling C<nbdkit_set_error> or setting
C<errno>), whereas C<next_ops-E<gt>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 C<next> function.  However
be careful when modifying strings because for some methods
(eg. C<.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 C<next> function then the corresponding method in the
plugin will never be called.  In particular, your C<.open> method, if
you have one, B<must> call the C<.next> method.

=head1 CALLBACKS

C<struct nbdkit_filter> has some static fields describing the filter
and optional callback functions which can be used to intercept plugin
methods.

=head2 C<.name>

 const char *name;

This field (a string) is required, and B<must> contain only ASCII
alphanumeric characters and be unique amongst all filters.

=head2 C<.version>

 const char *version;

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

=head2 C<.longname>

 const char *longname;

An optional free text name of the filter.  This field is used in error
messages.

=head2 C<.description>

 const char *description;

An optional multi-line description of the filter.

=head2 C<.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.

=head2 C<.unload>

 void unload (void);

This may be called once just before the filter is unloaded from
memory.  Note that it's not guaranteed that C<.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 L<nbdkit-plugin(3)/SHUTDOWN>.

=head2 C<.config>

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

This intercepts the plugin C<.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, C<.config> should call C<nbdkit_error> with an
error message and return C<-1>.

=head2 C<.config_complete>

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

This intercepts the plugin C<.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, C<.config_complete> should call C<nbdkit_error>
with an error message and return C<-1>.

=head2 C<.config_help>

 const char *config_help;

This optional multi-line help message should summarize any
C<key=value> parameters that it takes.  It does I<not> need to repeat
what already appears in C<.description>.

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

=head2 C<.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 C<.close>
callback.

Note that the handle is completely opaque to nbdkit, but it must not
be NULL.

If there is an error, C<.open> should call C<nbdkit_error> with an
error message and return C<NULL>.

=head2 C<.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.

=head2 C<.prepare>

=head2 C<.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 (C<.prepare>) or just before closing the
connection (C<.finalize>).

For example if you need to scan the underlying disk to check for a
partition table, you could do it in your C<.prepare> method (calling
the plugin's C<.pread> method via C<next_ops>).  Or if you need to
cleanly update superblock data in the image on close you can do it in
your C<.finalize> method (calling the plugin's C<.pwrite> method).
Doing these things in the filter's C<.open> or C<.close> method is not
possible.

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

=head2 C<.get_size>

 int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
                      void *handle);

This intercepts the plugin C<.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 E<ge> 0.  If there is an error, C<.get_size>
should call C<nbdkit_error> with an error message and return C<-1>.
If this function is called more than once for the same connection, it
should return the same value; similarly, the filter may cache
C<next_ops-E<gt>get_size> for a given connection rather than repeating
calls.

=head2 C<.can_write>

=head2 C<.can_flush>

=head2 C<.is_rotational>

=head2 C<.can_trim>

 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);

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

If there is an error, the callback should call C<nbdkit_error> with an
error message and return C<-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
C<next_ops> for a given connection rather than repeating calls.

=head2 C<.can_zero>

 int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
                  void *handle);

This controls whether write zero support will be advertised to the
client.  This function has no counterpart in plugins, because nbdkit
can always emulate zero by using pwrite; but a filter may want to
force different handling than the nbdkit implementation.  If this
callback is omitted, the default returned for the plugin layer is
true.

If there is an error, the callback should call C<nbdkit_error> with an
error message and return C<-1>.  Like the other initial queries
documented above, per-connection caching the of return value of this
function is allowed.

=head2 C<.can_fua>

 int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
                 void *handle);

This controls how the Forced Unit Access flag will be handled; it is
only relevant for connections that are not read-only.  This intercepts
the corresponding plugin method, to control feature bits advertised to
the client.  Unlike other feature functions with just two success
states, this one returns three success values: C<NBDKIT_FUA_NONE> to
avoid advertising FUA support to the client, C<NBDKIT_FUA_EMULATE> if
FUA is emulated by nbdkit calling flush after a write transaction, and
C<NBDKIT_FUA_NATIVE> if FUA semantics are handled by the plugin
without the overhead of an extra flush from nbdkit.

The difference between the two non-zero values may affect choices made
in the filter: when splitting a write request that requested FUA from
the client, native support should pass the FUA flag on to each
sub-request; while if it is known that FUA is emulated by a flush, it
is more efficient to only flush once after all sub-requests have
completed (often by passing C<NBDKIT_FLAG_FUA> on to only the final
sub-request, or by dropping the flag and ending with a direct call to
C<next_ops-E<gt>flush>).

If this callback is omitted, the default returned for the plugin layer
is C<NBDKIT_FUA_EMULATE> if C<can_flush> returned true, otherwise it
is C<NBDKIT_FUA_NONE>.

If there is an error, the callback should call C<nbdkit_error> with an
error message and return C<-1>.  Like the other initial queries
documented above, per-connection caching of the return value of this
function is allowed.

=head2 C<.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 C<.pread> method and can be used to read or
modify data read by the plugin.

The parameter C<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 C<next_ops-E<gt>pread>.

If there is an error (including a short read which couldn't be
recovered from), C<.pread> should call C<nbdkit_error> with an error
message B<and> return -1 with C<err> set to the positive errno value
to return to the client.

=head2 C<.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 C<.pwrite> method and can be used to modify
data written by the plugin.

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

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

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

=head2 C<.flush>

 int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
               void *handle, uint32_t flags, int *err);

This intercepts the plugin C<.flush> method and can be used to modify
flush requests.

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

The parameter C<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 C<next_ops-E<gt>flush>.

If there is an error, C<.flush> should call C<nbdkit_error> with an
error message B<and> return -1 with C<err> set to the positive errno
value to return to the client.

=head2 C<.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 C<.trim> method and can be used to modify
trim requests.

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

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

If there is an error, C<.trim> should call C<nbdkit_error> with an
error message B<and> return -1 with C<err> set to the positive errno
value to return to the client.

=head2 C<.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 C<.zero> method and can be used to modify
zero requests.

This function will not be called if C<.can_write> returned false; in
turn, the filter should not call C<next_ops-E<gt>zero> if
C<next_ops-E<gt>can_zero> did not return true.

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

Note that unlike the plugin C<.zero> which is permitted to fail with
C<EOPNOTSUPP> to force a fallback to C<.pwrite>, the function
C<next_ops-E<gt>zero> will never fail with C<err> set to C<EOPNOTSUPP>
because the fallback has already taken place.

If there is an error, C<.zero> should call C<nbdkit_error> with an
error message B<and> return -1 with C<err> set to the positive errno
value to return to the client.  The filter should never fail with
C<EOPNOTSUPP> (while plugins have automatic fallback to C<.pwrite>,
filters do not).

=head1 ERROR HANDLING

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

C<nbdkit_error> has the following prototype and works like
L<printf(3)>:

 void nbdkit_error (const char *fs, ...);
 void nbdkit_verror (const char *fs, va_list args);

For convenience, C<nbdkit_error> preserves the value of C<errno>.

=head1 DEBUGGING

Run the server with I<-f> and I<-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
C<nbdkit_debug>, which has the following prototype and works like
L<printf(3)>:

 void nbdkit_debug (const char *fs, ...);
 void nbdkit_vdebug (const char *fs, va_list args);

For convenience, C<nbdkit_debug> preserves the value of C<errno>.
Note that C<nbdkit_debug> only prints things when the server is in
verbose mode (I<-v> option).

=head1 INSTALLING THE FILTER

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

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

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

 nbdkit --filter=name plugin [args]

The location of the C<$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

=head1 PKG-CONFIG/PKGCONF

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

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

The above will fail unless nbdkit E<ge> 1.2.3 and the header file is
installed, and will set C<NBDKIT_CFLAGS> and C<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

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(1)>.

Filters:

L<nbdkit-blocksize-filter(1)>,
L<nbdkit-cache-filter(1)>,
L<nbdkit-cow-filter(1)>,
L<nbdkit-delay-filter(1)>,
L<nbdkit-fua-filter(1)>,
L<nbdkit-log-filter(1)>,
L<nbdkit-nozero-filter(1)>,
L<nbdkit-offset-filter(1)>,
L<nbdkit-partition-filter(1)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2013-2018 Red Hat Inc.

=head1 LICENSE

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

=over 4

=item *

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

=item *

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.

=item *

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.

=back

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.