[PATCH] docs: qsd: Explain --export nbd,name=... default

[PATCH] docs: qsd: Explain --export nbd,name=... default

[Kevin Wolf]

The 'name' option for NBD exports is optional. Add a note that the
default for the option is the node name (people could otherwise expect
that it's the empty string like for qemu-nbd).

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 docs/tools/qemu-storage-daemon.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
index fe3042d609..086493ebb3 100644
--- a/docs/tools/qemu-storage-daemon.rst
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -80,8 +80,9 @@ Standard options:
   requests for modifying data (the default is off).
 
   The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
-  the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
-  the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
+  the NBD export name (if not specified, it defaults to the given
+  ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
+  block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
   metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
 
   The ``vhost-user-blk`` export type takes a vhost-user socket address on which
-- 
2.29.2

Re: [PATCH] docs: qsd: Explain --export nbd,name=... default

[Max Reitz]

On 05.03.21 10:48, Kevin Wolf wrote:
> The 'name' option for NBD exports is optional. Add a note that the
> default for the option is the node name (people could otherwise expect
> that it's the empty string like for qemu-nbd).
> 
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>   docs/tools/qemu-storage-daemon.rst | 5 +++--
>   1 file changed, 3 insertions(+), 2 deletions(-)

Reviewed-by: Max Reitz <mreitz@redhat.com>

Re: [PATCH] docs: qsd: Explain --export nbd,name=... default

[Eric Blake]

On 3/5/21 3:48 AM, Kevin Wolf wrote:
> The 'name' option for NBD exports is optional. Add a note that the
> default for the option is the node name (people could otherwise expect
> that it's the empty string like for qemu-nbd).
> 
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>  docs/tools/qemu-storage-daemon.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

Hmm. If we are only exporting a single image, letting "" serve as the
default export name as a synonym for the non-empty node-name might be
nice.  But we can export more than one image at a time, at which point
"" has no sane default, so always requiring the client to know the node
name is tolerable.  And 'qemu-nbd --list' or 'nbdinfo --list' are
capable of showing which node name(s) an NBD server is exposing.

Reviewed-by: Eric Blake <eblake@redhat.com>

> 
> diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
> index fe3042d609..086493ebb3 100644
> --- a/docs/tools/qemu-storage-daemon.rst
> +++ b/docs/tools/qemu-storage-daemon.rst
> @@ -80,8 +80,9 @@ Standard options:
>    requests for modifying data (the default is off).
>  
>    The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
> -  the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
> -  the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
> +  the NBD export name (if not specified, it defaults to the given
> +  ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
> +  block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
>    metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
>  
>    The ``vhost-user-blk`` export type takes a vhost-user socket address on which
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org