org.libvirt
Class Domain

java.lang.Object
  org.libvirt.Domain

public class Domain
extends java.lang.Object

A virtual machine defined within libvirt.

Field Summary

protected Libvirt

libvirt The libvirt connection from the hypervisor

Method Summary

int	abortJob() Requests that the current background job be aborted at the soonest opportunity.
void	attachDevice(java.lang.String xmlDesc) Creates a virtual device attachment to backend.
void	attachDeviceFlags(java.lang.String xmlDesc, int flags) Creates a virtual device attachment to backend.
DomainBlockInfo	blockInfo(java.lang.String path) This function returns block device (disk) stats for block devices attached to the domain.
DomainBlockStats	blockStats(java.lang.String path) Returns block device (disk) stats for block devices attached to this domain.
void	coreDump(java.lang.String to, int flags) Dumps the core of this domain on a given file for analysis.
int	cpuMapLength(int maxCpus) It returns the length (in bytes) required to store the complete CPU map between a single virtual & all physical CPUs of a domain.
int	create() Launches this defined domain.
int	create(int flags) Launches this defined domain with the provide flags.
void	destroy() Destroys this domain object.
void	detachDevice(java.lang.String xmlDesc) Destroys a virtual device attachment to backend.
void	detachDeviceFlags(java.lang.String xmlDesc, int flags) Destroys a virtual device attachment to backend.
void	finalize()
int	free() Frees this domain object.
boolean	getAutostart() Provides a boolean value indicating whether the network is configured to be automatically started when the host machine boots.
Connect	getConnect() Provides the connection object associated with a domain.
int	getID() Gets the hypervisor ID number for the domain
DomainInfo	getInfo() Extract information about a domain.
DomainJobInfo	getJobInfo() Extract information about progress of a background job on a domain.
long	getMaxMemory() Retrieve the maximum amount of physical memory allocated to a domain.
int	getMaxVcpus() Provides the maximum number of virtual CPUs supported for the guest VM.
java.lang.String	getName() Gets the public name for this domain
java.lang.String	getOSType() Gets the type of domain operation system.
SchedParameter[]	getSchedulerParameters() Gets the scheduler parameters.
java.lang.String[]	getSchedulerType() Gets the scheduler type.
int[]	getUUID() Get the UUID for this domain.
java.lang.String	getUUIDString() Gets the UUID for this domain as string.
int[]	getVcpusCpuMaps() Returns the cpumaps for this domain Only the lower 8 bits of each int in the array contain information.
VcpuInfo[]	getVcpusInfo() Extracts information about virtual CPUs of this domain
java.lang.String	getXMLDesc(int flags) Provides an XML description of the domain.
int	hasCurrentSnapshot() Determine if the domain has a snapshot
int	hasManagedSaveImage() Determine if the domain has a managed save image
DomainInterfaceStats	interfaceStats(java.lang.String path) Returns network interface stats for interfaces attached to this domain.
int	isActive() Determine if the domain is currently running
int	isPersistent() Determine if the domain has a persistent configuration which means it will still exist after shutting down
int	managedSave() suspend a domain and save its memory contents to a file on disk.
int	managedSaveRemote() Remove any managed save images from the domain
MemoryStatistic[]	memoryStats(int number) This function provides memory statistics for the domain.
Domain	migrate(Connect dconn, long flags, java.lang.String dname, java.lang.String uri, long bandwidth) Migrate this domain object from its current host to the destination host given by dconn (a connection to the destination host).
int	migrateSetMaxDowntime(long downtime) Sets maximum tolerable time for which the domain is allowed to be paused at the end of live migration.
int	migrateToURI(java.lang.String uri, long flags, java.lang.String dname, long bandwidth) Migrate the domain object from its current host to the destination host given by duri.
void	pinVcpu(int vcpu, int[] cpumap) Dynamically changes the real CPUs which can be allocated to a virtual CPU.
protected void	processError() Error handling logic to throw errors.
void	reboot(int flags) Reboot this domain, the domain object is still usable there after but the domain OS is being stopped for a restart.
void	resume() Resume this suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain().
int	revertToSnapshot(DomainSnapshot snapshot) Revert the domain to a given snapshot.
void	save(java.lang.String to) Suspends this domain and saves its memory contents to a file on disk.
void	setAutostart(boolean autostart) Configures the network to be automatically started when the host machine boots.
void	setMaxMemory(long memory) * Dynamically change the maximum amount of physical memory allocated to a domain.
void	setMemory(long memory) Dynamically changes the target amount of physical memory allocated to this domain.
void	setSchedulerParameters(SchedParameter[] params) Changes the scheduler parameters
void	setVcpus(int nvcpus) Dynamically changes the number of virtual CPUs used by this domain.
void	shutdown() Shuts down this domain, the domain object is still usable there after but the domain OS is being stopped.
DomainSnapshot	snapshotCreateXML(java.lang.String xmlDesc) Creates a new snapshot of a domain based on the snapshot xml contained in xmlDesc.
DomainSnapshot	snapshotCurrent() Get the current snapshot for a domain, if any.
java.lang.String[]	snapshotListNames() Collect the list of domain snapshots for the given domain.
DomainSnapshot	snapshotLookupByName(java.lang.String name) Retrieve a snapshot by name
int	snapshotNum() Provides the number of domain snapshots for this domain..
void	suspend() Suspends this active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated.
void	undefine() undefines this domain but does not stop it if it is running
int	updateDeviceFlags(java.lang.String xml, int flags) Change a virtual device on a domain

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

