docs/dbus.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>D-Bus API bindings</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a name="description">Description</a></h2>
  10
  11     <p>
  12       libvirt-dbus wraps libvirt API to provide a high-level object-oriented
  13       API better suited for dbus-based applications.
  14     </p>
  15
  16     <h2><a name="git">GIT source repository</a></h2>
  17     <p>
  18       The D-Bus bindings source code is maintained in a
  19       <a href="https://git-scm.com/">git</a> repository available on
  20       <a href="https://libvirt.org/git/">libvirt.org</a>:
  21     </p>
  22
  23 <pre>
  24 git clone https://libvirt.org/git/libvirt-dbus.git
  25 </pre>
  26
  27     <p>
  28       They can also be browsed online:
  29     </p>
  30
  31 <pre>
  32 <a href="https://libvirt.org/git/?p=libvirt-dbus.git">https://libvirt.org/git/?p=libvirt-dbus.git</a>
  33 </pre>
  34
  35     <h2><a name="usage">Usage</a></h2>
  36
  37     <p>
  38       libvirt-dbus exports libvirt API using D-Bus objects with methods and
  39       properties described by interfaces.  Currently only local connection
  40       to libvirt is exported and the list of supported drivers depends
  41       on the type of the bus connection (session or system).
  42     </p>
  43
  44     <p>
  45       The name of the libvirt-dbus service is <code>org.libvirt</code>.
  46       libvirt-dbus distributes an interface XML descriptions which can be
  47       usually found at <code>/usr/share/dbus-1/interfaces/</code>.
  48     </p>
  49
  50     <p>
  51       By default unprivileged user has access only to the session D-Bus
  52       connection. In order to allow specific user "foo" to access the system
  53       D-Bus connection you need to create a file
  54       <code>/etc/dbus-1/system.d/org.libvirt.conf</code> that contains:
  55     </p>
  56
  57 <pre>
  58 &lt;?xml version="1.0"?&gt;
  59 &lt;!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
  60  "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
  61
  62 &lt;busconfig&gt;
  63
  64   &lt;policy user="foo"&gt;
  65     &lt;allow send_destination="org.libvirt"/&gt;
  66   &lt;/policy&gt;
  67
  68 &lt;/busconfig&gt;
  69 </pre>
  70
  71     <p>
  72       To get a list of supported drivers for the specific bus connection
  73       you can run these commands (not all drivers may be available on
  74       the host):
  75     </p>
  76
  77 <pre>
  78 gdbus introspect --xml --session --dest org.libvirt --object-path /org/libvirt
  79 gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt
  80 </pre>
  81
  82     <p>
  83       Every object is introspectable so you can get a list of available
  84       interfaces with methods, signals and properties running this command:
  85     </p>
  86
  87 <pre>
  88 gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt/QEMU
  89 </pre>
  90
  91     <p>
  92       To get a list of domains for specific connection driver you can run
  93       this command:
  94     </p>
  95
  96 <pre>
  97 gdbus call --system --dest org.libvirt --object-path /org/libvirt/QEMU \
  98     --method org.libvirt.Connect.ListDomains 0
  99 </pre>
 100
 101   </body>
 102 </html>