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 <[email protected]>
Acked-by: Greg Kurz <[email protected]>
Message-id: 20200124162606[email protected]

diff --git a/MAINTAINERS b/MAINTAINERS
index db3cbc18c925d1e816c8c4898916e647a2896d9c..1f0bc72f2189a56b6c2664adfdc11aed8a5a93aa 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1574,6 +1574,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/Makefile b/Makefile
index 1e0440c3738d062dedad89970667d06a3b4b05e5..a6f5d440828465c6b5009ab9c70a6824807ed05e 100644 (file)
--- 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/docs/interop/conf.py b/docs/interop/conf.py
index baea7fb50eedd44059e4de158c208d7b223b9a30..b0f322207cafd8e8f2884f92638d0d86e52462b1 100644 (file)
--- 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 <[email protected]>'], 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 d756a826b2606ba28ade444ee42bb3dfc57eb406..3b763b1eebe1c82b144fd7d323a47c36242c3337 100644 (file)
--- 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 (file)
index 0000000..6cdeedf
--- /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 (file)
index f4cbb60..0000000
--- 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