libvirt

protected Libvirt libvirt

The libvirt connection from the hypervisor

Method Detail

abortJob

public int abortJob()
             throws LibvirtException

Requests that the current background job be aborted at the soonest opportunity. This will block until the job has either completed, or aborted.

Returns:

0 in case of success and -1 in case of failure.

Throws:

LibvirtException

See Also:

Libvirt Documentation

attachDevice

public void attachDevice(java.lang.String xmlDesc)
                  throws LibvirtException

Creates a virtual device attachment to backend.

Parameters:

xmlDesc - XML description of one device

Throws:

LibvirtException

See Also:

Libvirt Documentation

attachDeviceFlags

public void attachDeviceFlags(java.lang.String xmlDesc,
                              int flags)
                       throws LibvirtException

Creates a virtual device attachment to backend.

Parameters:

xmlDesc - XML description of one device

flags - the an OR'ed set of virDomainDeviceModifyFlags

Throws:

LibvirtException

See Also:

Libvirt Documentation

blockInfo

public DomainBlockInfo blockInfo(java.lang.String path)
                          throws LibvirtException

This function returns block device (disk) stats for block devices attached to the domain.

Parameters:

path - the path to the block device

Returns:

the info, or null if an error

Throws:

LibvirtException

blockStats

public DomainBlockStats blockStats(java.lang.String path)
                            throws LibvirtException

Returns block device (disk) stats for block devices attached to this domain. The path parameter is the name of the block device. Get this by calling virDomainGetXMLDesc and finding the attribute within //domain/devices/disk. (For example, "xvda"). Domains may have more than one block device. To get stats for each you should make multiple calls to this function. Individual fields within the DomainBlockStats object may be returned as -1, which indicates that the hypervisor does not support that particular statistic.

Parameters:

path - path to the block device

Returns:

the statistics in a DomainBlockStats object

Throws:

LibvirtException

coreDump

public void coreDump(java.lang.String to,
                     int flags)
              throws LibvirtException

Dumps the core of this domain on a given file for analysis. Note that for remote Xen Daemon the file path will be interpreted in the remote host.

Parameters:

to - path for the core file

flags - extra flags, currently unused

Throws:

LibvirtException

cpuMapLength

