docs/interop/dbus.rst

   1 =====
   2 D-Bus
   3 =====
   4
   5 Introduction
   6 ============
   7
   8 QEMU may be running with various helper processes involved:
   9  - vhost-user* processes (gpu, virtfs, input, etc...)
  10  - TPM emulation (or other devices)
  11  - user networking (slirp)
  12  - network services (DHCP/DNS, samba/ftp etc)
  13  - background tasks (compression, streaming etc)
  14  - client UI
  15  - admin & cli
  16
  17 Having several processes allows stricter security rules, as well as
  18 greater modularity.
  19
  20 While QEMU itself uses QMP as primary IPC (and Spice/VNC for remote
  21 display), D-Bus is the de facto IPC of choice on Unix systems. The
  22 wire format is machine friendly, good bindings exist for various
  23 languages, and there are various tools available.
  24
  25 Using a bus, helper processes can discover and communicate with each
  26 other easily, without going through QEMU. The bus topology is also
  27 easier to apprehend and debug than a mesh. However, it is wise to
  28 consider the security aspects of it.
  29
  30 Security
  31 ========
  32
  33 A QEMU D-Bus bus should be private to a single VM. Thus, only
  34 cooperative tasks are running on the same bus to serve the VM.
  35
  36 D-Bus, the protocol and standard, doesn't have mechanisms to enforce
  37 security between peers once the connection is established. Peers may
  38 have additional mechanisms to enforce security rules, based for
  39 example on UNIX credentials.
  40
  41 The daemon can control which peers can send/recv messages using
  42 various metadata attributes, however, this is alone is not generally
  43 sufficient to make the deployment secure.  The semantics of the actual
  44 methods implemented using D-Bus are just as critical. Peers need to
  45 carefully validate any information they received from a peer with a
  46 different trust level.
  47
  48 dbus-daemon policy
  49 ------------------
  50
  51 dbus-daemon can enforce various policies based on the UID/GID of the
  52 processes that are connected to it. It is thus a good idea to run
  53 helpers as different UID from QEMU and set appropriate policies.
  54
  55 Depending on the use case, you may choose different scenarios:
  56
  57  - Everything the same UID
  58
  59    - Convenient for developers
  60    - Improved reliability - crash of one part doesn't take
  61      out entire VM
  62    - No security benefit over traditional QEMU, unless additional
  63      unless additional controls such as SELinux or AppArmor are
  64      applied
  65
  66  - Two UIDs, one for QEMU, one for dbus & helpers
  67
  68    - Moderately improved user based security isolation
  69
  70  - Many UIDs, one for QEMU one for dbus and one for each helpers
  71
  72    - Best user based security isolation
  73    - Complex to manager distinct UIDs needed for each VM
  74
  75 For example, to allow only ``qemu`` user to talk to ``qemu-helper``
  76 ``org.qemu.Helper1`` service, a dbus-daemon policy may contain:
  77
  78 .. code:: xml
  79
  80   <policy user="qemu">
  81      <allow send_destination="org.qemu.Helper1"/>
  82      <allow receive_sender="org.qemu.Helper1"/>
  83   </policy>
  84
  85   <policy user="qemu-helper">
  86      <allow own="org.qemu.Helper1"/>
  87   </policy>
  88
  89
  90 dbus-daemon can also perform SELinux checks based on the security
  91 context of the source and the target. For example, ``virtiofs_t``
  92 could be allowed to send a message to ``svirt_t``, but ``virtiofs_t``
  93 wouldn't be allowed to send a message to ``virtiofs_t``.
  94
  95 See dbus-daemon man page for details.
  96
  97 Guidelines
  98 ==========
  99
 100 When implementing new D-Bus interfaces, it is recommended to follow
 101 the "D-Bus API Design Guidelines":
 102 https://dbus.freedesktop.org/doc/dbus-api-design.html
 103
 104 The "org.qemu.*" prefix is reserved for services implemented &
 105 distributed by the QEMU project.
 106
 107 QEMU Interfaces
 108 ===============
 109
 110 :doc:`dbus-vmstate`
 111
 112 :doc:`dbus-display`