[092/104] virtiofsd: add man page

From: Stefan Hajnoczi <stefanha@redhat.com>

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 Makefile                       |  7 +++
 tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 tools/virtiofsd/virtiofsd.texi

On 12/12/2019 16:38, Dr. David Alan Gilbert (git) wrote:
> From: Stefan Hajnoczi <stefanha@redhat.com>
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>   Makefile                       |  7 +++
>   tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
>   2 files changed, 92 insertions(+)
>   create mode 100644 tools/virtiofsd/virtiofsd.texi
> 

... deleted ...

> +@c man begin EXAMPLES
> +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> +
> +@example
> +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> +host# qemu-system-x86_64 \
> +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> +    -numa node,memdev=mem \
> +    ...
> +guest# mount -t virtio_fs \
> +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> +    myfs /mnt



Should this be 'mount -t virtiofs myfs /mnt' like on 
https://virtio-fs.gitlab.io/howto-qemu.html ?

otherwise

Reviewed-by: Liam Merwick <liam.merwick@oracle.com>

* Liam Merwick (liam.merwick@oracle.com) wrote:
> On 12/12/2019 16:38, Dr. David Alan Gilbert (git) wrote:
> > From: Stefan Hajnoczi <stefanha@redhat.com>
> > 
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >   Makefile                       |  7 +++
> >   tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
> >   2 files changed, 92 insertions(+)
> >   create mode 100644 tools/virtiofsd/virtiofsd.texi
> > 
> 
> ... deleted ...
> 
> > +@c man begin EXAMPLES
> > +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> > +
> > +@example
> > +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> > +host# qemu-system-x86_64 \
> > +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> > +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> > +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> > +    -numa node,memdev=mem \
> > +    ...
> > +guest# mount -t virtio_fs \
> > +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> > +    myfs /mnt
> 
> 
> 
> Should this be 'mount -t virtiofs myfs /mnt' like on
> https://virtio-fs.gitlab.io/howto-qemu.html ?

It should! The man page still had the old format; thanks for spotting
it.

> otherwise
> 
> Reviewed-by: Liam Merwick <liam.merwick@oracle.com>

Thank you!

Dave

> 
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK

On Thu, Dec 12, 2019 at 04:38:52PM +0000, Dr. David Alan Gilbert (git) wrote:
> From: Stefan Hajnoczi <stefanha@redhat.com>
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  Makefile                       |  7 +++
>  tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
>  2 files changed, 92 insertions(+)
>  create mode 100644 tools/virtiofsd/virtiofsd.texi

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

with some notes at the very end


> diff --git a/Makefile b/Makefile
> index fa15174ba0..53d175d12f 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -357,6 +357,9 @@ DOCS+=docs/qemu-cpu-models.7
>  ifdef CONFIG_VIRTFS
>  DOCS+=fsdev/virtfs-proxy-helper.1
>  endif
> +ifdef CONFIG_LINUX
> +DOCS+=tools/virtiofsd/virtiofsd.1
> +endif
>  ifdef CONFIG_TRACE_SYSTEMTAP
>  DOCS+=scripts/qemu-trace-stap.1
>  endif
> @@ -863,6 +866,9 @@ ifdef CONFIG_VIRTFS
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
>  	$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
>  endif
> +ifdef CONFIG_LINUX
> +	$(INSTALL_DATA) tools/virtiofsd/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> +endif
>  
>  install-datadir:
>  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_datadir)"
> @@ -1061,6 +1067,7 @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
>  qemu.1: qemu-option-trace.texi
>  qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
>  fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
> +tools/virtiofsd/virtiofsd.1: tools/virtiofsd/virtiofsd.texi
>  qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
>  docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
> diff --git a/tools/virtiofsd/virtiofsd.texi b/tools/virtiofsd/virtiofsd.texi
> new file mode 100644
> index 0000000000..eec7fbf4e6
> --- /dev/null
> +++ b/tools/virtiofsd/virtiofsd.texi
> @@ -0,0 +1,85 @@
> +@example
> +@c man begin SYNOPSIS
> +@command{virtiofsd} [OPTION] @option{--socket-path=}@var{path}|@option{--fd=}@var{fdnum} @option{-o source=}@var{path}
> +@c man end
> +@end example
> +
> +@c man begin DESCRIPTION
> +
> +Share a host directory tree with a guest through a virtio-fs device.  This
> +program is a vhost-user backend that implements the virtio-fs device.  Each
> +virtio-fs device instance requires its own virtiofsd process.
> +
> +This program is designed to work with QEMU's @code{--device vhost-user-fs-pci}
> +but should work with any virtual machine monitor (VMM) that supports
> +vhost-user.  See the EXAMPLES section below.
> +
> +This program must be run as the root user.

