mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 21:55:25 +00:00
259 lines
12 KiB
HTML
259 lines
12 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="">
|
|
<title>Libvir the virtualization API</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<h1 align="center">Libvir the virtualization API</h1>
|
|
|
|
<h1>Note: this is the flat content of the <a href="index.html">web
|
|
site</a></h1>
|
|
|
|
<h1 style="text-align: center">libvir</h1>
|
|
|
|
<h3>what is <span class="style1">libvir?</span></h3>
|
|
|
|
<p>Libvir is a C toolkit to interract with the virtualization capabilities of
|
|
recent versions of Linux (and other OSes). It is free software available
|
|
under the <a href="http://www.opensource.org/licenses/lgpl-license.html">GNU
|
|
Lesser General Public License</a>. Virtualization of the Linux Operating
|
|
System means the ability to run multiple instances of Operating Systems
|
|
concurently on a single hardware system where the basic resources are driven
|
|
by a Linux instance. The library aim at providing long term stable C API
|
|
primarily for the <a
|
|
href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen
|
|
paravirtualization</a> mechanism but should be able to integrate other
|
|
virtualization mechanisms if needed.</p>
|
|
|
|
<h2><a name="News">Releases</a></h2>
|
|
|
|
<p>Here is the list of official releases, however since it is early on in the
|
|
development of libvir, it is preferable when possible to just use the <a
|
|
href="downloads.html">CVS version or snapshot</a>, contact the mailing list
|
|
and check the <a href="ChangeLog.html">ChangeLog</a> to gauge progresses.</p>
|
|
|
|
<h3>0.0.1: Dec 19 2005</h3>
|
|
<ul>
|
|
<li>First release</li>
|
|
<li>Basic management of existing Xen domains</li>
|
|
<li>Minimal autogenerated Python bindings</li>
|
|
</ul>
|
|
|
|
<h2><a name="Introducti">Introduction</a></h2>
|
|
|
|
<p>Libvir is a C toolkit to interract with the virtualization capabilities of
|
|
recent versions of Linux (and other OSes), but ibvir won't try to provide all
|
|
possible interfaces for interacting with the virtualization features.</p>
|
|
|
|
<p>To avoid ambiguity about the terms used here here are the definitions for
|
|
soem of the specific terms used in libvir documentation:</p>
|
|
<ul>
|
|
<li>a <strong>node</strong> is a single physical machine</li>
|
|
<li>an <strong>hypervisor</strong> is a layer of software allowing to
|
|
virtualize a node in a set of virtual machines with possibly different
|
|
configurations than the node itself</li>
|
|
<li>a <strong>domain</strong> is an instance of an operating system running
|
|
on a virtualized machine</li>
|
|
</ul>
|
|
|
|
<p style="text-align: center"><img
|
|
alt="Hypervisor and domains running on a node" src="node.gif"></p>
|
|
|
|
<p>Now we can define the goal of libvir: to provide the lowest possible
|
|
generic and stable layer to manage domains on a node.</p>
|
|
|
|
<p>This implies the following:</p>
|
|
<ul>
|
|
<li>the API should not be targetted to a single virtualization environment
|
|
though Xen is the current default, which also means that some very
|
|
specific capabilities which are not generic enough may not be provided as
|
|
libvir APIs</li>
|
|
<li>the API should allow to do efficiently and cleanly all the operations
|
|
needed to manage domains on a node</li>
|
|
<li>the API will not try to provide hight level multi-nodes management
|
|
features like load balancing, though they could be implemented on top of
|
|
libvir</li>
|
|
<li>stability of the API is a big concern, libvir should isolate
|
|
applications from the frequent changes expected at the lower level of the
|
|
virtualization framework</li>
|
|
</ul>
|
|
|
|
<p>So libvir should be a building block for higher level management tools or
|
|
for applications focusing on virtualization on a single node (the only
|
|
exception being domain migration between node capabilities which may need to
|
|
be added at the libvir level). Where possible libvir should be extendable to
|
|
be able to provide the same API for remote nodes, however this is not the
|
|
case at the moment, the code currently handle only local node access.</p>
|
|
|
|
<h2><a name="architecture">libvir architecture</a></h2>
|
|
|
|
<p>When running in a Xen environment, programs using libvir 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
|
|
domains. It also runs the Xen Store, a database of informations shared by the
|
|
hypervisor, the kernels, the drivers and the xen daemon. Xend. The xen daemon
|
|
supervise the control and execution of the sets of domains. The hypervisor,
|
|
drivers, kernels and daemons communicate though a shared system bus
|
|
implemented in the hypervisor. The figure below tries to provide a view of
|
|
this environment:</p>
|
|
<img src="architecture.gif" alt="The Xen architecture">
|
|
|
|
<p>The library can be initialized in 2 ways depending on the level of
|
|
priviledge 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>
|
|
</ul>
|
|
|
|
<p>The library will usually interract 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 informations at
|
|
least when possible (i.e. when the running program using libvir has root
|
|
priviledge access). </p>
|
|
|
|
<p> If it runs without root access virConnectOpenReadOnly() should be used to
|
|
connect to initialize the library. It will try to open the read-only socket
|
|
<code>/var/run/xenstored/socket_ro</code> to connect to the Xen Store and
|
|
also try to use the RPC to the Xen daemon. In this case use of hypervisor
|
|
calls and write to the Xen Store will not be possible, restraining the amount
|
|
of APIs available and slowing down information gathering about domains. </p>
|
|
|
|
<h2><a name="Downloads">Downloads</a></h2>
|
|
|
|
<p>The latest versions of libvir can be found on the <a
|
|
href="ftp://libvir.org/libvir/">libvir.org</a> server ( <a
|
|
href="http://libvir.org/sources/">HTTP</a>, <a
|
|
href="ftp://libvir.org/libvir/">FTP</a>). You will find there the released
|
|
versions as well as <a
|
|
href="http://libvir.org/sources/libvir-cvs-snapshot.tar.gz">snapshot
|
|
tarballs</a> updated from CVS head every hour</p>
|
|
|
|
<p>Anonymous <a href="http://ximbiot.com/cvs/cvshome/docs/">CVS</a> is also
|
|
available, first register onto the server:</p>
|
|
|
|
<p><code>cvs -d :pserver:anoncvs@libvir.org:2401/data/cvs login</code></p>
|
|
|
|
<p>it will request a password, enter <strong>anoncvs</strong>. Then you can
|
|
checkout the development tree with:</p>
|
|
|
|
<p><code>cvs -d :pserver:anoncvs@libvir.org:2401/data/cvs co libvir</code></p>
|
|
|
|
<p>Use ./autogen.sh to configure the local checkout, then <code>make</code>
|
|
and <code>make install</code>, as usual. All normal cvs commands are now
|
|
available except commiting to the base.</p>
|
|
|
|
<h2><a name="FAQ">FAQ</a></h2>
|
|
|
|
<p>Table of Contents:</p>
|
|
<ul>
|
|
<li><a href="FAQ.html#License">License(s)</a></li>
|
|
<li><a href="FAQ.html#Installati">Installation</a></li>
|
|
<li><a href="FAQ.html#Compilatio">Compilation</a></li>
|
|
<li><a href="FAQ.html#Developer">Developer corner</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="License">License</a>(s)</h3>
|
|
<ol>
|
|
<li><em>Licensing Terms for libvir</em>
|
|
<p>libvir is released under the <a
|
|
href="http://www.opensource.org/licenses/lgpl-license.html">GNU Lesser
|
|
General Public License</a>, see the file COPYING.LIB in the distribution
|
|
for the precise wording. The only library that libvir depends upon is the
|
|
Xen store access library which is also licenced under the LGPL.</p>
|
|
</li>
|
|
<li><em>Can I embed libvir in a proprietary application ?</em>
|
|
<p>Yes. The LGPL allows you to embed libvir into a proprietary
|
|
application. It would be graceful to send-back bug fixes and improvements
|
|
as patches for possible incorporation in the main development tree. It
|
|
will decrease your maintainance costs anyway if you do so.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3><a name="Installati">Installation</a></h3>
|
|
<ol>
|
|
<li><em>Where can I get libvir</em> ?
|
|
<p>The original distribution comes from <a
|
|
href="ftp://libvir.org/libvir/">ftp://libvir.org/libvir/</a>.</p>
|
|
</li>
|
|
<li><em>I can't install the libvir/libvir-devel RPM packages due to failed
|
|
dependencies</em>
|
|
<p>The most generic solution is to re-fetch the latest src.rpm , and
|
|
rebuild it locally with</p>
|
|
<p><code>rpm --rebuild libvir-xxx.src.rpm</code>.</p>
|
|
<p>If everything goes well it will generate two binary rpm packages (one
|
|
providing the shared libs and virsh, and the other one, the -devel
|
|
package, providing includes, static libraries and scripts needed to build
|
|
applications with libvir that you can install locally.</p>
|
|
<p>One can also rebuild the RPMs from a tarball:</p>
|
|
<p><code>rpmbuild -ta libdir-xxx.tar.gz</code></p>
|
|
<p>Or from a configured tree with:</p>
|
|
<p><code>make rpm</code></p>
|
|
</li>
|
|
<li><em>Failure to use the API for non-root users</em>
|
|
<p>Large parts of the API may only be accessible with root priviledges,
|
|
however the read only access to the xenstore data doesnot have to be
|
|
forbidden to user, at least for monitoring purposes. If "virsh info"
|
|
fails to run as an user, change the mode of the xenstore read-only socket
|
|
with:</p>
|
|
<p><code>chmod 666 /var/run/xenstored/socket_ro</code></p>
|
|
<p>and also make sure that the Xen Daemon is running correctly</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3><a name="Compilatio">Compilation</a></h3>
|
|
<ol>
|
|
<li><em>What is the process to compile libvir ?</em>
|
|
<p>As most UNIX libraries libvir follows the "standard":</p>
|
|
<p><code>gunzip -c libvir-xxx.tar.gz | tar xvf -</code></p>
|
|
<p><code>cd libvir-xxxx</code></p>
|
|
<p><code>./configure --help</code></p>
|
|
<p>to see the options, then the compilation/installation proper</p>
|
|
<p><code>./configure [possible options]</code></p>
|
|
<p><code>make</code></p>
|
|
<p><code>make install</code></p>
|
|
<p>At that point you may have to rerun ldconfig or a similar utility to
|
|
update your list of installed shared libs.</p>
|
|
</li>
|
|
<li><em>What other libraries are needed to compile/install libvir ?</em>
|
|
<p>Libvir requires libxenstore, which is usually provided by the xen
|
|
packages as well as the public headers to compile against libxenstore.</p>
|
|
</li>
|
|
<li><em>I use the CVS version and there is no configure script</em>
|
|
<p>The configure script (and other Makefiles) are generated. Use the
|
|
autogen.sh script to regenerate the configure script and Makefiles,
|
|
like:</p>
|
|
<p><code>./autogen.sh --prefix=/usr --disable-shared</code></p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3><a name="Developer">Developer</a> corner</h3>
|
|
<ol>
|
|
<li><em>Troubles compiling or linking programs using libvir</em>
|
|
<p>To simplify the process of reusing the library, libvir comes with
|
|
pkgconfig support, which can be used directly from autoconf support or
|
|
via the pkg-config command line tool, like:</p>
|
|
<p><code>pkg-config libvir --libs</code></p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h2><a name="Reporting">Reporting bugs and getting help</a></h2>
|
|
|
|
<p>There is a mailing-list <a
|
|
href="mailto:libvir-list@redhat.com">libvir-list@redhat.com</a> for libvir,
|
|
with an <a href="https://www.redhat.com/archives/libvir-list/">on-line
|
|
archive</a>. Please subscribe to this list before posting by visiting the <a
|
|
href="https://www.redhat.com/mailman/listinfo/libvir-list">associated Web</a>
|
|
page and follow the instructions. Patches with explanations and provided as
|
|
attachments are really appreciated and will be discussed on the mailing list.
|
|
If possible generate the patches by using cvs diff -u in a CVS checkout.</p>
|
|
|
|
<p>We expect to use <a href="https://bugzilla.redhat.com/">Red Hat
|
|
Bugzilla</a> to track bugs for libvir, though there isn't a libvir software
|
|
module defined yet, in the meantime use the mailing-list, thanks !.</p>
|
|
</body>
|
|
</html>
|