public int cpuMapLength(int maxCpus)

It returns the length (in bytes) required to store the complete CPU map between a single virtual & all physical CPUs of a domain.

create

public int create()
           throws LibvirtException

Launches this defined domain. If the call succeed the domain moves from the defined to the running domains pools.

Throws:

LibvirtException

create

public int create(int flags)
           throws LibvirtException

Launches this defined domain with the provide flags. If the call succeed the domain moves from the defined to the running domains pools.

Throws:

LibvirtException

destroy

public void destroy()
             throws LibvirtException

Destroys this domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor. The data structure is freed and should not be used thereafter if the call does not return an error. This function may requires priviledged access

Throws:

LibvirtException

detachDevice

public void detachDevice(java.lang.String xmlDesc)
                  throws LibvirtException

Destroys a virtual device attachment to backend.

Parameters:

xmlDesc - XML description of one device

Throws:

LibvirtException

See Also:

Libvirt Documentation

detachDeviceFlags

public void detachDeviceFlags(java.lang.String xmlDesc,
                              int flags)
                       throws LibvirtException

Destroys a virtual device attachment to backend.

Parameters:

xmlDesc - XML description of one device

Throws:

LibvirtException

See Also:

Libvirt Documentation

finalize

public void finalize()
              throws LibvirtException

Overrides:

finalize in class java.lang.Object

Throws:

LibvirtException

free

public int free()
         throws LibvirtException

Frees this domain object. The running instance is kept alive. The data structure is freed and should not be used thereafter.

Returns:

number of references left (>= 0) for success, -1 for failure.

Throws:

LibvirtException

getAutostart

public boolean getAutostart()
                     throws LibvirtException

Provides a boolean value indicating whether the network is configured to be automatically started when the host machine boots.

Returns:

the result

Throws:

LibvirtException

getConnect

public Connect getConnect()

Provides the connection object associated with a domain.

Returns:

the Connect object

getID

public int getID()
          throws LibvirtException

Gets the hypervisor ID number for the domain

Returns:

the hypervisor ID

Throws:

LibvirtException

getInfo

public DomainInfo getInfo()
                   throws LibvirtException

Extract information about a domain. Note that if the connection used to get the domain is limited only a partial set of the information can be extracted.

Returns:

a DomainInfo object describing this domain

Throws:

LibvirtException

See Also:

Libvirt Documentation

getJobInfo

public DomainJobInfo getJobInfo()
                         throws LibvirtException

Extract information about progress of a background job on a domain. Will return an error if the domain is not active.

Returns:

a DomainJobInfo object describing this domain

Throws:

LibvirtException

See Also:

Libvirt Documentation

getMaxMemory

public long getMaxMemory()
                  throws LibvirtException

Retrieve the maximum amount of physical memory allocated to a domain.

Returns:

the memory in kilobytes

Throws:

LibvirtException

getMaxVcpus

public int getMaxVcpus()
                throws LibvirtException

Provides the maximum number of virtual CPUs supported for the guest VM. If the guest is inactive, this is basically the same as virConnectGetMaxVcpus. If the guest is running this will reflect the maximum number of virtual CPUs the guest was booted with.

Returns:

the number of VCPUs

Throws:

LibvirtException

getName

public java.lang.String getName()
                         throws LibvirtException

Gets the public name for this domain

Returns:

the name

Throws:

LibvirtException

getOSType

public java.lang.String getOSType()
                           throws LibvirtException

Gets the type of domain operation system.

Returns:

the type

Throws:

LibvirtException

getSchedulerParameters

public SchedParameter[] getSchedulerParameters()
                                        throws LibvirtException

Gets the scheduler parameters.

Returns:

an array of SchedParameter objects

Throws:

LibvirtException

getSchedulerType

public java.lang.String[] getSchedulerType()
                                    throws LibvirtException

Gets the scheduler type.

Returns:

the type of the scheduler

Throws:

LibvirtException

