Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
3 contributors

Users who have contributed to this file

@rwmjones @ebblake @ptoscano
1192 lines (824 sloc) 40.9 KB

NAME

nbdkit-plugin - how to write nbdkit plugins

SYNOPSIS

#define NBDKIT_API_VERSION 2

#include <nbdkit-plugin.h>

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

static void *
myplugin_open (void)
{
  /* create a handle ... */
  return handle;
}

static struct nbdkit_plugin plugin = {
  .name              = "myplugin",
  .open              = myplugin_open,
  .get_size          = myplugin_get_size,
  .pread             = myplugin_pread,
  .pwrite            = myplugin_pwrite,
  /* etc */
};

NBDKIT_REGISTER_PLUGIN(plugin)

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

nbdkit [--args ...] ./myplugin.so [key=value ...]

When debugging, use the -fv options:

nbdkit -fv ./myplugin.so [key=value ...]

DESCRIPTION

An nbdkit plugin is a new source device which can be served using the Network Block Device (NBD) protocol. This manual page describes how to create an nbdkit plugin in C.

To see example plugins: https://github.com/libguestfs/nbdkit/tree/master/plugins

Plugins written in C have an ABI guarantee: a plugin compiled against an older version of nbdkit will still work correctly when loaded with a newer nbdkit. We also try (but cannot guarantee) to support plugins compiled against a newer version of nbdkit when loaded with an older nbdkit, although the plugin may have reduced functionality if it depends on features only provided by newer nbdkit.

For plugins written in C, we also provide an API guarantee: a plugin written against an older header will still compile unmodified with a newer nbdkit.

The API guarantee does not always apply to plugins written in other (non-C) languages which may have to adapt to changes when recompiled against a newer nbdkit.

To write plugins in other languages, see: __LANG_PLUGIN_LINKS__.

#define NBDKIT_API_VERSION 2

Plugins must choose which API version they want to use, by defining NBDKIT_API_VERSION to a positive integer prior to including nbdkit-plugin.h (or any other nbdkit header). The default version is 1 for backwards-compatibility with nbdkit v1.1.26 and earlier; however, it is recommended that new plugins be written to the maximum version (currently 2) as it enables more features and better interaction with nbdkit filters. Therefore, the rest of this document only covers the version 2 interface. A newer nbdkit will always support plugins written in C which were compiled against any prior API version.

#include <nbdkit-plugin.h>

All plugins should start by including this header file, after optionally choosing an API version.

#define THREAD_MODEL

All plugins must define a thread model. See "THREADS" below for details. It is generally safe to use:

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

struct nbdkit_plugin

All plugins must define and register one struct nbdkit_plugin, which contains the name of the plugin and pointers to callback functions.

static struct nbdkit_plugin plugin = {
  .name              = "myplugin",
  .longname          = "My Plugin",
  .description       = "This is my great plugin for nbdkit",
  .open              = myplugin_open,
  .get_size          = myplugin_get_size,
  .pread             = myplugin_pread,
  .pwrite            = myplugin_pwrite,
  /* etc */
};

NBDKIT_REGISTER_PLUGIN(plugin)

The .name field is the name of the plugin.

The callbacks are described below (see "CALLBACKS"). Only .name, .open, .get_size and .pread are required. All other callbacks can be omitted. However almost all plugins should have a .close callback. Most real-world plugins will also want to declare some of the other callbacks.

The nbdkit server calls the callbacks in the following order over the lifetime of the plugin:

.load

is called once just after the plugin is loaded into memory.

.config and .config_complete

.config is called zero or more times during command line parsing. .config_complete is called once after all configuration information has been passed to the plugin.

Both are called after loading the plugin but before any connections are accepted.

.thread_model

.thread_model is called once after all configuration information has been passed to the plugin, and before any connections are accepted.

.open

A new client has connected.

.can_write, .get_size and other option negotiation callbacks

These are called during option negotiation with the client, but before any data is served. These callbacks may return different values across different .open calls, but within a single connection, must always return the same value; other code in nbdkit may cache the per-connection value returned rather than using the callback a second time.