So there's no way for an unprivileged user to do file sharing like they
can with 9p right now ?

>                                              Upon startup the program will
> +switch into a new file system namespace with the shared directory tree as its
> +root.  This prevents "file system escapes" due to symlinks and other file
> +system objects that might lead to files outside the shared directory.  The
> +program also sandboxes itself using seccomp(2) to prevent ptrace(2) and other
> +vectors that could allow an attacker to compromise the system after gaining
> +control of the virtiofsd process.
> +
> +@c man end
> +
> +@c man begin OPTIONS
> +@table @option
> +@item -h, --help
> +Print help.
> +@item -V, --version
> +Print version.
> +@item -d, -o debug
> +Enable debug output.
> +@item --syslog
> +Print log messages to syslog instead of stderr.
> +@item -o log_level=@var{level}
> +Print only log messages matching @var{level} or more severe.  @var{level} is
> +one of @code{err}, @code{warn}, @code{info}, or @code{debug}.  The default is
> +@var{info}.
> +@item -o source=@var{path}
> +Share host directory tree located at @var{path}.  This option is required.
> +@item --socket-path=@var{path}, -o vhost_user_socket=@var{path}
> +Listen on vhost-user UNIX domain socket at @var{path}.
> +@item --fd=@var{fdnum}
> +Accept connections from vhost-user UNIX domain socket file descriptor @var{fdnum}.  The file descriptor must already be listening for connections.
> +@item --thread-pool-size=@var{num}
> +Restrict the number of worker threads per request queue to @var{num}.  The default is 64.
> +@item --cache=@code{none}|@code{auto}|@code{always}
> +Select the desired trade-off between coherency and performance.  @code{none}
> +forbids the FUSE client from caching to achieve best coherency at the cost of
> +performance.  @code{auto} acts similar to NFS with a 1 second metadata cache
> +timeout.  @code{always} sets a long cache lifetime at the expense of coherency.
> +@item --writeback
> +Enable writeback cache, allowing the FUSE client to buffer and merge write requests.
> +@end table
> +@c man end
> +
> +@c man begin EXAMPLES
> +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> +
> +@example
> +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> +host# qemu-system-x86_64 \
> +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> +    -numa node,memdev=mem \
> +    ...
> +guest# mount -t virtio_fs \
> +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> +    myfs /mnt
> +@end example
> +@c man end
> +
> +@ignore
> +@setfilename virtiofsd
> +@settitle QEMU virtio-fs shared file system daemon
> +
> +@c man begin AUTHOR

s/AUTHOR/COPYRIGHT/

since this isn't providing any author information.

> +Copyright (C) 2019 Red Hat, Inc.

2019-2020 !

And now insert

 @c man end
 @c man begin LICENSE

> +This is free software; see the source for copying conditions.  There is NO
> +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> +@c man end
> +@end ignore



Regards,
Daniel

* Daniel P. Berrangé (berrange@redhat.com) wrote:
> On Thu, Dec 12, 2019 at 04:38:52PM +0000, Dr. David Alan Gilbert (git) wrote:
> > From: Stefan Hajnoczi <stefanha@redhat.com>
> > 
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >  Makefile                       |  7 +++
> >  tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
> >  2 files changed, 92 insertions(+)
> >  create mode 100644 tools/virtiofsd/virtiofsd.texi
> 
> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

Thanks.

> with some notes at the very end

<snip>

