From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Subject: [PULL 8/8] virtfs-proxy-helper: Convert documentation to rST
Date: Mon, 3 Feb 2020 11:13:18 +0000 [thread overview]
Message-ID: <20200203111318.23378-9-peter.maydell@linaro.org> (raw)
In-Reply-To: <20200203111318.23378-1-peter.maydell@linaro.org>
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>
Acked-by: Greg Kurz <groug@kaod.org>
Message-id: 20200124162606.8787-9-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
diff --git a/Makefile b/Makefile
index 1e0440c3738..a6f5d440828 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 db3cbc18c92..1f0bc72f218 100644
--- 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/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
--
2.20.1
next prev parent reply other threads:[~2020-02-03 11:15 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-03 11:13 [PULL 0/8] docs queue Peter Maydell
2020-02-03 11:13 ` [PULL 1/8] Makefile: Ensure we don't run Sphinx in parallel for manpages Peter Maydell
2020-02-03 11:13 ` [PULL 2/8] hxtool: Support SRST/ERST directives Peter Maydell
2020-02-03 11:13 ` [PULL 3/8] docs/sphinx: Add new hxtool Sphinx extension Peter Maydell
2020-02-03 11:13 ` [PULL 4/8] qemu-img-cmds.hx: Add rST documentation fragments Peter Maydell
2020-02-03 11:13 ` [PULL 5/8] qemu-img: Convert invocation documentation to rST Peter Maydell
2020-02-03 11:13 ` [PULL 6/8] qemu-img-cmds.hx: Remove texinfo document fragments Peter Maydell
2020-02-03 11:13 ` [PULL 7/8] scripts/qemu-trace-stap: Convert documentation to rST Peter Maydell
2020-02-03 11:13 ` Peter Maydell [this message]
2020-02-03 13:04 ` [PULL 0/8] docs queue Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200203111318.23378-9-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.