.pread, .pwrite and other data serving callbacks

After option negotiation has finished, these may be called to serve data. Depending on the thread model chosen, they might be called in parallel from multiple threads. The data serving callbacks include a flags argument; the results of the negotiation callbacks influence whether particular flags will ever be passed to a data callback.

.close

The client has disconnected.

.open ... .close

The sequence .open ... .close can be called repeatedly over the lifetime of the plugin, and can be called in parallel (depending on the thread model).

.unload

is called once just before the plugin is unloaded from memory.

FLAGS

The following flags are defined by nbdkit, and used in various data serving callbacks as follows:

NBDKIT_FLAG_MAY_TRIM

This flag is used by the .zero callback; there is no way to disable this flag, although a plugin that does not support trims as a way to write zeroes may ignore the flag without violating expected semantics.

NBDKIT_FLAG_FUA

This flag represents Forced Unit Access semantics. It is used by the .pwrite, .zero, and .trim callbacks to indicate that the plugin must not return a result until the action has landed in persistent storage. This flag will not be sent to the plugin unless .can_fua is provided and returns NBDKIT_FUA_NATIVE.

The following defines are valid as successful return values for .can_fua:

NBDKIT_FUA_NONE

Forced Unit Access is not supported; the client must manually request a flush after writes have completed. The NBDKIT_FLAG_FUA flag will not be passed to the plugin's write callbacks.

NBDKIT_FUA_EMULATE

The client may request Forced Unit Access, but it is implemented by emulation, where nbdkit calls .flush after a write operation; this is semantically correct, but may hurt performance as it tends to flush more data than just what the client requested. The NBDKIT_FLAG_FUA flag will not be passed to the plugin's write callbacks.

NBDKIT_FUA_NATIVE

The client may request Forced Unit Access, which results in the NBDKIT_FLAG_FUA flag being passed to the plugin's write callbacks (.pwrite, .trim, and .zero). When the flag is set, these callbacks must not return success until the client's request has landed in persistent storage.

The following defines are valid as successful return values for .can_cache:

NBDKIT_CACHE_NONE

The server does not advertise caching support, and rejects any client-requested caching. Any .cache callback is ignored.

NBDKIT_CACHE_EMULATE

The nbdkit server advertises cache support to the client, where the client may request that the server cache a region of the export to potentially speed up future read and/or write operations on that region. The nbdkit server implements the caching by calling .pread and ignoring the results. This option exists to ease the implementation of a common form of caching; any .cache callback is ignored.

NBDKIT_CACHE_NATIVE

The nbdkit server advertises cache support to the client, where the client may request that the server cache a region of the export to potentially speed up future read and/or write operations on that region. The nbdkit server calls the .cache callback to perform the caching; if that callback is missing, the client's cache request succeeds without doing anything.

ERROR HANDLING

If there is an error in the plugin, the plugin should call nbdkit_error to report an error message; additionally, if the callback is involved in serving data, the plugin should call nbdkit_set_error to influence the error code that will be sent to the client. These two functions can be called in either order. Then, the callback should return the appropriate error indication, eg. NULL or -1.

If the call to nbdkit_set_error is omitted while serving data, then the global variable errno may be used. For plugins which have .errno_is_preserved == 1 the core code will use errno. In plugins written in non-C languages, we usually cannot trust that errno will not be overwritten when returning from that language to C. In that case, either the plugin must call nbdkit_set_error or hard-coded EIO is used.

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.

nbdkit_set_error can be called at any time, but only has an impact during callbacks for serving data, and only when the callback returns an indication of failure. It has the following prototype:

void nbdkit_set_error (int err);

FILENAMES AND PATHS

The server usually (not always) changes directory to / before it starts serving connections. This means that any relative paths passed during configuration will not work when the server is running (example: nbdkit plugin.so disk.img).

To avoid problems, prepend relative paths with the current directory before storing them in the handle. Or open files and store the file descriptor.

nbdkit_absolute_path

char *nbdkit_absolute_path (const char *filename);