> > +@c man begin DESCRIPTION
> > +
> > +Share a host directory tree with a guest through a virtio-fs device.  This
> > +program is a vhost-user backend that implements the virtio-fs device.  Each
> > +virtio-fs device instance requires its own virtiofsd process.
> > +
> > +This program is designed to work with QEMU's @code{--device vhost-user-fs-pci}
> > +but should work with any virtual machine monitor (VMM) that supports
> > +vhost-user.  See the EXAMPLES section below.
> > +
> > +This program must be run as the root user.
> 
> So there's no way for an unprivileged user to do file sharing like they
> can with 9p right now ?

Correct.

(Which also makes it a pain for using in a make check)

> >                                              Upon startup the program will
> > +switch into a new file system namespace with the shared directory tree as its
> > +root.  This prevents "file system escapes" due to symlinks and other file
> > +system objects that might lead to files outside the shared directory.  The
> > +program also sandboxes itself using seccomp(2) to prevent ptrace(2) and other
> > +vectors that could allow an attacker to compromise the system after gaining
> > +control of the virtiofsd process.
> > +
> > +@c man end
> > +
> > +@c man begin OPTIONS
> > +@table @option
> > +@item -h, --help
> > +Print help.
> > +@item -V, --version
> > +Print version.
> > +@item -d, -o debug
> > +Enable debug output.
> > +@item --syslog
> > +Print log messages to syslog instead of stderr.
> > +@item -o log_level=@var{level}
> > +Print only log messages matching @var{level} or more severe.  @var{level} is
> > +one of @code{err}, @code{warn}, @code{info}, or @code{debug}.  The default is
> > +@var{info}.
> > +@item -o source=@var{path}
> > +Share host directory tree located at @var{path}.  This option is required.
> > +@item --socket-path=@var{path}, -o vhost_user_socket=@var{path}
> > +Listen on vhost-user UNIX domain socket at @var{path}.
> > +@item --fd=@var{fdnum}
> > +Accept connections from vhost-user UNIX domain socket file descriptor @var{fdnum}.  The file descriptor must already be listening for connections.
> > +@item --thread-pool-size=@var{num}
> > +Restrict the number of worker threads per request queue to @var{num}.  The default is 64.
> > +@item --cache=@code{none}|@code{auto}|@code{always}
> > +Select the desired trade-off between coherency and performance.  @code{none}
> > +forbids the FUSE client from caching to achieve best coherency at the cost of
> > +performance.  @code{auto} acts similar to NFS with a 1 second metadata cache
> > +timeout.  @code{always} sets a long cache lifetime at the expense of coherency.
> > +@item --writeback
> > +Enable writeback cache, allowing the FUSE client to buffer and merge write requests.
> > +@end table
> > +@c man end
> > +
> > +@c man begin EXAMPLES
> > +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> > +
> > +@example
> > +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> > +host# qemu-system-x86_64 \
> > +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> > +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> > +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> > +    -numa node,memdev=mem \
> > +    ...
> > +guest# mount -t virtio_fs \
> > +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> > +    myfs /mnt
> > +@end example
> > +@c man end
> > +
> > +@ignore
> > +@setfilename virtiofsd
> > +@settitle QEMU virtio-fs shared file system daemon
> > +
> > +@c man begin AUTHOR
> 
> s/AUTHOR/COPYRIGHT/

OK

> since this isn't providing any author information.
> 
> > +Copyright (C) 2019 Red Hat, Inc.
> 
> 2019-2020 !

Time flies...

> And now insert
> 
>  @c man end
>  @c man begin LICENSE
> 
> > +This is free software; see the source for copying conditions.  There is NO
> > +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> > +@c man end
> > +@end ignore

Hmm, so it ends up like:


@c man end

@ignore
@setfilename virtiofsd
@settitle QEMU virtio-fs shared file system daemon

@c man begin COPYRIGHT
Copyright (C) 2019-2020 Red Hat, Inc.
@c man end
@c man begin LICENSE
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@c man end
@end ignore


That results in:

COPYRIGHT
       Copyright (C) 2019-2020 Red Hat, Inc.

but with no license printed.
That's from after a make doing a   nroff -man ./tools/virtiofsd/virtiofsd.1 |more

is that what's expected?  I'd expected to see the license somewhere.

Dave
> 
> 
> 
> Regards,
> Daniel
> -- 
> |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK

