From nobody Tue Feb 10 01:31:00 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1579883471; cv=none; d=zohomail.com; s=zohoarc; b=lJ8gyijvhh7r594keNuAAA52cXfZpgYH/PWE50mW5flY9fslWs020KnutUc6tp+b2gAguDFd+jSJTg+CuUR1AgJFG+/9V4kSCJx7fXO/R0kZhPvQWutiGGp+RWsBg8TBfZLxIrtTfrnbpAuhWygmnj8S63kHBxI/PUqY8cOe3hM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1579883471; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=WH7rcf6kZQLCAooNxGLvCLPcLVX0txly3whV92JnSP8=; b=g9TcWUDPtH1St2UaYVFAzsCqj5Ebap63yVkANTcHbv/nTDqpUW8xUkNuR/D24ko/2ek83Y+7tATWOb4vbcFOvHIA3zGqFQqTJlFHDB3b8Zm6o+OWtPz6l8ybBYVLRcSr32dSweXRD6NjrQz0FYxjeqxQjkDpXV2B9rvIlchOcp8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1579883471636222.58970191962396; Fri, 24 Jan 2020 08:31:11 -0800 (PST) Received: from localhost ([::1]:44556 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iv1rS-00030X-It for importer@patchew.org; Fri, 24 Jan 2020 11:31:10 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:38057) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iv1mt-0002v4-BS for qemu-devel@nongnu.org; Fri, 24 Jan 2020 11:26:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iv1mr-00030L-6e for qemu-devel@nongnu.org; Fri, 24 Jan 2020 11:26:27 -0500 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:36797) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iv1mr-0002yW-0Q for qemu-devel@nongnu.org; Fri, 24 Jan 2020 11:26:25 -0500 Received: by mail-wm1-x32c.google.com with SMTP id p17so56871wma.1 for ; Fri, 24 Jan 2020 08:26:24 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id q3sm7054998wmj.38.2020.01.24.08.26.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Jan 2020 08:26:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=WH7rcf6kZQLCAooNxGLvCLPcLVX0txly3whV92JnSP8=; b=LGOEBdJM7Rk14FIofHyr7x63E/QUjR2KRU8xttAafAzQzs1U+OVFLhgerBBVFtwtYQ itWJAorKvX9vi58vCbNGAPUdbGTid+7DDpu/DMSd9CyGbO29O5pqA2sZa349U9Y9CiVo gJRpLXdgy7WVIFgMSjy258HhhITvxVsQo5jLFfSJigrJ6hwlA+DHMYQlXSIsdv1+T8S2 80BmdcjyH8cvXNFKMSbVlPaQRrSYYnyDYcNzQBVg3Nucdu76LF+iCjKO0x2aMeNtoeRF 7rvEvxsuLaVKg/vaG9dD033oZVD4Zudi8JMEJRLm8nUsH7KS16fVk1+Wqkz5+V4cZ5b/ 1DiQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=WH7rcf6kZQLCAooNxGLvCLPcLVX0txly3whV92JnSP8=; b=BYHrtGzmPNV/nRGRx9ItcTBdCg/xW4SQdVERiYFBJCtxSIbqh07Wob2A4L9zXnV5FM 9i58LnsmfRlnKEEwvolU18eHci9HLQqHdZchD2Vmrsvg1CFQtTtCfK37e1P3b91BS0+V U3RgLhtwrtHf+eX2t3wC+XbjlU/5JWjdIVcb/u4/pkcFLYl2Be9zjIfNZf0rQ6vRqyuQ CFJO3BzOEmATsC2eY0zcI63EJoDQ1LE72ZDpy7F4pfjXwSKIW78vhMRAVrLNBxG3qlbb MHl8odUwOtu96/HG7837Hfij46C1SIQkFxDfqurNyMlks/zpWAA+dwGvG9uA0uX0Rz4+ 8WEw== X-Gm-Message-State: APjAAAV0J9CFFcOD8yRQpEU51RKP2afgGizUtPF/YuepmDhVb1eMRGNk o/NY5Tn5OCKd7lB500PvzoxLnKuJ8YmVUA== X-Google-Smtp-Source: APXvYqyim0M6sA9Fz99ZYjLifRDzYWIonc0AYnkR+Jtzfhy2n1QrQBgKavfqudFEW+8hShNFVSx5kg== X-Received: by 2002:a7b:c851:: with SMTP id c17mr26112wml.71.1579883182197; Fri, 24 Jan 2020 08:26:22 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST Date: Fri, 24 Jan 2020 16:26:06 +0000 Message-Id: <20200124162606.8787-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200124162606.8787-1-peter.maydell@linaro.org> References: <20200124162606.8787-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32c X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , qemu-block@nongnu.org, Markus Armbruster , Richard Henderson , Greg Kurz , Max Reitz , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" 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 Acked-by: Greg Kurz --- 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 5dded94bf63..e08882fd49f 100644 --- a/Makefile +++ b/Makefile @@ -354,7 +354,7 @@ DOCS+=3Ddocs/interop/qemu-ga-ref.html docs/interop/qemu= -ga-ref.txt docs/interop/qe DOCS+=3Ddocs/qemu-cpu-models.7 DOCS+=3D$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS -DOCS+=3Dfsdev/virtfs-proxy-helper.1 +DOCS+=3D$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 endif ifdef CONFIG_TRACE_SYSTEMTAP DOCS+=3D$(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 "$(DESTD= IR)$(mandir)/man1" endif =20 install-datadir: @@ -1051,7 +1051,7 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-d= eps,system) $(call build-manual,system,html) =20 $(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-help= er.1,\ $(SRC_PATH/qemu-img-cmds.hx)) =20 $(call define-manpage-rule,system,qemu-block-drivers.7) @@ -1078,7 +1078,6 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qg= a-qapi-doc.texi =20 qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-inf= o.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 =20 html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html sphinxdocs diff --git a/MAINTAINERS b/MAINTAINERS index 54c4429069d..83fb32b8601 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1573,6 +1573,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 =20 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 =3D [ ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server', ['Anthony Liguori '], 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-pro= xy-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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 --=20 2.20.1