<atitle="How and where to report bugs and request features"class="inactive"href="bugs.html">Bug reports</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="How to contact the developers via email and IRC"class="inactive"href="contact.html">Contact</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Miscellaneous links of interest related to libvirt"class="inactive"href="relatedlinks.html">Related Links</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Overview of all content on the website"class="inactive"href="sitemap.html">Sitemap</a>
</div>
</li>
</ul>
</li></ul>
</div>
<divid="content">
<h1>libvirt architecture</h1>
<p>Currently libvirt supports 2 kind of virtualization, and its
internal structure is based on a driver model which simplifies adding new
engines:</p>
<ul>
<li>
<ahref="#Xen">Xen hypervisor</a>
</li>
<li>
<ahref="#QEmu">QEmu and KVM based virtualization</a>
</li>
<li>
<ahref="#drivers">the driver architecture</a>
</li>
</ul>
<ul><li>
<ahref="#Xen">Xen hypervisor</a>
</li><li>
<ahref="#QEmu">QEmu and KVM based virtualization</a>
</li><li>
<ahref="#drivers">the driver architecture</a>
</li></ul>
<h3>
<aname="Xen"id="Xen">Libvirt Xen support</a>
</h3>
<aname="Xen"id="Xen">Libvirt Xen support</a>
</h3>
<p>When running in a Xen environment, programs using libvirt have to execute
in "Domain 0", which is the primary Linux OS loaded on the machine. That OS
kernel provides most if not all of the actual drivers used by the set of
...
...
@@ -112,13 +95,8 @@ this environment:</p>
privilege of the embedding program. If it runs with root access,
virConnectOpen() can be used, it will use three different ways to connect to
the Xen infrastructure:</p>
<ul>
<li>a connection to the Xen Daemon though an HTTP RPC layer</li>
<li>a read/write connection to the Xen Store</li>
<li>use Xen Hypervisor calls</li>
<li>when used as non-root libvirt connect to a proxy daemon running
as root and providing read-only support</li>
</ul>
<ul><li>a connection to the Xen Daemon though an HTTP RPC layer</li><li>a read/write connection to the Xen Store</li><li>use Xen Hypervisor calls</li><li>when used as non-root libvirt connect to a proxy daemon running
as root and providing read-only support</li></ul>
<p>The library will usually interact with the Xen daemon for any operation
changing the state of the system, but for performance and accuracy reasons
may talk directly to the hypervisor when gathering state information at
...
...
@@ -129,8 +107,8 @@ connect to initialize the library. It will then fork a libvirt_proxy
program running as root and providing read_only access to the API, this is
then only useful for reporting and monitoring.</p>
<h3>
<aname="QEmu"id="QEmu">Libvirt QEmu and KVM support</a>
</h3>
<aname="QEmu"id="QEmu">Libvirt QEmu and KVM support</a>
</h3>
<p>The model for QEmu and KVM is completely similar, basically KVM is based
on QEmu for the process controlling a new domain, only small details differs
between the two. In both case the libvirt API is provided by a controlling
...
...
@@ -143,8 +121,8 @@ domain, by specifying the architecture and machine type targeted.</p>
<p>The code controlling the QEmu process is available in the
<code>qemud/</code> directory.</p>
<h3>
<aname="drivers"id="drivers">the driver based architecture</a>
</h3>
<aname="drivers"id="drivers">the driver based architecture</a>
</h3>
<p>As the previous section explains, libvirt can communicate using different
channels with the current hypervisor, and should also be able to use
different kind of hypervisor. To simplify the internal design, code, ease
...
...
@@ -155,23 +133,15 @@ defining a common set of routines. That way the Xen Daemon access, the Xen
Store one, the Hypervisor hypercall are all isolated in separate C modules
implementing at least a subset of the common operations defined by the
drivers present in driver.h:</p>
<ul>
<li>xend_internal: implements the driver functions though the Xen
Daemon</li>
<li>xs_internal: implements the subset of the driver available though the
Xen Store</li>
<li>xen_internal: provide the implementation of the functions possible via
direct hypervisor access</li>
<li>proxy_internal: provide read-only Xen access via a proxy, the proxy code
is in the <code>proxy/</code>directory.</li>
<li>xm_internal: provide support for Xen defined but not running
domains.</li>
<li>qemu_internal: implement the driver functions for QEmu and
<ul><li>xend_internal: implements the driver functions though the Xen
Daemon</li><li>xs_internal: implements the subset of the driver available though the
Xen Store</li><li>xen_internal: provide the implementation of the functions possible via
direct hypervisor access</li><li>proxy_internal: provide read-only Xen access via a proxy, the proxy code
is in the <code>proxy/</code>directory.</li><li>xm_internal: provide support for Xen defined but not running
domains.</li><li>qemu_internal: implement the driver functions for QEmu and
KVM virtualization engines. It also uses a qemud/ specific daemon
which interacts with the QEmu process to implement libvirt API.</li>
<li>test: this is a test driver useful for regression tests of the
front-end part of libvirt.</li>
</ul>
which interacts with the QEmu process to implement libvirt API.</li><li>test: this is a test driver useful for regression tests of the
front-end part of libvirt.</li></ul>
<p>Note that a given driver may only implement a subset of those functions,
(for example saving a Xen domain state to disk and restoring it is only
possible though the Xen Daemon), in that case the driver entry points for
<atitle="How and where to report bugs and request features"class="inactive"href="bugs.html">Bug reports</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="How to contact the developers via email and IRC"class="inactive"href="contact.html">Contact</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Miscellaneous links of interest related to libvirt"class="inactive"href="relatedlinks.html">Related Links</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Overview of all content on the website"class="inactive"href="sitemap.html">Sitemap</a>
</div>
</li>
</ul>
</li></ul>
</div>
<divid="content">
<h1>Bindings for other languages</h1>
...
...
@@ -124,16 +106,11 @@
pure C. First the headers embeds the necessary declarations to
allow direct acces from C++ code, but also we have bindings for
higher level kind of languages:</p>
<ul>
<li>Python: Libvirt comes with direct support for the Python language
<ul><li>Python: Libvirt comes with direct support for the Python language
(just make sure you installed the libvirt-python package if not
compiling from sources). See below for more information about
using libvirt with python</li>
<li>Perl: Daniel Berrange provides <ahref="http://search.cpan.org/dist/Sys-Virt/">bindings for
Perl</a>.</li>
<li>OCaml: Richard Jones supplies <ahref="http://libvirt.org/ocaml/">bindings for OCaml</a>.</li>
<li>Ruby: David Lutterkort provides <ahref="http://libvirt.org/ruby/">bindings for Ruby</a>.</li>
</ul>
using libvirt with python</li><li>Perl: Daniel Berrange provides <ahref="http://search.cpan.org/dist/Sys-Virt/">bindings for
Perl</a>.</li><li>OCaml: Richard Jones supplies <ahref="http://libvirt.org/ocaml/">bindings for OCaml</a>.</li><li>Ruby: David Lutterkort provides <ahref="http://libvirt.org/ruby/">bindings for Ruby</a>.</li></ul>
<p>Support, requests or help for libvirt bindings are welcome on
the <ahref="https://www.redhat.com/mailman/listinfo/libvir-list/">mailing
list</a>, as usual try to provide enough background information
If you are using official binaries from <strong>Red Hat Enterprise Linux distribution</strong>,
tickets against the <code>Red Hat Enterprise Linux 5</code> product and
the <code>libvirt</code> component.
<ul><li><ahref="">View Red Hat Enterprise Linux libvirt tickets</a></li><li><ahref="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%205&component=libvirt">New Red Hat Enterprise Linux libvirt ticket</a></li></ul></li>
<li>
<ul><li><ahref="">View Red Hat Enterprise Linux libvirt tickets</a></li><li><ahref="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%205&component=libvirt">New Red Hat Enterprise Linux libvirt ticket</a></li></ul></li><li>
If you are using official binaries from another Linux distribution first
follow their own bug reporting guidelines.
</li>
</ul>
</li></ul>
<h2>How to file high quality bug reports</h2>
<p>
To increase the likelihood of your bug report being addressed it is
...
...
@@ -128,15 +104,8 @@
libvirt bugs use this checklist to see if you are providing enough
information:
</p>
<ul>
<li>The version number of the libvirt build, or date of the CVS
checkout</li>
<li>The hardware architecture being used</li>
<li>The name of the hypervisor (Xen, QEMU, KVM)</li>
<li>The XML config of the guest domain if relevant</li>
<li>For Xen hypervisor, the XenD logfile from /var/log/xen</li>
<li>For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu</li>
</ul>
<ul><li>The version number of the libvirt build, or date of the CVS
checkout</li><li>The hardware architecture being used</li><li>The name of the hypervisor (Xen, QEMU, KVM)</li><li>The XML config of the guest domain if relevant</li><li>For Xen hypervisor, the XenD logfile from /var/log/xen</li><li>For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu</li></ul>
<p>
If requesting a new feature attach any available patch to the ticket
and also email the patch to the libvirt mailing list for discussion
<atitle="How and where to report bugs and request features"class="inactive"href="bugs.html">Bug reports</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="How to contact the developers via email and IRC"class="inactive"href="contact.html">Contact</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Miscellaneous links of interest related to libvirt"class="inactive"href="relatedlinks.html">Related Links</a>
</div>
</li>
<li>
</li><li>
<div>
<atitle="Overview of all content on the website"class="inactive"href="sitemap.html">Sitemap</a>
</div>
</li>
</ul>
</li></ul>
</div>
<divid="content">
<h1>Handling of errors</h1>
<p>The main goals of libvirt when it comes to error handling are:</p>
<ul>
<li>provide as much detail as possible</li>
<li>provide the information as soon as possible</li>
<li>dont force the library user into one style of error handling</li>
</ul>
<ul><li>provide as much detail as possible</li><li>provide the information as soon as possible</li><li>dont force the library user into one style of error handling</li></ul>
<p>As result the library provide both synchronous, callback based and
asynchronous error reporting. When an error happens in the library code the
error is logged, allowing to retrieve it later and if the user registered an
...
...
@@ -99,43 +82,30 @@ the current connection they are related to, that way the error is stored in a
dynamic structure which can be made thread specific. Error callback can be
set specifically to a connection with</p>
<p>So error handling in the code is the following:</p>
<ol>
<li>if the error can be associated to a connection for example when failing
<ol><li>if the error can be associated to a connection for example when failing
to look up a domain
<ol><li>if there is a callback associated to the connection set with <ahref="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
call it with the error information</li><li>otherwise if there is a global callback set with <ahref="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
call it with the error information</li><li>otherwise call <ahref="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
which is the default error function of the library issuing the error
on stderr</li><li>save the error in the connection for later retrieval with <ahref="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li></ol></li>
<li>otherwise like when failing to create an hypervisor connection:
on stderr</li><li>save the error in the connection for later retrieval with <ahref="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li></ol></li><li>otherwise like when failing to create an hypervisor connection:
<ol><li>if there is a global callback set with <ahref="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
call it with the error information</li><li>otherwise call <ahref="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
which is the default error function of the library issuing the error
on stderr</li><li>save the error in the connection for later retrieval with <ahref="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li></ol></li>
</ol>
on stderr</li><li>save the error in the connection for later retrieval with <ahref="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li></ol></li></ol>
<p>In all cases the error information is provided as a <ahref="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
read-only structure <ahref="html/libvirt-virterror.html#virError">virError</a> containing the
following fields:</p>
<ul>
<li>code: an error number from the <ahref="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
enum</li>
<li>domain: an enum indicating which part of libvirt raised the error see
<li>level: the error level, usually VIR_ERR_ERROR, though there is room for
warnings like VIR_ERR_WARNING</li>
<li>message: the full human-readable formatted string of the error</li>
<li>conn: if available a pointer to the <ahref="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
connection to the hypervisor where this happened</li>
<li>dom: if available a pointer to the <ahref="html/libvirt-libvirt.html#virDomainPtr">virDomainPtr</a> domain
targeted in the operation</li>
</ul>
<ul><li>code: an error number from the <ahref="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
enum</li><li>domain: an enum indicating which part of libvirt raised the error see
<ahref="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li><li>level: the error level, usually VIR_ERR_ERROR, though there is room for
warnings like VIR_ERR_WARNING</li><li>message: the full human-readable formatted string of the error</li><li>conn: if available a pointer to the <ahref="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
connection to the hypervisor where this happened</li><li>dom: if available a pointer to the <ahref="html/libvirt-libvirt.html#virDomainPtr">virDomainPtr</a> domain
targeted in the operation</li></ul>
<p>and then extra raw information about the error which may be initialized
to 0 or NULL if unused</p>
<ul>
<li>str1, str2, str3: string information, usually str1 is the error
message format</li>
<li>int1, int2: integer information</li>
</ul>
<ul><li>str1, str2, str3: string information, usually str1 is the error
A <ahref="CIM/">CIM provider</a> for the DMTF virtualization schema
</li>
</ul>
</li></ul>
<h2>libvirt supports:</h2>
<ul>
<li>
<ul><li>
The <ahref="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen</a> hypervisor
on Linux and Solaris hosts.
</li>
<li>
</li><li>
The <ahref="http://fabrice.bellard.free.fr/qemu/">QEMU</a> emulator
</li>
<li>
</li><li>
The <ahref="http://kvm.qumranet.com/kvmwiki">KVM</a> Linux hypervisor
</li>
<li>
</li><li>
The <ahref="http://lxc.sourceforge.net/">LXC</a> Linux container system
</li>
<li>
</li><li>
The <ahref="http://openvz.org/">OpenVZ</a> Linux container system
</li>
<li>
</li><li>
Storage on IDE/SCSI/USB disks, FibreChannel, LVM, iSCSI, NFS and filesystems
</li>
</ul>
</li></ul>
<h2>libvirt provides:</h2>
<ul>
<li>Remote management using TLS encryption and x509 certificates</li>
<li>Remote management authenticating with Kerberos and SASL</li>
<li>Local access control using PolicyKit</li>
<li>Zero-conf discovery using Avahi multicast-DNS</li>
<li>Management of virtual machines, virtual networks and storage</li>
</ul>
<ul><li>Remote management using TLS encryption and x509 certificates</li><li>Remote management authenticating with Kerberos and SASL</li><li>Local access control using PolicyKit</li><li>Zero-conf discovery using Avahi multicast-DNS</li><li>Management of virtual machines, virtual networks and storage</li></ul>