The utility function nbdkit_absolute_path converts any path to an absolute path: if it is relative, then all this function does is prepend the current working directory to the path, with no extra checks.

Note that this function works only when used in the .config, and .config_complete callbacks.

If conversion was not possible, this calls nbdkit_error and returns NULL. Note that this function does not check that the file exists.

The returned string must be freed by the caller.

nbdkit_realpath

char *nbdkit_realpath (const char *filename);

The utility function nbdkit_realpath converts any path to an absolute path, resolving symlinks. Under the hood it uses the realpath function, and thus it fails if the path does not exist, or it is not possible to access to any of the components of the path.

Note that this function works only when used in the .config, and .config_complete callbacks.

If the path resolution was not possible, this calls nbdkit_error and returns NULL.

The returned string must be freed by the caller.

umask

All plugins will see a umask(2) of 0022.

CALLBACKS

.name

const char *name;

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

.version

const char *version;

Plugins 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 plugin. This field is used in error messages.

.description

const char *description;

An optional multi-line description of the plugin.

.load

void load (void);

This is called once just after the plugin is loaded into memory. You can use this to perform any global initialization needed by the plugin.

.unload

void unload (void);

This may be called once just before the plugin 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 plugin as robust as possible by not requiring cleanup. See also "SHUTDOWN" below.

.dump_plugin

void dump_plugin (void);

This optional callback is called when the nbdkit plugin --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 plugin will avoid conflicts.

.config

int config (const char *key, const char *value);

On the nbdkit command line, after the plugin filename, come an optional list of key=value arguments. These are passed to the plugin through this callback when the plugin is first loaded and before any connections are accepted.

This callback may be called zero or more times.

Both key and value parameters will be non-NULL. The strings are owned by nbdkit but will remain valid for the lifetime of the plugin, so the plugin does not need to copy them.

The key will be a non-empty string beginning with an ASCII alphabetic character (A-Z a-z). The rest of the key must contain only ASCII alphanumeric plus period, underscore or dash characters (A-Z a-z 0-9 . _ -). The value may be an arbitrary string, including an empty string.

The names of keys accepted by plugins is up to the plugin, but you should probably look at other plugins and follow the same conventions.

If the value is a relative path, then note that the server changes directory when it starts up. See "FILENAMES AND PATHS" above.

If the .config callback is not provided by the plugin, and the user tries to specify any key=value arguments, then nbdkit will exit with an error.

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

.magic_config_key

const char *magic_config_key;

This optional string can be used to set a "magic" key used when parsing plugin parameters. It affects how "bare parameters" (those which do not contain an = character) are parsed on the command line.

If magic_config_key != NULL then any bare parameters are passed to the .config method as: config (magic_config_key, argv[i]);.

If magic_config_key is not set then we behave as in nbdkit < 1.7: If the first parameter on the command line is bare then it is passed to the .config method as: config ("script", value);. Any other bare parameters give errors.

.config_complete

int config_complete (void);

This optional callback is called after all the configuration has been passed to the plugin. It is a good place to do checks, for example that the user has passed the required parameters to the plugin.

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 plugin doesn't take any config parameters you should probably omit this.

.thread_model

int thread_model (void)

This optional callback is called after all the configuration has been passed to the plugin. It can be used to force a stricter thread model based on configuration, compared to THREAD_MODEL. See "THREADS" below for details. Attempts to request a looser (more parallel) model are silently ignored.

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

.open

void *open (int readonly);

This is called when a new client connects to the nbdkit server. The callback should allocate a handle and return it. This handle is passed back to other 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.

The readonly flag informs the plugin that the user requested a read-only connection using the -r flag on the command line. Note that the plugin may additionally force the connection to be readonly (even if this flag is false) by returning false from the .can_write callback. So if your plugin can only serve read-only, you can ignore this parameter.

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.

Note there is no way in the NBD protocol to communicate close errors back to the client, for example if your plugin calls close(2) and you are checking for errors (as you should do). Therefore the best you can do is to log the error on the server. Well-behaved NBD clients should try to flush the connection before it is closed and check for errors, but obviously this is outside the scope of nbdkit.

