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> Acked-by: Greg Kurz <groug@kaod.org> Message-id: 20200124162606.8787-9-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell
parent
605ffebb2e
commit
78813586b0
|
|
@ -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
7
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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
]
|
||||
|
|
|
|||
|
|
@ -23,3 +23,4 @@ Contents:
|
|||
qemu-trace-stap
|
||||
vhost-user
|
||||
vhost-user-gpu
|
||||
virtfs-proxy-helper
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue