From 247e3a72753ed35306d673abde80a0cd08b9f571 Mon Sep 17 00:00:00 2001 From: Pavel Hrdina Date: Tue, 4 Jul 2017 16:50:00 +0200 Subject: [PATCH] docs: introduce libvirt-dbus binding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit libvirt-dbus is a new binding that wraps libvirt API into D-Bus calls. Reviewed-by: Daniel P. Berrangé Signed-off-by: Pavel Hrdina --- docs/bindings.html.in | 13 +++++- docs/dbus.html.in | 102 +++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 6 ++- docs/downloads.html.in | 15 ++++++ 4 files changed, 133 insertions(+), 3 deletions(-) create mode 100644 docs/dbus.html.in diff --git a/docs/bindings.html.in b/docs/bindings.html.in index 733c89bc20..46930cd6f6 100644 --- a/docs/bindings.html.in +++ b/docs/bindings.html.in @@ -2,7 +2,7 @@ -

Bindings for other languages

+

Bindings for other languages and integration API modules

Libvirt supports C and C++ directly, and has bindings available @@ -74,6 +74,17 @@ +

+ Integration API modules: +

+ +
    +
  • + D-Bus: Pavel Hrdina develops + D-Bus API. +
    • +
+

For information on using libvirt on Windows please see the Windows support page. diff --git a/docs/dbus.html.in b/docs/dbus.html.in new file mode 100644 index 0000000000..6ff71d2770 --- /dev/null +++ b/docs/dbus.html.in @@ -0,0 +1,102 @@ + + + + +

D-Bus API bindings

+ +
    + +

    Description

    + +

    + libvirt-dbus wraps libvirt API to provide a high-level object-oriented + API better suited for dbus-based applications. +

    + +

    GIT source repository

    +

    + The D-Bus bindings source code is maintained in a + git repository available on + libvirt.org: +

    + +
    +git clone https://libvirt.org/git/libvirt-dbus.git
+
    + +

    + They can also be browsed online: +

    + +
    +https://libvirt.org/git/?p=libvirt-dbus.git
+
    + +

    Usage

    + +

    + 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). +

    + +

    + The name of the libvirt-dbus service is org.libvirt. + libvirt-dbus distributes an interface XML descriptions which can be + usually found at /usr/share/dbus-1/interfaces/. +

    + +

    + 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 + /etc/dbus-1/system.d/org.libvirt.conf that contains: +

    + +
    +<?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>
+
    + +

    + 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): +

    + +
    +gdbus introspect --xml --session --dest org.libvirt --object-path /org/libvirt
+gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt
+
    + +

    + Every object is introspectable so you can get a list of available + interfaces with methods, signals and properties running this command: +

    + +
    +gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt/QEMU
+
    + +

    + To get a list of domains for specific connection driver you can run + this command: +

    + +
    +gdbus call --system --dest org.libvirt --object-path /org/libvirt/QEMU \
+    --method org.libvirt.Connect.ListDomains 0
+
    + + + diff --git a/docs/docs.html.in b/docs/docs.html.in index ee521c7460..40e0e3b82e 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -54,7 +54,7 @@
    Virsh Commands
    Command reference for virsh
    -
    Language bindings
    +
    Language bindings and API modules
    Bindings of the libvirt API for c#, go, @@ -63,7 +63,9 @@ perl, python, php, - ruby
    + ruby + and integration API modules for + D-Bus
    XML schemas
    diff --git a/docs/downloads.html.in b/docs/downloads.html.in index 7c28e2ba9b..8cca203e54 100644 --- a/docs/downloads.html.in +++ b/docs/downloads.html.in @@ -220,6 +220,21 @@ api ref + + D-Bus + + ftp + https + + + libvirt + + + gitlab + github + + + Console Proxy