.get_size

int64_t get_size (void *handle);

This is called during the option negotiation phase of the protocol to get the size (in bytes) of the block device being exported.

The returned size must be ≥ 0. If there is an error, .get_size should call nbdkit_error with an error message and return -1.

.can_write

int can_write (void *handle);

This is called during the option negotiation phase to find out if the handle supports writes.

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

This callback is not required. If omitted, then we return true iff a .pwrite callback has been defined.

.can_flush

int can_flush (void *handle);

This is called during the option negotiation phase to find out if the handle supports the flush-to-disk operation.

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

This callback is not required. If omitted, then we return true iff a .flush callback has been defined.

.is_rotational

int is_rotational (void *handle);

This is called during the option negotiation phase to find out if the backing disk is a rotational medium (like a traditional hard disk) or not (like an SSD). If true, this may cause the client to reorder requests to make them more efficient for a slow rotating disk.

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

This callback is not required. If omitted, then we return false.

.can_trim

int can_trim (void *handle);

This is called during the option negotiation phase to find out if the plugin supports the trim/discard operation for punching holes in the backing storage.

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

This callback is not required. If omitted, then we return true iff a .trim callback has been defined.

.can_zero

int can_zero (void *handle);

This is called during the option negotiation phase to find out if the plugin wants the .zero callback to be utilized. Support for writing zeroes is still advertised to the client (unless the nbdkit filter nozero is also used), so returning false merely serves as a way to avoid complicating the .zero callback to have to fail with EOPNOTSUPP on the connections where it will never be more efficient than using .pwrite up front.

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

This callback is not required. If omitted, then nbdkit always tries .zero first if it is present, and gracefully falls back to .pwrite if .zero was absent or failed with EOPNOTSUPP.

.can_extents

int can_extents (void *handle);

This is called during the option negotiation phase to find out if the plugin supports detecting allocated (non-sparse) regions of the disk with the .extents callback.

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

This callback is not required. If omitted, then we return true iff a .extents callback has been defined.

.can_fua

int can_fua (void *handle);

This is called during the option negotiation phase to find out if the plugin supports the Forced Unit Access (FUA) flag on write, zero, and trim requests. If this returns NBDKIT_FUA_NONE, FUA support is not advertised to the client; if this returns NBDKIT_FUA_EMULATE, the .flush callback must work (even if .can_flush returns false), and FUA support is emulated by calling .flush after any write operation; if this returns NBDKIT_FUA_NATIVE, then the .pwrite, .zero, and .trim callbacks (if implemented) must handle the flag NBDKIT_FLAG_FUA, by not returning until that action has landed in persistent storage.

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

This callback is not required unless a plugin wants to specifically handle FUA requests. If omitted, nbdkit checks whether .flush exists, and behaves as if this function returns NBDKIT_FUA_NONE or NBDKIT_FUA_EMULATE as appropriate.

.can_multi_conn

int can_multi_conn (void *handle);

This is called during the option negotiation phase to find out if the plugin is prepared to handle multiple connections from a single client. If the plugin sets this to true then a client may try to open multiple connections to the nbdkit server and spread requests across all connections to maximize parallelism. If the plugin sets it to false (which is the default) then well-behaved clients should only open a single connection, although we cannot control what clients do in practice.

Specifically it means that either the plugin does not cache requests at all. Or if it does cache them then the effects of a .flush request or setting NBDKIT_FLAG_FUA on a request must be visible across all connections to the plugin before the plugin replies to that request.

If you use Linux nbd-client(8) option -C num with num > 1 then Linux checks this flag and will refuse to connect if .can_multi_conn is false.

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

This callback is not required. If omitted, then we return false.

.can_cache

int can_cache (void *handle);

This is called during the option negotiation phase to find out if the plugin supports a cache operation. The nature of the caching is unspecified (including whether there are limits on how much can be cached at once, and whether writes to a cached region have write-through or write-back semantics), but the command exists to let clients issue a hint to the server that they will be accessing that region of the export.

