docs/nbdkit-plugin.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 nbdkit-plugin - How to write nbdkit plugins
   6
   7 =head1 SYNOPSIS
   8
   9  #include <nbdkit-plugin.h>
  10
  11  #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
  12
  13  static void *
  14  myplugin_open (void)
  15  {
  16    /* create a handle ... */
  17    return handle;
  18  }
  19
  20  static struct nbdkit_plugin plugin = {
  21    .name              = "myplugin",
  22    .open              = myplugin_open,
  23    .get_size          = myplugin_get_size,
  24    .pread             = myplugin_pread,
  25    .pwrite            = myplugin_pwrite,
  26    /* etc */
  27  };
  28
  29  NBDKIT_REGISTER_PLUGIN(plugin)
  30
  31 When this has been compiled to a shared library, do:
  32
  33  nbdkit [--args ...] myplugin.so [key=value ...]
  34
  35 When debugging, use the I<-fv> options:
  36
  37  nbdkit -fv myplugin.so [key=value ...]
  38
  39 =head1 DESCRIPTION
  40
  41 An nbdkit plugin is a new source device which can be served using the
  42 Network Block Device (NBD) protocol.  This manual page describes how
  43 to create an nbdkit plugin.
  44
  45 For example plugins, take a look at the source of nbdkit, in the
  46 C<plugins> directory.
  47
  48 =head1 C<nbdkit-plugin.h>
  49
  50 All plugins should start by including this header file:
  51
  52  #include <nbdkit-plugin.h>
  53
  54 =head1 C<#define THREAD_MODEL>
  55
  56 All plugins must define a thread model.  See L</THREADS> below for
  57 details.  It is generally safe to use:
  58
  59  #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
  60
  61 =head1 C<struct nbdkit_plugin>
  62
  63 All plugins must define and register one C<struct nbdkit_plugin>,
  64 which contains the name of the plugin and pointers to callback
  65 functions.
  66
  67  static struct nbdkit_plugin plugin = {
  68    .name              = "myplugin",
  69    .longname          = "My Plugin",
  70    .description       = "This is my great plugin for nbdkit",
  71    .open              = myplugin_open,
  72    .get_size          = myplugin_get_size,
  73    .pread             = myplugin_pread,
  74    .pwrite            = myplugin_pwrite,
  75    /* etc */
  76  };
  77
  78  NBDKIT_REGISTER_PLUGIN(plugin)
  79
  80 The C<.name> field is the name of the plugin.
  81
  82 The callbacks are described below (see L</CALLBACKS>).  Only C<.name>,
  83 C<.open>, C<.get_size> and C<.pread> are required.  All other
  84 callbacks can be omitted.  However almost all plugins should have a
  85 C<.close> callback.  Most real-world plugins will also want to declare
  86 some of the other callbacks.
  87
  88 The nbdkit server calls the callbacks in the following order over the
  89 lifetime of the plugin:
  90
  91 =over 4
  92
  93 =item C<.load>
  94
  95 is called once just after the plugin is loaded into memory.
  96
  97 =item C<.config> and C<.config_complete>
  98
  99 C<.config> is called zero or more times during command line parsing.
 100 C<.config_complete> is called once after all configuration information
 101 has been passed to the plugin.
 102
 103 Both are called after loading the plugin but before any connections
 104 are accepted.
 105
 106 =item C<.open>
 107
 108 A new client has connected.
 109
 110 =item C<.can_write>, C<.get_size> and other option negotiation callbacks
 111
 112 These are called during option negotiation with the client, but
 113 before any data is served.
 114
 115 =item C<.pread>, C<.pwrite> and other data serving callbacks
 116
 117 After option negotiation has finished, these may be called to serve
 118 data.  Depending on the thread model chosen, they might be called in
 119 parallel from multiple threads.
 120
 121 =item C<.close>
 122
 123 The client has disconnected.
 124
 125 =item C<.open> ... C<.close>
 126
 127 The sequence C<.open> ... C<.close> can be called repeatedly over the
 128 lifetime of the plugin, and can be called in parallel (depending on
 129 the thread model).
 130
 131 =item C<.unload>
 132
 133 is called once just before the plugin is unloaded from memory.
 134
 135 =back
 136
 137 =head1 ERROR HANDLING
 138
 139 If there is an error in the plugin, the plugin should call
 140 C<nbdkit_error> with the error message, and then return an error
 141 indication from the callback, eg. NULL or -1.
 142
 143 C<nbdkit_error> has the following prototype and works like
 144 L<printf(3)>:
 145
 146  void nbdkit_error (const char *fs, ...);
 147
 148 =head1 FILENAMES AND PATHS
 149
 150 The server usually (not always) changes directory to C</> before it
 151 starts serving connections.  This means that any relative paths passed
 152 during configuration will not work when the server is running
 153 (example: S<C<nbdkit plugin.so file=disk.img>>).
 154
 155 To avoid problems, prepend relative paths with the current directory
 156 before storing them in the handle.  Or open files and store the file
 157 descriptor.
 158
 159 =head2 C<nbdkit_absolute_path>
 160
 161  char *nbdkit_absolute_path (const char *filename);
 162
 163 The utility function C<nbdkit_absolute_path> converts any path to an
 164 absolute path.
 165
 166 If conversion was not possible, this calls C<nbdkit_error> and returns
 167 C<NULL>.  Note that this function does not check that the file exists.
 168
 169 The returned string must be freed by the caller.
 170
 171 =head1 CALLBACKS
 172
 173 =head2 C<.name>
 174
 175  const char *name;
 176
 177 This field (a string) is required, and B<must> contain only ASCII
 178 alphanumeric characters and be unique amongst all plugins.
 179
 180 =head2 C<.version>
 181
 182  const char *version;
 183
 184 Plugins may optionally set a version string which is displayed in help
 185 and debugging output.
 186
 187 =head2 C<.longname>
 188
 189  const char *longname;
 190
 191 An optional free text name of the plugin.  This field is used in error
 192 messages.
 193
 194 =head2 C<.description>
 195
 196  const char *description;
 197
 198 An optional multi-line description of the plugin.
 199
 200 =head2 C<.load>
 201
 202  void load (void);
 203
 204 This is called once just after the plugin is loaded into memory.  You
 205 can use this to perform any global initialization needed by the
 206 plugin.
 207
 208 =head2 C<.unload>
 209
 210  void unload (void);
 211
 212 This may be called once just before the plugin is unloaded from
 213 memory.  Note that it's not guaranteed that C<.unload> will always be
 214 called (eg. the server might be killed or segfault), so you should try
 215 to make the plugin as robust as possible by not requiring cleanup.
 216
 217 =head2 C<.config>
 218
 219  int config (const char *key, const char *value);
 220
 221 On the nbdkit command line, after the plugin filename, come an
 222 optional list of C<key=value> arguments.  These are passed to the
 223 plugin through this callback when the plugin is first loaded and
 224 before any connections are accepted.
 225
 226 This callback may be called zero or more times.  Both C<key> and
 227 C<value> parameters will be non-NULL, but it is possible for either to
 228 be empty strings.  The strings are owned by nbdkit but will remain
 229 valid for the lifetime of the plugin, so the plugin does not need to
 230 copy them.
 231
 232 The format of the C<key> accepted by plugins is up to the plugin, but
 233 you should probably look at other plugins and follow the same
 234 conventions.
 235
 236 If the value is a relative path, then note that the server changes
 237 directory when it starts up.  See L</FILENAMES AND PATHS> above.
 238
 239 If the C<.config> callback is not provided by the plugin, and the user
 240 tries to specify any C<key=value> arguments, then nbdkit will exit
 241 with an error.
 242
 243 If there is an error, C<.config> should call C<nbdkit_error> with an
 244 error message and return C<-1>.
 245
 246 =head2 C<.config_complete>
 247
 248  int config_complete (void);
 249
 250 This optional callback is called after all the configuration has been
 251 passed to the plugin.  It is a good place to do checks, for example
 252 that the user has passed the required parameters to the plugin.
 253
 254 If there is an error, C<.config_complete> should call C<nbdkit_error>
 255 with an error message and return C<-1>.
 256
 257 =head2 C<.config_help>
 258
 259  const char *config_help;
 260
 261 This optional multi-line help message should summarize any
 262 C<key=value> parameters that it takes.  It does I<not> need to repeat
 263 what already appears in C<.description>.
 264
 265 If the plugin doesn't take any config parameters you should probably
 266 omit this.
 267
 268 =head2 C<.open>
 269
 270  void *open (int readonly);
 271
 272 This is called when a new client connects to the nbdkit server.  The
 273 callback should allocate a handle and return it.  This handle
 274 is passed back to other callbacks and could be freed in the C<.close>
 275 callback.
 276
 277 Note that the handle is completely opaque to nbdkit, but it must not
 278 be NULL.
 279
 280 The C<readonly> flag informs the plugin that the user requested a
 281 read-only connection using the I<-r> flag on the command line.  Note
 282 that the plugin may I<additionally> force the connection to be
 283 readonly (even if this flag is false) by returning false from the
 284 C<.can_write> callback.  So if your plugin can only serve read-only,
 285 you can ignore this parameter.
 286
 287 If there is an error, C<.open> should call C<nbdkit_error> with an
 288 error message and return C<NULL>.
 289
 290 =head2 C<.close>
 291
 292  void close (void *handle);
 293
 294 This is called when the client closes the connection.  It should clean
 295 up any per-connection resources.
 296
 297 Note there is no way in the NBD protocol to communicate close errors
 298 back to the client, for example if your plugin calls L<close(2)> and
 299 you are checking for errors (as you should do).  Therefore the best
 300 you can do is to log the error on the server.  Well-behaved NBD
 301 clients I<should> try to flush the connection before it is closed and
 302 check for errors, but obviously this is outside the scope of nbdkit.
 303
 304 =head2 C<.get_size>
 305
 306  int64_t get_size (void *handle);
 307
 308 This is called during the option negotiation phase of the protocol
 309 to get the size (in bytes) of the block device being exported.
 310
 311 The returned size must be E<ge> 0.  If there is an error, C<.get_size>
 312 should call C<nbdkit_error> with an error message and return C<-1>.
 313
 314 =head2 C<.can_write>
 315
 316  int can_write (void *handle);
 317
 318 This is called during the option negotiation phase to find out if the
 319 handle supports writes.
 320
 321 If there is an error, C<.can_write> should call C<nbdkit_error> with
 322 an error message and return C<-1>.
 323
 324 This callback is not required.  If omitted, then we return true iff a
 325 C<.pwrite> callback has been defined.
 326
 327 =head2 C<.can_flush>
 328
 329  int can_flush (void *handle);
 330
 331 This is called during the option negotiation phase to find out if the
 332 handle supports the flush-to-disk operation.
 333
 334 If there is an error, C<.can_flush> should call C<nbdkit_error> with
 335 an error message and return C<-1>.
 336
 337 This callback is not required.  If omitted, then we return true iff a
 338 C<.flush> callback has been defined.
 339
 340 =head2 C<.is_rotational>
 341
 342  int is_rotational (void *handle);
 343
 344 This is called during the option negotiation phase to find out if the
 345 backing disk is a rotational medium (like a disk) or not (like an
 346 SSD).  If true, this may cause the client to reorder requests to make
 347 them more efficient for a slow rotating disk.
 348
 349 If there is an error, C<.is_rotational> should call C<nbdkit_error>
 350 with an error message and return C<-1>.
 351
 352 This callback is not required.  If omitted, then we return false.
 353
 354 =head2 C<.can_trim>
 355
 356  int can_trim (void *handle);
 357
 358 This is called during the option negotiation phase to find out if the
 359 plugin supports the trim/discard operation for punching holes in the
 360 backing storage.
 361
 362 If there is an error, C<.can_trim> should call C<nbdkit_error> with an
 363 error message and return C<-1>.
 364
 365 This callback is not required.  If omitted, then we return true iff a
 366 C<.trim> callback has been defined.
 367
 368 =head2 C<.pread>
 369
 370  int pread (void *handle, void *buf, uint32_t count, uint64_t offset);
 371
 372 During the data serving phase, nbdkit calls this callback to read data
 373 from the backing store.  C<count> bytes starting at C<offset> in the
 374 backing store should be read and copied into C<buf>.  nbdkit takes
 375 care of all bounds- and sanity-checking, so the plugin does not need
 376 to worry about that.
 377
 378 The callback must read the whole C<count> bytes if it can.  The NBD
 379 protocol doesn't allow partial reads (instead, these would be errors).
 380 If the whole C<count> bytes was read, the callback should return C<0>
 381 to indicate there was I<no> error.
 382
 383 If there is an error (including a short read which couldn't be
 384 recovered from), C<.pread> should call C<nbdkit_error> with an error
 385 message and return C<-1>.
 386
 387 =head2 C<.pwrite>
 388
 389  int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset);
 390
 391 During the data serving phase, nbdkit calls this callback to write
 392 data to the backing store.  C<count> bytes starting at C<offset> in
 393 the backing store should be written using the data in C<buf>.  nbdkit
 394 takes care of all bounds- and sanity-checking, so the plugin does not
 395 need to worry about that.
 396
 397 The callback must write the whole C<count> bytes if it can.  The NBD
 398 protocol doesn't allow partial writes (instead, these would be
 399 errors).  If the whole C<count> bytes was written successfully, the
 400 callback should return C<0> to indicate there was I<no> error.
 401
 402 If there is an error (including a short write which couldn't be
 403 recovered from), C<.pwrite> should call C<nbdkit_error> with an error
 404 message and return C<-1>.
 405
 406 =head2 C<.flush>
 407
 408  int flush (void *handle);
 409
 410 During the data serving phase, this callback is used to
 411 L<fdatasync(2)> the backing store, ie. to ensure it has been
 412 completely written to a permanent medium.  If that is not possible
 413 then you can omit this callback.
 414
 415 If there is an error, C<.flush> should call C<nbdkit_error> with an
 416 error message and return C<-1>.
 417
 418 =head2 C<.trim>
 419
 420  int trim (void *handle, uint32_t count, uint64_t offset);
 421
 422 During the data serving phase, this callback is used to "punch holes"
 423 in the backing store.  If that is not possible then you can omit this
 424 callback.
 425
 426 If there is an error, C<.trim> should call C<nbdkit_error> with an
 427 error message and return C<-1>.
 428
 429 =head1 THREADS
 430
 431 Each nbdkit plugin must declare its thread safety model by defining
 432 the C<THREAD_MODEL> macro.  (This macro is used by
 433 C<NBDKIT_REGISTER_PLUGIN>).
 434
 435 The possible settings for C<THREAD_MODEL> are defined below.
 436
 437 =over 4
 438
 439 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS>
 440
 441 Only a single handle can be open at any time, and all requests happen
 442 from one thread.
 443
 444 Note this means only one client can connect to the server at any time.
 445 If a second client tries to connect it will block waiting for the
 446 first client to close the connection.
 447
 448 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>
 449
 450 I<This is a safe default for most plugins>.
 451
 452 Multiple handles can be open at the same time, but data requests are
 453 serialized so that for the plugin as a whole only one read/write/etc
 454 request will be in progress at any time.
 455
 456 This is a useful setting if the library you are using is not
 457 thread-safe.  However performance may not be good.
 458
 459 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS>
 460
 461 Multiple handles can be open and multiple data requests can happen in
 462 parallel.  However only one request will happen per handle at a time
 463 (but requests on different handles might happen concurrently).
 464
 465 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL>
 466
 467 Multiple handles can be open and multiple data requests can happen in
 468 parallel (even on the same handle).
 469
 470 All the libraries you use must be thread-safe and reentrant.  You may
 471 also need to provide mutexes for fields in your connection handle.
 472
 473 =back
 474
 475 If none of the above thread models are suitable, then use
 476 C<NBDKIT_THREAD_MODEL_PARALLEL> and implement your own locking using
 477 C<pthread_mutex_t> etc.
 478
 479 =head1 PARSING SIZE PARAMETERS
 480
 481 Use the C<nbdkit_parse_size> utility function to parse human-readable
 482 size strings such as "100M" into the size in bytes.
 483
 484  int64_t nbdkit_parse_size (const char *str);
 485
 486 C<str> can be a string in a number of common formats.  The function
 487 returns the size in bytes.  If there was an error, it returns C<-1>.
 488
 489 =head1 DEBUGGING
 490
 491 Run the server with I<-f> and I<-v> options so it doesn't fork and you
 492 can see debugging information:
 493
 494  nbdkit -fv myplugin.so [key=value [key=value [...]]]
 495
 496 To print debugging information from within the plugin, call
 497 C<nbdkit_debug>, which has the following prototype and works like
 498 L<printf(3)>:
 499
 500  void nbdkit_debug (const char *fs, ...);
 501
 502 Note that C<nbdkit_debug> only prints things when the server is in
 503 verbose mode (I<-v> option).
 504
 505 =head1 SEE ALSO
 506
 507 L<nbdkit(1)>,
 508 L<nbdkit-example1-plugin(1)>,
 509 L<nbdkit-example2-plugin(1)>,
 510 L<nbdkit-example3-plugin(1)>.
 511
 512 =head1 AUTHORS
 513
 514 Richard W.M. Jones
 515
 516 =head1 COPYRIGHT
 517
 518 Copyright (C) 2013 Red Hat Inc.
 519
 520 =head1 LICENSE
 521
 522 Redistribution and use in source and binary forms, with or without
 523 modification, are permitted provided that the following conditions are
 524 met:
 525
 526 =over 4
 527
 528 =item *
 529
 530 Redistributions of source code must retain the above copyright
 531 notice, this list of conditions and the following disclaimer.
 532
 533 =item *
 534
 535 Redistributions in binary form must reproduce the above copyright
 536 notice, this list of conditions and the following disclaimer in the
 537 documentation and/or other materials provided with the distribution.
 538
 539 =item *
 540
 541 Neither the name of Red Hat nor the names of its contributors may be
 542 used to endorse or promote products derived from this software without
 543 specific prior written permission.
 544
 545 =back
 546
 547 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 548 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 549 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 550 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 551 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 552 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 553 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 554 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 555 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 556 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 557 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 558 SUCH DAMAGE.