Commit 78813586 authored by Peter Maydell's avatar Peter Maydell
Browse files

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: default avatarPeter Maydell <peter.maydell@linaro.org>
Acked-by: default avatarGreg Kurz <groug@kaod.org>
Message-id: 20200124162606.8787-9-peter.maydell@linaro.org
parent 605ffebb

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -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

Makefile

+3 −4
Original line number Diff line number Diff line
@@ -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

docs/interop/conf.py

+4 −1
Original line number Diff line number Diff line
@@ -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)

]

docs/interop/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -23,3 +23,4 @@ Contents: 
   qemu-trace-stap

   vhost-user

   vhost-user-gpu

   virtfs-proxy-helper

fsdev/virtfs-proxy-helper.texi→docs/interop/virtfs-proxy-helper.rst

+72 −0
Original line number Diff line number Diff line 
@example

@c man begin SYNOPSIS

@command{virtfs-proxy-helper} @var{options}

@c man end

@end example



@c man begin DESCRIPTION

@table @description

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

issues in pass-through security model:



1) TOCTTOU vulnerability: Following symbolic links in the server could

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

- 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
@@ -31,33 +34,39 @@ 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

Options

-------



@c man begin OPTIONS

The following options are supported:

@table @option

@item -h

@findex -h



.. program:: virtfs-proxy-helper



.. option:: -h



  Display help and exit

@item -p|--path path



.. option:: -p, --path PATH



  Path to export for proxy filesystem driver

@item -f|--fd socket-id



.. 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 -f|--fd

@item -s|--socket socket-file

  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

@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

.. option:: -u, --uid UID



  uid to give access to named socket file; used in combination with -g.



@c man begin AUTHOR

M. Mohan Kumar

@c man end
 
.. 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