mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-25 01:34:11 +03:00
4597 lines
165 KiB
HTML
4597 lines
165 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
|
|
concurrently on a single hardware system where the basic resources are driven
|
|
by a Linux (or Solaris) instance. The library aims at providing a long term
|
|
stable C API initially for <a
|
|
href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen
|
|
paravirtualization</a> but it can also integrate with other
|
|
virtualization mechanisms. It currently also supports <a
|
|
href="http://fabrice.bellard.free.fr/qemu/">QEMU</a>, <a
|
|
href="http://kvm.qumranet.com/">KVM</a> and
|
|
<a href="http://openvz.org/">OpenVZ</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 progress.</p>
|
|
|
|
|
|
|
|
<h3>0.4.2: Apr 8 2008</h3>
|
|
<ul>
|
|
<li>New features: memory operation for QEmu/KVM driver (Cole Robinson),
|
|
new routed networking schemas (Mads Olesen)</li>
|
|
<li>Documentation: storage documentation fixes (Atsushi Sakai), many
|
|
typo cleanups (Atsushi Sakai), string fixes (Francesco Tombolini)</li>
|
|
<li>Bug fixes: pointer errors in qemu (Jim Meyering), iSCSI login fix
|
|
(Chris Lalancette), well formedness error in test driver capabilities
|
|
(Cole Robinson), fixes cleanup code when daemon exits (Daniel Berrange),
|
|
CD Rom change on live QEmu/KVM domains (Cole Robinson), setting scheduler
|
|
parameter is forbidden for read-only (Saori Fukuta)i, fixes for TAP
|
|
devices (Daniel Berrange), assorted storage driver fixes (Daniel
|
|
Berrange), Makefile fixes (Jim Meyering), Xen-3.2 hypercall fix,
|
|
fix iptables rules to avoid blocking traffic within virtual network
|
|
(Daniel Berrange), XML output fix for directory pools (Daniel Berrange),
|
|
remove dandling domain/net/conn pointers from error data, do not
|
|
ask polkit auth when root (Daniel Berrange), handling of fork and
|
|
pipe errors when starting the daemon (Richard Jones)</li>
|
|
<li>Improvements: better validation of MAC addresses (Jim Meyering and
|
|
Hiroyuki Kaguchi),
|
|
virsh vcpupin error report (Shigeki Sakamoto), keep boot tag on
|
|
HVM domains (Cole Robinson), virsh non-root should not be limited to read
|
|
only anymore (Daniel Berrange), switch to polkit-auth from polkit-grant
|
|
(Daniel Berrange), better handling of missing SElinux data (Daniel
|
|
Berrange and Jim Meyering), cleanup of the connection opening logic
|
|
(Daniel Berrange), first bits of Linux Containers support (Dave Leskovec),
|
|
scheduler API support via xend (Saori Fukuta), improvement of the
|
|
testing framework and first tests (Jim Meyering), missing error
|
|
messages from virsh parameters validation (Shigeki Sakamoto),
|
|
improve support of older iscsiadm command (Chris Lalancette),
|
|
move linux container support in the daemon (Dan Berrange), older
|
|
awk implementation support (Mike Gerdts), NUMA support in test
|
|
driver (Cole Robinson), xen and hvm added to test driver capabilities
|
|
(Cole Robinson)</li>
|
|
<li>Code cleanup: remove unused getopt header (Jim Meyering), mark more
|
|
strings as translatable (Guido Günther and Jim Meyering), convert
|
|
error strings to something meaningful and translatable (Jim Meyering),
|
|
Linux Containers code cleanup, last error initializer (Guido Günther)</li>
|
|
</ul>
|
|
<h3>0.4.1: Mar 3 2008</h3>
|
|
<ul>
|
|
<li>New features: build on MacOSX (Richard Jones), storage management
|
|
(Daniel Berrange), Xenner - Xen on KVM - support (Daniel Berrange)</li>
|
|
<li>Documentation: Fix of various typos (Atsushi SAKAI), memory and
|
|
vcpu settings details (Richard Jones), ethernet bridging typo
|
|
(Maxwell Bottiger), add storage APIs documentation (Daniel Berrange)</li>
|
|
<li>Bug fixes: OpenVZ code compilation (Mikhail Pokidko), crash in
|
|
policykit auth handling (Daniel Berrange), large config files
|
|
(Daniel Berrange), cpumap hypercall size (Saori Fukuta), crash
|
|
in remote auth (Daniel Berrange), ssh args error (Daniel Berrange),
|
|
preserve vif order from config files (Hiroyuki Kaguchi), invalid
|
|
pointer access (Jim Meyering), virDomainGetXMLDesc flag handling,
|
|
device name conversion on stats (Daniel Berrange), double mutex lock
|
|
(Daniel Berrange), config file reading crashes (Guido Guenther),
|
|
xenUnifiedDomainSuspend bug (Marcus Meissner), do not crash if
|
|
/sys/hypervisor/capabilities is missing (Mark McLoughlin),
|
|
virHashRemoveSet bug (Hiroyuki Kaguchi), close-on-exec flag for
|
|
qemud signal pipe (Daniel Berrange), double free in OpenVZ
|
|
(Anton Protopopov), handle mac without addresses (Shigeki Sakamoto),
|
|
MAC addresses checks (Shigeki Sakamoto and Richard Jones),
|
|
allow to read non-seekable files (Jim Meyering)</li>
|
|
<li>Improvements: Windows build (Richard Jones), KVM/QEmu shutdown
|
|
(Guido Guenther), catch virExec output on debug (Mark McLoughlin),
|
|
integration of iptables and lokkit (Mark McLoughlin), keymap
|
|
parameter for VNC servers (Daniel Hokka Zakrisson), enable debug
|
|
by default using VIR_DEBUG (Daniel Berrange), xen 3.2 fixes
|
|
(Daniel Berrange), Python bindings for VCPU and scheduling
|
|
(Daniel Berrange), framework for automatic code syntax checks
|
|
(Jim Meyering), allow kernel+initrd setup in Xen PV (Daniel Berrange),
|
|
allow change of Disk/NIC of an inactive domains (Shigeki Sakamoto),
|
|
virsh commands to manipulate and create storage(Daniel Berrange),
|
|
update use of PolicyKit APIs, better detection of fedault hypervisor,
|
|
block device statistics for QEmu/KVM (Richard Jones), various improvements
|
|
for Xenner (Daniel Berrange)</li>
|
|
<li>Code cleanups: avoid warnings (Daniel Berrange), virRun helper
|
|
function (Dan Berrange), iptable code fixes (Mark McLoughlin),
|
|
static and const cleanups (Jim Meyering), malloc and python cleanups
|
|
(Jim Meyering), xstrtol_ull and xstrtol_ll functions (Daniel Berrange),
|
|
remove no-op networking from OpenVZ (Daniel Berrange), python generator
|
|
cleanups (Daniel Berrange), cleanup ref counting (Daniel Berrange),
|
|
remove uninitialized warnings (Jim Meyering), cleanup configure
|
|
for RHEL4 (Daniel Berrange), CR/LF cleanups (Richard Jones),
|
|
various automatic code check and associated cleanups (Jim Meyering),
|
|
various memory leaks (Jim Meyering), fix compilation when building
|
|
without Xen (Guido Guenther), mark translatables strings (Jim Meyering),
|
|
use virBufferAddLit for constant strings (Jim Meyering), fix
|
|
make distcheck (Jim Meyering), return values for python bindings (Cole
|
|
Robinson), trailing blanks fixes (Jim Meyering), gcc-4.3.0 fixes
|
|
(Mark McLoughlin), use safe read and write routines (Jim Meyering),
|
|
refactoring of code dealing with hypervisor capabilities (Daniel
|
|
Berrange), qemudReportError to use virErrorMsg (Cole Robinson),
|
|
intemediate library and Makefiles for compiling static and coverage
|
|
rule support (Jim Meyering), cleanup of various leaks (Jim Meyering)</li>
|
|
</ul>
|
|
|
|
<h3>0.4.0: Dec 18 2007</h3>
|
|
<ul>
|
|
<li>New features: Compilation on Windows cygwin/mingw (Richard Jones),
|
|
Ruby bindings (David Lutterkort), SASL based authentication for
|
|
libvirt remote support (Daniel Berrange), PolicyKit authentication
|
|
(Daniel Berrange)</li>
|
|
<li>Documentation: example files for QEMU and libvirtd configuations
|
|
(Daniel Berrange), english cleanups (Jim Paris), CIM and OpenVZ
|
|
references, document <shareable/>, daemon startup when using
|
|
QEMU/KVM, document HV support for new NUMA calls (Richard Jones),
|
|
various english fixes (Bruce Montague), OCaml docs links (Richard Jones),
|
|
describe the various bindings add Ruby link, Windows support page
|
|
(Richard Jones), authentication documentation updates (Daniel Berrange)
|
|
</li>
|
|
<li>Bug fixes: NUMA topology error handling (Beth Kon), NUMA topology
|
|
cells without CPU (Beth Kon), XML to/from XM bridge config (Daniel
|
|
Berrange), XM processing of vnc parameters (Daniel Berrange), Reset
|
|
migration source after failure (Jim Paris), negative integer in config
|
|
(Tatsuro Enokura), zero terminating string buffer, detect integer
|
|
overflow (Jim Meyering), QEmu command line ending fixes (Daniel Berrange),
|
|
recursion problem in the daemon (Daniel Berrange), HVM domain with CDRom
|
|
(Masayuki Sunou), off by one error in NUMA cpu count (Beth Kon),
|
|
avoid xend errors when adding disks (Masayuki Sunou), compile error
|
|
(Chris Lalancette), transposed fwrite args (Jim Meyering), compile
|
|
without xen and on solaris (Jim Paris), parsing of interface names
|
|
(Richard Jones), overflow for starts on 32bits (Daniel Berrange),
|
|
fix problems in error reporting (Saori Fukuta), wrong call to
|
|
brSetForwardDelay changed to brSetEnableSTP (Richard Jones),
|
|
allow shareable disk in old Xen, fix wrong certificate file (Jim
|
|
Meyering), avoid some startup error when non-root, off-by-1 buffer
|
|
NULL termination (Daniel Berrange), various string allocation fixes
|
|
(Daniel Berrange), avoid problems with vnetXXX interfaces in domain dumps
|
|
(Daniel Berrange), build fixes for RHEL (Daniel Berrange), virsh prompt
|
|
should not depend on uid (Richard Jones), fix scaping of '<' (Richard
|
|
Jones), fix detach-disk on Xen tap devices (Saori Fukuta), CPU
|
|
parameter setting in XM config (Saori Fukuta), credential handling
|
|
fixes (Daniel Berrange), fix compatibility with Xen 3.2.0 (Daniel
|
|
Berrange)
|
|
</li>
|
|
<li>Improvements: /etc/libvirt/qemu.conf configuration for QEMU driver
|
|
(Daniel Berrange), NUMA cpu pinning in config files (DV and Saori Fukuta),
|
|
CDRom media change in KVM/QEMU (Daniel Berrange), tests for
|
|
<shareable/> in configs, pinning inactive domains for Xen 3.0.3
|
|
(Saori Fukuta), use gnulib for portability enhancement (Jim Meyering),
|
|
--without-libvirtd config option (Richard Jones), Python bindings for
|
|
NUMA, add extra utility functions to buffer (Richard Jones),
|
|
separate qparams module for handling query parameters (Richard Jones)
|
|
</li>
|
|
<li>Code cleanups: remove virDomainRestart from API as it was never used
|
|
(Richard Jones), constify params for attach/detach APIs (Daniel Berrange),
|
|
gcc printf attribute checkings (Jim Meyering), refactoring of device
|
|
parsing code and shell escaping (Daniel Berrange), virsh schedinfo
|
|
parameters validation (Masayuki Sunou), Avoid risk of format string abuse
|
|
(Jim Meyering), integer parsing cleanups (Jim Meyering), build out
|
|
of the source tree (Jim Meyering), URI parsing refactoring (Richard
|
|
Jones), failed strdup/malloc handling (Jim Meyering), Make "make
|
|
distcheck" work (Jim Meyering), improve xen internall error reports
|
|
(Richard Jones), cleanup of the daemon remote code (Daniel Berrange),
|
|
rename error VIR_FROM_LINUX to VIR_FROM_STATS_LINUX (Richard Jones),
|
|
don't compile the proxy if without Xen (Richard Jones), fix paths when
|
|
configuring for /usr prefix, improve error reporting code (Jim Meyering),
|
|
detect heap allocation failure (Jim Meyering), disable xen sexpr parsing
|
|
code if Xen is disabled (Daniel Berrange), cleanup of the GetType
|
|
entry point for Xen drivers, move some QEmu path handling to generic
|
|
module (Daniel Berrange), many code cleanups related to the Windows
|
|
port (Richard Jones), disable the proxy if using PolicyKit, readline
|
|
availability detection, test libvirtd's config-processing code (Jim
|
|
Meyering), use a variable name as sizeof argument (Jim Meyering)
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>0.3.3: Sep 30 2007</h3>
|
|
<ul>
|
|
<li>New features: Avahi mDNS daemon export (Daniel Berrange),
|
|
NUMA support (Beth Kan) </li>
|
|
<li>Documentation: cleanups (Toth Istvan), typos (Eduardo Pereira), </li>
|
|
<li>Bug fixes: memory corruption on large dumps (Masayuki Sunou), fix
|
|
virsh vncdisplay command exit (Masayuki Sunou), Fix network stats
|
|
TX/RX result (Richard Jones), warning on Xen 3.0.3 (Richard Jones),
|
|
missing buffer check in virDomainXMLDevID (Hugh Brock), avoid zombies
|
|
when using remote (Daniel Berrange), xend connection error message
|
|
(Richard Jones), avoid ssh tty prompt (Daniel Berrange), username
|
|
handling for remote URIs (Fabian Deutsch), fix potential crash
|
|
on multiple input XML tags (Daniel Berrange), Solaris Xen hypercalls
|
|
fixup (Mark Johnson)</li>
|
|
<li>Improvements: OpenVZ support (Shuveb Hussain and Anoop Cyriac),
|
|
CD-Rom reload on XEn (Hugh Brock), PXE boot got QEmu/KVM (Daniel
|
|
Berrange), QEmu socket permissions customization (Daniel Berrange),
|
|
more QEmu support (Richard Jones), better path detection for qemu and
|
|
dnsmasq (Richard Jones), QEmu flags are per-Domain (Daniel Berrange),
|
|
virsh freecell command, Solaris portability fixes (Mark Johnson),
|
|
default bootloader support (Daniel Berrange), new virNodeGetFreeMemory
|
|
API, vncpasswd extraction in configuration files if secure (Mark
|
|
Johnson and Daniel Berrange), Python bindings for block and interface
|
|
statistics</li>
|
|
<li>Code cleanups: virDrvOpenRemoteFlags definition (Richard Jones),
|
|
configure tests and output (Daniel Berrange)</li>
|
|
</ul>
|
|
<h3>0.3.2: Aug 21 2007</h3>
|
|
<ul>
|
|
<li>New features: KVM migration and save/restore (Jim Paris),
|
|
added API for migration (Richard Jones), added APIs for block device and
|
|
interface statistic (Richard Jones).</li>
|
|
<li>Documentation: examples for XML network APIs,
|
|
fix typo and schedinfo synopsis in man page (Atsushi SAKAI),
|
|
hypervisor support page update (Richard Jones).</li>
|
|
<li>Bug fixes: remove a couple of leaks in QEmu/KVM backend(Daniel berrange),
|
|
fix GnuTLS 1.0 compatibility (Richard Jones), --config/-f option
|
|
mistake for libvirtd (Richard Jones), remove leak in QEmu backend
|
|
(Jim Paris), fix some QEmu communication bugs (Jim Paris), UUID
|
|
lookup though proxy fix, setvcpus checking bugs (with Atsushi SAKAI),
|
|
int checking in virsh parameters (with Masayuki Sunou), deny devices
|
|
attach/detach for < Xen 3.0.4 (Masayuki Sunou), XenStore query
|
|
memory leak (Masayuki Sunou), virsh schedinfo cleanup (Saori Fukuta).</li>
|
|
<li>Improvement: virsh new ttyconsole command, networking API implementation
|
|
for test driver (Daniel berrange), qemu/kvm feature reporting of
|
|
ACPI/APIC (David Lutterkort), checking of QEmu architectures (Daniel
|
|
berrange), improve devices XML errors reporting (Masayuki Sunou),
|
|
speedup of domain queries on Xen (Daniel berrange), augment XML dumps
|
|
with interface devices names (Richard Jones), internal API to query
|
|
drivers for features (Richard Jones).
|
|
</li>
|
|
<li>Cleanups: Improve virNodeGetInfo implentation (Daniel berrange),
|
|
general UUID code cleanup (Daniel berrange), fix API generator
|
|
file selection. </li>
|
|
</ul>
|
|
|
|
<h3>0.3.1: Jul 24 2007</h3>
|
|
<ul>
|
|
<li>Documentation: index to remote page, script to test certificates,
|
|
IPv6 remote support docs (Daniel Berrange), document
|
|
VIRSH_DEFAULT_CONNECT_URI in virsh man page (David Lutterkort),
|
|
Relax-NG early grammar for the network XML (David Lutterkort)</li>
|
|
<li>Bug fixes: leaks in disk XML parsing (Masayuki Sunou), hypervisor
|
|
alignment call problems on PPC64 (Christian Ehrhardt), dead client
|
|
registration in daemon event loop (Daniel Berrange), double free
|
|
in error handling (Daniel Berrange), close on exec for log file
|
|
descriptors in the daemon (Daniel Berrange), avoid caching problem
|
|
in remote daemon (Daniel Berrange), avoid crash after QEmu domain
|
|
failure (Daniel Berrange)</li>
|
|
<li>Improvements: checks of x509 certificates and keys (Daniel Berrange),
|
|
error reports in the daemon (Daniel Berrange), checking of Ethernet MAC
|
|
addresses in XML configs (Masayuki Sunou), support for a new
|
|
clock switch between UTC and localtime (Daniel Berrange), early
|
|
version of OpenVZ support (Shuveb Hussain), support for input devices
|
|
on PS/2 and USB buses (Daniel Berrange), more tests especially
|
|
the QEmu support (Daniel Berrange), range check in credit scheduler
|
|
(with Saori Fukuta and Atsushi Sakai), add support for listen VNC
|
|
parameter un QEmu and fix command line arg (Daniel Berrange)</li>
|
|
<li>Cleanups: debug tracing (Richard Jones), removal of --with-qemud-pid-file
|
|
(Richard Jones), remove unused virDeviceMode, new util module for
|
|
code shared between drivers (Shuveb Hussain), xen header location
|
|
detection (Richard Jones)</li>
|
|
</ul>
|
|
<h3>0.3.0: Jul 9 2007</h3>
|
|
<ul>
|
|
<li>Secure Remote support (Richard Jones).
|
|
See <a href="http://libvirt.org/remote.html">the remote page</a>
|
|
of the documentation
|
|
<li>Documentation: remote support (Richard Jones), description of
|
|
the URI connection strings (Richard Jones), update of virsh man
|
|
page, matrix of libvirt API/hypervisor support with version
|
|
information (Richard Jones)</li>
|
|
<li>Bug fixes: examples Makefile.am generation (Richard Jones),
|
|
SetMem fix (Mark Johnson), URI handling and ordering of
|
|
drivers (Daniel Berrange), fix virsh help without hypervisor (Richard
|
|
Jones), id marshalling fix (Daniel Berrange), fix virConnectGetMaxVcpus
|
|
on remote (Richard Jones), avoid a realloc leak (Jim Meyering), scheduler
|
|
parameters handling for Xen (Richard Jones), various early remote
|
|
bug fixes (Richard Jones), remove virsh leaks of domains references
|
|
(Masayuki Sunou), configCache refill bug (Richard Jones), fix
|
|
XML serialization bugs</li>
|
|
<li>Improvements: QEmu switch to XDR-based protocol (Dan Berrange),
|
|
device attach/detach commands (Masayuki Sunou), OCaml bindings
|
|
(Richard Jones), new entry points virDomainGetConnect and
|
|
virNetworkGetConnect useful for bindings (Richard Jones),
|
|
reunitifaction of remote and qemu daemon under a single libvirtd
|
|
with a config file (Daniel Berrange)</li>
|
|
<li>Cleanups: parsing of connection URIs (Richard Jones), messages
|
|
from virsh (Saori Fukuta), Coverage files (Daniel Berrange),
|
|
Solaris fixes (Mark Johnson), avoid [r]index calls (Richard Jones),
|
|
release information in Xen backend, virsh cpupin command cleanups
|
|
(Masayuki Sunou), xen:/// suppport as standard Xen URI (Richard Jones and
|
|
Daniel Berrange), improve driver selection/decline mechanism (Richard
|
|
Jones), error reporting on XML dump (Richard Jones), Remove unused
|
|
virDomainKernel structure (Richard Jones), daemon event loop event
|
|
handling (Daniel Berrange), various unifications cleanup in the daemon
|
|
merging (Daniel Berrange), internal file and timer monitoring API
|
|
(Daniel Berrange), remove libsysfs dependancy, call brctl program
|
|
directly (Daniel Berrange), virBuffer functions cleanups (Richard Jones),
|
|
make init script LSB compliant, error handling on lookup functions
|
|
(Richard Jones), remove internal virGetDomainByID (Richard Jones),
|
|
revamp of xen subdrivers interfaces (Richard Jones)</li>
|
|
<li>Localization updates</li>
|
|
</ul>
|
|
<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 information 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 information take over <os> information</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 information from xend (Daniel Berrange)</li>
|
|
<li> fix another problem in the hypercalls change in Xen changeset
|
|
86d26e6ec89b when getting domain information (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 information
|
|
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 unprivileged 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 targeted 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 information 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
|
|
privilege of the embedding program. If it runs with root access,
|
|
virConnectOpen() can be used, it will use three different ways to connect to
|
|
the Xen infrastructure:</p>
|
|
<ul>
|
|
<li>a connection to the Xen Daemon though an HTTP RPC layer</li>
|
|
<li>a read/write connection to the Xen Store</li>
|
|
<li>use Xen Hypervisor calls</li>
|
|
<li>when used as non-root libvirt connect to a proxy daemon running
|
|
as root and providing read-only support</li>
|
|
</ul>
|
|
|
|
<p>The library will usually interact with the Xen daemon for any operation
|
|
changing the state of the system, but for performance and accuracy reasons
|
|
may talk directly to the hypervisor when gathering state information at
|
|
least when possible (i.e. when the running program using libvirt has root
|
|
privilege 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 targeted.</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
|
|
maintenance 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 hypervisor drivers
|
|
defining a common set of routines. That way the Xen Daemon access, the Xen
|
|
Store one, the Hypervisor hypercall are all isolated in separate C modules
|
|
implementing at least a subset of the common operations defined by the
|
|
drivers present in driver.h:</p>
|
|
<ul>
|
|
<li>xend_internal: implements the driver functions though the Xen
|
|
Daemon</li>
|
|
<li>xs_internal: implements the subset of the driver available though the
|
|
Xen Store</li>
|
|
<li>xen_internal: provide the implementation of the functions possible via
|
|
direct hypervisor access</li>
|
|
<li>proxy_internal: provide read-only Xen access via a proxy, the proxy code
|
|
is in the <code>proxy/</code>directory.</li>
|
|
<li>xm_internal: provide support for Xen defined but not running
|
|
domains.</li>
|
|
<li>qemu_internal: implement the driver functions for QEmu and
|
|
KVM virtualization engines. It also uses a qemud/ specific daemon
|
|
which interacts with the QEmu process to implement libvirt API.</li>
|
|
<li>test: this is a test driver useful for regression tests of the
|
|
front-end part of libvirt.</li>
|
|
</ul>
|
|
|
|
<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
|
|
dependent 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 available 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>
|
|
<li>shareable an optional empty element indicating the device
|
|
can be used read/write with other domains</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 interface 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>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><clock sync="localtime"/></span>
|
|
<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 optional <code><clock></code> element is used to specify
|
|
whether the emulated BIOS clock in the guest is synced to either
|
|
<code>localtime</code> or <code>utc</code>. In general Windows will
|
|
want <code>localtime</code> while all other operating systems will
|
|
want <code>utc</code>. The default is thus <code>utc</code></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 information 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 dependent 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>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><clock sync="localtime"/></span>
|
|
<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 <clock> optional is supported as with Xen HVM</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 an 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
|
|
overridden 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 overridden 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 bridge='br0'/>
|
|
</interface>
|
|
|
|
<interface type='bridge'>
|
|
<source bridge='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 overridden 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
|
|
overridden.</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 network, 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 first block (in red) indicates the host hardware capabilities, 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 information and potential features.</p>
|
|
|
|
<p>The third block (in green) gives similar information 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">Bindings for other languages</a></h2>
|
|
|
|
<p>Libvirt comes with bindings to support other languages than
|
|
pure C. First the headers embeds the necessary declarations to
|
|
allow direct acces from C++ code, but also we have bindings for
|
|
higher level kind of languages:</p>
|
|
<ul>
|
|
<li>Python: Libvirt comes with direct support for the Python language
|
|
(just make sure you installed the libvirt-python package if not
|
|
compiling from sources). See below for more information about
|
|
using libvirt with python</li>
|
|
<li>Perl: Daniel Berrange provides <a
|
|
href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">bindings for
|
|
Perl</a>.</li>
|
|
<li>OCaml: Richard Jones supplies <a
|
|
href="http://libvirt.org/ocaml/">bindings for OCaml</a>.</li>
|
|
<li>Ruby: David Lutterkork provides <a
|
|
href= "http://libvirt.org/ruby/">bindings for Ruby</a>.</li>
|
|
</ul>
|
|
|
|
<p>Support, requests or help for libvirt bindings are welcome on
|
|
the <a href="https://www.redhat.com/mailman/listinfo/libvir-list/">mailing
|
|
list</a>, as usual try to provide enough background information
|
|
and make sure you use recent version, see the <a href="bugs.html">help
|
|
page</a>.</p>
|
|
|
|
<p>The remaining of this page focuses on the Python bindings.</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 information 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 information as soon as possible</li>
|
|
<li>dont force the library user into one style of error handling</li>
|
|
</ul>
|
|
|
|
<p>As result the library provide both synchronous, callback based and
|
|
asynchronous error reporting. When an error happens in the library code the
|
|
error is logged, allowing to retrieve it later and if the user registered an
|
|
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 possible 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 information</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 information is 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
|
|
targeted in the operation</li>
|
|
</ul>
|
|
|
|
<p>and then extra raw information about the error which may be initialized
|
|
to 0 or NULL if unused</p>
|
|
<ul>
|
|
<li>str1, str2, str3: string information, usually str1 is the error
|
|
message format</li>
|
|
<li>int1, int2: integer information</li>
|
|
</ul>
|
|
|
|
<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>,
|
|
check 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
|
|
first 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 maintenance 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 privileges,
|
|
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:</p>
|
|
<ul>
|
|
<li>If you are using official binaries from Fedora: <a href="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt">log a new bug for Fedora</a></li>
|
|
<li>If you are using official binaries from Red Hat Enterprise Linux 5: <a href="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=Red%20Hat%20Enterprise%20Linux%205">log a new bug for RHEL</a></li>
|
|
<li>Otherwise: <a href="http://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=Virtualization%20Tools">log a new bug here</a></li>
|
|
</ul>
|
|
<p> Don't forget to 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>
|
|
|
|
<p>Some of the libvirt developers may be found on IRC on the OFTC
|
|
network. Use the settings:</p>
|
|
<ul>
|
|
<li>server: irc.oftc.net</li>
|
|
<li>port: 6667 (the usual IRC port)</li>
|
|
<li>channel: #virt</li>
|
|
</ul>
|
|
<p> But there is no guarantee that someone will be watching or able to reply,
|
|
use the mailing-list if you don't get an answer there.</p>
|
|
|
|
<h2><a name="Windows" id="Windows">Windows support</a></h2>
|
|
|
|
<p>
|
|
Instructions for compiling and installing libvirt on Windows.
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="#Windows_binaries">Binaries</a></li>
|
|
<li><a href="#Windows_compiling">Compiling from source</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="Windows_binaries">Binaries</a></h3>
|
|
|
|
<p>
|
|
Binaries will be available from
|
|
<a href="ftp://libvirt.org/libvirt/win32">the download area</a>
|
|
(but we don't have binaries at the moment).
|
|
</p>
|
|
|
|
<h3><a name="Windows_compiling">Compiling from source</a></h3>
|
|
|
|
<p>
|
|
These are the steps to compile libvirt and the other
|
|
tools from source on Windows.
|
|
</p>
|
|
|
|
<p>
|
|
You will need:
|
|
</p>
|
|
|
|
<ol>
|
|
<li> MS Windows. Microsoft makes free (as beer) versions
|
|
of some of its operating systems available to
|
|
<a href="http://msdn.microsoft.com/">MSDN subscribers</a>.
|
|
We used Windows 2008 Server for testing, virtualized under
|
|
Linux using KVM-53 (earlier versions of KVM and QEMU won't
|
|
run recent versions of Windows because of lack of full ACPI
|
|
support, so make sure you have the latest KVM).
|
|
</li>
|
|
|
|
<li> <a href="http://www.cygwin.com/">Cygwin</a>'s
|
|
<a href="http://www.cygwin.com/setup.exe">setup.exe</a>.
|
|
</li>
|
|
|
|
<li> A large amount of free disk space to install Cygwin.
|
|
Make sure you have 10 GB free to install most Cygwin packages,
|
|
although if you pare down the list of dependencies you may
|
|
get away with much less. </li>
|
|
|
|
<li> A network connection for Windows, since Cygwin downloads packages
|
|
from the net as it installs. </li>
|
|
|
|
<li> <a href="http://www.libvirt.org/downloads.html">Libvirt
|
|
latest version from CVS</a> </li>
|
|
|
|
<li> The latest source patch from
|
|
<a href="ftp://libvirt.org/libvirt/win32">the download area</a>. </li>
|
|
|
|
<li> A version of Cygwin sunrpc, patched to support building
|
|
<code>librpc.dll</code>.
|
|
A patch and a binary package are available from
|
|
<a href="ftp://libvirt.org/libvirt/win32">the download area</a>. </li>
|
|
</ol>
|
|
|
|
<p>
|
|
These are the steps to take to compile libvirt from
|
|
source on Windows:
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Run Cygwin
|
|
<a href="http://www.cygwin.com/setup.exe">setup.exe</a>.
|
|
When it starts up it will show a dialog like this:
|
|
</p>
|
|
|
|
<img src="windows-cygwin-1.png" width="504" height="388"
|
|
alt="Cygwin Net Release Setup Program" />
|
|
</li>
|
|
|
|
<li>
|
|
<p>Step through the setup program accepting defaults
|
|
or making choices as appropriate, until you get to the
|
|
screen for selecting packages:</p>
|
|
|
|
<img src="windows-cygwin-2.png" width="505" height="388"
|
|
alt="Cygwin Select Packages screen" />
|
|
|
|
<p>
|
|
The user interface here is very confusing. You have to
|
|
click the "recycling icon" as shown by the arrow:
|
|
</p>
|
|
|
|
<img src="windows-cygwin-3.png" width="298" height="200"
|
|
alt="Cygwin Recycling Icon" />
|
|
|
|
<p>
|
|
which takes the package (and all packages in the subtree)
|
|
through several states such as "Install", "Reinstall", "Keep",
|
|
"Skip", "Uninstall", etc.
|
|
</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<p>You can install "All" (everything) or better select
|
|
just the groups and packages needed. Select the following
|
|
groups and packages for installation:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th valign="top" align="right"> Groups </th>
|
|
<td>
|
|
Archive <br/>
|
|
Base <br/>
|
|
Devel <br/>
|
|
Editors <br/>
|
|
Mingw <br/>
|
|
Perl <br/>
|
|
Python <br/>
|
|
Shells <br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th valign="top" align="right"> Packages </th>
|
|
<td>
|
|
openssh <br/>
|
|
sunrpc ≥ 4.0-4 (see below) <br/>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Once Cygwin has finished installing, start a Cygwin bash shell
|
|
(either click on the desktop icon or look for Cygwin bash shell
|
|
in the Start menu). </p>
|
|
|
|
<p> The very first time you start the Cygwin bash shell, you may
|
|
find you need to run the <code>mkpasswd</code> and <code>mkgroup</code>
|
|
commands in order to create <code>/etc/passwd</code> and
|
|
<code>/etc/group</code> files from Windows users. If this
|
|
is needed then a message is printed in the shell.
|
|
Note that you need to do this as Windows Administrator. </p>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Install Cygwin sunrpc ≥ 4.0-4 package, patched to include
|
|
<code>librpc.dll</code>.
|
|
To do this, first check to see whether <code>/usr/lib/librpc.dll</code>
|
|
exists. If it does, you're good to go and can skip to the next
|
|
step. </p>
|
|
|
|
<p>
|
|
If you don't have this file, either install the binary package
|
|
<a href="ftp://libvirt.org/libvirt/win32/sunrpc-4.0-4.tar.bz2">sunrpc-4.0-4.tar.bz2</a> (just unpack it, as Administrator, in the Cygwin root directory).
|
|
Or you can download the
|
|
<a href="ftp://libvirt.org/libvirt/win32/sunrpc-4.0-dll.patch">source patch</a>
|
|
and apply it by hand to the Cygwin sunrpc package (eg. using
|
|
cygport).
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
Check out
|
|
<a href="http://www.libvirt.org/downloads.html">Libvirt from CVS</a> and
|
|
<a href="ftp://libvirt.org/libvirt/win32">apply the latest Windows patch</a>
|
|
to the source.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Configure libvirt by doing: </p>
|
|
<pre>
|
|
autoreconf
|
|
./configure --without-xen --without-qemu
|
|
</pre>
|
|
<p> (The autoreconf step is probably optional). </p>
|
|
<p> The configure step will tell you if you have all the
|
|
required parts installed. If something is missing you
|
|
will need to go back through Cygwin setup and install it.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Rebuild the XDR structures: </p>
|
|
<pre>
|
|
rm qemud/remote_protocol.[ch] qemud/remote_dispatch_*.h
|
|
make -C qemud remote_protocol.c
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Build: </p>
|
|
<pre>
|
|
make
|
|
</pre>
|
|
<p> If this step is not successful, you should post a full
|
|
report <i>including complete messages</i> to
|
|
<a href="http://www.redhat.com/mailman/listinfo/libvir-list">the
|
|
libvirt mailing list</a>.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p> Test it. If you have access to a remote machine
|
|
running Xen or QEMU/KVM, and the libvirt daemon (<code>libvirtd</code>)
|
|
then you should be able to connect to it and display
|
|
domains using, eg:
|
|
</p>
|
|
<pre>
|
|
src/virsh.exe <a href="http://libvirt.org/uri.html">-c qemu://remote/system</a> list --all
|
|
</pre>
|
|
<p>
|
|
Please read more about <a href="http://libvirt.org/remote.html">remote
|
|
support</a> before sending bug reports, to make sure that
|
|
any problems are really Windows and not just with remote
|
|
configuration / security.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
You may want to install the library and programs by doing:
|
|
</p>
|
|
<pre>
|
|
make install
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
The above steps should also build and install Python modules.
|
|
However for reasons which I don't fully understand, Python won't
|
|
look in the
|
|
non-standard <code>/usr/local/lib/python*/site-packages/</code>
|
|
directory by default so you may need to set the environment
|
|
variable PYTHONPATH:
|
|
</p>
|
|
|
|
<pre>
|
|
export PYTHONPATH=/usr/local/lib/python2.5/site-packages
|
|
</pre>
|
|
|
|
<p>
|
|
(Change the version number to your version of Python). You
|
|
can test Python support from the command line:
|
|
</p>
|
|
|
|
<pre>
|
|
python
|
|
>>> import libvirt
|
|
>>> conn = libvirt.open ("test:///default")
|
|
>>> conn.listDomainsID ()
|
|
[1]
|
|
>>> dom = conn.lookupByID (1)
|
|
>>> dom.XMLDesc (0)
|
|
"<domain type='test' id='1'> ..."
|
|
</pre>
|
|
|
|
<p>
|
|
The most common failure will be with <code>import libvirt</code>
|
|
which usually indicates that either <code>PYTHONPATH</code> is
|
|
wrong or a DLL cannot be loaded.
|
|
</p>
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
<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>
|
|
<ul>
|
|
<li><a href="#Remote_basic_usage">Basic usage</a></li>
|
|
<li><a href="#Remote_transports">Transports</a></li>
|
|
<li><a href="#Remote_URI_reference">Remote URIs</a>
|
|
<ul>
|
|
<li><a href="#Remote_URI_parameters">Extra parameters</a></li>
|
|
</ul></li>
|
|
<li><a href="#Remote_certificates">Generating TLS certificates</a>
|
|
<ul>
|
|
<li><a href="#Remote_PKI">Public Key Infrastructure set up</a></li>
|
|
<li><a href="#Remote_TLS_background">Background to TLS certificates</a></li>
|
|
<li><a href="#Remote_TLS_CA">Setting up a Certificate Authority (CA)</a></li>
|
|
<li><a href="#Remote_TLS_server_certificates">Issuing server certificates</a></li>
|
|
<li><a href="#Remote_TLS_client_certificates">Issuing client certificates</a></li>
|
|
<li><a href="#Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a></li>
|
|
</ul></li>
|
|
<li><a href="#Remote_libvirtd_configuration">libvirtd configuration file</a></li>
|
|
<li><a href="#Remote_IPv6">IPv6 support</a></li>
|
|
<li><a href="#Remote_limitations">Limitations</a></li>
|
|
<li><a href="#Remote_implementation_notes">Implementation notes</a></li>
|
|
</ul>
|
|
|
|
<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 and libvirtd should be running
|
|
on the remote machine. 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>
|
|
|
|
<tr>
|
|
<td> <code>no_tty</code> </td>
|
|
<td> ssh </td>
|
|
<td>
|
|
If set to a non-zero value, this stops ssh from asking for
|
|
a password if it cannot log in to the remote machine automatically
|
|
(eg. using ssh-agent etc.). Use this when you don't have access
|
|
to a terminal - for example in graphical programs which use libvirt.
|
|
</td>
|
|
</tr>
|
|
<tr> <td colspan="2"></td>
|
|
<td> Example: <code>no_tty=1</code> </td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<h3><a name="Remote_certificates">Generating TLS certificates</a></h3>
|
|
|
|
<h4><a name="Remote_PKI">Public Key Infrastructure set up</a></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 '--listen' and '--verbose' options while the
|
|
client is connecting. The verbose log messages should
|
|
tell you enough to diagnose the problem.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
<p> You can use the <a href="pki_check.sh">pki_check.sh</a> shell script
|
|
to analyze the setup on the client or server machines, preferably as root.
|
|
It will try to point out the possible problems and provide solutions to
|
|
fix the set up up to a point where you have secure remote access.</p>
|
|
|
|
|
|
<h3><a name="Remote_libvirtd_configuration">libvirtd configuration file</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>
|
|
<pre>setting = value</pre>
|
|
<p>The following settings, values and default are:</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> mdns_adv <i>[0|1]</i> </td>
|
|
<td> 1 (advertise with mDNS) </td>
|
|
<td>
|
|
If set to 1 then the virtualization service will be advertised over
|
|
mDNS to hosts on the local LAN segment.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> mdns_name <i>"name"</i> </td>
|
|
<td> "Virtualization Host HOSTNAME" </td>
|
|
<td>
|
|
The name to advertise for this host with Avahi mDNS. The default
|
|
includes the machine's short hostname. This must be unique to the
|
|
local LAN segment.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> unix_sock_group <i>"groupname"</i> </td>
|
|
<td> "root" </td>
|
|
<td>
|
|
The UNIX group to own the UNIX domain socket. If the socket permissions allow
|
|
group access, then applications running under matching group can access the
|
|
socket. Only valid if running as root
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> unix_sock_ro_perms <i>"octal-perms"</i> </td>
|
|
<td> "0777" </td>
|
|
<td>
|
|
The permissions for the UNIX domain socket for read-only client connections.
|
|
The default allows any user to monitor domains.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> unix_sock_rw_perms <i>"octal-perms"</i> </td>
|
|
<td> "0700" </td>
|
|
<td>
|
|
The permissions for the UNIX domain socket for read-write client connections.
|
|
The default allows only root to manage domains.
|
|
</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>
|
|
The libvirtd service and libvirt remote client driver both use the
|
|
<code>getaddrinfo()</code> functions for name resolution and are
|
|
thus fully IPv6 enabled. ie, if a server has IPv6 address configured
|
|
the daemon will listen for incoming connections on both IPv4 and IPv6
|
|
protocols. If a client has an IPv6 address configured and the DNS
|
|
address resolved for a service is reachable over IPv6, then an IPv6
|
|
connection will be made, otherwise IPv4 will be used. In summary it
|
|
should just 'do the right thing(tm)'.
|
|
</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="ACL">Access control</a></h2>
|
|
|
|
<p>
|
|
When connecting to libvirt, some connections may require client
|
|
authentication before allowing use of the APIs. The set of possible
|
|
authentication mechanisms is administrator controlled, independent
|
|
of applications using libvirt.
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="#ACL_server_config">Server configuration</a></li>
|
|
<li><a href="#ACL_server_unix_perms">UNIX socket permissions/group</a></li>
|
|
<li><a href="#ACL_server_polkit">UNIX socket PolicyKit auth</a></li>
|
|
<li><a href="#ACL_server_username">Username/password auth</a></li>
|
|
<li><a href="#ACL_server_kerberos">Kerberos auth</a></li>
|
|
</ul>
|
|
|
|
<h3 name="ACL_server_config">Server configuration</h3>
|
|
|
|
<p>
|
|
The libvirt daemon allows the administrator to choose the authentication
|
|
mechanisms used for client connections on each network socket independently.
|
|
This is primarily controlled via the libvirt daemon master config file in
|
|
<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
|
|
have its authentication mechanism configured independently. There is
|
|
currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>.
|
|
The SASL scheme can be further configured to choose between a large
|
|
number of different mechanisms.
|
|
</p>
|
|
|
|
<h3 name="ACL_server_unix_perms">UNIX socket permissions/group</h3>
|
|
|
|
<p>
|
|
If libvirt does not contain support for PolicyKit, then access control for
|
|
the UNIX domain socket is done using traditional file user/group ownership
|
|
and permissions. There are 2 sockets, one for full read-write access, the
|
|
other for read-only access. The RW socket will be restricted (mode 0700) to
|
|
only allow the <code>root</code> user to connect. The read-only socket will
|
|
be open access (mode 0777) to allow any user to connect.
|
|
</p>
|
|
|
|
<p>
|
|
To allow non-root users greater access, the <code>libvirtd.conf</code> file
|
|
can be edited to change the permissions via the <code>unix_sock_rw_perms</code>,
|
|
config parameter and to set a user group via the <code>unix_sock_group</code>
|
|
parameter. For example, setting the former to mode <code>0770</code> and the
|
|
latter <code>wheel</code> would let any user in the wheel group connect to
|
|
the libvirt daemon.
|
|
</p>
|
|
|
|
<h3 name="ACL_server_polkit">UNIX socket PolicyKit auth</h3>
|
|
|
|
<p>
|
|
If libvirt contains support for PolicyKit, then access control options are
|
|
more advanced. The <code>unix_sock_auth</code> parameter will default to
|
|
<code>polkit</code>, and the file permissions will default to <code>0777</code>
|
|
even on the RW socket. Upon connecting to the socket, the client application
|
|
will be required to identify itself with PolicyKit. The default policy for the
|
|
RW daemon socket will require any application running in the current desktop
|
|
session to authenticate using the user's password. This is akin to <code>sudo</code>
|
|
auth, but does not require that the client application ultimately run as root.
|
|
Default policy will still allow any application to connect to the RO socket.
|
|
</p>
|
|
|
|
<p>
|
|
The default policy can be overridden by the administrator using the PolicyKit
|
|
master configuration file in <code>/etc/PolicyKit/PolicyKit.conf</code>. The
|
|
<code>PolicyKit.conf(5)</code> manual page provides details on the syntax
|
|
available. The two libvirt daemon actions available are named <code>org.libvirt.unix.monitor</code>
|
|
for the RO socket, and <code>org.libvirt.unix.manage</code> for the RW socket.
|
|
</p>
|
|
|
|
<p>
|
|
As an example, to allow a user <code>fred</code>full access to the RW socket,
|
|
while requiring <code>joe</code> to authenticate with the admin password,
|
|
would require adding the following snippet to <code>PolicyKit.conf</code>.
|
|
</p>
|
|
|
|
<pre>
|
|
<match action="org.libvirt.unix.manage" user="fred">
|
|
<return result="yes"/>
|
|
</match>
|
|
<match action="org.libvirt.unix.manage" user="joe">
|
|
<return result="auth_admin"/>
|
|
</match>
|
|
</pre>
|
|
|
|
<h3 name="ACL_server_username">Username/password auth</h3>
|
|
|
|
<p>
|
|
The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
|
|
The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
|
|
username+password style authentication. It also provides for encryption of the data
|
|
stream, so the security of the plain TCP socket is on a par with that of the TLS
|
|
socket. If desired the UNIX socket and TLS socket can also have SASL enabled by
|
|
setting the <code>auth_unix_ro</code>, <code>auth_unix_rw</code>, <code>auth_tls</code>
|
|
config params in <code>libvirt.conf</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Out of the box, no user accounts are defined, so no clients will be able to authenticate
|
|
on the TCP socket. Adding users and setting their passwords is done with the <code>saslpasswd2</code>
|
|
command. When running this command it is important to tell it that the appname is <code>libvirt</code>.
|
|
As an example, to add a user <code>fred</code>, run
|
|
</p>
|
|
|
|
<pre>
|
|
# saslpasswd2 -a libvirt fred
|
|
Password: xxxxxx
|
|
Again (for verification): xxxxxx
|
|
</pre>
|
|
|
|
<p>
|
|
To see a list of all accounts the <code>sasldblistusers2</code> command can be used.
|
|
This command expects to be given the path to the libvirt user database, which is kept
|
|
in <code>/etc/libvirt/passwd.db</code>
|
|
</p>
|
|
|
|
<pre>
|
|
# sasldblistusers2 -f /etc/libvirt/passwd.db
|
|
fred@t60wlan.home.berrange.com: userPassword
|
|
</pre>
|
|
|
|
<p>
|
|
Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used
|
|
again:
|
|
</p>
|
|
|
|
<pre>
|
|
# saslpasswd2 -a libvirt -d fred
|
|
</pre>
|
|
|
|
|
|
<h3 name="ACL_server_kerberos">Kerberos auth</h3>
|
|
|
|
<p>
|
|
The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
|
|
The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
|
|
username+password style authentication. To enable Kerberos single-sign-on instead,
|
|
the libvirt SASL configuration file must be changed. This is <code>/etc/sasl2/libvirt.conf</code>.
|
|
The <code>mech_list</code> parameter must first be changed to <code>gssapi</code>
|
|
instead of the default <code>digest-md5</code>. If SASL is enabled on the UNIX
|
|
and/or TLS sockets, Kerberos will also be used for them. Like DIGEST-MD5, the Kerberos
|
|
mechanism provides data encryption of the session.
|
|
</p>
|
|
|
|
<p>
|
|
Some operating systems do not install the SASL kerberos plugin by default. It
|
|
may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>.
|
|
To check whether the Kerberos plugin is installed run the <code>pluginviewer</code>
|
|
program and verify that <code>gssapi</code> is listed,eg:
|
|
</p>
|
|
|
|
<pre>
|
|
# pluginviewer
|
|
...snip...
|
|
Plugin "gssapiv2" [loaded], API version: 4
|
|
SASL mechanism: GSSAPI, best SSF: 56
|
|
security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
|
|
features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
|
|
</pre>
|
|
|
|
<p>
|
|
Next is is necessary for the administrator of the Kerberos realm to issue a principle
|
|
for the libvirt server. There needs to be one principle per host running the libvirt
|
|
daemon. The principle should be named <code>libvirt/full.hostname@KERBEROS.REALM</code>.
|
|
This is typically done by running the <code>kadmin.local</code> command on the Kerberos
|
|
server, though some Kerberos servers have alternate ways of setting up service principles.
|
|
Once created, the principle should be exported to a keytab, copied to the host running
|
|
the libvirt daemon and placed in <code>/etc/libvirt/krb5.tab</code>
|
|
</p>
|
|
|
|
<pre>
|
|
# kadmin.local
|
|
kadmin.local: add_principal libvirt/foo.example.com
|
|
Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
|
|
Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
|
|
Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
|
|
|
|
kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM
|
|
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
|
|
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
|
|
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
|
|
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
|
|
|
|
kadmin.local: quit
|
|
|
|
# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
|
|
# rm /root/libvirt-foo-example.tab
|
|
</pre>
|
|
|
|
<p>
|
|
Any client application wishing to connect to a Kerberos enabled libvirt server
|
|
merely needs to run <code>kinit</code> to gain a user principle. This may well
|
|
be done automatically when a user logs into a desktop session, if PAM is setup
|
|
to authenticate against Kerberos.
|
|
</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>libvirtd</code> daemon (named <code>libvirt_qemud</code>
|
|
in releases prior to 0.3.0). The purpose of this
|
|
daemon is to manage qemu instances.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>libvirtd</code> daemon should be started by the
|
|
init scripts when the machine boots. It should appear as
|
|
a process <code>libvirtd --daemon</code> running as root
|
|
in the background and will handle qemu instances on behalf
|
|
of all users of the machine (among other things). </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>libvirtd --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>
|
|
|
|
<h2><a name="HVSupport">Hypervisor support</a></h2>
|
|
|
|
<p>
|
|
This page documents which <a href="html/">libvirt calls</a> work on
|
|
which hypervisors.
|
|
</p>
|
|
|
|
<p>
|
|
This information changes frequently. This page was last checked or
|
|
updated on <i>2007-08-20</i>.
|
|
</p>
|
|
|
|
<h3>Domain functions</h3>
|
|
|
|
<p> x = not supported; empty cell means no information </p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Function </th>
|
|
<th> Since </th>
|
|
<th> Xen </th>
|
|
<th> QEMU </th>
|
|
<th> KVM </th>
|
|
<th> <a href="remote.html">Remote</a> </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> virConnectClose </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetCapabilities </td>
|
|
<td> 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetHostname </td>
|
|
<td> 0.3.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
<td> ≥ 0.3.3 </td>
|
|
<td> ≥ 0.3.3 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetMaxVcpus </td>
|
|
<td> 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetType </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetURI </td>
|
|
<td> 0.3.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectGetVersion </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectListDefinedDomains </td>
|
|
<td> 0.1.5 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectListDomains </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectNumOfDefinedDomains </td>
|
|
<td> 0.1.5 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectNumOfDomains </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectOpen </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectOpenReadOnly </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainAttachDevice </td>
|
|
<td> 0.1.9 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainBlockStats </td>
|
|
<td> 0.3.2 </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainCoreDump </td>
|
|
<td> 0.1.9 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainCreate </td>
|
|
<td> 0.1.5 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainCreateLinux </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.0.5 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainDefineXML </td>
|
|
<td> 0.1.5 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainDestroy </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainDetachDevice </td>
|
|
<td> 0.1.9 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainFree </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetAutostart </td>
|
|
<td> 0.2.1 </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetConnect </td>
|
|
<td> 0.3.0 </td>
|
|
<td colspan="4"> not a HV function </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetID </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetInfo </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetMaxMemory </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetMaxVcpus </td>
|
|
<td> 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetName </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetOSType </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetSchedulerParameters </td>
|
|
<td> 0.2.3 </td>
|
|
<td> ≥ 0.2.3 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetSchedulerType </td>
|
|
<td> 0.2.3 </td>
|
|
<td> ≥ 0.2.3 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetUUID </td>
|
|
<td> 0.1.10 </td>
|
|
<td> ≥ 0.1.10 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetUUIDString </td>
|
|
<td> 0.1.10 </td>
|
|
<td> ≥ 0.1.10 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetVcpus </td>
|
|
<td> 0.1.4 </td>
|
|
<td> ≥ 0.1.4 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainInterfaceStats </td>
|
|
<td> 0.3.2 </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainGetXMLDesc </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainLookupByID </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainLookupByName </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainLookupByUUID </td>
|
|
<td> 0.1.10 </td>
|
|
<td> ≥ 0.1.10 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainLookupByUUIDString </td>
|
|
<td> 0.1.10 </td>
|
|
<td> ≥ 0.1.10 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainMigrate </td>
|
|
<td> 0.3.2 </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> 0.3.2 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainPinVcpu </td>
|
|
<td> 0.1.4 </td>
|
|
<td> ≥ 0.1.4 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainReboot </td>
|
|
<td> 0.1.0 </td>
|
|
<td> ≥ 0.1.0 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainRestore </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainResume </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSave </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.2 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSetAutostart </td>
|
|
<td> 0.2.1 </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.2.1 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSetMaxMemory </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSetMemory </td>
|
|
<td> 0.1.1 </td>
|
|
<td> ≥ 0.1.1 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSetSchedulerParameters </td>
|
|
<td> 0.2.3 </td>
|
|
<td> ≥ 0.2.3 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSetVcpus </td>
|
|
<td> 0.1.4 </td>
|
|
<td> ≥ 0.1.4 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainShutdown </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainSuspend </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virDomainUndefine </td>
|
|
<td> 0.1.5 </td>
|
|
<td> ≥ 0.1.9 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virGetVersion </td>
|
|
<td> All </td>
|
|
<td> All </td>
|
|
<td colspan="3"> Returns -1 if HV unsupported. </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virInitialize </td>
|
|
<td> 0.1.0 </td>
|
|
<td colspan="4"> not a HV function </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNodeGetInfo </td>
|
|
<td> 0.1.0 </td>
|
|
<td> ≥ 0.1.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.2.0 </td>
|
|
<td> ≥ 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNodeGetFreeMemory </td>
|
|
<td> 0.3.3 </td>
|
|
<td> ≥ 0.3.3 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNodeGetCellsFreeMemory </td>
|
|
<td> 0.3.3 </td>
|
|
<td> ≥ 0.3.3 </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
<td> x </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Network functions</h3>
|
|
|
|
<p>
|
|
Network functions are not hypervisor-specific. For historical
|
|
reasons they require the QEMU daemon to be running (this
|
|
restriction may be lifted in future). Most network functions
|
|
first appeared in libvirt 0.2.0.
|
|
</p>
|
|
|
|
<table class="top_table">
|
|
<tr>
|
|
<th> Function </th>
|
|
<th> Since </th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td> virConnectNumOfNetworks </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectListNetworks </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectNumOfDefinedNetworks </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virConnectListDefinedNetworks </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkCreate </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkCreateXML </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkDefineXML </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkDestroy </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkFree </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetAutostart </td> <td> 0.2.1 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetConnect </td> <td> 0.3.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetBridgeName </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetName </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetUUID </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetUUIDString </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkGetXMLDesc </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkLookupByName </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkLookupByUUID </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkLookupByUUIDString </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkSetAutostart </td> <td> 0.2.1 </td>
|
|
</tr>
|
|
<tr>
|
|
<td> virNetworkUndefine </td> <td> 0.2.0 </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a name="Storage" id="Storage">Storage Management</a></h2>
|
|
|
|
<p>
|
|
This page describes the storage management capabilities in
|
|
libvirt.
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="#StorageCore">Core concepts</a></li>
|
|
<li><a href="#StoragePool">Storage pool XML</a>
|
|
<ul>
|
|
<li><a href="#StoragePoolFirst">First level elements</a></li>
|
|
<li><a href="#StoragePoolSource">Source elements</a></li>
|
|
<li><a href="#StoragePoolTarget">Target elements</a></li>
|
|
<li><a href="#StoragePoolExtents">Device extents</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#StorageVol">Storage volume XML</a>
|
|
<ul>
|
|
<li><a href="#StorageVolFirst">First level elements</a></li>
|
|
<li><a href="#StorageVolSource">Source elements</a></li>
|
|
<li><a href="#StorageVolTarget">Target elements</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#StorageBackend">Storage backend drivers</a>
|
|
<ul>
|
|
<li><a href="#StorageBackendDir">Directory backend</a></li>
|
|
<li><a href="#StorageBackendFS">Local filesystem backend</a></li>
|
|
<li><a href="#StorageBackendNetFS">Network filesystem backend</a></li>
|
|
<li><a href="#StorageBackendLogical">Logical backend</a></li>
|
|
<li><a href="#StorageBackendDisk">Disk backend</a></li>
|
|
<li><a href="#StorageBackendISCSI">iSCSI backend</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="StorageCore">Core concepts</a></h3>
|
|
|
|
<p>
|
|
The storage management APIs are based around 2 core concepts
|
|
</p>
|
|
|
|
<ol>
|
|
<li><strong>Volume</strong> - a single storage volume which can
|
|
be assigned to a guest, or used for creating further pools. A
|
|
volume is either a block device, a raw file, or a special format
|
|
file.</li>
|
|
<li><strong>Pool</strong> - provides a means for taking a chunk
|
|
of storage and carving it up into volumes. A pool can be used to
|
|
manage things such as a physical disk, a NFS server, a iSCSI target,
|
|
a host adapter, an LVM group.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
These two concepts are mapped through to two libvirt objects, a
|
|
<code>virStorageVolPtr</code> and a <code>virStoragePoolPtr</code>,
|
|
each with a collection of APIs for their management.
|
|
</p>
|
|
|
|
|
|
<h3><a name="StoragePool">Storage pool XML</a></h3>
|
|
|
|
<p>
|
|
Although all storage pool backends share the same public APIs and
|
|
XML format, they have varying levels of capabilities. Some may
|
|
allow creation of volumes, others may only allow use of pre-existing
|
|
volumes. Some may have constraints on volume size, or placement.
|
|
</p>
|
|
|
|
<p>The is the top level tag for a storage pool document is 'pool'. It has
|
|
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
|
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
|
<code>logical</code>. This corresponds to the storage backend drivers
|
|
listed further along in this document.
|
|
</p>
|
|
|
|
|
|
<h4><a name="StoragePoolFirst">First level elements</a></h4>
|
|
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd>Providing a name for the pool which is unique to the host.
|
|
This is mandatory when defining a pool</dd>
|
|
|
|
<dt>uuid</dt>
|
|
<dd>Providing an identifier for the pool which is globally unique.
|
|
This is optional when defining a pool, a UUID will be generated if
|
|
omitted</dd>
|
|
|
|
<dt>allocation</dt>
|
|
<dd>Providing the total storage allocation for the pool. This may
|
|
be larger than the sum of the allocation of all volumes due to
|
|
metadata overhead. This value is in bytes. This is not applicable
|
|
when creating a pool.</dd>
|
|
|
|
<dt>capacity</dt>
|
|
<dd>Providing the total storage capacity for the pool. Due to
|
|
underlying device constraints it may not be possible to use the
|
|
full capacity for storage volumes. This value is in bytes. This
|
|
is not applicable when creating a pool.</dd>
|
|
|
|
<dt>available</dt>
|
|
<dd>Providing the free space available for allocating new volumes
|
|
in the pool. Due to underlying device constraints it may not be
|
|
possible to allocate the entire free space to a single volume.
|
|
This value is in bytes. This is not applicable when creating a
|
|
pool.</dd>
|
|
|
|
<dt>source</dt>
|
|
<dd>Provides information about the source of the pool, such as
|
|
the underlying host devices, or remote server</dd>
|
|
|
|
<dt>target</dt>
|
|
<dd>Provides information about the representation of the pool
|
|
on the local host.</dd>
|
|
</dl>
|
|
|
|
<h4><a name="StoragePoolSource">Source elements</a></h4>
|
|
|
|
<dl>
|
|
<dt>device</dt>
|
|
<dd>Provides the source for pools backed by physical devices.
|
|
May be repeated multiple times depending on backend driver. Contains
|
|
a single attribute <code>path</code> which is the fully qualified
|
|
path to the block device node.</dd>
|
|
<dt>directory</dt>
|
|
<dd>Provides the source for pools backed by directories. May
|
|
only occur once. Contains a single attribute <code>path</code>
|
|
which is the fully qualified path to the block device node.</dd>
|
|
<dt>host</dt>
|
|
<dd>Provides the source for pools backed by storage from a
|
|
remote server. Will be used in combination with a <code>directory</code>
|
|
or <code>device</code> element. Contains an attribute <code>name<code>
|
|
which is the hostname or IP address of the server. May optionally
|
|
contain a <code>port</code> attribute for the protocol specific
|
|
port number.</dd>
|
|
<dt>format</dt>
|
|
<dd>Provides information about the format of the pool. This
|
|
contains a single attribute <code>type</code> whose value is
|
|
backend specific. This is typically used to indicate filesystem
|
|
type, or network filesystem type, or partition table type, or
|
|
LVM metadata type. All drivers are required to have a default
|
|
value for this, so it is optional.</dd>
|
|
</dl>
|
|
|
|
<h4><a name="StoragePoolTarget">Target elements</a></h4>
|
|
|
|
<dl>
|
|
<dt>path</dt>
|
|
<dd>Provides the location at which the pool will be mapped into
|
|
the local filesystem namespace. For a filesystem/directory based
|
|
pool it will be the name of the directory in which volumes will
|
|
be created. For device based pools it will be the name of the directory in which
|
|
devices nodes exist. For the latter <code>/dev/</code> may seem
|
|
like the logical choice, however, devices nodes there are not
|
|
guaranteed stable across reboots, since they are allocated on
|
|
demand. It is preferable to use a stable location such as one
|
|
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
|
</dd>
|
|
<dt>permissions<dt>
|
|
<dd>Provides information about the default permissions to use
|
|
when creating volumes. This is currently only useful for directory
|
|
or filesystem based pools, where the volumes allocated are simple
|
|
files. For pools where the volumes are device nodes, the hotplug
|
|
scripts determine permissions. It contains 4 child elements. The
|
|
<code>mode</code> element contains the octal permission set. The
|
|
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
|
element contains the numeric group ID. The <code>label</code> element
|
|
contains the MAC (eg SELinux) label string.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="StoragePoolExtents">Device extents</a></h4>
|
|
|
|
<p>
|
|
If a storage pool exposes information about its underlying
|
|
placement / allocation scheme, the <code>device</code> element
|
|
within the <code>source</code> element may contain information
|
|
about its available extents. Some pools have a constraint that
|
|
a volume must be allocated entirely within a single constraint
|
|
(eg disk partition pools). Thus the extent information allows an
|
|
application to determine the maximum possible size for a new
|
|
volume
|
|
</p>
|
|
|
|
<p>
|
|
For storage pools supporting extent information, within each
|
|
<code>device</code> element there will be zero or more <code>freeExtent</code>
|
|
elements. Each of these elements contains two attributes, <code>start</code>
|
|
and <code>end</code> which provide the boundaries of the extent on the
|
|
device, measured in bytes.
|
|
</p>
|
|
|
|
<h3><a name="StorageVol">Storage volume XML</a></h3>
|
|
|
|
<p>
|
|
A storage volume will be either a file or a device node.
|
|
</p>
|
|
|
|
<h4><a name="StorageVolFirst">First level elements</a></h4>
|
|
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd>Providing a name for the pool which is unique to the host.
|
|
This is mandatory when defining a pool</dd>
|
|
|
|
<dt>uuid</dt>
|
|
<dd>Providing an identifier for the pool which is globally unique.
|
|
This is optional when defining a pool, a UUID will be generated if
|
|
omitted</dd>
|
|
|
|
<dt>allocation</dt>
|
|
<dd>Providing the total storage allocation for the volume. This
|
|
may be smaller than the logical capacity if the volume is sparsely
|
|
allocated. It may also be larger than the logical capacity if the
|
|
volume has substantial metadata overhead. This value is in bytes.
|
|
If omitted when creating a volume, the volume will be fully
|
|
allocated at time of creation. If set to a value smaller than the
|
|
capacity, the pool has the <strong>option</strong> of deciding
|
|
to sparsely allocate a volume. It does not have to honour requests
|
|
for sparse allocation though.</dd>
|
|
|
|
<dt>capacity</dt>
|
|
<dd>Providing the logical capacity for the volume. This value is
|
|
in bytes. This is compulsory when creating a volume</dd>
|
|
|
|
<dt>source</dt>
|
|
<dd>Provides information about the underlying storage allocation
|
|
of the volume. This may not be available for some pool types.</dd>
|
|
|
|
<dt>target</dt>
|
|
<dd>Provides information about the representation of the volume
|
|
on the local host.</dd>
|
|
</dl>
|
|
|
|
<h4><a name="StorageVolTarget">Target elements</a></h4>
|
|
|
|
<dl>
|
|
<dt>path</dt>
|
|
<dd>Provides the location at which the pool will be mapped into
|
|
the local filesystem namespace. For a filesystem/directory based
|
|
pool it will be the name of the directory in which volumes will
|
|
be created. For device based pools it will be the name of the directory in which
|
|
devices nodes exist. For the latter <code>/dev/</code> may seem
|
|
like the logical choice, however, devices nodes there are not
|
|
guaranteed stable across reboots, since they are allocated on
|
|
demand. It is preferrable to use a stable location such as one
|
|
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
|
</dd>
|
|
<dt>format</dt>
|
|
<dd>Provides information about the pool specific volume format.
|
|
For disk pools it will provide the partition type. For filesystem
|
|
or directory pools it will provide the file format type, eg cow,
|
|
qcow, vmdk, raw. If omitted when creating a volume, the pool's
|
|
default format will be used. The actual format is specified via
|
|
the <code>type</code>. Consult the pool-specific docs for the
|
|
list of valid values.</dd>
|
|
<dt>permissions<dt>
|
|
<dd>Provides information about the default permissions to use
|
|
when creating volumes. This is currently only useful for directory
|
|
or filesystem based pools, where the volumes allocated are simple
|
|
files. For pools where the volumes are device nodes, the hotplug
|
|
scripts determine permissions. It contains 4 child elements. The
|
|
<code>mode</code> element contains the octal permission set. The
|
|
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
|
element contains the numeric group ID. The <code>label</code> element
|
|
contains the MAC (eg SELinux) label string.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
|
|
<h3><a name="StorageBackend">Storage backend drivers</a></h3>
|
|
|
|
<p>
|
|
This section illustrates the capabilities / format for each of
|
|
the different backend storage pool drivers
|
|
</p>
|
|
|
|
<h4><a name="StorageBackendDir">Directory pool</a></h4>
|
|
|
|
<p>
|
|
A pool with a type of <code>dir</code> provides the means to manage
|
|
files within a directory. The files can be fully allocated raw files,
|
|
sparsely allocated raw files, or one of the special disk formats
|
|
such as <code>qcow</code>,<code>qcow2</code>,<code>vmdk</code>,
|
|
<code>cow</code>, etc as supported by the <code>qemu-img</code>
|
|
program. If the directory does not exist at the time the pool is
|
|
defined, the <code>build</code> operation can be used to create it.
|
|
</p>
|
|
|
|
<h5>Example pool input definition</h5>
|
|
|
|
<pre>
|
|
<pool type="dir">
|
|
<name>virtimages</name>
|
|
<target>
|
|
<path>/var/lib/virt/images</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The directory pool does not use the pool format type element.
|
|
</p>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
One of the following options:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>raw</code>: a plain file</li>
|
|
<li><code>bochs</code>: Bochs disk image format</li>
|
|
<li><code>cloop</code>: compressed loopback disk image format</li>
|
|
<li><code>cow</code>: User Mode Linux disk image format</li>
|
|
<li><code>dmg</code>: Mac disk image format</li>
|
|
<li><code>iso</code>: CDROM disk image format</li>
|
|
<li><code>qcow</code>: QEMU v1 disk image format</li>
|
|
<li><code>qcow2</code>: QEMU v2 disk image format</li>
|
|
<li><code>vmdk</code>: VMWare disk image format</li>
|
|
<li><code>vpc</code>: VirtualPC disk image format</li>
|
|
</ul>
|
|
|
|
<p>
|
|
When listing existing volumes all these formats are supported
|
|
natively. When creating new volumes, only a subset may be
|
|
available. The <code>raw</code> type is guaranteed always
|
|
available. The <code>qcow2</code> type can be created if
|
|
either <code>qemu-img</code> or <code>qcow-create</code> tools
|
|
are present. The others are dependent on support of the
|
|
<code>qemu-img</code> tool.
|
|
|
|
<h4><a name="StorageBackendFS">Filesystem pool</a></h4>
|
|
|
|
<p>
|
|
This is a variant of the directory pool. Instead of creating a
|
|
directory on an existing mounted filesystem though, it expects
|
|
a source block device to be named. This block device will be
|
|
mounted and files managed in the directory of its mount point.
|
|
It will default to allowing the kernel to automatically discover
|
|
the filesystem type, though it can be specified manually if
|
|
required.
|
|
</p>
|
|
|
|
<h5>Example pool input</h5>
|
|
|
|
<pre>
|
|
<pool type="fs">
|
|
<name>virtimages</name>
|
|
<source>
|
|
<device path="/dev/VolGroup00/VirtImages"/>
|
|
</source>
|
|
<target>
|
|
<path>/var/lib/virt/images</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The filesystem pool supports the following formats:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>auto</code> - automatically determine format</li>
|
|
<li><code>ext2</code></li>
|
|
<li><code>ext3</code></li>
|
|
<li><code>ext4</code></li>
|
|
<li><code>ufs</code></li>
|
|
<li><code>iso9660</code></li>
|
|
<li><code>udf</code></li>
|
|
<li><code>gfs</code></li>
|
|
<li><code>gfs2</code></li>
|
|
<li><code>vfat</code></li>
|
|
<li><code>hfs+</code></li>
|
|
<li><code>xfs</code></li>
|
|
</ul>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
The valid volume types are the same as for the <code>directory</code>
|
|
pool type.
|
|
</p>
|
|
|
|
<h4><a name="StorageBackendNetFS">Network filesystem pool</a></h4>
|
|
|
|
<p>
|
|
This is a variant of the filesystem pool. Instead of requiring
|
|
a local block device as the source, it requires the name of a
|
|
host and path of an exported directory. It will mount this network
|
|
filesystem and manage files within the directory of its mount
|
|
point. It will default to using NFS as the protocol.
|
|
</p>
|
|
|
|
<h5>Example pool input</h5>
|
|
|
|
<pre>
|
|
<pool type="netfs">
|
|
<name>virtimages</name>
|
|
<source>
|
|
<host name="nfs.example.com"/>
|
|
<dir path="/var/lib/virt/images"/>
|
|
</source>
|
|
<target>
|
|
<path>/var/lib/virt/images</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The network filesystem pool supports the following formats:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>auto</code> - automatically determine format</li>
|
|
<li><code>nfs</code></li>
|
|
</ul>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
The valid volume types are the same as for the <code>directory</code>
|
|
pool type.
|
|
</p>
|
|
|
|
<h4><a name="StorageBackendLogical">Logical volume pools</a></h4>
|
|
|
|
<p>
|
|
This provides a pool based on an LVM volume group. For a
|
|
pre-defined LVM volume group, simply providing the group
|
|
name is sufficient, while to build a new group requires
|
|
providing a list of source devices to serve as physical
|
|
volumes. Volumes will be allocated by carving out chunks
|
|
of storage from the volume group.
|
|
</p>
|
|
|
|
<h5>Example pool input</h5>
|
|
|
|
<pre>
|
|
<pool type="logical">
|
|
<name>HostVG</name>
|
|
<source>
|
|
<device path="/dev/sda1"/>
|
|
<device path="/dev/sdb1"/>
|
|
<device path="/dev/sdc1"/>
|
|
</source>
|
|
<target>
|
|
<path>/dev/HostVG</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The logical volume pool does not use the pool format type element.
|
|
</p>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
The logical volume pool does not use the volume format type element.
|
|
</p>
|
|
|
|
|
|
<h4><a name="StorageBackendDisk">Disk volume pools</a></h4>
|
|
|
|
<p>
|
|
This provides a pool based on a physical disk. Volumes are created
|
|
by adding partitions to the disk. Disk pools are have constraints
|
|
on the size and placement of volumes. The 'free extents'
|
|
information will detail the regions which are available for creating
|
|
new volumes. A volume cannot span across 2 different free extents.
|
|
</p>
|
|
|
|
<h5>Example pool input</h5>
|
|
|
|
<pre>
|
|
<pool type="disk">
|
|
<name>sda</name>
|
|
<source>
|
|
<device path='/dev/sda'/>
|
|
</source>
|
|
<target>
|
|
<path>/dev</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The disk volume pool accepts the following pool format types, representing
|
|
the common partition table types:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>dos</code></li>
|
|
<li><code>dvh</code></li>
|
|
<li><code>gpt</code></li>
|
|
<li><code>mac</code></li>
|
|
<li><code>bsd</code></li>
|
|
<li><code>pc98</code></li>
|
|
<li><code>sun</code></li>
|
|
</ul>
|
|
|
|
<p>
|
|
The <code>dos</code> or <code>gpt</code> formats are recommended for
|
|
best portability - the latter is needed for disks larger than 2TB.
|
|
</p>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
The disk volume pool accepts the following volume format types, representing
|
|
the common partition entry types:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>none</code></li>
|
|
<li><code>linux</code></li>
|
|
<li><code>fat16</code></li>
|
|
<li><code>fat32</code></li>
|
|
<li><code>linux-swap</code></li>
|
|
<li><code>linux-lvm</code></li>
|
|
<li><code>linux-raid</code></li>
|
|
<li><code>extended</code></li>
|
|
</ul>
|
|
|
|
|
|
<h4><a name="StorageBackendISCSI">iSCSI volume pools</a></h4>
|
|
|
|
<p>
|
|
This provides a pool based on an iSCSI target. Volumes must be
|
|
pre-allocated on the iSCSI server, and cannot be created via
|
|
the libvirt APIs. Since /dev/XXX names may change each time libvirt
|
|
logs into the iSCSI target, it is recommended to configure the pool
|
|
to use <code>/dev/disk/by-path</code> or <code>/dev/disk/by-id</code>
|
|
for the target path. These provide persistent stable naming for LUNs
|
|
</p>
|
|
|
|
<h5>Example pool input</h5>
|
|
|
|
<pre>
|
|
<pool type="iscsi">
|
|
<name>virtimages</name>
|
|
<source>
|
|
<host name="iscsi.example.com"/>
|
|
<device path="demo-target"/>
|
|
</source>
|
|
<target>
|
|
<path>/dev/disk/by-path</path>
|
|
</target>
|
|
</pool>
|
|
</pre>
|
|
|
|
<h5>Valid pool format types</h5>
|
|
|
|
<p>
|
|
The logical volume pool does not use the pool format type element.
|
|
</p>
|
|
|
|
<h5>Valid volume format types</h5>
|
|
|
|
<p>
|
|
The logical volume pool does not use the volume format type element.
|
|
</p>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|