getUUID

public int[] getUUID()
              throws LibvirtException

Get the UUID for this domain.

Returns:

the UUID as an unpacked int array

Throws:

LibvirtException

See Also:

rfc4122

getUUIDString

public java.lang.String getUUIDString()
                               throws LibvirtException

Gets the UUID for this domain as string.

Returns:

the UUID in canonical String format

Throws:

LibvirtException

See Also:

rfc4122

getVcpusCpuMaps

public int[] getVcpusCpuMaps()
                      throws LibvirtException

Returns the cpumaps for this domain Only the lower 8 bits of each int in the array contain information.

Returns:

a bitmap of real CPUs for all vcpus of this domain

Throws:

LibvirtException

getVcpusInfo

public VcpuInfo[] getVcpusInfo()
                        throws LibvirtException

Extracts information about virtual CPUs of this domain

Returns:

an array of VcpuInfo object describing the VCPUs

Throws:

LibvirtException

getXMLDesc

public java.lang.String getXMLDesc(int flags)
                            throws LibvirtException

Provides an XML description of the domain. The description may be reused later to relaunch the domain with createLinux().

Parameters:

flags - not used

Returns:

the XML description String

Throws:

LibvirtException

See Also:

The XML Description format

hasCurrentSnapshot

public int hasCurrentSnapshot()
                       throws LibvirtException

Determine if the domain has a snapshot

Returns:

1 if running, 0 if inactive, -1 on error

Throws:

LibvirtException

See Also:

hasManagedSaveImage

public int hasManagedSaveImage()
                        throws LibvirtException

Determine if the domain has a managed save image

Returns:

0 if no image is present, 1 if an image is present, and -1 in case of error

Throws:

LibvirtException

See Also:

interfaceStats

public DomainInterfaceStats interfaceStats(java.lang.String path)
                                    throws LibvirtException

Returns network interface stats for interfaces attached to this domain. The path parameter is the name of the network interface. Domains may have more than network interface. To get stats for each you should make multiple calls to this function. Individual fields within the DomainInterfaceStats object may be returned as -1, which indicates that the hypervisor does not support that particular statistic.

Parameters:

path - path to the interface

Returns:

the statistics in a DomainInterfaceStats object

Throws:

LibvirtException

isActive

public int isActive()
             throws LibvirtException

Determine if the domain is currently running

Returns:

1 if running, 0 if inactive, -1 on error

Throws:

LibvirtException

See Also:

Libvirt Documentation

isPersistent

public int isPersistent()
                 throws LibvirtException

Determine if the domain has a persistent configuration which means it will still exist after shutting down

Returns:

1 if persistent, 0 if transient, -1 on error

Throws:

LibvirtException

See Also:

Libvirt Documentation

managedSave

public int managedSave()
                throws LibvirtException

suspend a domain and save its memory contents to a file on disk.

Returns:

0 in case of success or -1 in case of failure

Throws:

LibvirtException

See Also:

Libvirt Documentation

managedSaveRemote

public int managedSaveRemote()
                      throws LibvirtException

Remove any managed save images from the domain

Returns:

Throws:

LibvirtException

See Also:

Libvirt Documentation

memoryStats

public MemoryStatistic[] memoryStats(int number)
                              throws LibvirtException

This function provides memory statistics for the domain.

Parameters:

number - the number of stats to retrieve

Returns:

the collection of stats, or null if an error occurs.

Throws:

LibvirtException

migrate

public Domain migrate(Connect dconn,
                      long flags,
                      java.lang.String dname,
                      java.lang.String uri,
                      long bandwidth)
               throws LibvirtException

