[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST
From: |
Greg Kurz |
Subject: |
Re: [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST |
Date: |
Fri, 24 Jan 2020 17:47:38 +0100 |
On Fri, 24 Jan 2020 16:26:06 +0000
Peter Maydell <address@hidden> 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 <address@hidden>
> ---
Thanks !
Acked-by: Greg Kurz <address@hidden>
> 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 <address@hidden>'], 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
- Re: [PATCH v2 2/8] hxtool: Support SRST/ERST directives, (continued)
- [PATCH v2 3/8] docs/sphinx: Add new hxtool Sphinx extension, Peter Maydell, 2020/01/24
- [PATCH v2 4/8] qemu-img-cmds.hx: Add rST documentation fragments, Peter Maydell, 2020/01/24
- [PATCH v2 6/8] qemu-img-cmds.hx: Remove texinfo document fragments, Peter Maydell, 2020/01/24
- [PATCH v2 7/8] scripts/qemu-trace-stap: Convert documentation to rST, Peter Maydell, 2020/01/24
- [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST, Peter Maydell, 2020/01/24
- Re: [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST,
Greg Kurz <=
- [PATCH v2 5/8] qemu-img: Convert invocation documentation to rST, Peter Maydell, 2020/01/24
- Re: [PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST, Peter Maydell, 2020/01/31