[libvirt] [PATCH] docs: introduce libvirt-dbus binding
Pavel Hrdina
phrdina at redhat.com
Fri Mar 23 07:35:34 UTC 2018
libvirt-dbus is a new binding that wraps libvirt API into D-Bus calls.
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
---
docs/bindings.html.in | 4 ++
docs/dbus.html.in | 102 +++++++++++++++++++++++++++++++++++++++++++++++++
docs/docs.html.in | 1 +
docs/downloads.html.in | 15 ++++++++
4 files changed, 122 insertions(+)
create mode 100644 docs/dbus.html.in
diff --git a/docs/bindings.html.in b/docs/bindings.html.in
index 733c89bc20..236bdcf2ae 100644
--- a/docs/bindings.html.in
+++ b/docs/bindings.html.in
@@ -18,6 +18,10 @@
<strong>Go</strong>: Daniel Berrange develops
<a href="https://godoc.org/github.com/libvirt/libvirt-go">Go bindings</a>.
</li>
+ <li>
+ <strong>D-Bus</strong>: Pavel Hrdina develops
+ <a href="dbus.html">D-Bus bindings</a>.
+ </li>
<li>
<strong>Java</strong>: Daniel Veillard develops
<a href="java.html">Java bindings</a>.
diff --git a/docs/dbus.html.in b/docs/dbus.html.in
new file mode 100644
index 0000000000..0da8096122
--- /dev/null
+++ b/docs/dbus.html.in
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+ <h1>D-Bus API bindings</h1>
+
+ <ul id="toc"></ul>
+
+ <h2><a name="description">Description</a></h2>
+
+ <p>
+ libvirt-dbus wraps libvirt API to provide a high-level object-oriented
+ API better suited for dbus-based applications.
+ </p>
+
+ <h2><a name="git">GIT source repository</a></h2>
+ <p>
+ The D-Bus bindings source code is maintained in a
+ <a href="https://git-scm.com/">git</a> repository available on
+ <a href="https://libvirt.org/git/">libvirt.org</a>:
+ </p>
+
+<pre>
+git clone https://libvirt.org/git/libvirt-dbus.git
+</pre>
+
+ <p>
+ They can also be browsed online:
+ </p>
+
+<pre>
+<a href="https://libvirt.org/git/?p=libvirt-dbus.git">https://libvirt.org/git/?p=libvirt-dbus.git</a>
+</pre>
+
+ <h2><a name="usage">Usage</a></h2>
+
+ <p>
+ libvirt-dbus exports libvirt API using D-Bus objects with methods and
+ properties described by interfaces. Currently only local connection
+ to libvirt is exported and the list of supported drivers depends
+ on the type of the bus connection (session or system).
+ </p>
+
+ <p>
+ The name of the libvirt-dbus service is <code>org.libvirt</code>.
+ libvirt-dbus distributes an interface XML descriptions which can be
+ usually found at <code>/usr/share/dbus-1/interfaces/</code>.
+ </p>
+
+ <p>
+ By default unprivileged user has access only to the session D-Bus
+ connection. In order to allow specific user "foo" to access the system
+ D-Bus connection you need to create a file
+ <code>/etc/dbus-1/system.d/org.libvirt.conf</code> that contains:
+ </p>
+
+<pre>
+<?xml version="1.0"?>
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+
+<busconfig>
+
+ <policy user="foo">
+ <allow send_destination="org.libvirt"/>
+ </policy>
+
+</busconfig>
+</pre>
+
+ <p>
+ To get a list of supported drivers for the specific bus connection
+ you can run these commands (not all drivers may be available on
+ the host):
+ </p>
+
+<pre>
+gdbus introspect --xml --session --dest org.libvirt --object-path /org/libvirt
+gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt
+</pre>
+
+ <p>
+ Every object is introspectable so you can get a list of available
+ interfaces with methods, signals and properties running this command:
+ </p>
+
+<pre>
+gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt/QEMU
+</pre>
+
+ <p>
+ To get a list of domains for specific connection driver you can run
+ this command:
+ </p>
+
+<pre>
+gdbus call --system --dest org.libvirt --object-path /org/libvirt/QEMU \
+ --method org.libvirt.Connect.ListDomains 0
+</pre>
+
+ </body>
+</html>
diff --git a/docs/docs.html.in b/docs/docs.html.in
index a8d544f83f..abd344ca2e 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -57,6 +57,7 @@
<dt><a href="bindings.html">Language bindings</a></dt>
<dd>Bindings of the libvirt API for
<a href="csharp.html">c#</a>,
+ <a href="dbus.html">D-Bus</a>,
<a href="https://godoc.org/github.com/libvirt/libvirt-go">go</a>,
<a href="java.html">java</a>,
<a href="https://libvirt.org/ocaml/">ocaml</a>.
diff --git a/docs/downloads.html.in b/docs/downloads.html.in
index 7c28e2ba9b..c2bc7af3e9 100644
--- a/docs/downloads.html.in
+++ b/docs/downloads.html.in
@@ -60,6 +60,21 @@
</td>
<td></td>
</tr>
+ <tr>
+ <td>D-Bus</td>
+ <td>
+ <a href="ftp://libvirt.org/libvirt/dbus/">ftp</a>
+ <a href="https://libvirt.org/sources/dbus/">https</a>
+ </td>
+ <td>
+ <a href="https://libvirt.org/git/?p=libvirt-dbus.git;a=summary">libvirt</a>
+ </td>
+ <td>
+ <a href="https://gitlab.com/libvirt/libvirt-dbus">gitlab</a>
+ <a href="https://github.com/libvirt/libvirt-dbus">github</a>
+ </td>
+ <td></td>
+ </tr>
<tr>
<td>Go</td>
<td>
--
2.14.3
More information about the libvir-list
mailing list