[v2,8/8] virtfs-proxy-helper: Convert documentation to rST

The virtfs-proxy-helper documentation is currently in
fsdev/qemu-trace-stap.texi in Texinfo format, which we
present to the user as:
 * a virtfs-proxy-helper manpage
 * but not (unusually for QEMU) part of the HTML docs

Convert the documentation to rST format that lives in
the docs/ subdirectory, and present it to the user as:
 * a virtfs-proxy-helper manpage
 * part of the interop/ Sphinx manual

There are minor formatting changes to suit Sphinx, but no
content changes. In particular I've split the -u and -g
options into each having their own description text.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                             |  7 ++-
 MAINTAINERS                          |  1 +
 docs/interop/conf.py                 |  5 +-
 docs/interop/index.rst               |  1 +
 docs/interop/virtfs-proxy-helper.rst | 72 ++++++++++++++++++++++++++++
 fsdev/virtfs-proxy-helper.texi       | 63 ------------------------
 6 files changed, 81 insertions(+), 68 deletions(-)
 create mode 100644 docs/interop/virtfs-proxy-helper.rst
 delete mode 100644 fsdev/virtfs-proxy-helper.texi

On Fri, 24 Jan 2020 16:26:06 +0000
Peter Maydell <peter.maydell@linaro.org> wrote:

> The virtfs-proxy-helper documentation is currently in
> fsdev/qemu-trace-stap.texi in Texinfo format, which we
> present to the user as:
>  * a virtfs-proxy-helper manpage
>  * but not (unusually for QEMU) part of the HTML docs
> 
> Convert the documentation to rST format that lives in
> the docs/ subdirectory, and present it to the user as:
>  * a virtfs-proxy-helper manpage
>  * part of the interop/ Sphinx manual
> 
> There are minor formatting changes to suit Sphinx, but no
> content changes. In particular I've split the -u and -g
> options into each having their own description text.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---

Thanks !

Acked-by: Greg Kurz <groug@kaod.org>