Migrate this domain object from its current host to the destination host given by dconn (a connection to the destination host). Flags may be one of more of the following: Domain.VIR_MIGRATE_LIVE Attempt a live migration. If a hypervisor supports renaming domains during migration, then you may set the dname parameter to the new name (otherwise it keeps the same name). If this is not supported by the hypervisor, dname must be NULL or else you will get an error. Since typically the two hypervisors connect directly to each other in order to perform the migration, you may need to specify a path from the source to the destination. This is the purpose of the uri parameter.If uri is NULL, then libvirt will try to find the best method. Uri may specify the hostname or IP address of the destination host as seen from the source, or uri may be a URI giving transport, hostname, user, port, etc. in the usual form. Uri should only be specified if you want to migrate over a specific interface on the remote host. For Qemu/KVM, the uri should be of the form "tcp://hostname[:port]". This does not require TCP auth to be setup between the connections, since migrate uses a straight TCP connection (unless using the PEER2PEER flag, in which case URI should be a full fledged libvirt URI). Refer also to driver documentation for the particular URIs supported. If set to 0, libvirt will choose a suitable default. Some hypervisors do not support this feature and will return an error if bandwidth is not 0. To see which features are supported by the current hypervisor, see Connect.getCapabilities, /capabilities/host/migration_features. There are many limitations on migration imposed by the underlying technology - for example it may not be possible to migrate between different processors even with the same architecture, or between different types of hypervisor.

Parameters:

dconn - destination host (a Connect object)

flags - flags

dname - (optional) rename domain to this at destination

uri - (optional) dest hostname/URI as seen from the source host

bandwidth - optional) specify migration bandwidth limit in Mbps

Returns:

the new domain object if the migration was successful, or NULL in case of error. Note that the new domain object exists in the scope of the destination connection (dconn).

Throws:

LibvirtException

migrateSetMaxDowntime

public int migrateSetMaxDowntime(long downtime)
                          throws LibvirtException

Sets maximum tolerable time for which the domain is allowed to be paused at the end of live migration.

Parameters:

downtime - the time to be down

Returns:

0 in case of success, -1 otherwise.

Throws:

LibvirtException

See Also:

LIbvirt Documentation

migrateToURI

public int migrateToURI(java.lang.String uri,
                        long flags,
                        java.lang.String dname,
                        long bandwidth)
                 throws LibvirtException

Migrate the domain object from its current host to the destination host given by duri.

Parameters:

uri - The destination URI

flags - Controls the migrate

dname - The name at the destnation

bandwidth - Specify the migration bandwidth

Returns:

0 if successful, -1 if not

Throws:

LibvirtException

See Also:

://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI

pinVcpu

public void pinVcpu(int vcpu,
                    int[] cpumap)
             throws LibvirtException

Dynamically changes the real CPUs which can be allocated to a virtual CPU. This function requires priviledged access to the hypervisor.

Parameters:

vcpu - virtual cpu number

cpumap - bit map of real CPUs represented by the the lower 8 bits of each int in the array. Each bit set to 1 means that corresponding CPU is usable. Bytes are stored in little-endian order: CPU0-7, 8-15... In each byte, lowest CPU number is least significant bit.

Throws:

LibvirtException

processError

protected void processError()
                     throws LibvirtException

Error handling logic to throw errors. Must be called after every libvirt call.

Throws:

LibvirtException

reboot

public void reboot(int flags)
            throws LibvirtException

Reboot this domain, the domain object is still usable there after but the domain OS is being stopped for a restart. Note that the guest OS may ignore the request.

Parameters:

flags - extra flags for the reboot operation, not used yet

Throws:

LibvirtException

resume

public void resume()
            throws LibvirtException

Resume this suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain(). This function may requires privileged access

Throws:

LibvirtException

revertToSnapshot

public int revertToSnapshot(DomainSnapshot snapshot)
                     throws LibvirtException

Revert the domain to a given snapshot.

Parameters:

snapshot - the snapshot to revert to

Returns:

0 if the creation is successful, -1 on error.

Throws:

LibvirtException

See Also:

Libvirt Documentation

save

public void save(java.lang.String to)
          throws LibvirtException