If this returns NBDKIT_CACHE_NONE, cache support is not advertised to the client; if this returns NBDKIT_CACHE_EMULATE, caching is emulated by the server calling .pread and ignoring the results; if this returns NBDKIT_CACHE_NATIVE, then the .cache callback will be used. If there is an error, .can_cache should call nbdkit_error with an error message and return -1.

This callback is not required. If omitted, then we return NBDKIT_CACHE_NONE if the .cache callback is missing, or NBDKIT_CACHE_NATIVE if it is defined.

.pread

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

During the data serving phase, nbdkit calls this callback to read data from the backing store. count bytes starting at offset in the backing store should be read and copied into buf. nbdkit takes care of all bounds- and sanity-checking, so the plugin does not need to worry about that.

The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input.

The callback must read the whole count bytes if it can. The NBD protocol doesn't allow partial reads (instead, these would be errors). If the whole count bytes was read, the callback should return 0 to indicate there was no error.

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 nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

.pwrite

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

During the data serving phase, nbdkit calls this callback to write data to the backing store. count bytes starting at offset in the backing store should be written using the data in buf. nbdkit takes care of all bounds- and sanity-checking, so the plugin does not need to worry about that.

This function will not be called if .can_write returned false. The parameter flags may include NBDKIT_FLAG_FUA on input based on the result of .can_fua.

The callback must write the whole count bytes if it can. The NBD protocol doesn't allow partial writes (instead, these would be errors). If the whole count bytes was written successfully, the callback should return 0 to indicate there was no error.

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 nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

.flush

int flush (void *handle, uint32_t flags);

During the data serving phase, this callback is used to fdatasync(2) the backing store, ie. to ensure it has been completely written to a permanent medium. If that is not possible then you can omit this callback.

This function will not be called directly by the client if .can_flush returned false; however, it may still be called by nbdkit if .can_fua returned NBDKIT_FUA_EMULATE. The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input.

If there is an error, .flush should call nbdkit_error with an error message, and nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

.trim

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

During the data serving phase, this callback is used to "punch holes" in the backing store. If that is not possible then you can omit this callback.

This function will not be called if .can_trim returned false. The parameter flags may include NBDKIT_FLAG_FUA on input based on the result of .can_fua.

If there is an error, .trim should call nbdkit_error with an error message, and nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

.zero

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

During the data serving phase, this callback is used to write count bytes of zeroes at offset in the backing store.

This function will not be called if .can_zero returned false. On input, the parameter flags may include NBDKIT_FLAG_MAY_TRIM unconditionally, and NBDKIT_FLAG_FUA based on the result of .can_fua.

If NBDKIT_FLAG_MAY_TRIM is requested, the operation can punch a hole instead of writing actual zero bytes, but only if subsequent reads from the hole read as zeroes. If this callback is omitted, or if it fails with EOPNOTSUPP (whether by nbdkit_set_error or errno), then .pwrite will be used instead.

The callback must write the whole count bytes if it can. The NBD protocol doesn't allow partial writes (instead, these would be errors). If the whole count bytes was written successfully, the callback should return 0 to indicate there was no error.

If there is an error, .zero should call nbdkit_error with an error message, and nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

.extents

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

During the data serving phase, this callback is used to detect allocated, sparse and zeroed regions of the disk.

This function will not be called if .can_extents returned false. nbdkit's default behaviour in this case is to treat the whole virtual disk as if it was allocated.

The callback should detect and return the list of extents overlapping the range [offset...offset+count-1]. The extents parameter points to an opaque object which the callback should fill in by calling nbdkit_add_extent. See "Extents list" below.

If there is an error, .extents should call nbdkit_error with an error message, and nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

Extents list

The plugin extents callback is passed an opaque pointer struct nbdkit_extents *extents. This structure represents a list of filesystem extents describing which areas of the disk are allocated, which are sparse (“holes”), and, if supported, which are zeroes.

The extents callback should scan the disk starting at offset and call nbdkit_add_extent for each extent found.