>  Makefile                             |  7 ++-
>  MAINTAINERS                          |  1 +
>  docs/interop/conf.py                 |  5 +-
>  docs/interop/index.rst               |  1 +
>  docs/interop/virtfs-proxy-helper.rst | 72 ++++++++++++++++++++++++++++
>  fsdev/virtfs-proxy-helper.texi       | 63 ------------------------
>  6 files changed, 81 insertions(+), 68 deletions(-)
>  create mode 100644 docs/interop/virtfs-proxy-helper.rst
>  delete mode 100644 fsdev/virtfs-proxy-helper.texi
> 
> diff --git a/Makefile b/Makefile
> index 5dded94bf63..e08882fd49f 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -354,7 +354,7 @@ DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qe
>  DOCS+=docs/qemu-cpu-models.7
>  DOCS+=$(MANUAL_BUILDDIR)/index.html
>  ifdef CONFIG_VIRTFS
> -DOCS+=fsdev/virtfs-proxy-helper.1
> +DOCS+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1
>  endif
>  ifdef CONFIG_TRACE_SYSTEMTAP
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
> @@ -859,7 +859,7 @@ endif
>  endif
>  ifdef CONFIG_VIRTFS
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
> -	$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  
>  install-datadir:
> @@ -1051,7 +1051,7 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
>  	$(call build-manual,system,html)
>  
>  $(call define-manpage-rule,interop,\
> -       qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1,\
> +       qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\
>         $(SRC_PATH/qemu-img-cmds.hx))
>  
>  $(call define-manpage-rule,system,qemu-block-drivers.7)
> @@ -1078,7 +1078,6 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
>  
>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
>  qemu.1: qemu-option-trace.texi
> -fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
>  
>  html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 54c4429069d..83fb32b8601 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1573,6 +1573,7 @@ S: Odd Fixes
>  F: hw/9pfs/
>  X: hw/9pfs/xen-9p*
>  F: fsdev/
> +F: docs/interop/virtfs-proxy-helper.rst
>  F: tests/qtest/virtio-9p-test.c
>  T: git https://github.com/gkurz/qemu.git 9p-next
>  
> diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> index baea7fb50ee..b0f322207ca 100644
> --- a/docs/interop/conf.py
> +++ b/docs/interop/conf.py
> @@ -24,5 +24,8 @@ man_pages = [
>      ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
>       ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
>      ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> -     [], 1)
> +     [], 1),
> +    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
> +     u'QEMU 9p virtfs proxy filesystem helper',
> +     ['M. Mohan Kumar'], 1)
>  ]
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index d756a826b26..3b763b1eebe 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -23,3 +23,4 @@ Contents:
>     qemu-trace-stap
>     vhost-user
>     vhost-user-gpu
> +   virtfs-proxy-helper
> diff --git a/docs/interop/virtfs-proxy-helper.rst b/docs/interop/virtfs-proxy-helper.rst
> new file mode 100644
> index 00000000000..6cdeedf8e93
> --- /dev/null
> +++ b/docs/interop/virtfs-proxy-helper.rst
> @@ -0,0 +1,72 @@
> +QEMU 9p virtfs proxy filesystem helper
> +======================================
> +
> +Synopsis
> +--------
> +
> +**virtfs-proxy-helper** [*OPTIONS*]
> +
> +Description
> +-----------
> +
> +Pass-through security model in QEMU 9p server needs root privilege to do
> +few file operations (like chown, chmod to any mode/uid:gid).  There are two
> +issues in pass-through security model:
> +
> +- TOCTTOU vulnerability: Following symbolic links in the server could
> +  provide access to files beyond 9p export path.
> +
> +- Running QEMU with root privilege could be a security issue.
> +
> +To overcome above issues, following approach is used: A new filesystem
> +type 'proxy' is introduced. Proxy FS uses chroot + socket combination
> +for securing the vulnerability known with following symbolic links.
> +Intention of adding a new filesystem type is to allow qemu to run
> +in non-root mode, but doing privileged operations using socket IO.
> +
> +Proxy helper (a stand alone binary part of qemu) is invoked with
> +root privileges. Proxy helper chroots into 9p export path and creates
> +a socket pair or a named socket based on the command line parameter.
> +QEMU and proxy helper communicate using this socket. QEMU proxy fs
> +driver sends filesystem request to proxy helper and receives the
> +response from it.
> +
> +The proxy helper is designed so that it can drop root privileges except
> +for the capabilities needed for doing filesystem operations.
> +
> +Options
> +-------
> +
> +The following options are supported:
> +
> +.. program:: virtfs-proxy-helper
> +
> +.. option:: -h
> +
> +  Display help and exit
> +
> +.. option:: -p, --path PATH
> +
> +  Path to export for proxy filesystem driver
> +
> +.. option:: -f, --fd SOCKET_ID
> +
> +  Use given file descriptor as socket descriptor for communicating with
> +  qemu proxy fs drier. Usually a helper like libvirt will create
> +  socketpair and pass one of the fds as parameter to this option.
> +
> +.. option:: -s, --socket SOCKET_FILE
> +
> +  Creates named socket file for communicating with qemu proxy fs driver
> +
> +.. option:: -u, --uid UID
> +
> +  uid to give access to named socket file; used in combination with -g.
> +
> +.. option:: -g, --gid GID
> +
> +  gid to give access to named socket file; used in combination with -u.
> +
> +.. option:: -n, --nodaemon
> +
> +  Run as a normal program. By default program will run in daemon mode
> diff --git a/fsdev/virtfs-proxy-helper.texi b/fsdev/virtfs-proxy-helper.texi
> deleted file mode 100644
> index f4cbb60623b..00000000000
> --- a/fsdev/virtfs-proxy-helper.texi
> +++ /dev/null
> @@ -1,63 +0,0 @@
> -@example
> -@c man begin SYNOPSIS
> -@command{virtfs-proxy-helper} @var{options}
> -@c man end
> -@end example
> -
> -@c man begin DESCRIPTION
> -@table @description
> -Pass-through security model in QEMU 9p server needs root privilege to do
> -few file operations (like chown, chmod to any mode/uid:gid).  There are two
> -issues in pass-through security model
> -
> -1) TOCTTOU vulnerability: Following symbolic links in the server could
> -provide access to files beyond 9p export path.
> -
> -2) Running QEMU with root privilege could be a security issue.
> -
> -To overcome above issues, following approach is used: A new filesystem
> -type 'proxy' is introduced. Proxy FS uses chroot + socket combination
> -for securing the vulnerability known with following symbolic links.
> -Intention of adding a new filesystem type is to allow qemu to run
> -in non-root mode, but doing privileged operations using socket IO.
> -
> -Proxy helper(a stand alone binary part of qemu) is invoked with
> -root privileges. Proxy helper chroots into 9p export path and creates
> -a socket pair or a named socket based on the command line parameter.
> -QEMU and proxy helper communicate using this socket. QEMU proxy fs
> -driver sends filesystem request to proxy helper and receives the
> -response from it.
> -
> -The proxy helper is designed so that it can drop root privileges except
> -for the capabilities needed for doing filesystem operations.
> -
> -@end table
> -@c man end
> -
> -@c man begin OPTIONS
> -The following options are supported:
> -@table @option
> -@item -h
> -@findex -h
> -Display help and exit
> -@item -p|--path path
> -Path to export for proxy filesystem driver
> -@item -f|--fd socket-id
> -Use given file descriptor as socket descriptor for communicating with
> -qemu proxy fs drier. Usually a helper like libvirt will create
> -socketpair and pass one of the fds as parameter to -f|--fd
> -@item -s|--socket socket-file
> -Creates named socket file for communicating with qemu proxy fs driver
> -@item -u|--uid uid -g|--gid gid
> -uid:gid combination to give access to named socket file
> -@item -n|--nodaemon
> -Run as a normal program. By default program will run in daemon mode
> -@end table
> -@c man end
> -
> -@setfilename virtfs-proxy-helper
> -@settitle QEMU 9p virtfs proxy filesystem helper
> -
> -@c man begin AUTHOR
> -M. Mohan Kumar
> -@c man end