1nbdkit-filter(3) NBDKIT nbdkit-filter(3)
2
6 nbdkit-filter - how to write nbdkit filters
7
9 #include <nbdkit-filter.h>
10 static int
12 myfilter_config (nbdkit_next_config *next, void *nxdata,
13 const char *key, const char *value)
14 {
15 if (strcmp (key, "myparameter") == 0) {
16 // ...
17 return 0;
18 }
19 else {
20 // pass through to next filter or plugin
21 return next (nxdata, key, value);
22 }
23 }
24 static struct nbdkit_filter filter = {
26 .name = "filter",
27 .config = myfilter_config,
28 /* etc */
29 };
30 NBDKIT_REGISTER_FILTER(filter)
32 When this has been compiled to a shared library, do:
34 nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]
36 When debugging, use the -fv options:
38 nbdkit -fv --filter=./myfilter.so plugin [key=value ...]
40
42 One or more nbdkit filters can be placed in front of an nbdkit plugin
43 to modify the behaviour of the plugin. This manual page describes how
44 to create an nbdkit filter.
45 Filters can be used for example to limit requests to an offset/limit,
47 add copy-on-write support, or inject delays or errors (for testing).
48 Different filters can be stacked:
50 NBD ┌─────────┐ ┌─────────┐ ┌────────┐
52 client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
53 request └─────────┘ └─────────┘ └────────┘
54 Each filter intercepts plugin functions (see nbdkit-plugin(3)) and can
56 call the next filter or plugin in the chain, modifying parameters,
57 calling before the filter function, in the middle or after. Filters
58 may even short-cut the chain. As an example, to process its own
59 parameters the filter can intercept the ".config" method:
60 static int
62 myfilter_config (nbdkit_next_config *next, void *nxdata,
63 const char *key, const char *value)
64 {
65 if (strcmp (key, "myparameter") == 0) {
66 // ...
67 // here you would handle this key, value
68 // ...
69 return 0;
70 }
71 else {
72 // pass through to next filter or plugin
73 return next (nxdata, key, value);
74 }
75 }
76 static struct nbdkit_filter filter = {
78 // ...
79 .config = myfilter_config,
80 // ...
81 };
82 The call to "next (nxdata, ...)" calls the ".config" method of the next
84 filter or plugin in the chain. In the example above any instances of
85 "myparameter=..." on the command line would not be seen by the plugin.
86 To see example filters:
88 https://github.com/libguestfs/nbdkit/tree/master/filters
89 Filters must be written in C.
91 Unlike plugins, where we provide a stable ABI guarantee that permits
93 operation across version differences, filters can only be run with the
94 same version of nbdkit that they were compiled with. The reason for
95 this is two-fold: the filter API includes access to struct
96 nbdkit_next_ops that is likely to change if new callbacks are added
97 (old nbdkit cannot safely run new filters that access new methods); and
98 if we added new methods then an old filter would not see them and so
99 they would be passed unmodified through the filter, and in some cases
100 that leads to data corruption (new nbdkit cannot safely run old filters
101 unaware of new methods). Therefore, unlike plugins, you should not
102 expect to distribute filters separately from nbdkit.
103
105 All filters should start by including this header file.
106
108 All filters must define and register one "struct nbdkit_filter", which
109 contains the name of the filter and pointers to plugin methods that the
110 filter wants to intercept.
111 static struct nbdkit_filter filter = {
113 .name = "filter",
114 .longname = "My Filter",
115 .description = "This is my great filter for nbdkit",
116 .config = myfilter_config,
117 /* etc */
118 };
119 NBDKIT_REGISTER_FILTER(filter)
121 The ".name" field is the name of the filter. This is the only field
123 which is required.
124
126 nbdkit-filter.h defines some function types ("nbdkit_next_config",
127 "nbdkit_next_config_complete", "nbdkit_next_get_ready",
128 "nbdkit_next_after_fork", "nbdkit_next_preconnect",
129 "nbdkit_next_list_exports", "nbdkit_next_default_export",
130 "nbdkit_next_open") and a structure called "struct nbdkit_next_ops".
131 These abstract the next plugin or filter in the chain. There is also
132 an opaque pointer "nxdata" which must be passed along when calling
133 these functions. The value of "nxdata" passed to ".open" has a stable
134 lifetime that lasts to the corresponding ".close", with all
135 intermediate functions (such as ".pread") receiving the same value for
136 convenience. Functions where "nxdata" is not reused are ".config",
137 ".config_complete", ".get_ready", and ".after_fork", which are called
138 during initialization outside any connections, and ".preconnect",
139 ".list_exports", and ".default_export", which are called based on
140 client connections but prior to the stable lifetime of ".open".
141 Next config, open and close
143 The filter’s ".config", ".config_complete", ".get_ready", ".after_fork"
144 and ".open" methods may only call the next ".config",
145 ".config_complete", ".get_ready", ".after_fork" and ".open" method in
146 the chain (optionally for ".config").
147 The filter’s ".close" method is called when an old connection closed,
149 and this has no "next" parameter because it cannot be short-circuited.
150 "next_ops"
152 The filter’s other methods like ".prepare", ".get_size", ".pread" etc ―
153 always called in the context of a connection ― are passed a pointer to
154 "struct nbdkit_next_ops" which contains a comparable set of accessors
155 to plugin methods that can be called during a connection. The
156 "next_ops" parameter is stable between ".prepare" and ".finalize";
157 intermediate functions (such as ".pread") receive the same value for
158 convenience.
159 It is possible for a filter to issue (for example) extra
161 "next_ops->pread" calls in response to a single ".pwrite" call.
162 Note that the semantics of the functions in "struct nbdkit_next_ops"
164 are slightly different from what a plugin implements: for example, when
165 a plugin's ".pread" returns -1 on error, the error value to advertise
166 to the client is implicit (via the plugin calling "nbdkit_set_error" or
167 setting "errno"), whereas "next_ops->pread" exposes this via an
168 explicit parameter, allowing a filter to learn or modify this error if
169 desired.
170 There is also a "next_ops->reopen" function which is used by
172 nbdkit-retry-filter(1) to close and reopen the underlying plugin. It
173 should be used with caution because it is difficult to use safely.
174 Other considerations
176 You can modify parameters when you call the "next" function. However
177 be careful when modifying strings because for some methods (eg.
178 ".config") the plugin may save the string pointer that you pass along.
179 So you may have to ensure that the string is not freed for the lifetime
180 of the server; you may find "nbdkit_strdup_intern" helpful for avoiding
181 a memory leak while still obeying lifecycle constraints.
182 Note that if your filter registers a callback but in that callback it
184 doesn't call the "next" function then the corresponding method in the
185 plugin will never be called. In particular, your ".open" method, if
186 you have one, must call the ".next" method.
187
189 "struct nbdkit_filter" has some static fields describing the filter and
190 optional callback functions which can be used to intercept plugin
191 methods.
192 ".name"
194 const char *name;
195 This field (a string) is required, and must contain only ASCII
197 alphanumeric characters or non-leading dashes, and be unique amongst
198 all filters.
199 ".longname"
201 const char *longname;
202 An optional free text name of the filter. This field is used in error
204 messages.
205 ".description"
207 const char *description;
208 An optional multi-line description of the filter.
210 ".load"
212 void load (void);
213 This is called once just after the filter is loaded into memory. You
215 can use this to perform any global initialization needed by the filter.
216 ".unload"
218 void unload (void);
219 This may be called once just before the filter is unloaded from memory.
221 Note that it's not guaranteed that ".unload" will always be called (eg.
222 the server might be killed or segfault), so you should try to make the
223 filter as robust as possible by not requiring cleanup. See also
224 "SHUTDOWN" in nbdkit-plugin(3).
225 ".config"
227 int (*config) (nbdkit_next_config *next, void *nxdata,
228 const char *key, const char *value);
229 This intercepts the plugin ".config" method and can be used by the
231 filter to parse its own command line parameters. You should try to
232 make sure that command line parameter keys that the filter uses do not
233 conflict with ones that could be used by a plugin.
234 If there is an error, ".config" should call "nbdkit_error" with an
236 error message and return "-1".
237 ".config_complete"
239 int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
240 This intercepts the plugin ".config_complete" method and can be used to
242 ensure that all parameters needed by the filter were supplied on the
243 command line.
244 If there is an error, ".config_complete" should call "nbdkit_error"
246 with an error message and return "-1".
247 ".config_help"
249 const char *config_help;
250 This optional multi-line help message should summarize any "key=value"
252 parameters that it takes. It does not need to repeat what already
253 appears in ".description".
254 If the filter doesn't take any config parameters you should probably
256 omit this.
257 ".thread_model"
259 int (*thread_model) (void);
260 Filters may tighten (but not relax) the thread model of the plugin, by
262 defining this callback. Note that while plugins use a compile-time
263 definition of "THREAD_MODEL", filters do not need to declare a model at
264 compile time; instead, this callback is called after ".config_complete"
265 and before any connections are created. See "THREADS" in
266 nbdkit-plugin(3) for a discussion of thread models.
267 The final thread model used by nbdkit is the smallest (ie. most
269 serialized) out of all the filters and the plugin, and applies for all
270 connections. Requests for a model larger than permitted by the plugin
271 are silently ignored. It is acceptable for decisions made during
272 ".config" and ".config_complete" to determine which model to request.
273 This callback is optional; if it is not present, the filter must be
275 written to handle fully parallel requests, including when multiple
276 requests are issued in parallel on the same connection, similar to a
277 plugin requesting "NBDKIT_THREAD_MODEL_PARALLEL". This ensures the
278 filter doesn't slow down other filters or plugins.
279 If there is an error, ".thread_model" should call "nbdkit_error" with
281 an error message and return "-1".
282 ".get_ready"
284 int (*get_ready) (nbdkit_next_get_ready *next, void *nxdata,
285 int thread_model);
286 This intercepts the plugin ".get_ready" method and can be used by the
288 filter to get ready to serve requests.
289 The "thread_model" parameter informs the filter about the final thread
291 model chosen by nbdkit after considering the results of ".thread_model"
292 of all filters in the chain after ".config_complete". This does not
293 need to be passed on to "next", as the model can no longer be altered
294 at this point.
295 If there is an error, ".get_ready" should call "nbdkit_error" with an
297 error message and return "-1".
298 ".after_fork"
300 int (*after_fork) (nbdkit_next_after_fork *next, void *nxdata);
301 This intercepts the plugin ".after_fork" method and can be used by the
303 filter to start background threads (although these have limited
304 usefulness since they will not be able to access the plugin).
305 If there is an error, ".after_fork" should call "nbdkit_error" with an
307 error message and return "-1".
308 ".preconnect"
310 int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata,
311 int readonly);
312 This intercepts the plugin ".preconnect" method and can be used to
314 filter access to the server.
315 If there is an error, ".preconnect" should call "nbdkit_error" with an
317 error message and return "-1".
318 ".list_exports"
320 int (*list_exports) (nbdkit_next_list_exports *next, void *nxdata,
321 int readonly, int is_tls,
322 struct nbdkit_exports *exports);
323 This intercepts the plugin ".list_exports" method and can be used to
325 filter which exports are advertised.
326 The "readonly" parameter matches what is passed to <.preconnect> and
328 ".open", and may be changed by the filter when calling into the plugin.
329 The "is_tls" parameter informs the filter whether TLS negotiation has
330 been completed by the client, but is not passed on to "next" because it
331 cannot be altered.
332 It is possible for filters to transform the exports list received back
334 from the layer below. Without error checking it would look like this:
335 myfilter_list_exports (...)
337 {
338 size_t i;
339 struct nbdkit_exports *exports2;
340 struct nbdkit_export e;
341 char *name, *desc;
342 exports2 = nbdkit_exports_new ();
344 next_list_exports (nxdata, readonly, exports);
345 for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
346 e = nbdkit_get_export (exports2, i);
347 name = adjust (e.name);
348 desc = adjust (e.desc);
349 nbdkit_add_export (exports, name, desc);
350 free (name);
351 free (desc);
352 }
353 nbdkit_exports_free (exports2);
354 }
355 If there is an error, ".list_exports" should call "nbdkit_error" with
357 an error message and return "-1".
358 Allocating and freeing nbdkit_exports list
360 Two functions are provided to filters only for allocating and freeing
362 the list:
363 struct nbdkit_exports *nbdkit_exports_new (void);
365 Allocates and returns a new, empty exports list.
367 On error this function can return "NULL". In this case it calls
369 "nbdkit_error" as required. "errno" will be set to a suitable value.
370 void nbdkit_exports_free (struct nbdkit_exports *);
372 Frees an existing exports list.
374 Iterating over nbdkit_exports list
376 Two functions are provided to filters only to iterate over the exports
378 in order:
379 size_t nbdkit_exports_count (const struct nbdkit_exports *);
381 Returns the number of exports in the list.
383 struct nbdkit_export {
385 char *name;
386 char *description;
387 };
388 const struct nbdkit_export nbdkit_get_export (const struct nbdkit_exports *,
389 size_t i);
390 Returns a copy of the "i"'th export.
392 ".default_export"
394 const char *default_export (nbdkit_next_default_export *next, void *nxdata,
395 int readonly, int is_tls)
396 This intercepts the plugin ".default_export" method and can be used to
398 alter the canonical export name used in place of the default "".
399 The "readonly" parameter matches what is passed to <.preconnect> and
401 ".open", and may be changed by the filter when calling into the plugin.
402 The "is_tls" parameter informs the filter whether TLS negotiation has
403 been completed by the client, but is not passed on to "next" because it
404 cannot be altered.
405 ".open"
407 void * (*open) (nbdkit_next_open *next, void *nxdata,
408 int readonly, const char *exportname, int is_tls);
409 This is called when a new client connection is opened and can be used
411 to allocate any per-connection data structures needed by the filter.
412 The handle (which is not the same as the plugin handle) is passed back
413 to other filter callbacks and could be freed in the ".close" callback.
414 Note that the handle is completely opaque to nbdkit, but it must not be
416 NULL. If you don't need to use a handle, return
417 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
418 If there is an error, ".open" should call "nbdkit_error" with an error
420 message and return "NULL".
421 This callback is optional, but if provided, it should call "next",
423 passing "readonly" and "exportname" possibly modified according to how
424 the filter plans to use the plugin ("is_tls" is not passed, because a
425 filter cannot modify it). Typically, the filter passes the same values
426 as it received, or passes readonly=true to provide a writable layer on
427 top of a read-only backend. However, it is also acceptable to attempt
428 write access to the plugin even if this filter is readonly, such as
429 when a file system mounted read-only still requires write access to the
430 underlying device in case a journal needs to be replayed for
431 consistency as part of the mounting process.
432 The "exportname" string is only guaranteed to be available during the
434 call (different than the lifetime for the return of
435 "nbdkit_export_name" used by plugins). If the filter needs to use it
436 (other than immediately passing it down to the next layer) it must take
437 a copy, although "nbdkit_strdup_intern" is useful for this task. The
438 "exportname" and "is_tls" parameters are provided so that filters do
439 not need to use the plugin-only interfaces of "nbdkit_export_name" and
440 "nbdkit_is_tls".
441 The filter should generally call "next" as its first step, to allocate
443 from the plugin outwards, so that ".close" running from the outer
444 filter to the plugin will be in reverse. Skipping a call to "next" is
445 acceptable if the filter will not access "next_ops" during any of the
446 remaining callbacks reached on the same connection.
447 ".close"
449 void (*close) (void *handle);
450 This is called when the client closes the connection. It should clean
452 up any per-connection resources used by the filter. It is called
453 beginning with the outermost filter and ending with the plugin (the
454 opposite order of ".open" if all filters call "next" first), although
455 this order technically does not matter since the callback cannot report
456 failures or access the underlying plugin.
457 ".prepare"
459 ".finalize"
460 int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
461 void *handle, int readonly);
462 int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
463 void *handle);
464 These two methods can be used to perform any necessary operations just
466 after opening the connection (".prepare") or just before closing the
467 connection (".finalize").
468 For example if you need to scan the underlying disk to check for a
470 partition table, you could do it in your ".prepare" method (calling the
471 plugin's ".get_size" and ".pread" methods via "next_ops"). Or if you
472 need to cleanly update superblock data in the image on close you can do
473 it in your ".finalize" method (calling the plugin's ".pwrite" method).
474 Doing these things in the filter's ".open" or ".close" method is not
475 possible.
476 For ".prepare", the value of "readonly" is the same as was passed to
478 ".open", declaring how this filter will be used.
479 Note that nbdkit performs sanity checking on requests made to the
481 underlying plugin; for example, "next_ops->pread" cannot be called on a
482 given connection unless "next_ops->get_size" has first been called at
483 least once in the same connection (to ensure the read requests are in
484 bounds), and "next_ops->pwrite" further requires an earlier successful
485 call to "next_ops->can_write". In many filters, these prerequisites
486 will be automatically called during the client negotiation phase, but
487 there are cases where a filter overrides query functions or makes I/O
488 calls into the plugin before handshaking is complete, where the filter
489 needs to make those prerequisite calls manually during ".prepare".
490 There is no "next_ops->prepare" or "next_ops->finalize". Unlike other
492 filter methods, prepare and finalize are not chained through the
493 "next_ops" structure. Instead the core nbdkit server calls the prepare
494 and finalize methods of all filters. Prepare methods are called
495 starting with the filter closest to the plugin and proceeding outwards
496 (matching the order of ".open" if all filters call "next" before doing
497 anything locally), and only when an outer filter did not skip the
498 "next" call during ".open". Finalize methods are called in the reverse
499 order of prepare methods, with the outermost filter first (and matching
500 the order of ".close"), and only if the prepare method succeeded.
501 If there is an error, both callbacks should call "nbdkit_error" with an
503 error message and return "-1". An error in ".prepare" is reported to
504 the client, but leaves the connection open (a client may try again with
505 a different export name, for example); while an error in ".finalize"
506 forces the client to disconnect.
507 ".get_size"
509 int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
510 void *handle);
511 This intercepts the plugin ".get_size" method and can be used to read
513 or modify the apparent size of the block device that the NBD client
514 will see.
515 The returned size must be ≥ 0. If there is an error, ".get_size"
517 should call "nbdkit_error" with an error message and return "-1". This
518 function is only called once per connection and cached by nbdkit.
519 Similarly, repeated calls to "next_ops->get_size" will return a cached
520 value.
521 ".export_description"
523 const char *export_description (struct nbdkit_next_ops *next_ops,
524 void *nxdata, void *handle);
525 This intercepts the plugin ".export_description" method and can be used
527 to read or modify the export description that the NBD client will see.
528 ".can_write"
530 ".can_flush"
531 ".is_rotational"
532 ".can_trim"
533 ".can_zero"
534 ".can_fast_zero"
535 ".can_extents"
536 ".can_fua"
537 ".can_multi_conn"
538 ".can_cache"
539 int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
540 void *handle);
541 int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
542 void *handle);
543 int (*is_rotational) (struct nbdkit_next_ops *next_ops,
544 void *nxdata,
545 void *handle);
546 int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
547 void *handle);
548 int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
549 void *handle);
550 int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
551 void *handle);
552 int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
553 void *handle);
554 int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
555 void *handle);
556 int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
557 void *handle);
558 int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
559 void *handle);
560 These intercept the corresponding plugin methods, and control feature
562 bits advertised to the client.
563 Of note, the semantics of ".can_zero" callback in the filter are
565 slightly different from the plugin, and must be one of three success
566 values visible only to filters:
567 "NBDKIT_ZERO_NONE"
569 Completely suppress advertisement of write zero support (this can
570 only be done from filters, not plugins).
571 "NBDKIT_ZERO_EMULATE"
573 Inform nbdkit that write zeroes should immediately fall back to
574 ".pwrite" emulation without trying ".zero" (this value is returned
575 by "next_ops->can_zero" if the plugin returned false in its
576 ".can_zero").
577 "NBDKIT_ZERO_NATIVE"
579 Inform nbdkit that write zeroes should attempt to use ".zero",
580 although it may still fall back to ".pwrite" emulation for
581 "ENOTSUP" or "EOPNOTSUPP" failures (this value is returned by
582 "next_ops->can_zero" if the plugin returned true in its
583 ".can_zero").
584 Remember that most of the feature check functions return merely a
586 boolean success value, while ".can_zero", ".can_fua" and ".can_cache"
587 have three success values.
588 The difference between ".can_fua" values may affect choices made in the
590 filter: when splitting a write request that requested FUA from the
591 client, if "next_ops->can_fua" returns "NBDKIT_FUA_NATIVE", then the
592 filter should pass the FUA flag on to each sub-request; while if it is
593 known that FUA is emulated by a flush because of a return of
594 "NBDKIT_FUA_EMULATE", it is more efficient to only flush once after all
595 sub-requests have completed (often by passing "NBDKIT_FLAG_FUA" on to
596 only the final sub-request, or by dropping the flag and ending with a
597 direct call to "next_ops->flush").
598 If there is an error, the callback should call "nbdkit_error" with an
600 error message and return "-1". These functions are called at most once
601 per connection and cached by nbdkit. Similarly, repeated calls to any
602 of the "next_ops" counterparts will return a cached value; by calling
603 into the plugin during ".prepare", you can ensure that later use of the
604 cached values during data commands like <.pwrite> will not fail.
605 ".pread"
607 int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
608 void *handle, void *buf, uint32_t count, uint64_t offset,
609 uint32_t flags, int *err);
610 This intercepts the plugin ".pread" method and can be used to read or
612 modify data read by the plugin.
613 The parameter "flags" exists in case of future NBD protocol extensions;
615 at this time, it will be 0 on input, and the filter should not pass any
616 flags to "next_ops->pread".
617 If there is an error (including a short read which couldn't be
619 recovered from), ".pread" should call "nbdkit_error" with an error
620 message and return -1 with "err" set to the positive errno value to
621 return to the client.
622 ".pwrite"
624 int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
625 void *handle,
626 const void *buf, uint32_t count, uint64_t offset,
627 uint32_t flags, int *err);
628 This intercepts the plugin ".pwrite" method and can be used to modify
630 data written by the plugin.
631 This function will not be called if ".can_write" returned false; in
633 turn, the filter should not call "next_ops->pwrite" if
634 "next_ops->can_write" did not return true.
635 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
637 the result of ".can_fua". In turn, the filter should only pass
638 "NBDKIT_FLAG_FUA" on to "next_ops->pwrite" if "next_ops->can_fua"
639 returned a positive value.
640 If there is an error (including a short write which couldn't be
642 recovered from), ".pwrite" should call "nbdkit_error" with an error
643 message and return -1 with "err" set to the positive errno value to
644 return to the client.
645 ".flush"
647 int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
648 void *handle, uint32_t flags, int *err);
649 This intercepts the plugin ".flush" method and can be used to modify
651 flush requests.
652 This function will not be called if ".can_flush" returned false; in
654 turn, the filter should not call "next_ops->flush" if
655 "next_ops->can_flush" did not return true.
656 The parameter "flags" exists in case of future NBD protocol extensions;
658 at this time, it will be 0 on input, and the filter should not pass any
659 flags to "next_ops->flush".
660 If there is an error, ".flush" should call "nbdkit_error" with an error
662 message and return -1 with "err" set to the positive errno value to
663 return to the client.
664 ".trim"
666 int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
667 void *handle, uint32_t count, uint64_t offset,
668 uint32_t flags, int *err);
669 This intercepts the plugin ".trim" method and can be used to modify
671 trim requests.
672 This function will not be called if ".can_trim" returned false; in
674 turn, the filter should not call "next_ops->trim" if
675 "next_ops->can_trim" did not return true.
676 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
678 the result of ".can_fua". In turn, the filter should only pass
679 "NBDKIT_FLAG_FUA" on to "next_ops->trim" if "next_ops->can_fua"
680 returned a positive value.
681 If there is an error, ".trim" should call "nbdkit_error" with an error
683 message and return -1 with "err" set to the positive errno value to
684 return to the client.
685 ".zero"
687 int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
688 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
689 int *err);
690 This intercepts the plugin ".zero" method and can be used to modify
692 zero requests.
693 This function will not be called if ".can_zero" returned
695 "NBDKIT_ZERO_NONE"; in turn, the filter should not call
696 "next_ops->zero" if "next_ops->can_zero" returned "NBDKIT_ZERO_NONE".
697 On input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
699 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
700 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
701 In turn, the filter may pass "NBDKIT_FLAG_MAY_TRIM" unconditionally,
702 but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
703 "next_ops->zero" if the corresponding "next_ops->can_fua" or
704 "next_ops->can_fast_zero" returned a positive value.
705 Note that unlike the plugin ".zero" which is permitted to fail with
707 "ENOTSUP" or "EOPNOTSUPP" to force a fallback to ".pwrite", the
708 function "next_ops->zero" will not fail with "err" set to "ENOTSUP" or
709 "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used, because otherwise
710 the fallback has already taken place.
711 If there is an error, ".zero" should call "nbdkit_error" with an error
713 message and return -1 with "err" set to the positive errno value to
714 return to the client. The filter should not fail with "ENOTSUP" or
715 "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO" (while
716 plugins have automatic fallback to ".pwrite", filters do not).
717 ".extents"
719 int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
720 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
721 struct nbdkit_extents *extents,
722 int *err);
723 This intercepts the plugin ".extents" method and can be used to modify
725 extent requests.
726 This function will not be called if ".can_extents" returned false; in
728 turn, the filter should not call "next_ops->extents" if
729 "next_ops->can_extents" did not return true.
730 It is possible for filters to transform the extents list received back
732 from the layer below. Without error checking it would look like this:
733 myfilter_extents (..., uint32_t count, uint64_t offset, ...)
735 {
736 size_t i;
737 struct nbdkit_extents *extents2;
738 struct nbdkit_extent e;
739 int64_t size;
740 size = next_ops->get_size (nxdata);
742 extents2 = nbdkit_extents_new (offset + shift, size);
743 next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
744 for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
745 e = nbdkit_get_extent (extents2, i);
746 e.offset -= shift;
747 nbdkit_add_extent (extents, e.offset, e.length, e.type);
748 }
749 nbdkit_extents_free (extents2);
750 }
751 If there is an error, ".extents" should call "nbdkit_error" with an
753 error message and return -1 with "err" set to the positive errno value
754 to return to the client.
755 Allocating and freeing nbdkit_extents list
757 Two functions are provided to filters only for allocating and freeing
759 the map:
760 struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);
762 Allocates and returns a new, empty extents list. The "start" parameter
764 is the start of the range described in the list, and the "end"
765 parameter is the offset of the byte beyond the end. Normally you would
766 pass in "offset" as the start and the size of the plugin as the end,
767 but for filters which adjust offsets, they should pass in the adjusted
768 offset.
769 On error this function can return "NULL". In this case it calls
771 "nbdkit_error" and/or "nbdkit_set_error" as required. "errno" will be
772 set to a suitable value.
773 void nbdkit_extents_free (struct nbdkit_extents *);
775 Frees an existing extents list.
777 Iterating over nbdkit_extents list
779 Two functions are provided to filters only to iterate over the extents
781 in order:
782 size_t nbdkit_extents_count (const struct nbdkit_extents *);
784 Returns the number of extents in the list.
786 struct nbdkit_extent {
788 uint64_t offset;
789 uint64_t length;
790 uint32_t type;
791 };
792 struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
793 size_t i);
794 Returns a copy of the "i"'th extent.
796 Enforcing alignment of an nbdkit_extents list
798 A convenience function is provided to filters only which makes it
800 easier to ensure that the client only encounters aligned extents.
801 int nbdkit_extents_aligned (struct nbdkit_next_ops *next_ops,
803 nbdkit_backend *nxdata,
804 uint32_t count, uint64_t offset,
805 uint32_t flags, uint32_t align,
806 struct nbdkit_extents *extents, int *err);
807 Calls next_ops->extents as needed until at least "align" bytes are
809 obtained, where "align" is a power of 2. Anywhere the underlying
810 plugin returns differing extents within "align" bytes, this function
811 treats that portion of the disk as a single extent with zero and sparse
812 status bits determined by the intersection of all underlying extents.
813 It is an error to call this function with "count" or "offset" that is
814 not already aligned.
815 ".cache"
817 int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
818 void *handle, uint32_t count, uint64_t offset,
819 uint32_t flags, int *err);
820 This intercepts the plugin ".cache" method and can be used to modify
822 cache requests.
823 This function will not be called if ".can_cache" returned
825 "NBDKIT_CACHE_NONE" or "NBDKIT_CACHE_EMULATE"; in turn, the filter
826 should not call "next_ops->cache" unless "next_ops->can_cache" returned
827 "NBDKIT_CACHE_NATIVE".
828 The parameter "flags" exists in case of future NBD protocol extensions;
830 at this time, it will be 0 on input, and the filter should not pass any
831 flags to "next_ops->cache".
832 If there is an error, ".cache" should call "nbdkit_error" with an error
834 message and return -1 with "err" set to the positive errno value to
835 return to the client.
836
838 If there is an error in the filter itself, the filter should call
839 "nbdkit_error" to report an error message. If the callback is involved
840 in serving data, the explicit "err" parameter determines the error code
841 that will be sent to the client; other callbacks should return the
842 appropriate error indication, eg. "NULL" or "-1".
843 "nbdkit_error" has the following prototype and works like printf(3):
845 void nbdkit_error (const char *fs, ...);
847 void nbdkit_verror (const char *fs, va_list args);
848 For convenience, "nbdkit_error" preserves the value of "errno", and
850 also supports the glibc extension of a single %m in a format string
851 expanding to "strerror(errno)", even on platforms that don't support
852 that natively.
853
855 Run the server with -f and -v options so it doesn't fork and you can
856 see debugging information:
857 nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]
859 To print debugging information from within the filter, call
861 "nbdkit_debug", which has the following prototype and works like
862 printf(3):
863 void nbdkit_debug (const char *fs, ...);
865 void nbdkit_vdebug (const char *fs, va_list args);
866 For convenience, "nbdkit_debug" preserves the value of "errno", and
868 also supports the glibc extension of a single %m in a format string
869 expanding to "strerror(errno)", even on platforms that don't support
870 that natively. Note that "nbdkit_debug" only prints things when the
871 server is in verbose mode (-v option).
872 Debug Flags
874 Debug Flags in filters work exactly the same way as plugins. See
875 "Debug Flags" in nbdkit-plugin(3).
876
878 The filter is a "*.so" file and possibly a manual page. You can of
879 course install the filter "*.so" file wherever you want, and users will
880 be able to use it by running:
881 nbdkit --filter=/path/to/filter.so plugin [args]
883 However if the shared library has a name of the form
885 "nbdkit-name-filter.so" and if the library is installed in the
886 $filterdir directory, then users can be run it by only typing:
887 nbdkit --filter=name plugin [args]
889 The location of the $filterdir directory is set when nbdkit is compiled
891 and can be found by doing:
892 nbdkit --dump-config
894 If using the pkg-config/pkgconf system then you can also find the
896 filter directory at compile time by doing:
897 pkg-config nbdkit --variable=filterdir
899
901 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
902 should be installed on the correct path when the nbdkit development
903 environment is installed. You can use this in autoconf configure.ac
904 scripts to test for the development environment:
905 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
907 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
909 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
910 for compiling filters.
911 You can also run pkg-config/pkgconf directly, for example:
913 if ! pkg-config nbdkit --exists; then
915 echo "you must install the nbdkit development environment"
916 exit 1
917 fi
918 You can also substitute the filterdir variable by doing:
920 PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])
922 which defines "$(NBDKIT_FILTERDIR)" in automake-generated Makefiles.
924
926 nbdkit(1), nbdkit-plugin(3).
927 Standard filters provided by nbdkit:
929 nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
931 nbdkit-cacheextents-filter(1), nbdkit-checkwrite-filter(1),
932 nbdkit-cow-filter(1), nbdkit-ddrescue-filter(1),
933 nbdkit-delay-filter(1), nbdkit-error-filter(1),
934 nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1),
935 nbdkit-exportname-filter(1), nbdkit-ext2-filter(1),
936 nbdkit-extentlist-filter(1), nbdkit-fua-filter(1),
937 nbdkit-gzip-filter(1), nbdkit-ip-filter(1), nbdkit-limit-filter(1),
938 nbdkit-log-filter(1), nbdkit-nocache-filter(1),
939 nbdkit-noextents-filter(1), nbdkit-nofilter-filter(1),
940 nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1),
941 nbdkit-offset-filter(1), nbdkit-partition-filter(1),
942 nbdkit-pause-filter(1), nbdkit-rate-filter(1),
943 nbdkit-readahead-filter(1), nbdkit-retry-filter(1),
944 nbdkit-stats-filter(1), nbdkit-swab-filter(1), nbdkit-tar-filter(1),
945 nbdkit-tls-fallback-filter(1), nbdkit-truncate-filter(1),
946 nbdkit-xz-filter(1) .
947
949 Eric Blake
950 Richard W.M. Jones
952
954 Copyright (C) 2013-2020 Red Hat Inc.
955
957 Redistribution and use in source and binary forms, with or without
958 modification, are permitted provided that the following conditions are
959 met:
960 · Redistributions of source code must retain the above copyright
962 notice, this list of conditions and the following disclaimer.
963 · Redistributions in binary form must reproduce the above copyright
965 notice, this list of conditions and the following disclaimer in the
966 documentation and/or other materials provided with the
967 distribution.
968 · Neither the name of Red Hat nor the names of its contributors may
970 be used to endorse or promote products derived from this software
971 without specific prior written permission.
972 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
974 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
975 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
976 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
977 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
978 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
979 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
980 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
981 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
982 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
983 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
984nbdkit-1.24.2 2021-03-02 nbdkit-filter(3)