Package org.libvirt
Class Domain
- java.lang.Object
-
- org.libvirt.Domain
-
public class Domain extends java.lang.Object
A virtual machine defined within libvirt.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 domainDomainInfo
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 domainjava.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 domainjava.lang.String
getXMLDesc(int flags)
Provides an XML description of the domain.int
hasCurrentSnapshot()
Determine if the domain has a snapshotint
hasManagedSaveImage()
Determine if the domain has a managed save imageDomainInterfaceStats
interfaceStats(java.lang.String path)
Returns network interface stats for interfaces attached to this domain.int
isActive()
Determine if the domain is currently runningint
isPersistent()
Determine if the domain has a persistent configuration which means it will still exist after shutting downint
managedSave()
suspend a domain and save its memory contents to a file on disk.int
managedSaveRemove()
Remove any managed save images from the domainMemoryStatistic[]
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 parametersvoid
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 nameint
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 runningint
updateDeviceFlags(java.lang.String xml, int flags)
Change a virtual device on a domain
-
-
-
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 deviceflags
- 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 theattribute 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 fileflags
- 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 classjava.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
-
managedSaveRemove
public int managedSaveRemove() throws LibvirtException
Remove any managed save images from the domain- Returns:
- 0 in case of success, and -1 in case of error
- 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
- flagsdname
- (optional) rename domain to this at destinationuri
- (optional) dest hostname/URI as seen from the source hostbandwidth
- 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 URIflags
- Controls the migratedname
- The name at the destnationbandwidth
- Specify the migration bandwidth- Returns:
- 0 if successful, -1 if not
- Throws:
LibvirtException
- See Also:
- 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 numbercpumap
- 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 withflags
- controls the update- Returns:
- 0 in case of success, -1 in case of failure.
- Throws:
LibvirtException
- See Also:
- Libvirt Documentation
-
-
-
-