[PATCH nbdkit] server: Deprecate the -e/--exportname parameter.
This parameter provided a name for the "default export" -- ie. the one and only export returned to the client by NBD_OPT_LIST. But nbdkit traditionally didn't care what export name the client requested. Since 1.16 plugins have been able to serve different content per export name (and return errors for unknown exports), but the -e option didn't reflect that and only created confusion. What we actually have to do is ask the plugin what exports it provides and return that list to the client. This is for future work. This commit deprecates and hides the parameter. If used the option now does nothing at all. There are some visible but very minor changes resulting from this commit: (1) NBD_OPT_LIST advertises a single export called "" (instead of the -e parameter). We intend to replace this implementation soon with a correct one. (2) The --run option no longer sets $exportname (to -e) nor puts the export name into the $uri. However this was always the wrong thing to do since export names are per connection, not per server. Existing --run scripts will see $exportname expand to "" which is most likely what they saw before and overwhelmingly more likely to be correct than if the -e option had been used. (3) The -e option had the side-effect of forcing the newstyle protocol, so weirdly this worked and made the server use newstyle: nbdkit -o -e '' ... but this would fail with an error at start-up: nbdkit -e '' -o ... I thought it best to remove this odd behaviour completely. (4) I have temporarily disabled tests/test-long-name.sh. This is still a valid test, but we will have to rewrite it to use (probably) sh or eval plugins once we have an implementation of list_exports. --- docs/nbdkit-captive.pod | 12 ++---------- docs/nbdkit-protocol.pod | 15 +++++++-------- docs/nbdkit.pod | 13 ------------- docs/synopsis.txt | 3 +-- server/internal.h | 1 - server/captive.c | 18 +----------------- server/main.c | 21 +-------------------- server/protocol-handshake-newstyle.c | 12 +++++++++--- tests/test-data-7E.sh | 2 +- tests/test-data-raw.sh | 3 +-- tests/test-long-name.sh | 4 ++++ 11 files changed, 27 insertions(+), 77 deletions(-) diff --git a/docs/nbdkit-captive.pod b/docs/nbdkit-captive.pod index 09628367..66c5c81c 100644 --- a/docs/nbdkit-captive.pod +++ b/docs/nbdkit-captive.pod @@ -47,14 +47,12 @@ The following shell variables are available in the I<--run> argument: =item C<$uri> A URI that refers to the nbdkit port or socket in the preferred form -documented by the NBD project. If nbdkit was started with the B<-e> -option to set the preferred export name, this is included in the URI. +documented by the NBD project. =item C<$nbd> An older URL that refers to the nbdkit port or socket in a manner -specific to certain tools. This form does not include an export name, -even if B<-e> was used. +specific to certain tools. Note there is some magic here, since qemu and guestfish URLs have a different format, so nbdkit tries to guess which you are running. If @@ -68,12 +66,6 @@ If E<ne> "", the port number that nbdkit is listening on. If E<ne> "", the Unix domain socket that nbdkit is listening on. -=item C<$exportname> - -The default export name (which may be "") that nbdkit will advertise -in response to NBD_OPT_LIST. This comes from the B<-e> -(B<--exportname>) command line option. - =back I<--run> implies I<--foreground>. It is not possible, and probably diff --git a/docs/nbdkit-protocol.pod b/docs/nbdkit-protocol.pod index d90993fb..172d1326 100644 --- a/docs/nbdkit-protocol.pod +++ b/docs/nbdkit-protocol.pod @@ -5,7 +5,7 @@ nbdkit - which parts of the NBD protocol nbdkit supports =head1 SYNOPSIS nbdkit [-n|--newstyle] [--mask-handshake MASK] [--no-sr] [-o|--oldstyle] - [-e|--exportname EXPORTNAME] [...] + [...] =head1 DESCRIPTION @@ -29,9 +29,6 @@ can support (in some cases, this can be limited by what callbacks the plugin handles), even if the client does not negotiate to use all advertised features. -Use the I<-e> or I<--exportname> flag to set the optional exportname -for the newstyle protocol. - Nbdkit also includes some options that are useful mainly when performing integration tests, for proving whether clients have sane fallback behavior when dealing various older servers permitted by the @@ -101,11 +98,13 @@ Supported in nbdkit E<ge> 1.1.12, and the default in nbdkit E<ge> 1.3. =item export names -Supported in nbdkit E<ge> 1.1.12. +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. -nbdkit can advertise an export name, but ignores any export name sent -by the client. nbdkit does I<not> support serving different data on -different export names. +Versions of nbdkit before 1.16 could advertize 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. =item C<NBD_FLAG_NO_ZEROES> diff --git a/docs/nbdkit.pod b/docs/nbdkit.pod index a6cf988c..b204709b 100644 --- a/docs/nbdkit.pod +++ b/docs/nbdkit.pod @@ -214,19 +214,6 @@ An alternative to this is L<nbdkit-captive(1)/CAPTIVE NBDKIT>. This option implies I<--foreground>. -=item B<-e> EXPORTNAME - -=item B<--export> EXPORTNAME - -=item B<--export-name> EXPORTNAME - -=item B<--exportname> EXPORTNAME - -Set the exportname. - -If not set, exportname C<""> (empty string) is used. Exportnames are -not allowed with the oldstyle protocol. - =item B<-f> =item B<--foreground> diff --git a/docs/synopsis.txt b/docs/synopsis.txt index 07b9dcff..caf49922 100644 --- a/docs/synopsis.txt +++ b/docs/synopsis.txt @@ -1,5 +1,4 @@ -nbdkit [-D|--debug PLUGIN|FILTER|nbdkit.FLAG=N] - [-e|--exportname EXPORTNAME] [--exit-with-parent] +nbdkit [-D|--debug PLUGIN|FILTER|nbdkit.FLAG=N] [--exit-with-parent] [--filter FILTER ...] [-f|--foreground] [-g|--group GROUP] [-i|--ipaddr IPADDR] [--log stderr|syslog|null] diff --git a/server/internal.h b/server/internal.h index 68c53366..ebc63a52 100644 --- a/server/internal.h +++ b/server/internal.h @@ -108,7 +108,6 @@ enum log_to { }; extern struct debug_flag *debug_flags; -extern const char *exportname; extern bool foreground; extern const char *ipaddr; extern enum log_to log_to; diff --git a/server/captive.c b/server/captive.c index f8107604..aa717870 100644 --- a/server/captive.c +++ b/server/captive.c @@ -61,8 +61,6 @@ run_command (void) if (!run) return; - assert (exportname != NULL); - fp = open_memstream (&cmd, &len); if (fp == NULL) { perror ("open_memstream"); @@ -74,27 +72,13 @@ run_command (void) if (port) { fprintf (fp, "nbd://localhost:"); shell_quote (port, fp); - if (strcmp (exportname, "") != 0) { - putc ('/', fp); - uri_quote (exportname, fp); - } } else if (unixsocket) { - fprintf (fp, "nbd+unix://"); - if (strcmp (exportname, "") != 0) { - putc ('/', fp); - uri_quote (exportname, fp); - } - fprintf (fp, "\\?socket="); + fprintf (fp, "nbd+unix://\\?socket="); uri_quote (unixsocket, fp); } putc ('\n', fp); - /* Expose $exportname. */ - fprintf (fp, "exportname="); - shell_quote (exportname, fp); - putc ('\n', fp); - /* Construct older $nbd "URL". Unfortunately guestfish and qemu take * different syntax, so try to guess which one we need. */ diff --git a/server/main.c b/server/main.c index c432f5bd..d815fe12 100644 --- a/server/main.c +++ b/server/main.c @@ -79,7 +79,6 @@ static bool is_config_key (const char *key, size_t len); struct debug_flag *debug_flags; /* -D */ bool exit_with_parent; /* --exit-with-parent */ -const char *exportname; /* -e */ bool foreground; /* -f */ const char *ipaddr; /* -i */ enum log_to log_to = LOG_TO_DEFAULT; /* --log */ @@ -345,13 +344,7 @@ main (int argc, char *argv[]) break; case 'e': - exportname = optarg; - if (strnlen (exportname, NBD_MAX_STRING + 1) > NBD_MAX_STRING) { - nbdkit_error ("export name too long"); - exit (EXIT_FAILURE); - } - /* TODO: Check that name is valid UTF-8? */ - newstyle = true; + /* Does nothing, ignored for compatibility with older nbdkit. */ break; case 'f': @@ -487,18 +480,6 @@ main (int argc, char *argv[]) exit (EXIT_FAILURE); } - /* Oldstyle protocol + exportname not allowed. */ - if (!newstyle && exportname != NULL) { - fprintf (stderr, - "%s: cannot use oldstyle protocol (-o) and exportname (-e)\n", - program_name); - exit (EXIT_FAILURE); - } - - /* If exportname was not set on the command line, use "". */ - if (exportname == NULL) - exportname = ""; - /* --tls=require and oldstyle won't work. */ if (tls == 2 && !newstyle) { fprintf (stderr, diff --git a/server/protocol-handshake-newstyle.c b/server/protocol-handshake-newstyle.c index 192d00f3..fa44f253 100644 --- a/server/protocol-handshake-newstyle.c +++ b/server/protocol-handshake-newstyle.c @@ -75,12 +75,15 @@ send_newstyle_option_reply (uint32_t option, uint32_t reply) return 0; } +/* Reply to NBD_OPT_LIST with a single empty export name. + * TODO: Ask the plugin for the list of exports. + */ static int send_newstyle_option_reply_exportname (uint32_t option, uint32_t reply) { GET_CONN; struct nbd_fixed_new_option_reply fixed_new_option_reply; - size_t name_len = strlen (exportname); + const size_t name_len = 0; /* length of export name */ uint32_t len; fixed_new_option_reply.magic = htobe64 (NBD_REP_MAGIC); @@ -100,11 +103,14 @@ send_newstyle_option_reply_exportname (uint32_t option, uint32_t reply) name_of_nbd_opt (option), "sending length"); return -1; } +#if 0 + /* If we were sending a non-"" export name, this is what we'd use. */ if (conn->send (exportname, name_len, 0) == -1) { nbdkit_error ("write: %s: %s: %m", name_of_nbd_opt (option), "sending export name"); return -1; } +#endif return 0; } @@ -364,8 +370,8 @@ negotiate_handshake_newstyle_options (void) } /* Send back the exportname. */ - debug ("newstyle negotiation: %s: advertising export '%s'", - name_of_nbd_opt (option), exportname); + debug ("newstyle negotiation: %s: advertising export \"\"", + name_of_nbd_opt (option)); if (send_newstyle_option_reply_exportname (option, NBD_REP_SERVER) == -1) return -1; diff --git a/tests/test-data-7E.sh b/tests/test-data-7E.sh index e06d3c7e..c4fa86b1 100755 --- a/tests/test-data-7E.sh +++ b/tests/test-data-7E.sh @@ -45,7 +45,7 @@ rm -f $files cleanup_fn rm -f $files # Run nbdkit. -start_nbdkit -P data-7E.pid -U $sock --export= \ +start_nbdkit -P data-7E.pid -U $sock \ --filter=partition \ data size=7E partition=1 \ data=" diff --git a/tests/test-data-raw.sh b/tests/test-data-raw.sh index 36ee8028..446e2093 100755 --- a/tests/test-data-raw.sh +++ b/tests/test-data-raw.sh @@ -44,8 +44,7 @@ rm -f $files cleanup_fn rm -f $files # Run nbdkit. -start_nbdkit -P data-raw.pid -U $sock --export "" \ - data raw=123 size=512 +start_nbdkit -P data-raw.pid -U $sock data raw=123 size=512 nbdsh --connect "nbd+unix://?socket=$sock" \ -c ' diff --git a/tests/test-long-name.sh b/tests/test-long-name.sh index 6a512603..f70f492d 100755 --- a/tests/test-long-name.sh +++ b/tests/test-long-name.sh @@ -38,6 +38,10 @@ fail=0 # Test handling of NBD maximum string length of 4k. +echo "$0: This test needs to be rewritten to use alternate method to" +echo "send back the export name to the client." +exit 77 + requires qemu-io --version requires qemu-nbd --version requires nbdsh -c 'exit(not h.supports_uri())' -- 2.27.0
On 7/21/20 10:10 AM, Richard W.M. Jones wrote:
This parameter provided a name for the "default export" -- ie. the one and only export returned to the client by NBD_OPT_LIST. But nbdkit traditionally didn't care what export name the client requested. Since 1.16 plugins have been able to serve different content per export name (and return errors for unknown exports), but the -e option didn't reflect that and only created confusion.
What we actually have to do is ask the plugin what exports it provides and return that list to the client. This is for future work.
This commit deprecates and hides the parameter. If used the option now does nothing at all.
There are some visible but very minor changes resulting from this commit:
(1) NBD_OPT_LIST advertises a single export called "" (instead of the -e parameter). We intend to replace this implementation soon with a correct one.
And in the meantime, we still allow clients to connect with any name at all, and that still makes no difference for plugins that don't read the client's request.
(2) The --run option no longer sets $exportname (to -e) nor puts the export name into the $uri. However this was always the wrong thing to do since export names are per connection, not per server. Existing --run scripts will see $exportname expand to "" which is most likely what they saw before and overwhelmingly more likely to be correct than if the -e option had been used.
(3) The -e option had the side-effect of forcing the newstyle protocol, so weirdly this worked and made the server use newstyle:
nbdkit -o -e '' ...
but this would fail with an error at start-up:
nbdkit -e '' -o ...
I thought it best to remove this odd behaviour completely.
If we wanted, we could mandate that if -o is in effect, any use of -e must be '' (that's what I did in qemu-nbd prior to when I ripped old-style protocol out completely; and it is similar to what 'qemu-nbd --list' does - basically, the code is most consistent when it pretends that the export name for any old-style connection is "", rather than forbidden). But I'm also fine with just dropping the odd behavior (-e is now a no-op, whether you use new- or old-style).
(4) I have temporarily disabled tests/test-long-name.sh. This is still a valid test, but we will have to rewrite it to use (probably) sh or eval plugins once we have an implementation of list_exports. ---
--- a/docs/nbdkit-captive.pod
-nbdkit can advertise an export name, but ignores any export name sent -by the client. nbdkit does I<not> support serving different data on -different export names. +Versions of nbdkit before 1.16 could advertize a single export name to
advertise (particularly since that was the spelling in the previous text).
+++ b/server/captive.c @@ -61,8 +61,6 @@ run_command (void) if (!run) return;
- assert (exportname != NULL); - fp = open_memstream (&cmd, &len); if (fp == NULL) { perror ("open_memstream"); @@ -74,27 +72,13 @@ run_command (void) if (port) { fprintf (fp, "nbd://localhost:"); shell_quote (port, fp); - if (strcmp (exportname, "") != 0) { - putc ('/', fp); - uri_quote (exportname, fp); - } } else if (unixsocket) { - fprintf (fp, "nbd+unix://"); - if (strcmp (exportname, "") != 0) { - putc ('/', fp); - uri_quote (exportname, fp); - } - fprintf (fp, "\\?socket="); + fprintf (fp, "nbd+unix://\\?socket="); uri_quote (unixsocket, fp); }
Hmm. When we do allow plugins to advertise exportnames, we'll probably want a way to specify the right exportname (suppose a plugin advertises both "a" and "b" and serves different content accordingly, --run then has to know which one to go with, rather than assuming "" will work). But I don't mind that being for later.
putc ('\n', fp);
- /* Expose $exportname. */ - fprintf (fp, "exportname="); - shell_quote (exportname, fp); - putc ('\n', fp); -
This breaks anyone that does 'set -u' in a shell script, or where --run triggers a binary that then calls getenv("exportname") and expects a non-NULL value. I'd still leave 'exportname=\n' in the --run command line, to guarantee it is set but empty. Otherwise makes sense to me. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On 7/21/20 12:46 PM, Eric Blake wrote:
(2) The --run option no longer sets $exportname (to -e) nor puts the export name into the $uri. However this was always the wrong thing to do since export names are per connection, not per server. Existing --run scripts will see $exportname expand to "" which is most likely what they saw before and overwhelmingly more likely to be correct than if the -e option had been used.
The more I think about it, the more I disagree with disabling this. Or, put another way, I think that the _only_ time -e makes sense is _when_ you are using --run. Consider: nbdkit -U - -e foo info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"' nbdkit -U - -e bar info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"' Of course, you can accomplish the same with: nbdkit -U - info --run 'nbdsh -u nbd+unix:///foo\?socket=$unixsocket \ -c "print(h.pread(3, 0))"' but that's a lot more painful to write. We _don't_ need to advertise 'foo' or 'bar' over NBD_OPT_INFO (at least, not for plugins that don't implement the forthcoming .export_list callback), but _do_ need a way for the captive application (nbdsh in this case) to know _which_ export the captive should connect to. And, if we reinstate _just_ that usage of -e,...
(4) I have temporarily disabled tests/test-long-name.sh. This is still a valid test, but we will have to rewrite it to use (probably) sh or eval plugins once we have an implementation of list_exports. ---
...we may not have to disable this test after all. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On Tue, Jul 21, 2020 at 07:51:29PM -0500, Eric Blake wrote:
On 7/21/20 12:46 PM, Eric Blake wrote:
(2) The --run option no longer sets $exportname (to -e) nor puts the export name into the $uri. However this was always the wrong thing to do since export names are per connection, not per server. Existing --run scripts will see $exportname expand to "" which is most likely what they saw before and overwhelmingly more likely to be correct than if the -e option had been used.
The more I think about it, the more I disagree with disabling this. Or, put another way, I think that the _only_ time -e makes sense is _when_ you are using --run. Consider:
nbdkit -U - -e foo info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"' nbdkit -U - -e bar info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"'
Of course, you can accomplish the same with:
nbdkit -U - info --run 'nbdsh -u nbd+unix:///foo\?socket=$unixsocket \ -c "print(h.pread(3, 0))"'
but that's a lot more painful to write.
We _don't_ need to advertise 'foo' or 'bar' over NBD_OPT_INFO (at least, not for plugins that don't implement the forthcoming .export_list callback), but _do_ need a way for the captive application (nbdsh in this case) to know _which_ export the captive should connect to.
And, if we reinstate _just_ that usage of -e,...
(4) I have temporarily disabled tests/test-long-name.sh. This is still a valid test, but we will have to rewrite it to use (probably) sh or eval plugins once we have an implementation of list_exports. ---
...we may not have to disable this test after all.
I feel for the end user this is all pretty confusing and requires them to have some insight into what the plugin is expecting and even understanding of the protocol. Perhaps we should have a rule something like this: - plugins should serve default content on the "" export - unless they implement .list_exports, in which case the first export returned is the default export Then we could implement --run transparently by having it set $exportname/$uri to the first entry in .list_exports or "" if .list_exports is not implemented. Here's another idea: Is it possible that if the --run script itself overrides exportname it could be used by $uri. Not sure if there's some kind of delayed shell variable expansion that would make this possible: nbdkit ... --run 'exportname=foo; nbdsh -u $uri ...' Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-builder quickly builds VMs from scratch http://libguestfs.org/virt-builder.1.html
On 7/22/20 4:02 AM, Richard W.M. Jones wrote:
The more I think about it, the more I disagree with disabling this. Or, put another way, I think that the _only_ time -e makes sense is _when_ you are using --run. Consider:
nbdkit -U - -e foo info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"' nbdkit -U - -e bar info --run 'nbdsh -u $uri -c "print(h.pread(3, 0))"'
Of course, you can accomplish the same with:
nbdkit -U - info --run 'nbdsh -u nbd+unix:///foo\?socket=$unixsocket \ -c "print(h.pread(3, 0))"'
but that's a lot more painful to write.
We _don't_ need to advertise 'foo' or 'bar' over NBD_OPT_INFO (at least, not for plugins that don't implement the forthcoming .export_list callback), but _do_ need a way for the captive application (nbdsh in this case) to know _which_ export the captive should connect to.
And, if we reinstate _just_ that usage of -e,...
(4) I have temporarily disabled tests/test-long-name.sh. This is still a valid test, but we will have to rewrite it to use (probably) sh or eval plugins once we have an implementation of list_exports. ---
...we may not have to disable this test after all.
I feel for the end user this is all pretty confusing and requires them to have some insight into what the plugin is expecting and even understanding of the protocol.
Perhaps we should have a rule something like this:
- plugins should serve default content on the "" export
- unless they implement .list_exports, in which case the first export returned is the default export
That could be expensive, reading the entire list and throwing away all but the first. I'm now leaning towards two callbacks: .list_exports: compute all exports to advertise .default_export: compute the name to be returned for NBD_OPT_INFO("") and to use by default as $exportname in --run Then, any plugin that wants to advertise a different default export name supplies .default_export, and if .default_export is missing, we supply "" on their behalf. We could also translate a client request for "" into .default_export before calling .open (v3) or populating nbdkit_export_name (v2) (I could see that mattering for the file plugin with a mode that serves all files in a directory, since stat("") fails but providing a default filename as the largest file in the directory could be useful).
Then we could implement --run transparently by having it set $exportname/$uri to the first entry in .list_exports or "" if .list_exports is not implemented.
Here's another idea: Is it possible that if the --run script itself overrides exportname it could be used by $uri. Not sure if there's some kind of delayed shell variable expansion that would make this possible:
nbdkit ... --run 'exportname=foo; nbdsh -u $uri ...'
Not as written, but we _can_ do the following. Right now, --run creates a shell fragment, which prepends this code in front of the user's: uri=... nbd=... ... exportname=... we could instead prepend: set_export() { uri=... nbd=... ... exportname=$1 } set_export ... where that last line uses .default_export (defaulting to "" as usual). The user can now run: nbdkit ... --run 'set_export foo; nbdsh -u "$uri" ... ' Oh, and I just realized, because $uri can contain ?, we really should scrub all uses in the tree to always write it as "$uri" rather than unquoted, just to set a good example. (It's unlikely that anyone would ever have a subdirectory named 'nbd+unix:' in their current working directory to the point that the ? would trigger unintended globbing, but better safe than sorry...) -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On Wed, Jul 22, 2020 at 06:12:30AM -0500, Eric Blake wrote:
On 7/22/20 4:02 AM, Richard W.M. Jones wrote:
Perhaps we should have a rule something like this:
- plugins should serve default content on the "" export
- unless they implement .list_exports, in which case the first export returned is the default export
That could be expensive, reading the entire list and throwing away all but the first. I'm now leaning towards two callbacks:
.list_exports: compute all exports to advertise .default_export: compute the name to be returned for NBD_OPT_INFO("") and to use by default as $exportname in --run
Maybe I don't understand this, but isn't NBD_OPT_INFO("") explicitly asking for info about the "" export name? In what situation would .default_export ever return anything other than ""?
Then, any plugin that wants to advertise a different default export name supplies .default_export, and if .default_export is missing, we supply "" on their behalf. We could also translate a client request for "" into .default_export before calling .open (v3) or populating nbdkit_export_name (v2) (I could see that mattering for the file plugin with a mode that serves all files in a directory, since stat("") fails but providing a default filename as the largest file in the directory could be useful).
Then we could implement --run transparently by having it set $exportname/$uri to the first entry in .list_exports or "" if .list_exports is not implemented.
Here's another idea: Is it possible that if the --run script itself overrides exportname it could be used by $uri. Not sure if there's some kind of delayed shell variable expansion that would make this possible:
nbdkit ... --run 'exportname=foo; nbdsh -u $uri ...'
Not as written, but we _can_ do the following. Right now, --run creates a shell fragment, which prepends this code in front of the user's:
uri=... nbd=... ... exportname=...
we could instead prepend:
set_export() { uri=... nbd=... ... exportname=$1 } set_export ...
where that last line uses .default_export (defaulting to "" as usual). The user can now run:
nbdkit ... --run 'set_export foo; nbdsh -u "$uri" ... '
Cure is beginning to sound worse than the disease. We can bring back -e but only for the narrow use case of specifying an export name for --run and with lots of documentation about why it's needed.
Oh, and I just realized, because $uri can contain ?, we really should scrub all uses in the tree to always write it as "$uri" rather than unquoted, just to set a good example. (It's unlikely that anyone would ever have a subdirectory named 'nbd+unix:' in their current working directory to the point that the ? would trigger unintended globbing, but better safe than sorry...)
Yes indeed. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com libguestfs lets you edit virtual machines. Supports shell scripting, bindings from many languages. http://libguestfs.org
On 7/22/20 6:25 AM, Richard W.M. Jones wrote:
On Wed, Jul 22, 2020 at 06:12:30AM -0500, Eric Blake wrote:
On 7/22/20 4:02 AM, Richard W.M. Jones wrote:
Perhaps we should have a rule something like this:
- plugins should serve default content on the "" export
- unless they implement .list_exports, in which case the first export returned is the default export
That could be expensive, reading the entire list and throwing away all but the first. I'm now leaning towards two callbacks:
.list_exports: compute all exports to advertise .default_export: compute the name to be returned for NBD_OPT_INFO("") and to use by default as $exportname in --run
Maybe I don't understand this, but isn't NBD_OPT_INFO("") explicitly asking for info about the "" export name? In what situation would .default_export ever return anything other than ""?
The NBD protocol permits it in replies to NBD_OPT_INFO: * `NBD_INFO_NAME` (1) Represents the server's canonical name of the export. The name MAY differ from the name presented in the client's option request, and the information item MAY be omitted if the client option request already used the canonical name. This information type represents the same name that would appear in the name portion of an `NBD_REP_SERVER` in response to `NBD_OPT_LIST`. That is, when I added NBD_OPT_INFO to the NBD protocol, I specifically envisioned a server where if the client asks "I want the default export, what am I going to be served?" the server can then reply with a canonical name rather than "".
we could instead prepend:
set_export() { uri=... nbd=... ... exportname=$1 } set_export ...
where that last line uses .default_export (defaulting to "" as usual). The user can now run:
nbdkit ... --run 'set_export foo; nbdsh -u "$uri" ... '
Cure is beginning to sound worse than the disease. We can bring back -e but only for the narrow use case of specifying an export name for --run and with lots of documentation about why it's needed.
Yep, now you see why I was starting to complain that we were premature on crippling -e with --run.
Oh, and I just realized, because $uri can contain ?, we really should scrub all uses in the tree to always write it as "$uri" rather than unquoted, just to set a good example. (It's unlikely that anyone would ever have a subdirectory named 'nbd+unix:' in their current working directory to the point that the ? would trigger unintended globbing, but better safe than sorry...)
Yes indeed.
As that's an easy scrub, I'll probably complete it momentarily. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
I realise I forgot the update the filter documentation, so the patch below has been squashed into my copy. The filter documentation probably needs a review to make sure it is up to date as certain functions like reopen are missing. Rich. diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod index acac3e50..f0ff9ef2 100644 --- a/docs/nbdkit-filter.pod +++ b/docs/nbdkit-filter.pod @@ -329,7 +329,7 @@ an error message and return C<-1>. =head2 C<.open> void * (*open) (nbdkit_next_open *next, void *nxdata, - int readonly); + int readonly, const char *exportname); This is called when a new client connection is opened and can be used to allocate any per-connection data structures needed by the filter. @@ -345,17 +345,22 @@ If there is an error, C<.open> should call C<nbdkit_error> with an error message and return C<NULL>. This callback is optional, but if provided, it must call C<next>, -passing a value for C<readonly> according to how the filter plans to -use the plugin. Typically, the filter passes the same value as it -received, or passes true to provide a writable layer on top of a -read-only backend. However, it is also acceptable to attempt write -access to the plugin even if this filter is readonly, such as when a -file system mounted read-only still requires write access to the -underlying device in case a journal needs to be replayed for -consistency as part of the mounting process. The filter should -generally call C<next> as its first step, to allocate from the plugin -outwards, so that C<.close> running from the outer filter to the -plugin will be in reverse. +passing C<readonly> and C<exportname> possibly modified according to +how the filter plans to use the plugin. Typically, the filter passes +the same values as it received, or passes readonly=true to provide a +writable layer on top of a read-only backend. However, it is also +acceptable to attempt write access to the plugin even if this filter +is readonly, such as when a file system mounted read-only still +requires write access to the underlying device in case a journal needs +to be replayed for consistency as part of the mounting process. + +The C<exportname> string is only guaranteed to be available during the +call. If the filter needs to use it (other than immediately passing +it down to the next layer) it must take a copy. + +The filter should generally call C<next> as its first step, to +allocate from the plugin outwards, so that C<.close> running from the +outer filter to the plugin will be in reverse. =head2 C<.close> -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into KVM guests. http://libguestfs.org/virt-v2v
participants (2)
-
Eric Blake -
Richard W.M. Jones