Package org.libvirt

Class Domain

java.lang.Object
org.libvirt.Domain

public class Domain extends Object
A virtual machine defined within libvirt.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Libvirt
    The libvirt connection from the hypervisor
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Requests that the current background job be aborted at the soonest opportunity.
    void
    Creates a virtual device attachment to backend.
    void
    attachDeviceFlags(String xmlDesc, int flags)
    Creates a virtual device attachment to backend.
    This function returns block device (disk) stats for block devices attached to the domain.
    Returns block device (disk) stats for block devices attached to this domain.
    void
    coreDump(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 invalid input: '&' all physical CPUs of a domain.
    int
    Launches this defined domain.
    int
    create(int flags)
    Launches this defined domain with the provide flags.
    void
    Destroys this domain object.
    void
    Destroys a virtual device attachment to backend.
    void
    detachDeviceFlags(String xmlDesc, int flags)
    Destroys a virtual device attachment to backend.
    void
     
    int
    Frees this domain object.
    boolean
    Provides a boolean value indicating whether the network is configured to be automatically started when the host machine boots.
    Provides the connection object associated with a domain.
    int
    Gets the hypervisor ID number for the domain
    Extract information about a domain.
    Extract information about progress of a background job on a domain.
    long
    Retrieve the maximum amount of physical memory allocated to a domain.
    int
    Provides the maximum number of virtual CPUs supported for the guest VM.
    Gets the public name for this domain
    Gets the type of domain operation system.
    Gets the scheduler parameters.
    Gets the scheduler type.
    int[]
    Get the UUID for this domain.
    Gets the UUID for this domain as string.
    int[]
    Returns the cpumaps for this domain Only the lower 8 bits of each int in the array contain information.
    Extracts information about virtual CPUs of this domain
    getXMLDesc(int flags)
    Provides an XML description of the domain.
    int
    Determine if the domain has a snapshot
    int
    Determine if the domain has a managed save image
    Returns network interface stats for interfaces attached to this domain.
    int
    Determine if the domain is currently running
    int
    Determine if the domain has a persistent configuration which means it will still exist after shutting down
    int
    suspend a domain and save its memory contents to a file on disk.
    int
    Remove any managed save images from the domain
    memoryStats(int number)
    This function provides memory statistics for the domain.
    migrate(Connect dconn, long flags, String dname, 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(String uri, long flags, 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
    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 this suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain().
    int
    Revert the domain to a given snapshot.
    void
    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
    Changes the scheduler parameters
    void
    setVcpus(int nvcpus)
    Dynamically changes the number of virtual CPUs used by this domain.
    void
    Shuts down this domain, the domain object is still usable there after but the domain OS is being stopped.
    Creates a new snapshot of a domain based on the snapshot xml contained in xmlDesc.
    Get the current snapshot for a domain, if any.
    Collect the list of domain snapshots for the given domain.
    Retrieve a snapshot by name
    int
    Provides the number of domain snapshots for this domain..
    void
    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
    undefines this domain but does not stop it if it is running
    int
    updateDeviceFlags(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 Details

    • libvirt

      protected Libvirt libvirt
      The libvirt connection from the hypervisor
  • Method Details

    • 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:
    • attachDevice

      public void attachDevice(String xmlDesc) throws LibvirtException
      Creates a virtual device attachment to backend.
      Parameters:
      xmlDesc - XML description of one device
      Throws:
      LibvirtException
      See Also:
    • attachDeviceFlags

      public void attachDeviceFlags(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:
    • blockInfo

      public DomainBlockInfo blockInfo(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(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(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 invalid input: '&' 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(String xmlDesc) throws LibvirtException
      Destroys a virtual device attachment to backend.
      Parameters:
      xmlDesc - XML description of one device
      Throws:
      LibvirtException
      See Also:
    • detachDeviceFlags

      public void detachDeviceFlags(String xmlDesc, int flags) throws LibvirtException
      Destroys a virtual device attachment to backend.
      Parameters:
      xmlDesc - XML description of one device
      Throws:
      LibvirtException
      See Also:
    • finalize

      public void finalize() throws LibvirtException
      Overrides:
      finalize in class 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:
    • 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:
    • 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 String getName() throws LibvirtException
      Gets the public name for this domain
      Returns:
      the name
      Throws:
      LibvirtException
    • getOSType

      public 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 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:
    • getUUIDString

      public String getUUIDString() throws LibvirtException
      Gets the UUID for this domain as string.
      Returns:
      the UUID in canonical String format
      Throws:
      LibvirtException
      See Also:
    • 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 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:
    • 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:
      • invalid input: '<'
    • 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:
      • invalid input: '<'
    • interfaceStats

      public DomainInterfaceStats interfaceStats(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:
    • 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:
    • 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:
    • 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:
    • 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, String dname, 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:
    • migrateToURI

      public int migrateToURI(String uri, long flags, 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:
    • 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:
    • save

      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(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:
    • 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:
    • snapshotListNames

      public 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:
    • snapshotLookupByName

      public DomainSnapshot snapshotLookupByName(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:
    • snapshotNum

      public int snapshotNum() throws LibvirtException
      Provides the number of domain snapshots for this domain..
      Throws:
      LibvirtException
      See Also:
    • 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(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: