mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

virtfs-proxy-helper: Convert documentation to rST

Browse Source 
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
This commit is contained in:
Peter Maydell 2020-01-24 16:26:06 +00:00
parent 605ffebb2e
commit 78813586b0
6 changed files with 81 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
MAINTAINERS
View File

@ -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

7
Makefile
View File

@ -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

5
docs/interop/conf.py
View File

@ -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)
]

1
docs/interop/index.rst
View File

@ -23,3 +23,4 @@ Contents:
qemu-trace-stap
vhost-user
vhost-user-gpu
virtfs-proxy-helper

72
docs/interop/virtfs-proxy-helper.rst Normal file
View File

@ -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

63
fsdev/virtfs-proxy-helper.texi
View File

@ -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