Suspends this domain and saves its memory contents to a file on disk. After the call, if successful, the domain is not listed as running anymore (this may be a problem). Use Connect.virDomainRestore() to restore a domain after saving.

Parameters:

to - path for the output file

Throws:

LibvirtException

setAutostart

public void setAutostart(boolean autostart)
                  throws LibvirtException

Configures the network to be automatically started when the host machine boots.

Parameters:

autostart -

Throws:

LibvirtException

setMaxMemory

public void setMaxMemory(long memory)
                  throws LibvirtException

* Dynamically change the maximum amount of physical memory allocated to a domain. This function requires priviledged access to the hypervisor.

Parameters:

memory - the amount memory in kilobytes

Throws:

LibvirtException

setMemory

public void setMemory(long memory)
               throws LibvirtException

Dynamically changes the target amount of physical memory allocated to this domain. This function may requires priviledged access to the hypervisor.

Parameters:

memory - in kilobytes

Throws:

LibvirtException

setSchedulerParameters

public void setSchedulerParameters(SchedParameter[] params)
                            throws LibvirtException

Changes the scheduler parameters

Parameters:

params - an array of SchedParameter objects to be changed

Throws:

LibvirtException

setVcpus

public void setVcpus(int nvcpus)
              throws LibvirtException

Dynamically changes the number of virtual CPUs used by this domain. Note that this call may fail if the underlying virtualization hypervisor does not support it or if growing the number is arbitrary limited. This function requires priviledged access to the hypervisor.

Parameters:

nvcpus - the new number of virtual CPUs for this domain

Throws:

LibvirtException

shutdown

public void shutdown()
              throws LibvirtException

Shuts down this domain, the domain object is still usable there after but the domain OS is being stopped. Note that the guest OS may ignore the request. TODO: should we add an option for reboot, knowing it may not be doable in the general case ?

Throws:

LibvirtException

snapshotCreateXML

public DomainSnapshot snapshotCreateXML(java.lang.String xmlDesc)
                                 throws LibvirtException

Creates a new snapshot of a domain based on the snapshot xml contained in xmlDesc.

Parameters:

xmlDesc - string containing an XML description of the domain

Returns:

the snapshot, or null on Error

Throws:

LibvirtException

See Also:

Libvirt Documentation

snapshotCurrent

public DomainSnapshot snapshotCurrent()
                               throws LibvirtException

Get the current snapshot for a domain, if any.

Returns:

the snapshot, or null on Error

Throws:

LibvirtException

See Also:

Libvirt Documentation

snapshotListNames

public java.lang.String[] snapshotListNames()
                                     throws LibvirtException

Collect the list of domain snapshots for the given domain.

Returns:

The list of names, or null if an error

Throws:

LibvirtException

See Also:

Libvirt Documentation

snapshotLookupByName

public DomainSnapshot snapshotLookupByName(java.lang.String name)
                                    throws LibvirtException

Retrieve a snapshot by name

Parameters:

name - the name

Returns:

The located snapshot, or null if an error

Throws:

LibvirtException

See Also:

Libvirt Documentation

snapshotNum

public int snapshotNum()
                throws LibvirtException

Provides the number of domain snapshots for this domain..

Throws:

LibvirtException

See Also:

Libvirt Documentation

suspend

public void suspend()
             throws LibvirtException

Suspends this active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated. Use Domain.resume() to reactivate the domain. This function requires priviledged access.

Throws:

LibvirtException

undefine

public void undefine()
              throws LibvirtException

undefines this domain but does not stop it if it is running

Throws:

LibvirtException

updateDeviceFlags

public int updateDeviceFlags(java.lang.String xml,
                             int flags)
                      throws LibvirtException

Change a virtual device on a domain

Parameters:

xml - the xml to update with

flags - controls the update

Returns:

0 in case of success, -1 in case of failure.

Throws:

LibvirtException

See Also:

Libvirt Documentation