mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-05 21:01:13 +00:00
2548 lines
97 KiB
HTML
2548 lines
97 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="">
|
|
<title>Libvirt the virtualization API</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<h1 align="center">Libvirt 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">libvirt</h1>
|
|
|
|
<h3>what is <span class="style1">libvirt?</span></h3>
|
|
|
|
<p>Libvirt is a C toolkit to interact 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
|
|
initially for the <a
|
|
href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen
|
|
paravirtualization</a> but should be able to integrate other
|
|
virtualization mechanisms, it currently also support <a
|
|
href="http://fabrice.bellard.free.fr/qemu/">QEmu</a> and <a
|
|
href="http://kvm.qumranet.com/">KVM</a>.</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 libvirt, 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.2.3: Jun 8 2007</h3>
|
|
<ul>
|
|
<li>Documentation: documentation for upcoming remote access (Richard Jones),
|
|
virConnectNumOfDefinedDomains doc (Jan Michael), virsh help messages
|
|
for dumpxml and net-dumpxml (Chris Wright), </li>
|
|
<li>Bug fixes: RelaxNG schemas regexp fix (Robin Green), RelaxNG arch bug
|
|
(Mark McLoughlin), large buffers bug fixes (Shigeki Sakamoto), error
|
|
on out of memory condition (Shigeki Sakamoto), virshStrdup fix, non-root
|
|
driver when using Xen bug (Richard Jones), use --strict-order when
|
|
running dnsmasq (Daniel Berrange), virbr0 weirdness on restart (Mark
|
|
McLoughlin), keep connection error messages (Richard Jones), increase
|
|
QEmu read buffer on help (Daniel Berrange), rpm dependance on
|
|
dnsmasq (Daniel Berrange), fix XML boot device syntax (Daniel Berrange),
|
|
QEmu memory bug (Daniel Berrange), memory leak fix (Masayuki Sunou),
|
|
fix compiler flags (Richard Jones), remove type ioemu on recent Xen
|
|
HVM for paravirt drivers (Saori Fukuta), uninitialized string bug
|
|
(Masayuki Sunou), allow init even if the daemon is not running,
|
|
XML to config fix (Daniel Berrange)</li>
|
|
<li>Improvements: add a special error class for the test module (Richard
|
|
Jones), virConnectGetCapabilities on proxy (Richard Jones), allow
|
|
network driver to decline usage (Richard Jones), extend error messages
|
|
for upcoming remote access (Richard Jones), on_reboot support for QEmu
|
|
(Daniel Berrange), save daemon output in a log file (Daniel Berrange),
|
|
xenXMDomainDefineXML can override guest config (Hugh Brock),
|
|
add attach-device and detach-device commands to virsh (Masayuki Sunou
|
|
and Mark McLoughlin and Richard Jones), make virGetVersion case
|
|
insensitive and Python bindings (Richard Jones), new scheduler API
|
|
(Atsushi SAKAI), localizations updates, add logging option for virsh
|
|
(Nobuhiro Itou), allow arguments to be passed to bootloader (Hugh Brock),
|
|
increase the test suite (Daniel Berrange and Hugh Brock)</li>
|
|
<li>Cleanups: Remove VIR_DRV_OPEN_QUIET (Richard Jones), disable xm_internal.c
|
|
for Xen > 3.0.3 (Daniel Berrange), unused fields in _virDomain (Richard
|
|
Jones), export __virGetDomain and __virGetNetwork for libvirtd only
|
|
(Richard Jones), ignore old VNC config for HVM on recent Xen (Daniel
|
|
Berrange), various code cleanups, -Werror cleanup (Hugh Brock)</li>
|
|
</ul>
|
|
<h3>0.2.2: Apr 17 2007</h3>
|
|
<ul>
|
|
<li>Documentation: fix errors due to Amaya (with Simon Hernandez),
|
|
virsh uses kB not bytes (Atsushi SAKAI), add command line help to
|
|
qemud (Richard Jones), xenUnifiedRegister docs (Atsushi SAKAI),
|
|
strings typos (Nikolay Sivov), ilocalization probalem raised by
|
|
Thomas Canniot</li>
|
|
<li>Bug fixes: virsh memory values test (Masayuki Sunou), operations without
|
|
libvirt_qemud (Atsushi SAKAI), fix spec file (Florian La Roche, Jeremy
|
|
Katz, Michael Schwendt),
|
|
direct hypervisor call (Atsushi SAKAI), buffer overflow on qemu
|
|
networking command (Daniel Berrange), buffer overflow in quemud (Daniel
|
|
Berrange), virsh vcpupin bug (Masayuki Sunou), host PAE detections
|
|
and strcuctures size (Richard Jones), Xen PAE flag handling (Daniel
|
|
Berrange), bridged config configuration (Daniel Berrange), erroneous
|
|
XEN_V2_OP_SETMAXMEM value (Masayuki Sunou), memory free error (Mark
|
|
McLoughlin), set VIR_CONNECT_RO on read-only connections (S.Sakamoto),
|
|
avoid memory explosion bug (Daniel Berrange), integer overflow
|
|
for qemu CPU time (Daniel Berrange), QEMU binary path check (Daniel
|
|
Berrange)</li>
|
|
<li>Cleanups: remove some global variables (Jim Meyering), printf-style
|
|
functions checks (Jim Meyering), better virsh error messages, increase
|
|
compiler checkings and security (Daniel Berrange), virBufferGrow usage
|
|
and docs, use calloc instead of malloc/memset, replace all sprintf by
|
|
snprintf, avoid configure clobbering user's CTAGS (Jim Meyering),
|
|
signal handler error cleanup (Richard Jones), iptables internal code
|
|
claenup (Mark McLoughlin), unified Xen driver (Richard Jones),
|
|
cleanup XPath libxml2 calls, IPTables rules tightening (Daniel
|
|
Berrange), </li>
|
|
<li>Improvements: more regression tests on XML (Daniel Berrange), Python
|
|
bindings now generate exception in error cases (Richard Jones),
|
|
Python bindings for vir*GetAutoStart (Daniel Berrange),
|
|
handling of CD-Rom device without device name (Nobuhiro Itou),
|
|
fix hypervisor call to work with Xen 3.0.5 (Daniel Berrange),
|
|
DomainGetOSType for inactive domains (Daniel Berrange), multiple boot
|
|
devices for HVM (Daniel Berrange),
|
|
</li>
|
|
</ul>
|
|
<h3>0.2.1: Mar 16 2007</h3>
|
|
<ul>
|
|
<li>Various internal cleanups (Richard Jones,Daniel Berrange,Mark McLoughlin)</li>
|
|
<li>Bug fixes: libvirt_qemud daemon path (Daniel Berrange), libvirt
|
|
config directory (Daniel Berrange and Mark McLoughlin), memory leak
|
|
in qemud (Mark), various fixes on network support (Mark), avoid Xen
|
|
domain zombies on device hotplug errors (Daniel Berrange), various
|
|
fixes on qemud (Mark), args parsing (Richard Jones), virsh -t argument
|
|
(Saori Fukuta), avoid virsh crash on TAB key (Daniel Berrange), detect
|
|
xend operation failures (Kazuki Mizushima), don't listen on null socket
|
|
(Rich Jones), read-only socket cleanup (Rich Jones), use of vnc port 5900
|
|
(Nobuhiro Itou), assorted networking fixes (Daniel Berrange), shutoff and
|
|
shutdown mismatches (Kazuki Mizushima), unlimited memory handling
|
|
(Atsushi SAKAI), python binding fixes (Tatsuro Enokura)</li>
|
|
<li>Build and portability fixes: IA64 fixes (Atsushi SAKAI), dependancies
|
|
and build (Daniel Berrange), fix xend port detection (Daniel
|
|
Berrange), icompile time warnings (Mark), avoid const related
|
|
compiler warnings (Daniel Berrange), automated builds (Daniel
|
|
Berrange), pointer/int mismatch (Richard Jones), configure time
|
|
selection of drivers, libvirt spec hacking (Daniel Berrange)</li>
|
|
<li>Add support for network autostart and init scripts (Mark McLoughlin)</li>
|
|
<li>New API virConnectGetCapabilities() to detect the virtualization
|
|
capabilities of a host (Richard Jones)</li>
|
|
<li>Minor improvements: qemud signal handling (Mark), don't shutdown or reboot
|
|
domain0 (Kazuki Mizushima), QEmu version autodetection (Daniel Berrange),
|
|
network UUIDs (Mark), speed up UUID domain lookups (Tatsuro Enokura and
|
|
Daniel Berrange), support for paused QEmu CPU (Daniel Berrange), keymap
|
|
VNC attribute support (Takahashi Tomohiro and Daniel Berrange), maximum
|
|
number of virtual CPU (Masayuki Sunou), virtsh --readonly option (Rich
|
|
Jones), python bindings for new functions (Daniel Berrange)</li>
|
|
<li>Documentation updates especially on the XML formats</li>
|
|
</ul>
|
|
|
|
<h3>0.2.0: Feb 14 2007</h3>
|
|
<ul>
|
|
<li>Various internal cleanups (Mark McLoughlin, Richard Jones,
|
|
Daniel Berrange, Karel Zak)</li>
|
|
<li>Bug fixes: avoid a crash in connect (Daniel Berrange), virsh args
|
|
parsing (Richard Jones)</li>
|
|
<li>Add support for QEmu and KVM virtualization (Daniel Berrange)</li>
|
|
<li>Add support for network configuration (Mark McLoughlin)</li>
|
|
<li>Minor improvements: regression testing (Daniel Berrange),
|
|
localization string updates</li>
|
|
</ul>
|
|
|
|
<h3>0.1.11: Jan 22 2007</h3>
|
|
<ul>
|
|
<li>Finish XML <-> XM config files support</li>
|
|
<li>Remove memory leak when freeing virConf objects</li>
|
|
<li>Finishing inactive domain support (Daniel Berrange)</li>
|
|
<li>Added a Relax-NG schemas to check XML instances</li>
|
|
</ul>
|
|
|
|
<h3>0.1.10: Dec 20 2006</h3>
|
|
<ul>
|
|
<li>more localizations</li>
|
|
<li>bug fixes: VCPU info breakages on xen 3.0.3, xenDaemonListDomains buffer overflow (Daniel Berrange), reference count bug when creating Xen domains (Daniel Berrange).</li>
|
|
<li>improvements: support graphic framebuffer for Xen paravirt (Daniel Berrange), VNC listen IP range support (Daniel Berrange), support for default Xen config files and inactive domains of 3.0.4 (Daniel Berrange).</li>
|
|
</ul>
|
|
|
|
<h3>0.1.9: Nov 29 2006</h3>
|
|
<ul>
|
|
<li>python bindings: release interpeter lock when calling C (Daniel Berrange)</li>
|
|
<li>don't raise HTTP error when looking informations for a domain</li>
|
|
<li>some refactoring to use the driver for all entry points</li>
|
|
<li>better error reporting (Daniel Berrange)</li>
|
|
<li>fix OS reporting when running as non-root</li>
|
|
<li>provide XML parsing errors</li>
|
|
<li>extension of the test framework (Daniel Berrange)</li>
|
|
<li>fix the reconnect regression test</li>
|
|
<li>python bindings: Domain instances now link to the Connect to avoid garbage collection and disconnect</li>
|
|
<li>separate the notion of maximum memory and current use at the XML level</li>
|
|
<li>Fix a memory leak (Daniel Berrange)</li>
|
|
<li>add support for shareable drives</li>
|
|
<li>add support for non-bridge style networking configs for guests(Daniel Berrange)</li>
|
|
<li>python bindings: fix unsigned long marshalling (Daniel Berrange)</li>
|
|
<li>new config APIs virConfNew() and virConfSetValue() to build configs from scratch</li>
|
|
<li>hot plug device support based on Michel Ponceau patch</li>
|
|
<li>added support for inactive domains, new APIs, various associated cleanup (Daniel Berrange)</li>
|
|
<li>special device model for HVM guests (Daniel Berrange)</li>
|
|
<li>add API to dump core of domains (but requires a patched xend)</li>
|
|
<li>pygrub bootloader informations take over <os> informations</li>
|
|
<li>updated the localization strings</li>
|
|
</ul>
|
|
<h3>0.1.8: Oct 16 2006</h3>
|
|
<ul>
|
|
<li> Bug for system with page size != 4k</li>
|
|
<li> vcpu number initialization (Philippe Berthault)</li>
|
|
<li> don't label crashed domains as shut off (Peter Vetere)</li>
|
|
<li> fix virsh man page (Noriko Mizumoto)</li>
|
|
<li> blktapdd support for alternate drivers like blktap (Daniel Berrange)</li>
|
|
<li> memory leak fixes (xend interface and XML parsing) (Daniel Berrange)</li>
|
|
<li> compile fix</li>
|
|
<li> mlock/munlock size fixes (Daniel Berrange)</li>
|
|
<li> improve error reporting</li>
|
|
</ul>
|
|
<h3>0.1.7: Sep 29 2006</h3>
|
|
<ul>
|
|
<li> fix a memory bug on getting vcpu informations from xend (Daniel Berrange)</li>
|
|
<li> fix another problem in the hypercalls change in Xen changeset
|
|
86d26e6ec89b when getting domain informations (Daniel Berrange)</li>
|
|
</ul>
|
|
<h3>0.1.6: Sep 22 2006</h3>
|
|
<ul>
|
|
<li>Support for localization of strings using gettext (Daniel Berrange)</li>
|
|
<li>Support for new Xen-3.0.3 cdrom and disk configuration (Daniel Berrange)</li>
|
|
<li>Support for setting VNC port when creating domains with new
|
|
xend config files (Daniel Berrange) </li>
|
|
<li>Fix bug when running against xen-3.0.2 hypercalls (Jim Fehlig)</li>
|
|
<li>Fix reconnection problem when talking directly to http xend</li>
|
|
</ul>
|
|
<h3>0.1.5: Sep 5 2006</h3>
|
|
<ul>
|
|
<li>Support for new hypercalls change in Xen changeset 86d26e6ec89b</li>
|
|
<li>bug fixes: virParseUUID() was wrong, netwoking for paravirt guestsi
|
|
(Daniel Berrange), virsh on non-existent domains (Daniel Berrange),
|
|
string cast bug when handling error in python (Pete Vetere), HTTP
|
|
500 xend error code handling (Pete Vetere and Daniel Berrange)</li>
|
|
<li>improvements: test suite for SEXPR <-> XML format conversions (Daniel
|
|
Berrange), virsh output regression suite (Daniel Berrange), new environ
|
|
variable VIRSH_DEFAULT_CONNECT_URI for the default URI when connecting
|
|
(Daniel Berrange), graphical console support for paravirt guests
|
|
(Jeremy Katz), parsing of simple Xen config files (with Daniel Berrange),
|
|
early work on defined (not running) domains (Daniel Berrange),
|
|
virsh output improvement (Daniel Berrange</li>
|
|
</ul>
|
|
|
|
<h3>0.1.4: Aug 16 2006</h3>
|
|
<ul>
|
|
<li>bug fixes: spec file fix (Mark McLoughlin), error report problem (with
|
|
Hugh Brock), long integer in Python bindings (with Daniel Berrange), XML
|
|
generation bug for CDRom (Daniel Berrange), bug whem using number() XPath
|
|
function (Mark McLoughlin), fix python detection code, remove duplicate
|
|
initialization errors (Daniel Berrange)</li>
|
|
<li>improvements: UUID in XML description (Peter Vetere), proxy code
|
|
cleanup, virtual CPU and affinity support + virsh support (Michel
|
|
Ponceau, Philippe Berthault, Daniel Berrange), port and tty informations
|
|
for console in XML (Daniel Berrange), added XML dump to driver and proxy
|
|
support (Daniel Berrange), extention of boot options with support for
|
|
floppy and cdrom (Daniel Berrange), features block in XML to report/ask
|
|
PAE, ACPI, APIC for HVM domains (Daniel Berrange), fail saide-effect
|
|
operations when using read-only connection, large improvements to test
|
|
driver (Daniel Berrange) </li>
|
|
<li>documentation: spelling (Daniel Berrange), test driver examples.</li>
|
|
</ul>
|
|
|
|
<h3>0.1.3: Jul 11 2006</h3>
|
|
<ul>
|
|
<li>bugfixes: build as non-root, fix xend access when root, handling of
|
|
empty XML elements (Mark McLoughlin), XML serialization and parsing fixes
|
|
(Mark McLoughlin), allow to create domains without disk (Mark
|
|
McLoughlin),</li>
|
|
<li>improvement: xenDaemonLookupByID from O(n^2) to O(n) (Daniel Berrange),
|
|
support for fully virtualized guest (Jim Fehlig, DV, Mark McLoughlin)</li>
|
|
<li>documentation: augmented to cover hvm domains</li>
|
|
</ul>
|
|
|
|
<h3>0.1.2: Jul 3 2006</h3>
|
|
<ul>
|
|
<li>headers include paths fixup</li>
|
|
<li>proxy mechanism for unpriviledged read-only access by httpu</li>
|
|
</ul>
|
|
|
|
<h3>0.1.1: Jun 21 2006</h3>
|
|
<ul>
|
|
<li>building fixes: ncurses fallback (Jim Fehlig), VPATH builds (Daniel P.
|
|
Berrange)</li>
|
|
<li>driver cleanups: new entry points, cleanup of libvirt.c (with Daniel P.
|
|
Berrange)</li>
|
|
<li>Cope with API change introduced in Xen changeset 10277</li>
|
|
<li>new test driver for regression checks (Daniel P. Berrange)</li>
|
|
<li>improvements: added UUID to XML serialization, buffer usage (Karel
|
|
Zak), --connect argument to virsh (Daniel P. Berrange),</li>
|
|
<li>bug fixes: uninitialized memory access in error reporting, S-Expr
|
|
parsing (Jim Fehlig, Jeremy Katz), virConnectOpen bug, remove a TODO in
|
|
xs_internal.c</li>
|
|
<li>documentation: Python examples (David Lutterkort), new Perl binding
|
|
URL, man page update (Karel Zak)</li>
|
|
</ul>
|
|
|
|
<h3>0.1.0: Apr 10 2006</h3>
|
|
<ul>
|
|
<li>building fixes: --with-xen-distdir option (Ronald Aigner), out of tree
|
|
build and pkginfo cflag fix (Daniel Berrange)</li>
|
|
<li>enhancement and fixes of the XML description format (David Lutterkort
|
|
and Jim Fehlig)</li>
|
|
<li>new APIs: for Node information and Reboot</li>
|
|
<li>internal code cleanup: refactoring internals into a driver model, more
|
|
error handling, structure sharing, thread safety and ref counting</li>
|
|
<li>bug fixes: error message (Jim Meyering), error allocation in virsh (Jim
|
|
Meyering), virDomainLookupByID (Jim Fehlig),</li>
|
|
<li>documentation: updates on architecture, and format, typo fix (Jim
|
|
Meyering)</li>
|
|
<li>bindings: exception handling in examples (Jim Meyering), perl ones out
|
|
of tree (Daniel Berrange)</li>
|
|
<li>virsh: more options, create, nodeinfo (Karel Zak), renaming of some
|
|
options (Karel Zak), use stderr only for errors (Karel Zak), man page
|
|
(Andrew Puch)</li>
|
|
</ul>
|
|
|
|
<h3>0.0.6: Feb 28 2006</h3>
|
|
<ul>
|
|
<li>add UUID lookup and extract API</li>
|
|
<li>add error handling APIs both synchronous and asynchronous</li>
|
|
<li>added minimal hook for error handling at the python level, improved the
|
|
python bindings</li>
|
|
<li>augment the documentation and tests to cover error handling</li>
|
|
</ul>
|
|
|
|
<h3>0.0.5: Feb 23 2006</h3>
|
|
<ul>
|
|
<li>Added XML description parsing, dependance to libxml2, implemented the
|
|
creation API virDomainCreateLinux()</li>
|
|
<li>new APIs to lookup and name domain by UUID</li>
|
|
<li>fixed the XML dump when using the Xend access</li>
|
|
<li>Fixed a few more problem related to the name change</li>
|
|
<li>Adding regression tests in python and examples in C</li>
|
|
<li>web site improvement, extended the documentation to cover the XML
|
|
format and Python API</li>
|
|
<li>Added devhelp help for Gnome/Gtk programmers</li>
|
|
</ul>
|
|
|
|
<h3>0.0.4: Feb 10 2006</h3>
|
|
<ul>
|
|
<li>Fix various bugs introduced in the name change</li>
|
|
</ul>
|
|
|
|
<h3>0.0.3: Feb 9 2006</h3>
|
|
<ul>
|
|
<li>Switch name from from 'libvir' to libvirt</li>
|
|
<li>Starting infrastructure to add code examples</li>
|
|
<li>Update of python bindings for completeness</li>
|
|
</ul>
|
|
|
|
<h3>0.0.2: Jan 29 2006</h3>
|
|
<ul>
|
|
<li>Update of the documentation, web site redesign (Diana Fong)</li>
|
|
<li>integration of HTTP xend RPC based on libxend by Anthony Liquori for
|
|
most operations</li>
|
|
<li>Adding Save and Restore APIs</li>
|
|
<li>extended the virsh command line tool (Karel Zak)</li>
|
|
<li>remove xenstore transactions (Anthony Liguori)</li>
|
|
<li>fix the Python bindings bug when domain and connections where freed</li>
|
|
</ul>
|
|
|
|
<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>Libvirt is a C toolkit to interact with the virtualization capabilities of
|
|
recent versions of Linux (and other OSes), but libvirt 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
|
|
some of the specific concepts used in libvirt 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 provided by the hypervisor</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 libvirt: 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
|
|
libvirt 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
|
|
libvirt</li>
|
|
<li>stability of the API is a big concern, libvirt should isolate
|
|
applications from the frequent changes expected at the lower level of the
|
|
virtualization framework</li>
|
|
</ul>
|
|
|
|
<p>So libvirt should be a building block for higher level management tools
|
|
and for applications focusing on virtualization of a single node (the only
|
|
exception being domain migration between node capabilities which may need to
|
|
be added at the libvirt level). Where possible libvirt 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 accesses
|
|
(extension for remote access support is being worked on, see <a
|
|
href="bugs.html">the mailing list</a> discussions about it).</p>
|
|
|
|
<h2><a name="architecture">libvirt architecture</a></h2>
|
|
|
|
<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><a href="#Xen">Xen hypervisor</a></li>
|
|
<li><a href="#QEmu">QEmu and KVM based virtualization</a></li>
|
|
<li><a href="#drivers">the driver architecture</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="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
|
|
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>
|
|
<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 informations at
|
|
least when possible (i.e. when the running program using libvirt has root
|
|
priviledge access).</p>
|
|
|
|
<p>If it runs without root access virConnectOpenReadOnly() should be used to
|
|
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><a name="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
|
|
process forked by libvirt in the background and which launch and control the
|
|
QEmu or KVM process. That program called libvirt_qemud talks though a specific
|
|
protocol to the library, and connects to the console of the QEmu process in
|
|
order to control and report on its status. Libvirt tries to expose all the
|
|
emulations models of QEmu, the selection is done when creating the new
|
|
domain, by specifying the architecture and machine type targetted.</p>
|
|
|
|
<p>The code controlling the QEmu process is available in the
|
|
<code>qemud/</code> directory.</p>
|
|
|
|
<h3><a name="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
|
|
maintainance and simplify the support of other virtualization engine the
|
|
internals have been structured as one core component, the libvirt.c module
|
|
acting as a front-end for the library API and a set of hypvisor drivers
|
|
defining a common set of routines. That way the Xen Daemon accces, 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 availble 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 interracts 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
|
|
unsupported functions are initialized to NULL.</p>
|
|
|
|
<p></p>
|
|
|
|
<h2><a name="Downloads">Downloads</a></h2>
|
|
|
|
<p>The latest versions of libvirt can be found on the <a
|
|
href="ftp://libvirt.org/libvirt/">libvirt.org</a> server ( <a
|
|
href="http://libvirt.org/sources/">HTTP</a>, <a
|
|
href="ftp://libvirt.org/libvirt/">FTP</a>). You will find there the released
|
|
versions as well as <a
|
|
href="http://libvirt.org/sources/libvirt-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@libvirt.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@libvirt.org:2401/data/cvs co
|
|
libvirt</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="Format">XML Format</a></h2>
|
|
|
|
<p>This section describes the XML format used to represent domains, there are
|
|
variations on the format based on the kind of domains run and the options
|
|
used to launch them:</p>
|
|
|
|
<ul>
|
|
<li><a href="#Normal1">Normal paravirtualized Xen domains</a></li>
|
|
<li><a href="#Fully1">Fully virtualized Xen domains</a></li>
|
|
<li><a href="#KVM1">KVM domains</a></li>
|
|
<li><a href="#Net1">Networking options for QEmu and KVM</a></li>
|
|
<li><a href="#QEmu1">QEmu domains</a></li>
|
|
<li><a href="#Capa1">Discovering virtualization capabilities</a></li>
|
|
</ul>
|
|
|
|
<p>The formats try as much as possible to follow the same structure and reuse
|
|
elements and attributes where it makes sense.</p>
|
|
|
|
<h3 id="Normal"><a name="Normal1" id="Normal1">Normal paravirtualized Xen
|
|
guests</a>:</h3>
|
|
|
|
<p>The library use an XML format to describe domains, as input to <a
|
|
href="html/libvirt-libvirt.html#virDomainCreateLinux">virDomainCreateLinux()</a>
|
|
and as the output of <a
|
|
href="html/libvirt-libvirt.html#virDomainGetXMLDesc">virDomainGetXMLDesc()</a>,
|
|
the following is an example of the format as returned by the shell command
|
|
<code>virsh xmldump fc4</code> , where fc4 was one of the running domains:</p>
|
|
<pre><domain type='xen' <span style="color: #0071FF; background-color: #FFFFFF">id='18'</span>>
|
|
<name>fc4</name>
|
|
<span style="color: #00B200; background-color: #FFFFFF"><os>
|
|
<type>linux</type>
|
|
<kernel>/boot/vmlinuz-2.6.15-1.43_FC5guest</kernel>
|
|
<initrd>/boot/initrd-2.6.15-1.43_FC5guest.img</initrd>
|
|
<root>/dev/sda1</root>
|
|
<cmdline> ro selinux=0 3</cmdline>
|
|
</os></span>
|
|
<memory>131072</memory>
|
|
<vcpu>1</vcpu>
|
|
<devices>
|
|
<span style="color: #FF0080; background-color: #FFFFFF"><disk type='file'>
|
|
<source file='/u/fc4.img'/>
|
|
<target dev='sda1'/>
|
|
</disk></span>
|
|
<span style="color: #0000FF; background-color: #FFFFFF"><interface type='bridge'>
|
|
<source bridge='xenbr0'/>
|
|
<mac address='</span><span style="color: #0000FF; background-color: #FFFFFF"></span><span style="color: #0000FF; background-color: #FFFFFF">aa:00:00:00:00:11'/>
|
|
<script path='/etc/xen/scripts/vif-bridge'/>
|
|
</interface></span>
|
|
<span style="color: #FF8000; background-color: #FFFFFF"><console tty='/dev/pts/5'/></span>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<p>The root element must be called <code>domain</code> with no namespace, the
|
|
<code>type</code> attribute indicates the kind of hypervisor used, 'xen' is
|
|
the default value. The <code>id</code> attribute gives the domain id at
|
|
runtime (not however that this may change, for example if the domain is saved
|
|
to disk and restored). The domain has a few children whose order is not
|
|
significant:</p>
|
|
<ul>
|
|
<li>name: the domain name, preferably ASCII based</li>
|
|
<li>memory: the maximum memory allocated to the domain in kilobytes</li>
|
|
<li>vcpu: the number of virtual cpu configured for the domain</li>
|
|
<li>os: a block describing the Operating System, its content will be
|
|
dependant on the OS type
|
|
<ul>
|
|
<li>type: indicate the OS type, always linux at this point</li>
|
|
<li>kernel: path to the kernel on the Domain 0 filesystem</li>
|
|
<li>initrd: an optional path for the init ramdisk on the Domain 0
|
|
filesystem</li>
|
|
<li>cmdline: optional command line to the kernel</li>
|
|
<li>root: the root filesystem from the guest viewpoint, it may be
|
|
passed as part of the cmdline content too</li>
|
|
</ul>
|
|
</li>
|
|
<li>devices: a list of <code>disk</code>, <code>interface</code> and
|
|
<code>console</code> descriptions in no special order</li>
|
|
</ul>
|
|
|
|
<p>The format of the devices and their type may grow over time, but the
|
|
following should be sufficient for basic use:</p>
|
|
|
|
<p>A <code>disk</code> device indicates a block device, it can have two
|
|
values for the type attribute either 'file' or 'block' corresponding to the 2
|
|
options availble at the Xen layer. It has two mandatory children, and one
|
|
optional one in no specific order:</p>
|
|
<ul>
|
|
<li>source with a file attribute containing the path in Domain 0 to the
|
|
file or a dev attribute if using a block device, containing the device
|
|
name ('hda5' or '/dev/hda5')</li>
|
|
<li>target indicates in a dev attribute the device where it is mapped in
|
|
the guest</li>
|
|
<li>readonly an optional empty element indicating the device is
|
|
read-only</li>
|
|
</ul>
|
|
|
|
<p>An <code>interface</code> element describes a network device mapped on the
|
|
guest, it also has a type whose value is currently 'bridge', it also have a
|
|
number of children in no specific order:</p>
|
|
<ul>
|
|
<li>source: indicating the bridge name</li>
|
|
<li>mac: the optional mac address provided in the address attribute</li>
|
|
<li>ip: the optional IP address provided in the address attribute</li>
|
|
<li>script: the script used to bridge the interfcae in the Domain 0</li>
|
|
<li>target: and optional target indicating the device name.</li>
|
|
</ul>
|
|
|
|
<p>A <code>console</code> element describes a serial console connection to
|
|
the guest. It has no children, and a single attribute <code>tty</code> which
|
|
provides the path to the Pseudo TTY on which the guest console can be
|
|
accessed</p>
|
|
|
|
<p>Life cycle actions for the domain can also be expressed in the XML format,
|
|
they drive what should be happening if the domain crashes, is rebooted or is
|
|
poweroff. There is various actions possible when this happen:</p>
|
|
<ul>
|
|
<li>destroy: The domain is cleaned up (that's the default normal processing
|
|
in Xen)</li>
|
|
<li>restart: A new domain is started in place of the old one with the same
|
|
configuration parameters</li>
|
|
<li>preserve: The domain will remain in memory until it is destroyed
|
|
manually, it won't be running but allows for post-mortem debugging</li>
|
|
<li>rename-restart: a variant of the previous one but where the old domain
|
|
is renamed before being saved to allow a restart</li>
|
|
</ul>
|
|
|
|
<p>The following could be used for a Xen production system:</p>
|
|
<pre><domain>
|
|
...
|
|
<on_reboot>restart</on_reboot>
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_crash>rename-restart</on_crash>
|
|
...
|
|
</domain></pre>
|
|
|
|
<p>While the format may be extended in various ways as support for more
|
|
hypervisor types and features are added, it is expected that this core subset
|
|
will remain functional in spite of the evolution of the library.</p>
|
|
|
|
<h3 id="Fully"><a name="Fully1" id="Fully1">Fully virtualized guests</a>
|
|
(added in 0.1.3):</h3>
|
|
|
|
<p>Here is an example of a domain description used to start a fully
|
|
virtualized (a.k.a. HVM) Xen domain. This requires hardware virtualization
|
|
support at the processor level but allows to run unmodified operating
|
|
systems:</p>
|
|
<pre><domain type='xen' id='3'>
|
|
<name>fv0</name>
|
|
<uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
|
|
<os>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><type>hvm</type></span>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><loader>/usr/lib/xen/boot/hvmloader</loader></span>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><boot dev='hd'/></span>
|
|
</os>
|
|
<memory>524288</memory>
|
|
<vcpu>1</vcpu>
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_reboot>restart</on_reboot>
|
|
<on_crash>restart</on_crash>
|
|
<features>
|
|
<span style="color: #E50000; background-color: #FFFFFF"><pae/>
|
|
<acpi/>
|
|
<apic/></span>
|
|
</features>
|
|
<devices>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><emulator>/usr/lib/xen/bin/qemu-dm</emulator></span>
|
|
<interface type='bridge'>
|
|
<source bridge='xenbr0'/>
|
|
<mac address='00:16:3e:5d:c7:9e'/>
|
|
<script path='vif-bridge'/>
|
|
</interface>
|
|
<disk type='file'>
|
|
<source file='/root/fv0'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='hda'</span>/>
|
|
</disk>
|
|
<disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='cdrom'</span>>
|
|
<source file='/root/fc5-x86_64-boot.iso'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='hdc'</span>/>
|
|
<readonly/>
|
|
</disk>
|
|
<disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='floppy'</span>>
|
|
<source file='/root/fd.img'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='fda'</span>/>
|
|
</disk>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><graphics type='vnc' port='5904'/></span>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<p>There is a few things to notice specifically for HVM domains:</p>
|
|
<ul>
|
|
<li>the optional <code><features></code> block is used to enable
|
|
certain guest CPU / system features. For HVM guests the following
|
|
features are defined:
|
|
<ul>
|
|
<li><code>pae</code> - enable PAE memory addressing</li>
|
|
<li><code>apic</code> - enable IO APIC</li>
|
|
<li><code>acpi</code> - enable ACPI bios</li>
|
|
</ul>
|
|
</li>
|
|
<li>the <code><os></code> block description is very different, first
|
|
it indicates that the type is 'hvm' for hardware virtualization, then
|
|
instead of a kernel, boot and command line arguments, it points to an os
|
|
boot loader which will extract the boot informations from the boot device
|
|
specified in a separate boot element. The <code>dev</code> attribute on
|
|
the <code>boot</code> tag can be one of:
|
|
<ul>
|
|
<li><code>fd</code> - boot from first floppy device</li>
|
|
<li><code>hd</code> - boot from first harddisk device</li>
|
|
<li><code>cdrom</code> - boot from first cdrom device</li>
|
|
</ul>
|
|
</li>
|
|
<li>the <code><devices></code> section includes an emulator entry
|
|
pointing to an additional program in charge of emulating the devices</li>
|
|
<li>the disk entry indicates in the dev target section that the emulation
|
|
for the drive is the first IDE disk device hda. The list of device names
|
|
supported is dependant on the Hypervisor, but for Xen it can be any IDE
|
|
device <code>hda</code>-<code>hdd</code>, or a floppy device
|
|
<code>fda</code>, <code>fdb</code>. The <code><disk></code> element
|
|
also supports a 'device' attribute to indicate what kinda of hardware to
|
|
emulate. The following values are supported:
|
|
<ul>
|
|
<li><code>floppy</code> - a floppy disk controller</li>
|
|
<li><code>disk</code> - a generic hard drive (the default it
|
|
omitted)</li>
|
|
<li><code>cdrom</code> - a CDROM device</li>
|
|
</ul>
|
|
For Xen 3.0.2 and earlier a CDROM device can only be emulated on the
|
|
<code>hdc</code> channel, while for 3.0.3 and later, it can be emulated
|
|
on any IDE channel.</li>
|
|
<li>the <code><devices></code> section also include at least one
|
|
entry for the graphic device used to render the os. Currently there is
|
|
just 2 types possible 'vnc' or 'sdl'. If the type is 'vnc', then an
|
|
additional <code>port</code> attribute will be present indicating the TCP
|
|
port on which the VNC server is accepting client connections.</li>
|
|
</ul>
|
|
|
|
<p>It is likely that the HVM description gets additional optional elements
|
|
and attributes as the support for fully virtualized domain expands,
|
|
especially for the variety of devices emulated and the graphic support
|
|
options offered.</p>
|
|
|
|
<h3><a name="KVM1">KVM domain (added in 0.2.0)</a></h3>
|
|
|
|
<p>Support for the <a href="http://kvm.qumranet.com/">KVM virtualization</a>
|
|
is provided in recent Linux kernels (2.6.20 and onward). This requires
|
|
specific hardware with acceleration support and the availability of the
|
|
special version of the <a
|
|
href="http://fabrice.bellard.free.fr/qemu/">QEmu</a> binary. Since this
|
|
relies on QEmu for the machine emulation like fully virtualized guests the
|
|
XML description is quite similar, here is a simple example:</p>
|
|
<pre><domain <span style="color: #FF0000; background-color: #FFFFFF">type='kvm'</span>>
|
|
<name>demo2</name>
|
|
<uuid>4dea24b3-1d52-d8f3-2516-782e98a23fa0</uuid>
|
|
<memory>131072</memory>
|
|
<vcpu>1</vcpu>
|
|
<os>
|
|
<type>hvm</type>
|
|
</os>
|
|
<devices>
|
|
<span style="color: #FF0000; background-color: #FFFFFF"><emulator>/home/user/usr/kvm-devel/bin/qemu-system-x86_64</emulator></span>
|
|
<disk type='file' device='disk'>
|
|
<source file='/home/user/fedora/diskboot.img'/>
|
|
<target dev='hda'/>
|
|
</disk>
|
|
<interface <span style="color: #FF0000; background-color: #FFFFFF">type='user'</span>>
|
|
<mac address='24:42:53:21:52:45'/>
|
|
</interface>
|
|
<graphics type='vnc' port='-1'/>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<p>The specific points to note if using KVM are:</p>
|
|
<ul>
|
|
<li>the top level domain element carries a type of 'kvm'</li>
|
|
<li>the <devices> emulator points to the special qemu binary required
|
|
for KVM</li>
|
|
<li>networking interface definitions definitions are somewhat different due
|
|
to a different model from Xen see below</li>
|
|
</ul>
|
|
|
|
<p>except those points the options should be quite similar to Xen HVM
|
|
ones.</p>
|
|
|
|
<h3><a name="Net1">Networking options for QEmu and KVM (added in 0.2.0)</a></h3>
|
|
|
|
<p>The networking support in the QEmu and KVM case is more flexible, and
|
|
support a variety of options:</p>
|
|
<ol>
|
|
<li>Userspace SLIRP stack
|
|
<p>Provides a virtual LAN with NAT to the outside world. The virtual
|
|
network has DHCP & DNS services and will give the guest VM addresses
|
|
starting from <code>10.0.2.15</code>. The default router will be
|
|
<code>10.0.2.2</code> and the DNS server will be <code>10.0.2.3</code>.
|
|
This networking is the only option for unprivileged users who need their
|
|
VMs to have outgoing access. Example configs are:</p>
|
|
<pre><interface type='user'/></pre>
|
|
<pre>
|
|
<interface type='user'>
|
|
<mac address="11:22:33:44:55:66:/>
|
|
</interface>
|
|
</pre>
|
|
</li>
|
|
<li>Virtual network
|
|
<p>Provides a virtual network using a bridge device in the host.
|
|
Depending on the virtual network configuration, the network may be
|
|
totally isolated,NAT'ing to aan explicit network device, or NAT'ing to
|
|
the default route. DHCP and DNS are provided on the virtual network in
|
|
all cases and the IP range can be determined by examining the virtual
|
|
network config with '<code>virsh net-dumpxml <network
|
|
name></code>'. There is one virtual network called'default' setup out
|
|
of the box which does NAT'ing to the default route and has an IP range of
|
|
<code>192.168.22.0/255.255.255.0</code>. Each guest will have an
|
|
associated tun device created with a name of vnetN, which can also be
|
|
overriden with the <target> element. Example configs are:</p>
|
|
<pre><interface type='network'>
|
|
<source network='default'/>
|
|
</interface>
|
|
|
|
<interface type='network'>
|
|
<source network='default'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="11:22:33:44:55:66:/>
|
|
</interface>
|
|
</pre>
|
|
</li>
|
|
<li>Bridge to to LAN
|
|
<p>Provides a bridge from the VM directly onto the LAN. This assumes
|
|
there is a bridge device on the host which has one or more of the hosts
|
|
physical NICs enslaved. The guest VM will have an associated tun device
|
|
created with a name of vnetN, which can also be overriden with the
|
|
<target> element. The tun device will be enslaved to the bridge.
|
|
The IP range / network configuration is whatever is used on the LAN. This
|
|
provides the guest VM full incoming & outgoing net access just like a
|
|
physical machine. Examples include:</p>
|
|
<pre><interface type='bridge'>
|
|
<source dev='br0'/>
|
|
</interface>
|
|
|
|
<interface type='bridge'>
|
|
<source dev='br0'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="11:22:33:44:55:66:/>
|
|
</interface> <interface type='bridge'>
|
|
<source dev='br0'/>
|
|
<target dev='vnet7'/>
|
|
<mac address="11:22:33:44:55:66:/>
|
|
</interface></pre>
|
|
</li>
|
|
<li>Generic connection to LAN
|
|
<p>Provides a means for the administrator to execute an arbitrary script
|
|
to connect the guest's network to the LAN. The guest will have a tun
|
|
device created with a name of vnetN, which can also be overriden with the
|
|
<target> element. After creating the tun device a shell script will
|
|
be run which is expected to do whatever host network integration is
|
|
required. By default this script is called /etc/qemu-ifup but can be
|
|
overriden.</p>
|
|
<pre><interface type='ethernet'/>
|
|
|
|
<interface type='ethernet'>
|
|
<target dev='vnet7'/>
|
|
<script path='/etc/qemu-ifup-mynet'/>
|
|
</interface></pre>
|
|
</li>
|
|
<li>Multicast tunnel
|
|
<p>A multicast group is setup to represent a virtual network. Any VMs
|
|
whose network devices are in the same multicast group can talk to each
|
|
other even across hosts. This mode is also available to unprivileged
|
|
users. There is no default DNS or DHCP support and no outgoing network
|
|
access. To provide outgoing network access, one of the VMs should have a
|
|
2nd NIC which is connected to one of the first 4 network types and do the
|
|
appropriate routing. The multicast protocol is compatible with that used
|
|
by user mode linux guests too. The source address used must be from the
|
|
multicast address block.</p>
|
|
<pre><interface type='mcast'>
|
|
<source address='230.0.0.1' port='5558'/>
|
|
</interface></pre>
|
|
</li>
|
|
<li>TCP tunnel
|
|
<p>A TCP client/server architecture provides a virtual network. One VM
|
|
provides the server end of the netowrk, all other VMS are configured as
|
|
clients. All network traffic is routed between the VMs via the server.
|
|
This mode is also available to unprivileged users. There is no default
|
|
DNS or DHCP support and no outgoing network access. To provide outgoing
|
|
network access, one of the VMs should have a 2nd NIC which is connected
|
|
to one of the first 4 network types and do the appropriate routing.</p>
|
|
<p>Example server config:</p>
|
|
<pre><interface type='server'>
|
|
<source address='192.168.0.1' port='5558'/>
|
|
</interface></pre>
|
|
<p>Example client config:</p>
|
|
<pre><interface type='client'>
|
|
<source address='192.168.0.1' port='5558'/>
|
|
</interface></pre>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>To be noted, options 2, 3, 4 are also supported by Xen VMs, so it is
|
|
possible to use these configs to have networking with both Xen &
|
|
QEMU/KVMs connected to each other.</p>
|
|
|
|
<h3>Q<a name="QEmu1">Emu domain (added in 0.2.0)</a></h3>
|
|
|
|
<p>Libvirt support for KVM and QEmu is the same code base with only minor
|
|
changes. The configuration is as a result nearly identical, the only changes
|
|
are related to QEmu ability to emulate <a
|
|
href="http://www.qemu.org/status.html">various CPU type and hardware
|
|
platforms</a>, and kqemu support (QEmu own kernel accelerator when the
|
|
emulated CPU is i686 as well as the target machine):</p>
|
|
<pre><domain <span style="color: #FF0000; background-color: #FFFFFF">type='qemu'</span>>
|
|
<name>QEmu-fedora-i686</name>
|
|
<uuid>c7a5fdbd-cdaf-9455-926a-d65c16db1809</uuid>
|
|
<memory>219200</memory>
|
|
<currentMemory>219200</currentMemory>
|
|
<vcpu>2</vcpu>
|
|
<os>
|
|
<span style="color: #FF0000; background-color: #FFFFFF"><type arch='i686' machine='pc'>hvm</type></span>
|
|
<boot dev='cdrom'/>
|
|
</os>
|
|
<devices>
|
|
<span style="color: #FF0000; background-color: #FFFFFF"><emulator>/usr/bin/qemu</emulator></span>
|
|
<disk type='file' device='cdrom'>
|
|
<source file='/home/user/boot.iso'/>
|
|
<target dev='hdc'/>
|
|
<readonly/>
|
|
</disk>
|
|
<disk type='file' device='disk'>
|
|
<source file='/home/user/fedora.img'/>
|
|
<target dev='hda'/>
|
|
</disk>
|
|
<interface type='network'>
|
|
<source name='default'/>
|
|
</interface>
|
|
<graphics type='vnc' port='-1'/>
|
|
</devices>
|
|
</domain></pre>
|
|
|
|
<p>The difference here are:</p>
|
|
<ul>
|
|
<li>the value of type on top-level domain, it's 'qemu' or kqemu if asking
|
|
for <a href="http://www.qemu.org/kqemu-tech.html">kernel assisted
|
|
acceleration</a></li>
|
|
<li>the os type block defines the architecture to be emulated, and
|
|
optionally the machine type, see the discovery API below</li>
|
|
<li>the emulator string must point to the right emulator for that
|
|
architecture</li>
|
|
</ul>
|
|
|
|
<h3><a name="Capa1">Discovering virtualization capabilities (Added in 0.2.1)</a></h3>
|
|
|
|
<p>As new virtualization engine support gets added to libvirt, and to handle
|
|
cases like QEmu supporting a variety of emulations, a query interface has
|
|
been added in 0.2.1 allowing to list the set of supported virtualization
|
|
capabilities on the host:</p>
|
|
<pre> char * virConnectGetCapabilities (virConnectPtr conn);</pre>
|
|
|
|
<p>The value returned is an XML document listing the virtualization
|
|
capabilities of the host and virtualization engine to which
|
|
<code>@conn</code> is connected. One can test it using <code>virsh</code>
|
|
command line tool command '<code>capabilities</code>', it dumps the XML
|
|
associated to the current connection. For example in the case of a 64 bits
|
|
machine with hardware virtualization capabilities enabled in the chip and
|
|
BIOS you will see</p>
|
|
<pre><capabilities>
|
|
<span style="color: #E50000; background-color: #FFFFFF"><host>
|
|
<cpu>
|
|
<arch>x86_64</arch>
|
|
<features>
|
|
<vmx/>
|
|
</features>
|
|
</cpu>
|
|
</host></span>
|
|
|
|
<!-- xen-3.0-x86_64 -->
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><guest>
|
|
<os_type>xen</os_type>
|
|
<arch name="x86_64">
|
|
<wordsize>64</wordsize>
|
|
<domain type="xen"></domain>
|
|
<emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
|
|
</arch>
|
|
<features>
|
|
</features>
|
|
</guest></span>
|
|
|
|
<!-- hvm-3.0-x86_32 -->
|
|
<span style="color: #00B200; background-color: #FFFFFF"><guest>
|
|
<os_type>hvm</os_type>
|
|
<arch name="i686">
|
|
<wordsize>32</wordsize>
|
|
<domain type="xen"></domain>
|
|
<emulator>/usr/lib/xen/bin/qemu-dm</emulator>
|
|
<machine>pc</machine>
|
|
<machine>isapc</machine>
|
|
<loader>/usr/lib/xen/boot/hvmloader</loader>
|
|
</arch>
|
|
<features>
|
|
</features>
|
|
</guest></span>
|
|
...
|
|
</capabilities></pre>
|
|
|
|
<p>The fist block (in red) indicates the host hardware capbilities, currently
|
|
it is limited to the CPU properties but other information may be available,
|
|
it shows the CPU architecture, and the features of the chip (the feature
|
|
block is similar to what you will find in a Xen fully virtualized domain
|
|
description).</p>
|
|
|
|
<p>The second block (in blue) indicates the paravirtualization support of the
|
|
Xen support, you will see the os_type of xen to indicate a paravirtual
|
|
kernel, then architecture informations and potential features.</p>
|
|
|
|
<p>The third block (in green) gives similar informations but when running a
|
|
32 bit OS fully virtualized with Xen using the hvm support.</p>
|
|
|
|
<p>This section is likely to be updated and augmented in the future, see <a
|
|
href="https://www.redhat.com/archives/libvir-list/2007-March/msg00215.html">the
|
|
discussion</a> which led to the capabilities format in the mailing-list
|
|
archives.</p>
|
|
|
|
<h2><a name="Python" id="Python">Binding for Python</a></h2>
|
|
|
|
<p>Libvirt comes with direct support for the Python language (just
|
|
make sure you installed the libvirt-python package if not compiling
|
|
from sources). Also note that Daniel Berrange provides <a
|
|
href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">bindings for
|
|
Perl</a> and Richard Jones supplies <a
|
|
href="http://et.redhat.com/~rjones/ocaml-libvirt/">bindings for
|
|
OCaml</a> too.</p>
|
|
|
|
<p>The Python binding should be complete and are mostly automatically
|
|
generated from the formal description of the API in xml. The bindings are
|
|
articulated around 2 classes <code>virConnect</code> and virDomain mapping to
|
|
the C types. Functions in the C API taking either type as argument then
|
|
becomes methods for the classes, their name is just stripped from the
|
|
virConnect or virDomain(Get) prefix and the first letter gets converted to
|
|
lower case, for example the C functions:</p>
|
|
|
|
<p><code>int <a
|
|
href="html/libvirt-libvirt.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
|
|
(virConnectPtr conn);</code></p>
|
|
|
|
<p><code>int <a
|
|
href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
|
|
(virDomainPtr domain, unsigned long memory);</code></p>
|
|
|
|
<p>become</p>
|
|
|
|
<p><code>virConn::numOfDomains(self)</code></p>
|
|
|
|
<p><code>virDomain::setMaxMemory(self, memory)</code></p>
|
|
|
|
<p>This process is fully automated, you can get a summary of the conversion
|
|
in the file libvirtclass.txt present in the python dir or in the docs.There
|
|
is a couple of function who don't map directly to their C counterparts due to
|
|
specificities in their argument conversions:</p>
|
|
<ul>
|
|
<li><code><a
|
|
href="html/libvirt-libvirt.html#virConnectListDomains">virConnectListDomains</a></code>
|
|
is replaced by <code>virDomain::listDomainsID(self)</code> which returns
|
|
a list of the integer ID for the currently running domains</li>
|
|
<li><code><a
|
|
href="html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a></code>
|
|
is replaced by <code>virDomain::info()</code> which returns a list of
|
|
<ol>
|
|
<li>state: one of the state values (virDomainState)</li>
|
|
<li>maxMemory: the maximum memory used by the domain</li>
|
|
<li>memory: the current amount of memory used by the domain</li>
|
|
<li>nbVirtCPU: the number of virtual CPU</li>
|
|
<li>cpuTime: the time used by the domain in nanoseconds</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>So let's look at a simple example inspired from the <code>basic.py</code>
|
|
test found in <code>python/tests/</code> in the source tree:</p>
|
|
<pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
|
|
import sys
|
|
|
|
conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)
|
|
if conn == None:
|
|
print 'Failed to open connection to the hypervisor'
|
|
sys.exit(1)
|
|
|
|
try:
|
|
dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")
|
|
except:
|
|
print 'Failed to find the main domain'
|
|
sys.exit(1)
|
|
|
|
print "Domain 0: id %d running %s" % (dom0.<span style="color: #FF0080; background-color: #FFFFFF">ID</span>(), dom0.<span style="color: #FF0080; background-color: #FFFFFF">OSType</span>())
|
|
print dom0.<span style="color: #FF0080; background-color: #FFFFFF">info</span>()</pre>
|
|
|
|
<p>There is not much to comment about it, it really is a straight mapping
|
|
from the C API, the only points to notice are:</p>
|
|
<ul>
|
|
<li>the import of the module called <code><span
|
|
style="color: #0071FF; background-color: #FFFFFF">libvirt</span></code></li>
|
|
<li>getting a connection to the hypervisor, in that case using the
|
|
openReadOnly function allows the code to execute as a normal user.</li>
|
|
<li>getting an object representing the Domain 0 using <span
|
|
style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
|
|
<li>if the domain is not found a libvirtError exception will be raised</li>
|
|
<li>extracting and printing some informations about the domain using
|
|
various <span
|
|
style="color: #E50073; background-color: #FFFFFF">methods</span>
|
|
associated to the virDomain class.</li>
|
|
</ul>
|
|
|
|
<h2><a name="Errors" id="Errors">Handling of errors</a></h2>
|
|
|
|
<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 informations 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
|
|
error callback it will be called synchronously. Once the call to libvirt ends
|
|
the error can be detected by the return value and the full information for
|
|
the last logged error can be retrieved.</p>
|
|
|
|
<p>To avoid as much as prossible troubles with a global variable in a
|
|
multithreaded environment, libvirt will associate when possible the errors to
|
|
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
|
|
to look up a domain
|
|
<ol>
|
|
<li>if there is a callback associated to the connection set with <a
|
|
href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
|
|
call it with the error informations</li>
|
|
<li>otherwise if there is a global callback set with <a
|
|
href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
|
|
call it with the error information</li>
|
|
<li>otherwise call <a
|
|
href="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 <a
|
|
href="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 <a
|
|
href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
|
|
call it with the error information</li>
|
|
<li>otherwise call <a
|
|
href="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 <a
|
|
href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>In all cases the error informations are provided as a <a
|
|
href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
|
|
read-only structure <a
|
|
href="html/libvirt-virterror.html#virError">virError</a> containing the
|
|
following fields:</p>
|
|
<ul>
|
|
<li>code: an error number from the <a
|
|
href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
|
|
enum</li>
|
|
<li>domain: an enum indicating which part of libvirt raised the error see
|
|
<a
|
|
href="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 <a
|
|
href="html/libvirt-libvirt.html#virConnectPtr">virConnectPtr</a>
|
|
connection to the hypervisor where this happened</li>
|
|
<li>dom: if available a pointer to the <a
|
|
href="html/libvirt-libvirt.html#virDomainPtr">virDomainPtr</a> domain
|
|
targetted in the operation</li>
|
|
</ul>
|
|
|
|
<p>and then extra raw informations about the error which may be initialized
|
|
to 0 or NULL if unused</p>
|
|
<ul>
|
|
<li>str1, str2, str3: string informations, usually str1 is the error
|
|
message format</li>
|
|
<li>int1, int2: integer informations</li>
|
|
</ul>
|
|
|
|
<p>So usually, setting up specific error handling with libvirt consist of
|
|
registering an handler with with <a
|
|
href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
|
|
with <a
|
|
href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
|
|
chech the value of the code value, take appropriate action, if needed let
|
|
libvirt print the error on stderr by calling <a
|
|
href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>.
|
|
For asynchronous error handing, set such a function doing nothing to avoid
|
|
the error being reported on stderr, and call virConnGetLastError or
|
|
virGetLastError when an API call returned an error value. It can be a good
|
|
idea to use <a
|
|
href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a
|
|
href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a>
|
|
once an error has been processed fully.</p>
|
|
|
|
<p>At the python level, there only a global reporting callback function at
|
|
this point, see the error.py example about it:</p>
|
|
<pre>def handler(ctxt, err):
|
|
global errno
|
|
|
|
#print "handler(%s, %s)" % (ctxt, err)
|
|
errno = err
|
|
|
|
libvirt.registerErrorHandler(handler, 'context') </pre>
|
|
|
|
<p>the second argument to the registerErrorHandler function is passed as the
|
|
fist argument of the callback like in the C version. The error is a tuple
|
|
containing the same field as a virError in C, but cast to Python.</p>
|
|
|
|
<h2><a name="FAQ" id="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 libvirt</em>
|
|
<p>libvirt 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 libvirt depends upon is
|
|
the Xen store access library which is also licenced under the LGPL.</p>
|
|
</li>
|
|
<li><em>Can I embed libvirt in a proprietary application ?</em>
|
|
<p>Yes. The LGPL allows you to embed libvirt 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 libvirt</em> ?
|
|
<p>The original distribution comes from <a
|
|
href="ftp://libvirt.org/libvirt/">ftp://libvirt.org/libvirt/</a>.</p>
|
|
</li>
|
|
<li><em>I can't install the libvirt/libvirt-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 libvirt-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 libvirt 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 dominfo"
|
|
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 with local
|
|
HTTP server enabled, this is defined in
|
|
<code>/etc/xen/xend-config.sxp</code> which need the following line to be
|
|
enabled:</p>
|
|
<p><code>(xend-http-server yes)</code></p>
|
|
<p>If needed restart the xend daemon after making the change with the
|
|
following command run as root:</p>
|
|
<p><code>service xend restart</code></p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3><a name="Compilatio">Compilation</a></h3>
|
|
<ol>
|
|
<li><em>What is the process to compile libvirt ?</em>
|
|
<p>As most UNIX libraries libvirt follows the "standard":</p>
|
|
<p><code>gunzip -c libvirt-xxx.tar.gz | tar xvf -</code></p>
|
|
<p><code>cd libvirt-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 libvirt ?</em>
|
|
<p>Libvirt 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 libvirt</em>
|
|
<p>To simplify the process of reusing the library, libvirt 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 libvirt --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 libvirt,
|
|
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 use Red Hat Bugzilla to track bugs and new feature requests to libvirt.
|
|
If you want to report a bug or ask for a feature, please check <a href="http://bugzilla.redhat.com/bugzilla/buglist.cgi?component=libvirt&component=libvirt-devel&component=libvirt-python&bug_status=ASSIGNED&bug_status=INVESTIGATE&bug_status=NEW&bug_status=REOPENED&bug_status=VERIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&Search=Search">the existing open bugs</a>, then if yours isn't a duplicate of
|
|
an existing bug, <a href="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora%20Core&component=libvirt">log a new bug</a> and attach any patch or extra data that you may have available. It is always a good idea to also
|
|
to post to the <a href="mailto:libvir-list@redhat.com">mailing-list</a>
|
|
too, so that everybody working on the project can see it, thanks !</p>
|
|
|
|
<h2><a name="Remote">Remote support</a></h2>
|
|
|
|
<p>
|
|
Libvirt allows you to access hypervisors running on remote
|
|
machines through authenticated and encrypted connections.
|
|
</p>
|
|
|
|
<h3><a name="Remote_basic_usage">Basic usage</a></h3>
|
|
|
|
<p>
|
|
On the remote machine, <code>libvirtd</code> should be running.
|
|
See <a href="#Remote_libvirtd_configuration">the section
|
|
on configuring libvirtd</a> for more information.
|
|
</p>
|
|
|
|
<p>
|
|
To tell libvirt that you want to access a remote resource,
|
|
you should supply a hostname in the normal <a href="uri.html">URI</a> that is passed
|
|
to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
|
|
For example, if you normally use <code>qemu:///system</code>
|
|
to access the system-wide QEMU daemon, then to access
|
|
the system-wide QEMU daemon on a remote machine called
|
|
<code>oirase</code> you would use <code>qemu://oirase/system</code>.
|
|
</p>
|
|
|
|
<p>
|
|
The <a href="#Remote_URI_reference">section on remote URIs</a>
|
|
describes in more detail these remote URIs.
|
|
</p>
|
|
|
|
<p>
|
|
From an API point of view, apart from the change in URI, the
|
|
API should behave the same. For example, ordinary calls
|
|
are routed over the remote connection transparently, and
|
|
values or errors from the remote side are returned to you
|
|
as if they happened locally. Some differences you may notice:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> Additional errors can be generated, specifically ones
|
|
relating to failures in the remote transport itself. </li>
|
|
<li> Remote calls are handled synchronously, so they will be
|
|
much slower than, say, direct hypervisor calls. </li>
|
|
</ul>
|
|
|
|
<h3><a name="Remote_transports">Transports</a></h3>
|
|
|
|
<p>
|
|
Remote libvirt supports a range of transports:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt> tls </dt>
|
|
<dd> <a href="http://en.wikipedia.org/wiki/Transport_Layer_Security"
|
|
title="Transport Layer Security">TLS</a>
|
|
1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually
|
|
listening on a public port number. To use this you will need to
|
|
<a href="#Remote_certificates"
|
|
title="Generating TLS certificates">generate client and
|
|
server certificates</a>.
|
|
The standard port is 16514.
|
|
</dd>
|
|
|
|
<dt> unix </dt>
|
|
<dd> Unix domain socket. Since this is only accessible on the
|
|
local machine, it is not encrypted, and uses Unix permissions or
|
|
SELinux for authentication.
|
|
The standard socket names are
|
|
<code>/var/run/libvirt/libvirt-sock</code> and
|
|
<code>/var/run/libvirt/libvirt-sock-ro</code> (the latter
|
|
for read-only connections).
|
|
</dd>
|
|
|
|
<dt> ssh </dt>
|
|
<dd> Transported over an ordinary
|
|
<a href="http://www.openssh.com/" title="OpenSSH homepage">ssh
|
|
(secure shell)</a> connection.
|
|
Requires <a href="http://netcat.sourceforge.net/">Netcat (nc)</a>
|
|
installed on the remote machine, and the remote libvirtd should
|
|
be listening on the unix transport. You should use some sort of
|
|
ssh key management (eg.
|
|
<a href="http://mah.everybody.org/docs/ssh"
|
|
title="Using ssh-agent with ssh">ssh-agent</a>)
|
|
otherwise programs which use
|
|
this transport will stop to ask for a password. </dd>
|
|
|
|
<dt> ext </dt>
|
|
<dd> Any external program which can make a connection to the
|
|
remote machine by means outside the scope of libvirt. </dd>
|
|
|
|
<dt> tcp </dt>
|
|
<dd> Unencrypted TCP/IP socket. Not recommended for production
|
|
use, this is normally disabled, but an administrator can enable
|
|
it for testing or use over a trusted network.
|
|
The standard port is 16509.
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
The default transport, if no other is specified, is <code>tls</code>.
|
|
</p>
|
|
|
|
<h3><a name="Remote_URI_reference">Remote URIs</a></h3>
|
|
|
|
<p>
|
|
See also: <a href="uri.html">documentation on ordinary ("local") URIs</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Remote URIs have the general form ("[...]" meaning an optional part):
|
|
</p>
|
|
|
|
<p>
|
|
<code>driver</code>[<code>+transport</code>]<code>://</code>[<code>username@</code>][<code>hostname</code>][<code>:port</code>]<code>/</code>[<code>path</code>][<code>?extraparameters</code>]
|
|
</p>
|
|
|
|
<p>
|
|
Either the transport or the hostname must be given in order
|
|
to distinguish this from a local URI.
|
|
</p>
|
|
|
|
<p>
|
|
Some examples:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> <code>xen+ssh://rjones@towada/</code> <br/> — Connect to a
|
|
remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh
|
|
username <code>rjones</code>.
|
|
</li>
|
|
|
|
<li> <code>xen://towada/</code> <br/> — Connect to a
|
|
remote Xen hypervisor on host <code>towada</code> using TLS.
|
|
</li>
|
|
|
|
<li> <code>xen://towada/?no_verify=1</code> <br/> — Connect to a
|
|
remote Xen hypervisor on host <code>towada</code> using TLS. Do not verify
|
|
the server's certificate.
|
|
</li>
|
|
|
|
<li> <code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code> <br/> —
|
|
Connect to the local qemu instances over a non-standard
|
|
Unix socket (the full path to the Unix socket is
|
|
supplied explicitly in this case).
|
|
</li>
|
|
|
|
<li> <code>test+tcp://localhost:5000/default</code> <br/> —
|
|
Connect to a libvirtd daemon offering unencrypted TCP/IP connections
|
|
on localhost port 5000 and use the test driver with default
|
|
settings.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<h4><a name="Remote_URI_parameters">Extra parameters</a></h4>
|
|
|
|
<p>
|
|
Extra parameters can be added to remote URIs as part
|
|
of the query string (the part following <q><code>?</code></q>).
|
|
Remote URIs understand the extra parameters shown below.
|
|
Any others are passed unmodified through to the back end.
|
|
Note that parameter values must be
|
|
<a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>.
|
|
</p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Name </th>
|
|
<th> Transports </th>
|
|
<th> Meaning </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>name</code> </td>
|
|
<td> <i>any transport</i> </td>
|
|
<td>
|
|
The name passed to the remote virConnectOpen function. The
|
|
name is normally formed by removing transport, hostname, port
|
|
number, username and extra parameters from the remote URI, but in certain
|
|
very complex cases it may be better to supply the name explicitly.
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>name=qemu:///system</code> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>command</code> </td>
|
|
<td> ssh, ext </td>
|
|
<td>
|
|
The external command. For ext transport this is required.
|
|
For ssh the default is <code>ssh</code>.
|
|
The PATH is searched for the command.
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>command=/opt/openssh/bin/ssh</code> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>socket</code> </td>
|
|
<td> unix, ssh </td>
|
|
<td>
|
|
The path to the Unix domain socket, which overrides the
|
|
compiled-in default. For ssh transport, this is passed to
|
|
the remote netcat command (see next).
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>netcat</code> </td>
|
|
<td> ssh </td>
|
|
<td>
|
|
The name of the netcat command on the remote machine.
|
|
The default is <code>nc</code>. For ssh transport, libvirt
|
|
constructs an ssh command which looks like:
|
|
|
|
<pre>
|
|
<i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i>
|
|
</pre>
|
|
|
|
where <i>port</i>, <i>username</i>, <i>hostname</i> can be
|
|
specified as part of the remote URI, and <i>command</i>, <i>netcat</i>
|
|
and <i>socket</i> come from extra parameters (or
|
|
sensible defaults).
|
|
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>no_verify</code> </td>
|
|
<td> tls </td>
|
|
<td>
|
|
If set to a non-zero value, this disables client checks of the
|
|
server's certificate. Note that to disable server checks of
|
|
the client's certificate or IP address you must
|
|
<a href="#Remote_libvirtd_configuration">change the libvirtd
|
|
configuration</a>.
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>no_verify=1</code> </td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<h3><a name="Remote_certificates">Generating TLS certificates</a></h3>
|
|
|
|
<h4>Public Key Infrastructure set up</h4>
|
|
|
|
<p>
|
|
If you are unsure how to create TLS certificates, skip to the
|
|
next section.
|
|
</p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Location </th>
|
|
<th> Machine </th>
|
|
<th> Description </th>
|
|
<th> Required fields </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>/etc/pki/CA/cacert.pem</code> </td>
|
|
<td> Installed on all clients and servers </td>
|
|
<td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td>
|
|
<td> n/a </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>/etc/pki/libvirt/ private/serverkey.pem</code> </td>
|
|
<td> Installed on the server </td>
|
|
<td> Server's private key (<a href="#Remote_TLS_server_certificates">more info</a>)</td>
|
|
<td> n/a </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>/etc/pki/libvirt/ servercert.pem</code> </td>
|
|
<td> Installed on the server </td>
|
|
<td> Server's certificate signed by the CA.
|
|
(<a href="#Remote_TLS_server_certificates">more info</a>) </td>
|
|
<td> CommonName (CN) must be the hostname of the server as it
|
|
is seen by clients. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>/etc/pki/libvirt/ private/clientkey.pem</code> </td>
|
|
<td> Installed on the client </td>
|
|
<td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td>
|
|
<td> n/a </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>/etc/pki/libvirt/ clientcert.pem</code> </td>
|
|
<td> Installed on the client </td>
|
|
<td> Client's certificate signed by the CA
|
|
(<a href="#Remote_TLS_client_certificates">more info</a>) </td>
|
|
<td> Distinguished Name (DN) can be checked against an access
|
|
control list (<code>tls_allowed_dn_list</code>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h4><a name="Remote_TLS_background">Background to TLS certificates</a></h4>
|
|
|
|
<p>
|
|
Libvirt supports TLS certificates for verifying the identity
|
|
of the server and clients. There are two distinct checks involved:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> The client should know that it is connecting to the right
|
|
server. Checking done by client by matching the certificate that
|
|
the server sends to the server's hostname. May be disabled by adding
|
|
<code>?no_verify=1</code> to the
|
|
<a href="#Remote_URI_parameters">remote URI</a>.
|
|
</li>
|
|
|
|
<li> The server should know that only permitted clients are
|
|
connecting. This can be done based on client's IP address, or on
|
|
client's IP address and client's certificate. Checking done by the
|
|
server. May be enabled and disabled in the <a
|
|
href="#Remote_libvirtd_configuration">libvirtd.conf file</a>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
For full certificate checking you will need to have certificates
|
|
issued by a recognised <a
|
|
href="http://en.wikipedia.org/wiki/Certificate_authority">Certificate
|
|
Authority (CA)</a> for your server(s) and all clients. To avoid the
|
|
expense of getting certificates from a commercial CA, you can set up
|
|
your own CA and tell your server(s) and clients to trust certificates
|
|
issues by your own CA. Follow the instructions in the next section.
|
|
</p>
|
|
|
|
<p>
|
|
Be aware that the <a href="#Remote_libvirtd_configuration">default
|
|
configuration for libvirtd</a> allows any client to connect provided
|
|
they have a valid certificate issued by the CA for their own IP
|
|
address. You may want to change this to make it less (or more)
|
|
permissive, depending on your needs.
|
|
</p>
|
|
|
|
<h4><a name="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a></h4>
|
|
|
|
<p>
|
|
You will need the <a
|
|
href="http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html">GnuTLS
|
|
certtool program documented here</a>. In Fedora, it is in the
|
|
<code>gnutls-utils</code> package.
|
|
</p>
|
|
|
|
<p>
|
|
Create a private key for your CA:
|
|
</p>
|
|
|
|
<pre>
|
|
certtool --generate-privkey > cakey.pem
|
|
</pre>
|
|
|
|
<p>
|
|
and self-sign it by creating a file with the
|
|
signature details called
|
|
<code>ca.info</code> containing:
|
|
</p>
|
|
|
|
<pre>
|
|
cn = <i>Name of your organization</i>
|
|
ca
|
|
cert_signing_key
|
|
</pre>
|
|
|
|
and sign:
|
|
|
|
<pre>
|
|
certtool --generate-self-signed --load-privkey cakey.pem \
|
|
--template ca.info --outfile cacert.pem
|
|
</pre>
|
|
|
|
<p>
|
|
(You can delete <code>ca.info</code> file now if you
|
|
want).
|
|
</p>
|
|
|
|
<p>
|
|
Now you have two files which matter:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>cakey.pem</code> - Your CA's private key (keep this very secret!)
|
|
</li>
|
|
<li>
|
|
<code>cacert.pem</code> - Your CA's certificate (this is public).
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<code>cacert.pem</code> has to be installed on clients and
|
|
server(s) to let them know that they can trust certificates issued by
|
|
your CA.
|
|
</p>
|
|
|
|
<p>
|
|
The normal installation directory for <code>cacert.pem</code>
|
|
is <code>/etc/pki/CA/cacert.pem</code> on all clients and servers.
|
|
</p>
|
|
|
|
<p>
|
|
To see the contents of this file, do:
|
|
</p>
|
|
|
|
<pre>
|
|
<b>certtool -i --infile cacert.pem</b>
|
|
|
|
X.509 certificate info:
|
|
|
|
Version: 3
|
|
Serial Number (hex): 00
|
|
Subject: CN=Red Hat Emerging Technologies
|
|
Issuer: CN=Red Hat Emerging Technologies
|
|
Signature Algorithm: RSA-SHA
|
|
Validity:
|
|
Not Before: Mon Jun 18 16:22:18 2007
|
|
Not After: Tue Jun 17 16:22:18 2008
|
|
<i>[etc]</i>
|
|
</pre>
|
|
|
|
<p>
|
|
This is all that is required to set up your CA. Keep the CA's private
|
|
key carefully as you will need it when you come to issue certificates
|
|
for your clients and servers.
|
|
</p>
|
|
|
|
<h4><a name="Remote_TLS_server_certificates">Issuing server certificates</a></h4>
|
|
|
|
<p>
|
|
For each server (libvirtd) you need to issue a certificate
|
|
with the X.509 CommonName (CN) field set to the hostname
|
|
of the server. The CN must match the hostname which
|
|
clients will be using to connect to the server.
|
|
</p>
|
|
|
|
<p>
|
|
In the example below, clients will be connecting to the
|
|
server using a <a href="#Remote_URI_reference">URI</a> of
|
|
<code>xen://oirase/</code>, so the CN must be "<code>oirase</code>".
|
|
</p>
|
|
|
|
<p>
|
|
Make a private key for the server:
|
|
</p>
|
|
|
|
<pre>
|
|
certtool --generate-privkey > serverkey.pem
|
|
</pre>
|
|
|
|
<p>
|
|
and sign that key with the CA's private key by first
|
|
creating a template file called <code>server.info</code>
|
|
(only the CN field matters, which as explained above must
|
|
be the server's hostname):
|
|
</p>
|
|
|
|
<pre>
|
|
organization = <i>Name of your organization</i>
|
|
cn = oirase
|
|
tls_www_server
|
|
encryption_key
|
|
signing_key
|
|
</pre>
|
|
|
|
<p>
|
|
and sign:
|
|
</p>
|
|
|
|
<pre>
|
|
certtool --generate-certificate --load-privkey serverkey.pem \
|
|
--load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
|
|
--template server.info --outfile servercert.pem
|
|
</pre>
|
|
|
|
<p>
|
|
This gives two files:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>serverkey.pem</code> - The server's private key.
|
|
</li>
|
|
<li>
|
|
<code>servercert.pem</code> - The server's public key.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
We can examine this certificate and its signature:
|
|
</p>
|
|
|
|
<pre>
|
|
<b>certtool -i --infile servercert.pem</b>
|
|
X.509 certificate info:
|
|
|
|
Version: 3
|
|
Serial Number (hex): 00
|
|
Subject: O=Red Hat Emerging Technologies,CN=oirase
|
|
Issuer: CN=Red Hat Emerging Technologies
|
|
Signature Algorithm: RSA-SHA
|
|
Validity:
|
|
Not Before: Mon Jun 18 16:34:49 2007
|
|
Not After: Tue Jun 17 16:34:49 2008
|
|
</pre>
|
|
|
|
<p>
|
|
Note the "Issuer" CN is "Red Hat Emerging Technologies" (the CA) and
|
|
the "Subject" CN is "oirase" (the server).
|
|
</p>
|
|
|
|
<p>
|
|
Finally we have two files to install:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>serverkey.pem</code> is
|
|
the server's private key which should be copied to the
|
|
server <i>only</i> as
|
|
<code>/etc/pki/libvirt/private/serverkey.pem</code>.
|
|
</li>
|
|
|
|
<li>
|
|
<code>servercert.pem</code> is the server's certificate
|
|
which can be installed on the server as
|
|
<code>/etc/pki/libvirt/servercert.pem</code>.
|
|
</li>
|
|
</ul>
|
|
|
|
<h4><a name="Remote_TLS_client_certificates">Issuing client certificates</a></h4>
|
|
|
|
<p>
|
|
For each client (ie. any program linked with libvirt, such as
|
|
<a href="http://virt-manager.et.redhat.com/">virt-manager</a>)
|
|
you need to issue a certificate with the X.509 Distinguished Name (DN)
|
|
set to a suitable name. You can decide this on a company / organisation
|
|
policy. For example, I use:
|
|
</p>
|
|
|
|
<pre>
|
|
C=GB,ST=London,L=London,O=Red Hat,CN=<i>name_of_client</i>
|
|
</pre>
|
|
|
|
<p>
|
|
The process is the same as for
|
|
<a href="#Remote_TLS_server_certificates">setting up the
|
|
server certificate</a> so here we just briefly cover the
|
|
steps.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Make a private key:
|
|
<pre>
|
|
certtool --generate-privkey > clientkey.pem
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
Act as CA and sign the certificate. Create client.info containing:
|
|
<pre>
|
|
country = GB
|
|
state = London
|
|
locality = London
|
|
organization = Red Hat
|
|
cn = client1
|
|
tls_www_client
|
|
encryption_key
|
|
signing_key
|
|
</pre>
|
|
and sign by doing:
|
|
<pre>
|
|
certtool --generate-certificate --load-privkey clientkey.pem \
|
|
--load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
|
|
--template client.info --outfile clientcert.pem
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
Install the certificates on the client machine:
|
|
<pre>
|
|
cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
|
|
cp clientcert.pem /etc/pki/libvirt/clientcert.pem
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
|
|
|
|
<h4><a name="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a></h4>
|
|
|
|
<dl>
|
|
<dt> failed to verify client's certificate </dt>
|
|
<dd>
|
|
<p>
|
|
On the server side, run the libvirtd server with
|
|
the '--remote' and '--verbose' options while the
|
|
client is connecting. The verbose log messages should
|
|
tell you enough to diagnose the problem.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="Remote_libvirtd_configuration">libvirtd configuration</a></h3>
|
|
|
|
<p>
|
|
Libvirtd (the remote daemon) is configured from a file called
|
|
<code>/etc/libvirt/libvirtd.conf</code>, or specified on
|
|
the command line using <code>-f filename</code> or
|
|
<code>--config filename</code>.
|
|
</p>
|
|
|
|
<p>
|
|
This file should contain lines of the form below.
|
|
Blank lines and comments beginning with <code>#</code> are ignored.
|
|
</p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Line </th>
|
|
<th> Default </th>
|
|
<th> Meaning </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> listen_tls <i>[0|1]</i> </td>
|
|
<td> 1 (on) </td>
|
|
<td>
|
|
Listen for secure TLS connections on the public TCP/IP port.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> listen_tcp <i>[0|1]</i> </td>
|
|
<td> 0 (off) </td>
|
|
<td>
|
|
Listen for unencrypted TCP connections on the public TCP/IP port.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tls_port <i>"service"</i> </td>
|
|
<td> "16514" </td>
|
|
<td>
|
|
The port number or service name to listen on for secure TLS connections.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tcp_port <i>"service"</i> </td>
|
|
<td> "16509" </td>
|
|
<td>
|
|
The port number or service name to listen on for unencrypted TCP connections.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tls_no_verify_certificate <i>[0|1]</i> </td>
|
|
<td> 0 (certificates are verified) </td>
|
|
<td>
|
|
If set to 1 then if a client certificate check fails, it is not an error.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tls_no_verify_address <i>[0|1]</i> </td>
|
|
<td> 0 (addresses are verified) </td>
|
|
<td>
|
|
If set to 1 then if a client IP address check fails, it is not an error.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> key_file <i>"filename"</i> </td>
|
|
<td> "/etc/pki/libvirt/ private/serverkey.pem" </td>
|
|
<td>
|
|
Change the path used to find the server's private key.
|
|
If you set this to an empty string, then no private key is loaded.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> cert_file <i>"filename"</i> </td>
|
|
<td> "/etc/pki/libvirt/ servercert.pem" </td>
|
|
<td>
|
|
Change the path used to find the server's certificate.
|
|
If you set this to an empty string, then no certificate is loaded.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> ca_file <i>"filename"</i> </td>
|
|
<td> "/etc/pki/CA/cacert.pem" </td>
|
|
<td>
|
|
Change the path used to find the trusted CA certificate.
|
|
If you set this to an empty string, then no trusted CA certificate is loaded.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> crl_file <i>"filename"</i> </td>
|
|
<td> (no CRL file is used) </td>
|
|
<td>
|
|
Change the path used to find the CA certificate revocation list (CRL) file.
|
|
If you set this to an empty string, then no CRL is loaded.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tls_allowed_dn_list ["DN1", "DN2"] </td>
|
|
<td> (none - DNs are not checked) </td>
|
|
<td>
|
|
<p>
|
|
Enable an access control list of client certificate Distinguished
|
|
Names (DNs) which can connect to the TLS port on this server.
|
|
</p>
|
|
<p>
|
|
The default is that DNs are not checked.
|
|
</p>
|
|
<p>
|
|
This list may contain wildcards such as <code>"C=GB,ST=London,L=London,O=Red Hat,CN=*"</code>
|
|
See the POSIX <code>fnmatch</code> function for the format
|
|
of the wildcards.
|
|
</p>
|
|
<p>
|
|
Note that if this is an empty list, <i>no client can connect</i>.
|
|
</p>
|
|
<p>
|
|
Note also that GnuTLS returns DNs without spaces
|
|
after commas between the fields (and this is what we check against),
|
|
but the <code>openssl x509</code> tool shows spaces.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> tls_allowed_ip_list ["ip1", "ip2", "ip3"] </td>
|
|
<td> (none - clients can connect from anywhere) </td>
|
|
<td>
|
|
<p>
|
|
Enable an access control list of the IP addresses of clients
|
|
who can connect to the TLS or TCP ports on this server.
|
|
</p>
|
|
<p>
|
|
The default is that clients can connect from any IP address.
|
|
</p>
|
|
<p>
|
|
This list may contain wildcards such as <code>192.168.*</code>
|
|
See the POSIX <code>fnmatch</code> function for the format
|
|
of the wildcards.
|
|
</p>
|
|
<p>
|
|
Note that if this is an empty list, <i>no client can connect</i>.
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h3><a name="Remote_IPv6">IPv6 support</a></h3>
|
|
|
|
<p>
|
|
IPv6 has received some limited testing and should work. Problems with
|
|
libvirt and IPv6 should be reported as <a href="bugs.html">bugs</a>.
|
|
</p>
|
|
|
|
<h3><a name="Remote_limitations">Limitations</a></h3>
|
|
|
|
<ul>
|
|
<li> Remote storage: To be fully useful, particularly for
|
|
creating new domains, it should be possible to enumerate
|
|
and provision storage on the remote machine. This is currently
|
|
in the design phase. </li>
|
|
|
|
<li> Migration: We expect libvirt will support migration,
|
|
and obviously remote support is what makes migration worthwhile.
|
|
This is also in the design phase. Issues <a
|
|
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
|
title="libvir-list mailing list">to discuss</a> include
|
|
which path the migration data should follow (eg. client to
|
|
client direct, or client to server to client) and security.
|
|
</li>
|
|
|
|
<li> Fine-grained authentication: libvirt in general,
|
|
but in particular the remote case should support more
|
|
fine-grained authentication for operations, rather than
|
|
just read-write/read-only as at present.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Please come and discuss these issues and more on <a
|
|
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
|
title="libvir-list mailing list">the mailing list</a>.
|
|
</p>
|
|
|
|
<h3><a name="Remote_implementation_notes">Implementation notes</a></h3>
|
|
|
|
<p>
|
|
The current implementation uses <a
|
|
href="http://en.wikipedia.org/wiki/External_Data_Representation"
|
|
title="External Data Representation">XDR</a>-encoded packets with a
|
|
simple remote procedure call implementation which also supports
|
|
asynchronous messaging and asynchronous and out-of-order replies,
|
|
although these latter features are not used at the moment.
|
|
</p>
|
|
|
|
<p>
|
|
The implementation should be considered <b>strictly internal</b> to
|
|
libvirt and <b>subject to change at any time without notice</b>. If
|
|
you wish to talk to libvirtd, link to libvirt. If there is a problem
|
|
that means you think you need to use the protocol directly, please
|
|
first discuss this on <a
|
|
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
|
title="libvir-list mailing list">the mailing list</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The messaging protocol is described in
|
|
<code>qemud/remote_protocol.x</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Authentication and encryption (for TLS) is done using <a
|
|
href="http://www.gnu.org/software/gnutls/" title="GnuTLS project
|
|
page">GnuTLS</a> and the RPC protocol is unaware of this layer.
|
|
</p>
|
|
|
|
<p>
|
|
Protocol messages are sent using a simple 32 bit length word (encoded
|
|
XDR int) followed by the message header (XDR
|
|
<code>remote_message_header</code>) followed by the message body. The
|
|
length count includes the length word itself, and is measured in
|
|
bytes. Maximum message size is <code>REMOTE_MESSAGE_MAX</code> and to
|
|
avoid denial of services attacks on the XDR decoders strings are
|
|
individually limited to <code>REMOTE_STRING_MAX</code> bytes. In the
|
|
TLS case, messages may be split over TLS records, but a TLS record
|
|
cannot contain parts of more than one message. In the common RPC case
|
|
a single <code>REMOTE_CALL</code> message is sent from client to
|
|
server, and the server then replies synchronously with a single
|
|
<code>REMOTE_REPLY</code> message, but other forms of messaging are
|
|
also possible.
|
|
</p>
|
|
|
|
<p>
|
|
The protocol contains support for multiple program types and protocol
|
|
versioning, modelled after SunRPC.
|
|
</p>
|
|
|
|
<h2><a name="uri">Connection URIs</a></h2>
|
|
|
|
<p>
|
|
Since libvirt supports many different kinds of virtualization
|
|
(often referred to as "drivers" or "hypervisors"), we need a
|
|
way to be able to specify which driver a connection refers to.
|
|
Additionally we may want to refer to a driver on a remote
|
|
machine over the network.
|
|
</p>
|
|
|
|
<p>
|
|
To this end, libvirt uses URIs as used on the Web and as defined in <a
|
|
href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. This page
|
|
documents libvirt URIs.
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="#URI_libvirt">Specifying URIs to libvirt</a></li>
|
|
<li><a href="#URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a></li>
|
|
<li><a href="#URI_xen">xen:/// URI</a></li>
|
|
<li><a href="#URI_qemu">qemu:///... QEMU and KVM URIs</a></li>
|
|
<li><a href="#URI_remote">Remote URIs</a></li>
|
|
<li><a href="#URI_test">test:///... Test URIs</a></li>
|
|
<li><a href="#URI_legacy">Other & legacy URI formats</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="URI_libvirt">Specifying URIs to libvirt</a></h3>
|
|
|
|
<p>
|
|
The URI is passed as the <code>name</code> parameter to <a href="html/libvirt-libvirt.html#virConnectOpen"><code>virConnectOpen</code></a> or <a href="html/libvirt-libvirt.html#virConnectOpenReadOnly"><code>virConnectOpenReadOnly</code></a>. For example:
|
|
</p>
|
|
|
|
<pre>
|
|
virConnectPtr conn = virConnectOpenReadOnly (<b>"test:///default"</b>);
|
|
</pre>
|
|
|
|
<h3><a name="URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a></h3>
|
|
|
|
<p>
|
|
In virsh use the <code>-c</code> or <code>--connect</code> option:
|
|
</p>
|
|
|
|
<pre>
|
|
virsh <b>-c test:///default</b> list
|
|
</pre>
|
|
|
|
<p>
|
|
If virsh finds the environment variable
|
|
<code>VIRSH_DEFAULT_CONNECT_URI</code> set, it will try this URI by
|
|
default.
|
|
</p>
|
|
|
|
<p>
|
|
When using the interactive virsh shell, you can also use the
|
|
<code>connect</code> <i>URI</i> command to reconnect to another
|
|
hypervisor.
|
|
</p>
|
|
|
|
<p>
|
|
In virt-manager use the <code>-c</code> or <code>--connect=</code><i>URI</i> option:
|
|
</p>
|
|
|
|
<pre>
|
|
virt-manager <b>-c test:///default</b>
|
|
</pre>
|
|
|
|
<p>
|
|
In virt-install use the <code>--connect=</code><i>URI</i> option:
|
|
</p>
|
|
|
|
<pre>
|
|
virt-install <b>--connect=test:///default</b> <i>[other options]</i>
|
|
</pre>
|
|
|
|
<h3><a name="URI_xen">xen:/// URI</a></h3>
|
|
|
|
<p><i>This section describes a feature which is new in libvirt >
|
|
0.2.3. For libvirt ≤ 0.2.3 use <a href="#URI_legacy_xen"><code>"xen"</code></a>.</i>
|
|
</p>
|
|
|
|
<p>
|
|
To access a Xen hypervisor running on the local machine
|
|
use the URI <code>xen:///</code>.
|
|
</p>
|
|
|
|
<h3><a name="URI_qemu">qemu:///... QEMU and KVM URIs</a></h3>
|
|
|
|
<p>
|
|
To use QEMU support in libvirt you must be running the
|
|
<code>libvirt_qemud</code> daemon. The purpose of this
|
|
daemon is to manage qemu instances.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>libvirt_qemud</code> daemon can be run in two ways. It may
|
|
be started by init scripts when the machine boots and run in "system
|
|
mode" (<code>libvirt_qemud --system</code>), in which case it manages
|
|
qemu instances on behalf of all users of the machine. It may be also
|
|
be started by the local user in what is known as "session mode"
|
|
(<code>libvirt_qemud --session</code>), to manage qemu instances for
|
|
just the current user. If no <code>libvirt_qemud</code> is running at
|
|
all, then the qemu driver starts one running in session mode.
|
|
</p>
|
|
|
|
<p>
|
|
So to connect to the daemon, one of two different URIs is used:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> <code>qemu:///system</code> connects to a system mode daemon. </li>
|
|
<li> <code>qemu:///session</code> connects to a session mode daemon. </li>
|
|
</ul>
|
|
|
|
<p>
|
|
(If you do <code>libvirt_qemud --help</code>, the daemon will print
|
|
out the paths of the Unix domain socket(s) that it listens on in
|
|
the various different modes).
|
|
</p>
|
|
|
|
<p>
|
|
KVM URIs are identical. You select between qemu, qemu accelerated and
|
|
KVM guests in the <a href="format.html#KVM1">guest XML as described
|
|
here</a>.
|
|
</p>
|
|
|
|
<h3><a name="URI_remote">Remote URIs</a></h3>
|
|
|
|
<p>
|
|
Remote URIs are formed by taking ordinary local URIs and adding a
|
|
hostname and/or transport name. For example:
|
|
</p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Local URI </th>
|
|
<th> Remote URI </th>
|
|
<th> Meaning </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>xen:///</code> </td>
|
|
<td> <code>xen://oirase/</code> </td>
|
|
<td> Connect to the Xen hypervisor running on host <code>oirase</code>
|
|
using TLS. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>xen:///</code> </td>
|
|
<td> <code>xen+ssh://oirase/</code> </td>
|
|
<td> Connect to the Xen hypervisor running on host <code>oirase</code>
|
|
by going over an <code>ssh</code> connection. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> <code>test:///default</code> </td>
|
|
<td> <code>test+tcp://oirase/default</code> </td>
|
|
<td> Connect to the test driver on host <code>oirase</code>
|
|
using an unsecured TCP connection. </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
Remote URIs in libvirt offer a rich syntax and many features.
|
|
We refer you to <a href="remote.html#Remote_URI_reference">the libvirt
|
|
remote URI reference</a> and <a href="remote.html">full documentation
|
|
for libvirt remote support</a>.
|
|
</p>
|
|
|
|
<h3><a name="URI_test">test:///... Test URIs</a></h3>
|
|
|
|
<p>
|
|
The test driver is a dummy hypervisor for test purposes.
|
|
The URIs supported are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> <code>test:///default</code> connects to a default set of
|
|
host definitions built into the driver. </li>
|
|
<li> <code>test:///path/to/host/definitions</code> connects to
|
|
a set of host definitions held in the named file.
|
|
</ul>
|
|
|
|
<h3><a name="URI_legacy">Other & legacy URI formats</a></h3>
|
|
|
|
<h4><a name="URI_NULL">NULL and empty string URIs</a></h4>
|
|
|
|
<p>
|
|
Libvirt allows you to pass a <code>NULL</code> pointer to
|
|
<code>virConnectOpen*</code>. Empty string (<code>""</code>) acts in
|
|
the same way. Traditionally this has meant
|
|
<q>connect to the local Xen hypervisor</q>. However in future this
|
|
may change to mean <q>connect to the best available hypervisor</q>.
|
|
</p>
|
|
|
|
<p>
|
|
The theory is that if, for example, Xen is unavailable but the
|
|
machine is running an OpenVZ kernel, then we should not try to
|
|
connect to the Xen hypervisor since that is obviously the wrong
|
|
thing to do.
|
|
</p>
|
|
|
|
<p>
|
|
In any case applications linked to libvirt can continue to pass
|
|
<code>NULL</code> as a default choice, but should always allow the
|
|
user to override the URI, either by constructing one or by allowing
|
|
the user to type a URI in directly (if that is appropriate). If your
|
|
application wishes to connect specifically to a Xen hypervisor, then
|
|
for future proofing it should choose a full <a
|
|
href="#URI_xen"><code>xen:///</code> URI</a>.
|
|
</p>
|
|
|
|
<h4><a name="URI_file">File paths (xend-unix-server)</a></h4>
|
|
|
|
<p>
|
|
If XenD is running and configured in <code>/etc/xen/xend-config.sxp</code>:
|
|
</p>
|
|
|
|
<pre>
|
|
(xend-unix-server yes)
|
|
</pre>
|
|
|
|
<p>
|
|
then it listens on a Unix domain socket, usually at
|
|
<code>/var/lib/xend/xend-socket</code>. You may pass a different path
|
|
using a file URI such as:
|
|
</p>
|
|
|
|
<pre>
|
|
virsh -c ///var/run/xend/xend-socket
|
|
</pre>
|
|
|
|
<h4><a name="URI_http">Legacy: <code>http://...</code> (xend-http-server)</a></h4>
|
|
|
|
<p>
|
|
If XenD is running and configured in <code>/etc/xen/xend-config.sxp</code>:
|
|
|
|
<pre>
|
|
(xend-http-server yes)
|
|
</pre>
|
|
|
|
<p>
|
|
then it listens on TCP port 8000. libvirt allows you to
|
|
try to connect to xend running on remote machines by passing
|
|
<code>http://<i>hostname</i>[:<i>port</i>]/</code>, for example:
|
|
|
|
<pre>
|
|
virsh -c http://oirase/ list
|
|
</pre>
|
|
|
|
<p>
|
|
This method is unencrypted and insecure and is definitely not
|
|
recommended for production use. Instead use <a
|
|
href="remote.html">libvirt's remote support</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Notes:
|
|
</p>
|
|
|
|
<ol>
|
|
<li> The HTTP client does not fully support IPv6. </li>
|
|
<li> Many features do not work as expected across HTTP connections, in
|
|
particular, <a
|
|
href="html/libvirt-libvirt.html#virConnectGetCapabilities">virConnectGetCapabilities</a>.
|
|
The <a href="remote.html">remote support</a> however does work
|
|
correctly. </li>
|
|
<li> XenD's new-style XMLRPC interface is not supported by
|
|
libvirt, only the old-style sexpr interface known in the Xen
|
|
documentation as "unix server" or "http server".</li>
|
|
</ol>
|
|
|
|
<h4><a name="URI_legacy_xen">Legacy: <code>"xen"</code></a></h4>
|
|
|
|
<p>
|
|
Another legacy URI is to specify name as the string
|
|
<code>"xen"</code>. This will continue to refer to the Xen
|
|
hypervisor. However you should prefer a full <a
|
|
href="#URI_xen"><code>xen:///</code> URI</a> in all future code.
|
|
</p>
|
|
|
|
<h4><a name="URI_http">Legacy: Xen proxy</a></h4>
|
|
|
|
<p>
|
|
Libvirt continues to support connections to a separately running Xen
|
|
proxy daemon. This provides a way to allow non-root users to make a
|
|
safe (read-only) subset of queries to the hypervisor.
|
|
</p>
|
|
|
|
<p>
|
|
There is no specific "Xen proxy" URI. However if a Xen URI of any of
|
|
the ordinary or legacy forms is used (eg. <code>NULL</code>,
|
|
<code>""</code>, <code>"xen"</code>, ...) which fails, <i>and</i> the
|
|
user is not root, <i>and</i> the Xen proxy socket can be connected to
|
|
(<code>/tmp/libvirt_proxy_conn</code>), then libvirt will use a proxy
|
|
connection.
|
|
</p>
|
|
|
|
<p>
|
|
You should consider using <a href="remote.html">libvirt remote support</a>
|
|
in future.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|