[PATCH] qsd: Document FUSE exports

[PATCH] qsd: Document FUSE exports

[Max Reitz]

Implementing FUSE exports required no changes to the storage daemon, so
we forgot to document them there.  Considering that both NBD and
vhost-user-blk exports are documented in its man page (and NBD exports
in its --help text), we should probably do the same for FUSE.

Signed-off-by: Max Reitz <mreitz@redhat.com>
---
 docs/tools/qemu-storage-daemon.rst   | 19 +++++++++++++++++++
 storage-daemon/qemu-storage-daemon.c |  4 ++++
 2 files changed, 23 insertions(+)

diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
index f63627eaf6..f5a906f6fc 100644
--- a/docs/tools/qemu-storage-daemon.rst
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -74,6 +74,7 @@ Standard options:
 .. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
   --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
   --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
+  --export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>[,growable=on|off][,writable=on|off]
 
   is a block export definition. ``node-name`` is the block node that should be
   exported. ``writable`` determines whether or not the export allows write
@@ -91,6 +92,16 @@ Standard options:
   ``logical-block-size`` sets the logical block size in bytes (the default is
   512). ``num-queues`` sets the number of virtqueues (the default is 1).
 
+  The ``fuse`` export type takes a mount point, which must be a regular file,
+  on which to export the given block node. That file will not be changed, it
+  will just appear to have the block node's content while the export is active
+  (very much like mounting a filesystem on a directory does not change what the
+  directory contains, it only shows a different content while the filesystem is
+  mounted). Consequently, applications that have opened the given file before
+  the export became active will continue to see its original content. If
+  ``growable`` is set, writes after the end of the exported file will grow the
+  block node to fit.
+
 .. option:: --monitor MONITORDEF
 
   is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
@@ -142,6 +153,14 @@ domain socket ``vhost-user-blk.sock``::
       --blockdev driver=qcow2,node-name=qcow2,file=file \
       --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
 
+Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
+file will then appear as a raw image::
+
+  $ qemu-storage-daemon \
+      --blockdev driver=file,node-name=file,filename=disk.qcow2 \
+      --blockdev driver=qcow2,node-name=qcow2,file=file \
+      --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
+
 See also
 --------
 
diff --git a/storage-daemon/qemu-storage-daemon.c b/storage-daemon/qemu-storage-daemon.c
index 9021a46b3a..bdf8877995 100644
--- a/storage-daemon/qemu-storage-daemon.c
+++ b/storage-daemon/qemu-storage-daemon.c
@@ -97,6 +97,10 @@ static void help(void)
 "                         export the specified block node over NBD\n"
 "                         (requires --nbd-server)\n"
 "\n"
+"  --export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>\n"
+"           [,growable=on|off][,writable=on|off]\n"
+"                         export the specified block node over FUSE\n"
+"\n"
 "  --monitor [chardev=]name[,mode=control][,pretty[=on|off]]\n"
 "                         configure a QMP monitor\n"
 "\n"
-- 
2.29.2

Re: [PATCH] qsd: Document FUSE exports

[Eric Blake]

On 2/17/21 5:58 AM, Max Reitz wrote:
> Implementing FUSE exports required no changes to the storage daemon, so
> we forgot to document them there.  Considering that both NBD and
> vhost-user-blk exports are documented in its man page (and NBD exports
> in its --help text), we should probably do the same for FUSE.
> 
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---
>  docs/tools/qemu-storage-daemon.rst   | 19 +++++++++++++++++++
>  storage-daemon/qemu-storage-daemon.c |  4 ++++
>  2 files changed, 23 insertions(+)

> @@ -142,6 +153,14 @@ domain socket ``vhost-user-blk.sock``::
>        --blockdev driver=qcow2,node-name=qcow2,file=file \
>        --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
>  
> +Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
> +file will then appear as a raw image::
> +
> +  $ qemu-storage-daemon \
> +      --blockdev driver=file,node-name=file,filename=disk.qcow2 \
> +      --blockdev driver=qcow2,node-name=qcow2,file=file \
> +      --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
> +

Should the example also mention how to unmount the file when you're done?

Otherwise looks good to me.  Any documentation is better than none, even
if we can add more, so

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

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

Re: [PATCH] qsd: Document FUSE exports

[Max Reitz]

On 17.02.21 17:26, Eric Blake wrote:
> On 2/17/21 5:58 AM, Max Reitz wrote:
>> Implementing FUSE exports required no changes to the storage daemon, so
>> we forgot to document them there.  Considering that both NBD and
>> vhost-user-blk exports are documented in its man page (and NBD exports
>> in its --help text), we should probably do the same for FUSE.
>>
>> Signed-off-by: Max Reitz <mreitz@redhat.com>
>> ---
>>   docs/tools/qemu-storage-daemon.rst   | 19 +++++++++++++++++++
>>   storage-daemon/qemu-storage-daemon.c |  4 ++++
>>   2 files changed, 23 insertions(+)
> 
>> @@ -142,6 +153,14 @@ domain socket ``vhost-user-blk.sock``::
>>         --blockdev driver=qcow2,node-name=qcow2,file=file \
>>         --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
>>   
>> +Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
>> +file will then appear as a raw image::
>> +
>> +  $ qemu-storage-daemon \
>> +      --blockdev driver=file,node-name=file,filename=disk.qcow2 \
>> +      --blockdev driver=qcow2,node-name=qcow2,file=file \
>> +      --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
>> +
> 
> Should the example also mention how to unmount the file when you're done?

Just as with other exports, the export goes away when it is deleted, 
which happens e.g. when the QSD exits.  I.e., fuse_export_delete() calls 
fuse_session_unmount().

> Otherwise looks good to me.  Any documentation is better than none, even
> if we can add more, so
> 
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks!

Max

Re: [PATCH] qsd: Document FUSE exports

[Max Reitz]

On 17.02.21 12:58, Max Reitz wrote:
> Implementing FUSE exports required no changes to the storage daemon, so
> we forgot to document them there.  Considering that both NBD and
> vhost-user-blk exports are documented in its man page (and NBD exports
> in its --help text), we should probably do the same for FUSE.
> 
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---
>   docs/tools/qemu-storage-daemon.rst   | 19 +++++++++++++++++++
>   storage-daemon/qemu-storage-daemon.c |  4 ++++
>   2 files changed, 23 insertions(+)

Thanks for the review, applied to my block branch:

https://git.xanclic.moe/XanClic/qemu/commits/branch/block

Max