docs/tools/virtfs-proxy-helper.rst

   1 QEMU 9p virtfs proxy filesystem helper
   2 ======================================
   3
   4 Synopsis
   5 --------
   6
   7 **virtfs-proxy-helper** [*OPTIONS*]
   8
   9 Description
  10 -----------
  11
  12 NOTE: The 9p 'proxy' backend is deprecated (since QEMU 8.1) and will be
  13 removed, along with this daemon, in a future version of QEMU!
  14
  15 Pass-through security model in QEMU 9p server needs root privilege to do
  16 few file operations (like chown, chmod to any mode/uid:gid).  There are two
  17 issues in pass-through security model:
  18
  19 - TOCTTOU vulnerability: Following symbolic links in the server could
  20   provide access to files beyond 9p export path.
  21
  22 - Running QEMU with root privilege could be a security issue.
  23
  24 To overcome above issues, following approach is used: A new filesystem
  25 type 'proxy' is introduced. Proxy FS uses chroot + socket combination
  26 for securing the vulnerability known with following symbolic links.
  27 Intention of adding a new filesystem type is to allow qemu to run
  28 in non-root mode, but doing privileged operations using socket IO.
  29
  30 Proxy helper (a stand alone binary part of qemu) is invoked with
  31 root privileges. Proxy helper chroots into 9p export path and creates
  32 a socket pair or a named socket based on the command line parameter.
  33 QEMU and proxy helper communicate using this socket. QEMU proxy fs
  34 driver sends filesystem request to proxy helper and receives the
  35 response from it.
  36
  37 The proxy helper is designed so that it can drop root privileges except
  38 for the capabilities needed for doing filesystem operations.
  39
  40 Options
  41 -------
  42
  43 The following options are supported:
  44
  45 .. program:: virtfs-proxy-helper
  46
  47 .. option:: -h
  48
  49   Display help and exit
  50
  51 .. option:: -p, --path PATH
  52
  53   Path to export for proxy filesystem driver
  54
  55 .. option:: -f, --fd SOCKET_ID
  56
  57   Use given file descriptor as socket descriptor for communicating with
  58   qemu proxy fs drier. Usually a helper like libvirt will create
  59   socketpair and pass one of the fds as parameter to this option.
  60
  61 .. option:: -s, --socket SOCKET_FILE
  62
  63   Creates named socket file for communicating with qemu proxy fs driver
  64
  65 .. option:: -u, --uid UID
  66
  67   uid to give access to named socket file; used in combination with -g.
  68
  69 .. option:: -g, --gid GID
  70
  71   gid to give access to named socket file; used in combination with -u.
  72
  73 .. option:: -n, --nodaemon
  74
  75   Run as a normal program. By default program will run in daemon mode