Extents overlapping the range [offset...offset+count-1] should be returned if possible. However nbdkit ignores extents < offset so the plugin may, if it is easier to implement, return all extent information for the whole disk. The plugin may return extents beyond the end of the range. It may also return extent information for less than the whole range, but it must return at least one extent overlapping offset.

The extents must be added in ascending order, and must be contiguous.

The flags parameter of the .extents callback may contain the flag NBDKIT_FLAG_REQ_ONE. This means that the client is only requesting information about the extent overlapping offset. The plugin may ignore this flag, or as an optimization it may return just a single extent for offset.

int nbdkit_add_extent (struct nbdkit_extents *extents,
                       uint64_t offset, uint64_t length, uint32_t type);

Add an extent covering [offset...offset+length-1] of one of the following four types:

type = 0

A normal, allocated data extent.

type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO

An unallocated extent, a.k.a. a “hole”, which reads back as zeroes. This is the normal type of hole applicable to most disks.

type = NBDKIT_EXTENT_ZERO

An allocated extent which is known to contain only zeroes.

type = NBDKIT_EXTENT_HOLE

An unallocated extent (hole) which does not read back as zeroes. Note this should only be used in specialized circumstances such as when writing a plugin for (or to emulate) certain SCSI drives which do not guarantee that trimmed blocks read back as zeroes.

nbdkit_extent_add returns 0 on success or -1 on failure. On failure nbdkit_error and/or nbdkit_set_error has already been called. errno will be set to a suitable value.

.cache

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

During the data serving phase, this callback is used to give the plugin a hint that the client intends to make further accesses to the given region of the export. The nature of caching is not specified further by the NBD specification (for example, a server may place limits on how much may be cached at once, and there is no way to control if writes to a cached area have write-through or write-back semantics). In fact, the cache command can always fail and still be compliant, and success might not guarantee a performance gain. If this callback is omitted, then the results of .can_cache determine whether nbdkit will reject cache requests, treat them as instant success, or emulate caching by calling .pread over the same region and ignoring the results.

This function will not be called if .can_cache did not return NBDKIT_CACHE_NATIVE. The parameter flags exists in case of future NBD protocol extensions; at this time, it will be 0 on input. A plugin must fail this function if flags includes an unrecognized flag, as that may indicate a requirement that the plugin comply must with a specific caching semantic.

If there is an error, .cache should call nbdkit_error with an error message, and nbdkit_set_error to record an appropriate error (unless errno is sufficient), then return -1.

THREADS

Each nbdkit plugin must declare its maximum thread safety model by defining the THREAD_MODEL macro. (This macro is used by NBDKIT_REGISTER_PLUGIN). Additionally, a plugin may implement the .thread_model callback, called right after .config_complete to make a runtime decision on which thread model to use. The nbdkit server chooses the most restrictive model between the plugin's THREAD_MODEL, the .thread_model if present, and any restrictions requested by filters.

The possible settings for THREAD_MODEL are defined below.

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS

Only a single handle can be open at any time, and all requests happen from one thread.

Note this means only one client can connect to the server at any time. If a second client tries to connect it will block waiting for the first client to close the connection.

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

This is a safe default for most plugins.

Multiple handles can be open at the same time, but requests are serialized so that for the plugin as a whole only one open/read/write/close (etc) request will be in progress at any time.

This is a useful setting if the library you are using is not thread-safe. However performance may not be good.

#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS

Multiple handles can be open and multiple data requests can happen in parallel. However only one request will happen per handle at a time (but requests on different handles might happen concurrently).

#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL

Multiple handles can be open and multiple data requests can happen in parallel (even on the same handle). The server may reorder replies, answering a later request before an earlier one.

All the libraries you use must be thread-safe and reentrant. You may also need to provide mutexes for fields in your connection handle.

If none of the above thread models are suitable, then use NBDKIT_THREAD_MODEL_PARALLEL and implement your own locking using pthread_mutex_t etc.

SHUTDOWN

When nbdkit receives certain signals it will shut down (see "SIGNALS" in nbdkit(1)). The server will wait for any currently running plugin callbacks to finish and also call the .unload callback before unloading the plugin.

