Re: [PATCH] docs: add virtiofsd(1) man page

[Peter Maydell]

On Mon, 27 Jan 2020 at 16:25, Stefan Hajnoczi <address@hidden> wrote:
>
> Document the virtiofsd(1) program and its command-line options.  This
> man page is a rST conversion of the original texi documentation that I
> wrote.
>
> Signed-off-by: Stefan Hajnoczi <address@hidden>
> ---
> Based-on: address@hidden
>           ("[PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: 
> convert to rST")
> ---
>  MAINTAINERS                |   1 +
>  Makefile                   |   8 ++-
>  docs/interop/conf.py       |   5 +-
>  docs/interop/index.rst     |   1 +
>  docs/interop/virtiofsd.rst | 123 +++++++++++++++++++++++++++++++++++++
>  5 files changed, 136 insertions(+), 2 deletions(-)
>  create mode 100644 docs/interop/virtiofsd.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 83fb32b860..1da0709129 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1603,6 +1603,7 @@ S: Supported
>  F: tools/virtiofsd/*
>  F: hw/virtio/vhost-user-fs*
>  F: include/hw/virtio/vhost-user-fs.h
> +F: docs/interop/virtiofsd.rst
>
>  virtio-input
>  M: Gerd Hoffmann <address@hidden>
> diff --git a/Makefile b/Makefile
> index 539f9ef079..ecd26044bc 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -348,6 +348,9 @@ DOCS=qemu-doc.html qemu-doc.txt qemu.1
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
> +ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> +DOCS+=$(MANUAL_BUILDDIR)/interop/virtiofsd.1
> +endif
>  DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
>  DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt 
> docs/interop/qemu-qmp-ref.7
>  DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt 
> docs/interop/qemu-ga-ref.7
> @@ -861,6 +864,9 @@ ifdef CONFIG_VIRTFS
>         $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
>         $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 
> "$(DESTDIR)$(mandir)/man1"
>  endif
> +ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> +       $(INSTALL_DATA) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"

Thie first argument should be "$(MANUAL_BUILDDIR)/docs/interop/virtiofsd.1",
otherwise build-and-install for an in-source-directory build
won't work.

> +endif
>
>  install-datadir:
>         $(INSTALL_DIR) "$(DESTDIR)$(qemu_datadir)"

> --- /dev/null
> +++ b/docs/interop/virtiofsd.rst
> @@ -0,0 +1,123 @@
> +QEMU virtio-fs shared file system daemon
> +========================================
> +
> +Synopsis
> +--------
> +
> +**virtiofsd** [*OPTIONS*]
> +
> +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 ``--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.  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

You can mark these manpage references up with :manpage:`seccomp(2)` if
you like, though it only affects the formatting (bold in manpage, italics
in HTML), so I haven't been very consistent in using it in the manpages
I converted from texinfo.

Thanks for doing the conversion to rST format!

PS: do you (ie redhat downstream) want a macro to make it easy to
replace instances of 'qemu-system-x86_64' in the example command
lines, the way qemu-block-drivers.rst does, or do you not care
for this particular manpage? (If you do we should probably move
that to conf.py rather than proliferating it across rst files.)

thanks
-- PMM