On Thu, Jan 09, 2020 at 08:02:13PM +0000, Dr. David Alan Gilbert wrote:
> * Daniel P. Berrangé (berrange@redhat.com) wrote:
> > On Thu, Dec 12, 2019 at 04:38:52PM +0000, Dr. David Alan Gilbert (git) wrote:
> > > From: Stefan Hajnoczi <stefanha@redhat.com>
> > > 
> > > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > > ---
> > >  Makefile                       |  7 +++
> > >  tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
> > >  2 files changed, 92 insertions(+)
> > >  create mode 100644 tools/virtiofsd/virtiofsd.texi
> > 
> > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> 
> Thanks.
> 
> > with some notes at the very end
> 
> <snip>
> 
> > > +@c man begin DESCRIPTION
> > > +
> > > +Share a host directory tree with a guest through a virtio-fs device.  This
> > > +program is a vhost-user backend that implements the virtio-fs device.  Each
> > > +virtio-fs device instance requires its own virtiofsd process.
> > > +
> > > +This program is designed to work with QEMU's @code{--device vhost-user-fs-pci}
> > > +but should work with any virtual machine monitor (VMM) that supports
> > > +vhost-user.  See the EXAMPLES section below.
> > > +
> > > +This program must be run as the root user.
> > 
> > So there's no way for an unprivileged user to do file sharing like they
> > can with 9p right now ?
> 
> Correct.
> 
> (Which also makes it a pain for using in a make check)
> 
> > >                                              Upon startup the program will
> > > +switch into a new file system namespace with the shared directory tree as its
> > > +root.  This prevents "file system escapes" due to symlinks and other file
> > > +system objects that might lead to files outside the shared directory.  The
> > > +program also sandboxes itself using seccomp(2) to prevent ptrace(2) and other
> > > +vectors that could allow an attacker to compromise the system after gaining
> > > +control of the virtiofsd process.
> > > +
> > > +@c man end
> > > +
> > > +@c man begin OPTIONS
> > > +@table @option
> > > +@item -h, --help
> > > +Print help.
> > > +@item -V, --version
> > > +Print version.
> > > +@item -d, -o debug
> > > +Enable debug output.
> > > +@item --syslog
> > > +Print log messages to syslog instead of stderr.
> > > +@item -o log_level=@var{level}
> > > +Print only log messages matching @var{level} or more severe.  @var{level} is
> > > +one of @code{err}, @code{warn}, @code{info}, or @code{debug}.  The default is
> > > +@var{info}.
> > > +@item -o source=@var{path}
> > > +Share host directory tree located at @var{path}.  This option is required.
> > > +@item --socket-path=@var{path}, -o vhost_user_socket=@var{path}
> > > +Listen on vhost-user UNIX domain socket at @var{path}.
> > > +@item --fd=@var{fdnum}
> > > +Accept connections from vhost-user UNIX domain socket file descriptor @var{fdnum}.  The file descriptor must already be listening for connections.
> > > +@item --thread-pool-size=@var{num}
> > > +Restrict the number of worker threads per request queue to @var{num}.  The default is 64.
> > > +@item --cache=@code{none}|@code{auto}|@code{always}
> > > +Select the desired trade-off between coherency and performance.  @code{none}
> > > +forbids the FUSE client from caching to achieve best coherency at the cost of
> > > +performance.  @code{auto} acts similar to NFS with a 1 second metadata cache
> > > +timeout.  @code{always} sets a long cache lifetime at the expense of coherency.
> > > +@item --writeback
> > > +Enable writeback cache, allowing the FUSE client to buffer and merge write requests.
> > > +@end table
> > > +@c man end
> > > +
> > > +@c man begin EXAMPLES
> > > +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> > > +
> > > +@example
> > > +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> > > +host# qemu-system-x86_64 \
> > > +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> > > +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> > > +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> > > +    -numa node,memdev=mem \
> > > +    ...
> > > +guest# mount -t virtio_fs \
> > > +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> > > +    myfs /mnt
> > > +@end example
> > > +@c man end
> > > +
> > > +@ignore
> > > +@setfilename virtiofsd
> > > +@settitle QEMU virtio-fs shared file system daemon
> > > +
> > > +@c man begin AUTHOR
> > 
> > s/AUTHOR/COPYRIGHT/
> 
> OK
> 
> > since this isn't providing any author information.
> > 
> > > +Copyright (C) 2019 Red Hat, Inc.
> > 
> > 2019-2020 !
> 
> Time flies...
> 
> > And now insert
> > 
> >  @c man end
> >  @c man begin LICENSE
> > 
> > > +This is free software; see the source for copying conditions.  There is NO
> > > +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> > > +@c man end
> > > +@end ignore
> 
> Hmm, so it ends up like:
> 
> 
> @c man end
> 
> @ignore
> @setfilename virtiofsd
> @settitle QEMU virtio-fs shared file system daemon
> 
> @c man begin COPYRIGHT
> Copyright (C) 2019-2020 Red Hat, Inc.
> @c man end
> @c man begin LICENSE
> This is free software; see the source for copying conditions.  There is NO
> warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> @c man end
> @end ignore
> 
> 
> That results in:
> 
> COPYRIGHT
>        Copyright (C) 2019-2020 Red Hat, Inc.
> 
> but with no license printed.
> That's from after a make doing a   nroff -man ./tools/virtiofsd/virtiofsd.1 |more
> 
> is that what's expected?  I'd expected to see the license somewhere.