Note that it's not guaranteed this can always happen (eg. the server might be killed by SIGKILL or segfault).

PARSING SIZE PARAMETERS

Use the nbdkit_parse_size utility function to parse human-readable size strings such as "100M" into the size in bytes.

int64_t nbdkit_parse_size (const char *str);

str can be a string in a number of common formats. The function returns the size in bytes. If there was an error, it returns -1.

PARSING BOOLEAN PARAMETERS

Use the nbdkit_parse_bool utility function to parse human-readable strings such as "on" into a boolean value.

int nbdkit_parse_bool (const char *str);

str can be a string containing a case-insensitive form of various common toggle values. The function returns 0 or 1 if the parse was successful. If there was an error, it returns -1.

READING PASSWORDS

The nbdkit_read_password utility function can be used to read passwords from config parameters:

int nbdkit_read_password (const char *value, char **password);

For example:

char *password = NULL;

static int
myplugin_config (const char *key, const char *value)
{
  ..
  if (strcmp (key, "password") == 0) {
    free (password);
    if (nbdkit_read_password (value, &password) == -1)
      return -1;
  }
  ..
}

The password result string is allocated by malloc, and so you may need to free it.

This function recognizes several password formats. A password may be used directly on the command line, eg:

nbdkit myplugin password=mostsecret

But more securely this function can also read a password interactively:

nbdkit myplugin password=-

or from a file:

nbdkit myplugin password=+/tmp/secret

(If the password begins with a - or + character then it must be passed in a file).

DEBUGGING

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

nbdkit -fv ./myplugin.so [key=value [key=value [...]]]

To print debugging information from within the plugin, 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

The -v option switches general debugging on or off, and this debugging should be used for messages which are useful for all users of your plugin.

In cases where you want to enable specific extra debugging to track down bugs in plugins or filters — mainly for use by the plugin/filter developers themselves — you can define Debug Flags. These are global ints called myplugin_debug_*:

int myplugin_debug_foo;
int myplugin_debug_bar;
...
if (myplugin_debug_foo) {
  nbdkit_debug ("lots of extra debugging about foo: ...");
}

Debug Flags can be controlled on the command line using the -D (or --debug) option:

nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]

Note myplugin is the name passed to .name in the struct nbdkit_plugin.

You should only use this feature for debug settings. For general settings use ordinary plugin parameters. Debug Flags can only be C ints. They are not supported by non-C language plugins.

INSTALLING THE PLUGIN

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

nbdkit /path/to/plugin.so [args]

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

nbdkit name [args]

The location of the $plugindir 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 plugin directory at compile time by doing:

pkgconf nbdkit --variable=plugindir

PKG-CONFIG/PKGCONF

nbdkit provides a pkg-config/pkgconf file called nbdkit.pc which should be installed on the correct path when the nbdkit plugin 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 plugins.

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

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

You can also substitute the plugindir variable by doing:

PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])

which defines $(NBDKIT_PLUGINDIR) in automake-generated Makefiles.

WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES

You can also write nbdkit plugins in Lua, OCaml, Perl, Python, Ruby, Rust, shell script or Tcl. Other programming languages may be offered in future.

For more information see: __LANG_PLUGIN_LINKS__.

Plugins written in scripting languages may also be installed in $plugindir. These must be called nbdkit-name-plugin without any extension. They must be executable, and they must use the shebang header (see "Shebang scripts" in nbdkit(1)). For example a plugin written in Perl called foo.pl might be installed like this:

$ head -1 foo.pl
#!/usr/sbin/nbdkit perl

$ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin

and then users will be able to run it like this:

$ nbdkit foo [args ...]

SEE ALSO

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

Standard plugins provided by nbdkit:

__PLUGIN_LINKS__.

AUTHORS

Eric Blake

Richard W.M. Jones

Pino Toscano

COPYRIGHT

Copyright (C) 2013-2018 Red Hat Inc.

POD ERRORS

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

Around line 834:

Non-ASCII character seen before =encoding in '(“holes”),'. Assuming UTF-8

You can’t perform that action at this time.