See also: https://www.redhat.com/archives/libguestfs/2020-July/msg00090.html --- docs/nbdkit-plugin.pod | 49 ++++++++++++++++++++++++++++++++++++---- docs/nbdkit-protocol.pod | 7 ++++-- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod index f8e9962a..6553d186 100644 --- a/docs/nbdkit-plugin.pod +++ b/docs/nbdkit-plugin.pod @@ -152,6 +152,9 @@ the plugin: │ preconnect │ │ └──────┬─────┘ │ ┌──────┴─────┐ │ + │list_exports│ │ + └──────┬─────┘ │ + ┌──────┴─────┐ │ │ open │ │ └──────┬─────┘ │ ┌──────┴─────┐ NBD option │ @@ -160,10 +163,10 @@ the plugin: ┌──────┴─────┐ ┌──────┴─────┐ client #2 │ get_size │ │ preconnect │ └──────┬─────┘ └──────┬─────┘ - ┌──────┴─────┐ data ┌──────┴─────┐ - │ pread │ serving │ open │ - └──────┬─────┘↺ └──────┬─────┘ - ┌──────┴─────┐ ... + ┌──────┴─────┐ data + │ pread │ serving + └──────┬─────┘↺ ... + ┌──────┴─────┐ │ pwrite │ └──────┬─────┘↺ ┌──────┴─────┐ ┌──────┴─────┐ │ close │ @@ -236,6 +239,12 @@ L<getpid(2)>. Called when a TCP connection has been made to the server. This happens early, before NBD or TLS negotiation. +=item C<.list_exports> + +Early in option negotiation the client may try to list the exports +served by the plugin, and plugins can optionally implement this +callback to answer the client. See L</EXPORT NAME> below. + =item C<.open> A new client has connected and finished the NBD handshake. TLS @@ -652,6 +661,38 @@ Returning C<0> will allow the connection to continue. If there is an error or you want to deny the connection, call C<nbdkit_error> with an error message and return C<-1>. +=head2 C<.list_exports> + + int list_exports (int readonly, struct nbdkit_exports *exports); + +This optional callback is called if the client tries to list the +exports served by the plugin (using C<NBD_OPT_LIST>). If the plugin +does not supply this callback then a single export called C<""> is +returned. The NBD protocol defines C<""> as the default export, so +this is suitable for plugins which ignore the export name and always +serve the same content. See also L</EXPORT NAME> below. + +The C<exports> parameter is an opaque object for collecting the list +of exports. Call C<nbdkit_add_export> to add a single export to the +list: + + int nbdkit_add_export (struct nbdkit_export *exports, + const char *name, const char *description); + +The C<name> must be a non-NULL, UTF-8 string no longer than 4096 +bytes. C<description> is an optional description of the export which +some clients can display but which is otherwise unused (if you don't +want a description, you can pass this parameter as C<NULL>). The +string(s) are copied into the exports list so you may free them +immediately after calling this function. + +The C<readonly> flag informs the plugin that the server was started +with the I<-r> flag on the command line. + +Returning C<0> will send the list of exports back to the client. If +there is an error, C<.list_exports> should call C<nbdkit_error> with +an error message and return C<-1>. + =head2 C<.open> void *open (int readonly); diff --git a/docs/nbdkit-protocol.pod b/docs/nbdkit-protocol.pod index e0e4042b..39b9481a 100644 --- a/docs/nbdkit-protocol.pod +++ b/docs/nbdkit-protocol.pod @@ -99,12 +99,15 @@ Supported in nbdkit E<ge> 1.1.12, and the default in nbdkit E<ge> 1.3. =item export names Partially supported in nbdkit E<ge> 1.1.12. Support for plugins to -read the client export name added in nbdkit E<ge> 1.15.2. +read the client export name added in nbdkit E<ge> 1.15.2. Support for +C<NBD_OPT_LIST> was added in nbdkit E<ge> 1.21.20. Versions of nbdkit before 1.16 could advertise a single export name to clients, specified through the now deprecated I<-e> option. In nbdkit 1.15.2, plugins could read the client requested export name using -C<nbdkit_export_name()> and serve different content. +C<nbdkit_export_name()> and serve different content. In nbdkit +1.21.20, plugins could implement C<.list_exports> to answer +C<NBD_OPT_LIST> queries. =item C<NBD_FLAG_NO_ZEROES> -- 2.27.0