No, that's not expected :-(  It seems my good intentions were killed by
texi2pod.pl which whitelists the permitted section names, and does not
allow "LICENSE" as one of them. Either ignore my suggestion, given that
this bug is pre-existing in all QEMU man pages, or fix texi2pod.pl to
allow LICENSE.

Regards,
Daniel

* Daniel P. Berrangé (berrange@redhat.com) wrote:
> On Thu, Jan 09, 2020 at 08:02:13PM +0000, Dr. David Alan Gilbert wrote:
> > * Daniel P. Berrangé (berrange@redhat.com) wrote:
> > > On Thu, Dec 12, 2019 at 04:38:52PM +0000, Dr. David Alan Gilbert (git) wrote:
> > > > From: Stefan Hajnoczi <stefanha@redhat.com>
> > > > 
> > > > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > > > ---
> > > >  Makefile                       |  7 +++
> > > >  tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
> > > >  2 files changed, 92 insertions(+)
> > > >  create mode 100644 tools/virtiofsd/virtiofsd.texi
> > > 
> > > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> > 
> > Thanks.
> > 
> > > with some notes at the very end
> > 
> > <snip>
> > 
> > > > +@c man begin DESCRIPTION
> > > > +
> > > > +Share a host directory tree with a guest through a virtio-fs device.  This
> > > > +program is a vhost-user backend that implements the virtio-fs device.  Each
> > > > +virtio-fs device instance requires its own virtiofsd process.
> > > > +
> > > > +This program is designed to work with QEMU's @code{--device vhost-user-fs-pci}
> > > > +but should work with any virtual machine monitor (VMM) that supports
> > > > +vhost-user.  See the EXAMPLES section below.
> > > > +
> > > > +This program must be run as the root user.
> > > 
> > > So there's no way for an unprivileged user to do file sharing like they
> > > can with 9p right now ?
> > 
> > Correct.
> > 
> > (Which also makes it a pain for using in a make check)
> > 
> > > >                                              Upon startup the program will
> > > > +switch into a new file system namespace with the shared directory tree as its
> > > > +root.  This prevents "file system escapes" due to symlinks and other file
> > > > +system objects that might lead to files outside the shared directory.  The
> > > > +program also sandboxes itself using seccomp(2) to prevent ptrace(2) and other
> > > > +vectors that could allow an attacker to compromise the system after gaining
> > > > +control of the virtiofsd process.
> > > > +
> > > > +@c man end
> > > > +
> > > > +@c man begin OPTIONS
> > > > +@table @option
> > > > +@item -h, --help
> > > > +Print help.
> > > > +@item -V, --version
> > > > +Print version.
> > > > +@item -d, -o debug
> > > > +Enable debug output.
> > > > +@item --syslog
> > > > +Print log messages to syslog instead of stderr.
> > > > +@item -o log_level=@var{level}
> > > > +Print only log messages matching @var{level} or more severe.  @var{level} is
> > > > +one of @code{err}, @code{warn}, @code{info}, or @code{debug}.  The default is
> > > > +@var{info}.
> > > > +@item -o source=@var{path}
> > > > +Share host directory tree located at @var{path}.  This option is required.
> > > > +@item --socket-path=@var{path}, -o vhost_user_socket=@var{path}
> > > > +Listen on vhost-user UNIX domain socket at @var{path}.
> > > > +@item --fd=@var{fdnum}
> > > > +Accept connections from vhost-user UNIX domain socket file descriptor @var{fdnum}.  The file descriptor must already be listening for connections.
> > > > +@item --thread-pool-size=@var{num}
> > > > +Restrict the number of worker threads per request queue to @var{num}.  The default is 64.
> > > > +@item --cache=@code{none}|@code{auto}|@code{always}
> > > > +Select the desired trade-off between coherency and performance.  @code{none}
> > > > +forbids the FUSE client from caching to achieve best coherency at the cost of
> > > > +performance.  @code{auto} acts similar to NFS with a 1 second metadata cache
> > > > +timeout.  @code{always} sets a long cache lifetime at the expense of coherency.
> > > > +@item --writeback
> > > > +Enable writeback cache, allowing the FUSE client to buffer and merge write requests.
> > > > +@end table
> > > > +@c man end
> > > > +
> > > > +@c man begin EXAMPLES
> > > > +Export @code{/var/lib/fs/vm001/} on vhost-user UNIX domain socket @code{/var/run/vm001-vhost-fs.sock}:
> > > > +
> > > > +@example
> > > > +host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001
> > > > +host# qemu-system-x86_64 \
> > > > +    -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \
> > > > +    -device vhost-user-fs-pci,chardev=char0,tag=myfs \
> > > > +    -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \
> > > > +    -numa node,memdev=mem \
> > > > +    ...
> > > > +guest# mount -t virtio_fs \
> > > > +    -o default_permissions,allow_other,user_id=0,group_id=0,rootmode=040000,dax \
> > > > +    myfs /mnt
> > > > +@end example
> > > > +@c man end
> > > > +
> > > > +@ignore
> > > > +@setfilename virtiofsd
> > > > +@settitle QEMU virtio-fs shared file system daemon
> > > > +
> > > > +@c man begin AUTHOR
> > > 
> > > s/AUTHOR/COPYRIGHT/
> > 
> > OK
> > 
> > > since this isn't providing any author information.
> > > 
> > > > +Copyright (C) 2019 Red Hat, Inc.
> > > 
> > > 2019-2020 !
> > 
> > Time flies...
> > 
> > > And now insert
> > > 
> > >  @c man end
> > >  @c man begin LICENSE
> > > 
> > > > +This is free software; see the source for copying conditions.  There is NO
> > > > +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> > > > +@c man end
> > > > +@end ignore
> > 
> > Hmm, so it ends up like:
> > 
> > 
> > @c man end
> > 
> > @ignore
> > @setfilename virtiofsd
> > @settitle QEMU virtio-fs shared file system daemon
> > 
> > @c man begin COPYRIGHT
> > Copyright (C) 2019-2020 Red Hat, Inc.
> > @c man end
> > @c man begin LICENSE
> > This is free software; see the source for copying conditions.  There is NO
> > warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> > @c man end
> > @end ignore
> > 
> > 
> > That results in:
> > 
> > COPYRIGHT
> >        Copyright (C) 2019-2020 Red Hat, Inc.
> > 
> > but with no license printed.
> > That's from after a make doing a   nroff -man ./tools/virtiofsd/virtiofsd.1 |more
> > 
> > is that what's expected?  I'd expected to see the license somewhere.
> 
> No, that's not expected :-(  It seems my good intentions were killed by
> texi2pod.pl which whitelists the permitted section names, and does not
> allow "LICENSE" as one of them. Either ignore my suggestion, given that
> this bug is pre-existing in all QEMU man pages, or fix texi2pod.pl to
> allow LICENSE.

OK, I've removed the 'man end/man begin LICENSE' and it now comes out
as:

COPYRIGHT
       Copyright (C) 2019-2020 Red Hat, Inc.

       This is free software; see the source for copying conditions.  There is
       NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.

which I think is OK.

Dave

> Regards,
> Daniel
> -- 
> |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK