I'm sponsoring the following fast-track for John Levon.
Updated manpages in materials directory.
1. Introduction
libvirt was introduced as PSARC 2007/157. virt-install does not seem to
have been introduced to ARC separately, but was part of LSARC 2007/175.
This case covers a refresh of both packages.
libvirt is being upgraded to version 0.6 (currently 0.4).
virt-install is being upgraded to 0.400.3 (from 0.300.3).
A patch binding is requested, though no backport is planned.
2. API changes
Both packages have APIs intended to be stable but controlled by the
upstream community. This section covers new additions to the APIs. Those
interested can read the upstream documentation for more information.
Except as noted, we ship the same API as upstream does without changes.
New virt-install and virsh options can be seen in the man-page diffs in
the case materials.
As before, virsh options that are not implemented on Solaris yet have
been ifdefed out.
Currently, libvirt, as a Volatile interface, has no API man pages; the
new API functions are listed below.
libvirt has a number of XML schemas: these are now delivered to
/usr/share/lib/xml/rng/libvirt/. OpenSolaris already uses this location
for Relax-NG schemas, but this is the first time it's been presented to
ARC, so this case marks the location as Committed. We also mark the
individual schemas as Committed.
Note the manpage diffs remove the incorrect verbiage about ldoms and
the libvirt tools. Solaris has not shipped with an ldoms libvirt driver,
though an external project exists. Future work will provide an
integrated solution for ldoms support with libvirt.
3. Incompatibilities
PSARC 2008/577 introduced the relative path APIs. This case marked them
as committed. After negative feedback from the upstream community, this
case will change them to be Obsolete Volatile. Practically, these
interfaces are not heavily used and were introduced only for
virt-convert's usage. It is expected that they will go away at some
point in the future, to be replaced by the community's solution to the
issue (namely virt-image).
PSARC 2007/157 marked usr/bin/i86/virsh and usr/bin/amd64/virsh as
Committed. These are implementation details and should correctly have
been Not-an-interface. This case fixes this.
The last virt-install version incorrectly accepted the --location flag
for HVM domains. The newer version reverts this bug, so --cdrom is
required instead.
Earlier versions of virt-install supported an interactive prompting mode
when not enough information was given. The newer version disables this
feature. Since it's only useful for interactive usage, this shouldn't be
a compatibility issue per se, though it does make virt-install even
harder to use.
No other compatibility issues have yet come to light.
4. Interface table
/usr/share/lib/xml/rng Committed
/usr/share/lib/xml/rng/libvirt/* Committed
libvirt API Volatile
usr/bin/virsh Committed
usr/bin/virsh cmdline Committed
usr/bin/virsh output Not-an-interface
usr/bin/i86/virsh Not-an-interface
usr/bin/amd64/virsh Not-an-interface
usr/include/libvirt/libvirt.h Volatile
usr/include/libvirt/virterror.h Volatile
usr/lib/libvirt.so Volatile
usr/lib/amd64/libvirt.so Volatile
usr/lib/python2.4/vendor-packages/libvirt.py Uncommitted
usr/lib/python2.4/vendor-packages/libvirt.pyc Uncommitted
usr/lib/python2.4/vendor-packages/libvirtmod.so Uncommitted
usr/lib/python2.4/vendor-packages/64/libvirtmod.so Uncommitted
virDomainGetRelativeXMLDesc Obsolete Volatile
virDomainDefineRelativeXML Obsolete Volatile
virsh(1M) --relative-path Obsolete Volatile
usr/bin/virt-install Committed
usr/bin/virt-install cmdline Committed
usr/bin/virt-install output Not-an-interface
5. References
http://libvirt.org/
http://www.virt-manager.org/
PSARC/2006/260 Solaris on Xen
LSARC/2007/175 Virtual Machine Manager
LSARC/2007/625 vncviewer
PSARC/2007/157 libvirt - a LGPL library to control guest domains
PSARC/2008/289 Least Privilege for xVM
PSARC/2008/577 Libvirt APIs for relative paths
PSARC/2008/579 virt-convert
PSARC/2008/596 Block Tap Support for Solaris
6. New libvirt functions
int virConnectRef (virConnectPtr conn);
int virDomainRef (virDomainPtr domain);
int virDomainBlockPeek (virDomainPtr dom,
const char *path,
unsigned long long offset,
size_t size,
void *buffer,
unsigned int flags);
int virDomainMemoryPeek (virDomainPtr dom,
unsigned long long start,
size_t size,
void *buffer,
unsigned int flags);
int virNetworkRef (virNetworkPtr network);
virConnectPtr virStoragePoolGetConnect
(virStoragePoolPtr pool);
int virConnectNumOfStoragePools (virConnectPtr
conn);
int virConnectListStoragePools (virConnectPtr conn,
char **const
names,
int maxnames);
int virConnectNumOfDefinedStoragePools(virConnectPtr
conn);
int virConnectListDefinedStoragePools(virConnectPtr
conn,
char **const
names,
int maxnames);
char * virConnectFindStoragePoolSources(virConnectPtr conn,
const char *type,
const char
*srcSpec,
unsigned int
flags);
virStoragePoolPtr virStoragePoolLookupByName (virConnectPtr conn,
const char *name);
virStoragePoolPtr virStoragePoolLookupByUUID (virConnectPtr conn,
const unsigned
char *uuid);
virStoragePoolPtr virStoragePoolLookupByUUIDString(virConnectPtr conn,
const char *uuid);
virStoragePoolPtr virStoragePoolLookupByVolume
(virStorageVolPtr vol);
virStoragePoolPtr virStoragePoolCreateXML (virConnectPtr conn,
const char
*xmlDesc,
unsigned int
flags);
virStoragePoolPtr virStoragePoolDefineXML (virConnectPtr conn,
const char
*xmlDesc,
unsigned int
flags);
int virStoragePoolBuild
(virStoragePoolPtr pool,
unsigned int
flags);
int virStoragePoolUndefine
(virStoragePoolPtr pool);
int virStoragePoolCreate
(virStoragePoolPtr pool,
unsigned int
flags);
int virStoragePoolDestroy
(virStoragePoolPtr pool);
int virStoragePoolDelete
(virStoragePoolPtr pool,
unsigned int
flags);
int virStoragePoolRef
(virStoragePoolPtr pool);
int virStoragePoolFree
(virStoragePoolPtr pool);
int virStoragePoolRefresh
(virStoragePoolPtr pool,
unsigned int
flags);
const char* virStoragePoolGetName
(virStoragePoolPtr pool);
int virStoragePoolGetUUID
(virStoragePoolPtr pool,
unsigned char
*uuid);
int virStoragePoolGetUUIDString
(virStoragePoolPtr pool,
char *buf);
int virStoragePoolGetInfo
(virStoragePoolPtr vol,
virStoragePoolInfoPtr info);
char * virStoragePoolGetXMLDesc
(virStoragePoolPtr pool,
unsigned int
flags);
int virStoragePoolGetAutostart
(virStoragePoolPtr pool,
int *autostart);
int virStoragePoolSetAutostart
(virStoragePoolPtr pool,
int autostart);
int virStoragePoolNumOfVolumes
(virStoragePoolPtr pool);
int virStoragePoolListVolumes
(virStoragePoolPtr pool,
char **const
names,
int maxnames);
virConnectPtr virStorageVolGetConnect
(virStorageVolPtr vol);
virStorageVolPtr virStorageVolLookupByName
(virStoragePoolPtr pool,
const char *name);
virStorageVolPtr virStorageVolLookupByKey (virConnectPtr conn,
const char *key);
virStorageVolPtr virStorageVolLookupByPath (virConnectPtr conn,
const char *path);
const char* virStorageVolGetName
(virStorageVolPtr vol);
const char* virStorageVolGetKey
(virStorageVolPtr vol);
virStorageVolPtr virStorageVolCreateXML
(virStoragePoolPtr pool,
const char
*xmldesc,
unsigned int
flags);
int virStorageVolDelete
(virStorageVolPtr vol,
unsigned int
flags);
int virStorageVolRef
(virStorageVolPtr vol);
int virStorageVolFree
(virStorageVolPtr vol);
int virStorageVolGetInfo
(virStorageVolPtr vol,
virStorageVolInfoPtr info);
char * virStorageVolGetXMLDesc
(virStorageVolPtr pool,
unsigned int
flags);
char * virStorageVolGetPath
(virStorageVolPtr vol);
int virNodeNumOfDevices (virConnectPtr conn,
const char *cap,
unsigned int flags);
int virNodeListDevices (virConnectPtr conn,
const char *cap,
char **const names,
int maxnames,
unsigned int flags);
virNodeDevicePtr virNodeDeviceLookupByName (virConnectPtr conn,
const char *name);
const char * virNodeDeviceGetName (virNodeDevicePtr dev);
const char * virNodeDeviceGetParent (virNodeDevicePtr dev);
int virNodeDeviceNumOfCaps (virNodeDevicePtr dev);
int virNodeDeviceListCaps (virNodeDevicePtr dev,
char **const names,
int maxnames);
char * virNodeDeviceGetXMLDesc (virNodeDevicePtr dev,
unsigned int flags);
int virNodeDeviceRef (virNodeDevicePtr dev);
int virNodeDeviceFree (virNodeDevicePtr dev);
typedef int (*virConnectDomainEventCallback)(virConnectPtr conn,
virDomainPtr dom,
int event,
int detail,
void *opaque);
typedef void (*virFreeCallback)(void *opaque);
int virConnectDomainEventRegister(virConnectPtr conn,
virConnectDomainEventCallback cb,
void *opaque,
virFreeCallback freecb);
int virConnectDomainEventDeregister(virConnectPtr conn,
virConnectDomainEventCallback cb);
typedef void (*virEventHandleCallback)(int watch, int fd, int events,
void *opaque);
typedef int (*virEventAddHandleFunc)(int fd, int event,
virEventHandleCallback cb,
void *opaque,
virFreeCallback ff);
typedef void (*virEventUpdateHandleFunc)(int watch, int event);
typedef int (*virEventRemoveHandleFunc)(int watch);
typedef void (*virEventTimeoutCallback)(int timer, void *opaque);
typedef int (*virEventAddTimeoutFunc)(int timeout,
virEventTimeoutCallback cb,
void *opaque,
virFreeCallback ff);
typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout);
typedef int (*virEventRemoveTimeoutFunc)(int timer);
void virEventRegisterImpl(virEventAddHandleFunc addHandle,
virEventUpdateHandleFunc updateHandle,
virEventRemoveHandleFunc removeHandle,
virEventAddTimeoutFunc addTimeout,
virEventUpdateTimeoutFunc updateTimeout,
virEventRemoveTimeoutFunc removeTimeout);
