Re: [PATCH 092/104] virtiofsd: add man page

[Daniel P . Berrangé]

On Thu, Jan 09, 2020 at 08:02:13PM +0000, Dr. David Alan Gilbert wrote:
> * Daniel P. Berrangé (address@hidden) wrote:
> > On Thu, Dec 12, 2019 at 04:38:52PM +0000, Dr. David Alan Gilbert (git) 
> > wrote:
> > > From: Stefan Hajnoczi <address@hidden>
> > > 
> > > Signed-off-by: Stefan Hajnoczi <address@hidden>
> > > ---
> > >  Makefile                       |  7 +++
> > >  tools/virtiofsd/virtiofsd.texi | 85 ++++++++++++++++++++++++++++++++++
> > >  2 files changed, 92 insertions(+)
> > >  create mode 100644 tools/virtiofsd/virtiofsd.texi
> > 
> > Reviewed-by: Daniel P. Berrangé <address@hidden>
> 
> 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
-- 
|: 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 :|