Package org.libvirt

Class Domain


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

      Fields 
      Modifier and Type Field Description
      protected Libvirt libvirt
      The libvirt connection from the hypervisor
    • 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 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 managedSaveRemove()
      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
      • 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
      • 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
      • 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
      • 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
      • 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
      • getSchedulerType

        public java.lang.String[] getSchedulerType()
                                            throws LibvirtException
        Gets the scheduler type.
        Returns:
        the type of the scheduler
        Throws:
        LibvirtException
      • 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
          • 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
          • 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:
            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
          • 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
          • 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
          • 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