From: Pavel Hrdina <phrdina@redhat.com> Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/dbus.html.in | 94 ----------------------------------------------- docs/dbus.rst | 75 +++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 76 insertions(+), 95 deletions(-) delete mode 100644 docs/dbus.html.in create mode 100644 docs/dbus.rst diff --git a/docs/dbus.html.in b/docs/dbus.html.in deleted file mode 100644 index 99f191a685..0000000000 --- a/docs/dbus.html.in +++ /dev/null @@ -1,94 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>D-Bus API bindings</h1> - - <ul id="toc"></ul> - - <h2><a id="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 id="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://gitlab.com/libvirt/libvirt-dbus">gitlab.com</a>: - </p> - -<pre> -git clone https://gitlab.com/libvirt/libvirt-dbus.git -</pre> - - <h2><a id="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/dbus.rst b/docs/dbus.rst new file mode 100644 index 0000000000..f026dc0aba --- /dev/null +++ b/docs/dbus.rst @@ -0,0 +1,75 @@ +================== +D-Bus API bindings +================== + +.. contents:: + +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 <https://git-scm.com/>`__ +repository available on +`gitlab.com <https://gitlab.com/libvirt/libvirt-dbus>`__: + +:: + + git clone https://gitlab.com/libvirt/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/meson.build b/docs/meson.build index 6effe4f838..e73cb3c6cd 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -20,7 +20,6 @@ docs_assets = [ docs_html_in_files = [ '404', 'csharp', - 'dbus', 'docs', 'formatcaps', 'formatdomaincaps', @@ -57,6 +56,7 @@ docs_rst_files = [ 'contact', 'contribute', 'daemons', + 'dbus', 'downloads', 'drivers', 'drvbhyve', -- 2.35.1