Package org.libvirt

Class 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 addAgentLifecycleListener​(AgentLifecycleListener cb)
      Adds the specified listener to receive agent lifecycle events for this domain.
      void addBlockJobListener​(BlockJobListener cb)
      Adds a callback to receive notifications of Block Job events
      void addIOErrorListener​(IOErrorListener cb)
      Adds a callback to receive notifications of IOError domain events occurring on this domain.
      void addLifecycleListener​(LifecycleListener l)
      Adds the specified listener to receive lifecycle events for this domain.
      void addPMSuspendListener​(PMSuspendListener l)
      Adds the specified listener to receive PMSuspend events for this domain.
      void addPMWakeupListener​(PMWakeupListener l)
      Adds the specified listener to receive PMWakeup events for this domain.
      void addRebootListener​(RebootListener l)
      Adds the specified listener to receive reboot events for this domain.
      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.
      void blockCommit​(java.lang.String disk, java.lang.String base, java.lang.String top, long bandwidth, int flags)
      Commit changes that were made to temporary top-level files within a disk image backing file chain into a lower-level base file.
      void blockCopy​(java.lang.String diskPath, java.lang.String xmlDesc, TypedParameter[] params, int flags)
      This function migrates domain's live block device (disk) to another block device.
      DomainBlockInfo blockInfo​(java.lang.String path)
      This function returns block device (disk) stats for block devices attached to the domain.
      void blockJobAbort​(java.lang.String disk, int flags)
      Cancel the active block job on the given disk.
      void blockPeek​(java.lang.String disk, long offset, java.nio.ByteBuffer buffer)
      Read the contents of a domain's disk device.
      void blockResize​(java.lang.String disk, long size, int flags)
      Resize a block device of domain while the domain is running.
      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.
      boolean equals​(java.lang.Object obj)  
      protected void finalize()  
      int free()
      Frees this domain object.
      boolean getAutostart()
      Provides a boolean value indicating whether the domain is configured to be automatically started when the host machine boots.
      DomainBlockJobInfo getBlockJobInfo​(java.lang.String disk, int flags)
      Request block job information for the given disk.
      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 getMetadata​(int type, java.lang.String uri, int flags)
      Retrieves the appropriate domain element given by type.
      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.
      SecurityLabel getSecurityLabel()
      Get the security label of an active domain.
      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 hashCode()  
      int hasManagedSaveImage()
      Determine if the domain has a managed save image
      java.util.Collection<DomainInterface> interfaceAddresses​(int source, int flags)
      Retrieves a list of the network interfaces present in given domain along with their IP and MAC addresses.
      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
      boolean isUpdated()
      Returns true if, and only if, this domain has been updated.
      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
      void memoryPeek​(long start, java.nio.ByteBuffer buffer, MemoryAddressMode mode)
      Read the contents of a domain's memory.
      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).
      Domain migrate​(Connect dconn, long flags, java.lang.String dxml, 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).
      Domain migrate​(Connect dconn, TypedParameter[] params, long flags)
      Migrate the 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.
      int migrateToURI​(java.lang.String dconnuri, java.lang.String miguri, java.lang.String dxml, long flags, java.lang.String dname, long bandwidth)
      Migrate the domain object from its current host to the destination denoted by a given URI.
      void pinVcpu​(int vcpu, int[] cpumap)
      Dynamically changes the real CPUs which can be allocated to a virtual CPU.
      void PMsuspend​(SuspendTarget target)
      Enter the given power management suspension target level.
      void PMsuspendFor​(SuspendTarget target, long duration, java.util.concurrent.TimeUnit unit)
      Enter the given power management suspension target level for the given duration.
      void PMwakeup()
      Immediately wake up a guest using power management.
      java.lang.String qemuAgentCommand​(java.lang.String cmd, int timeout, int flags)
      Commands for Qemu Guest Agent helper daemon
      java.lang.String qemuMonitorCommand​(java.lang.String cmd, int flags)
      Qemu Monitor Command - it will only work with hypervisor connections to the QEMU driver.
      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 removeBlockJobListener​(BlockJobListener cb)
      Removes BlockJobListener from the event framework, so it no longer receives events
      void reset()
      Reset a domain immediately without any guest OS shutdown.
      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.
      java.lang.String screenshot​(Stream stream, int screen)  
      void sendKey​(KeycodeSet codeset, int holdtime, int... keys)
      Send key(s) to the guest.
      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 setMetadata​(int type, java.lang.String metadata, java.lang.String key, java.lang.String uri, int flags)
      Sets the appropriate domain element given by type to the value of metadata.
      void setSchedulerParameters​(SchedParameter[] params)
      Changes the scheduler parameters
      void setUserPassword​(java.lang.String user, java.lang.String password, int flags)
      Sets the user password to the value specified by password.
      void setVcpus​(int nvcpus)
      Dynamically changes the number of virtual CPUs used by this domain.
      void setVcpusFlags​(int nvcpus, int flags)
      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 snapshotCreateXML​(java.lang.String xmlDesc, int flags)
      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.
      java.lang.String[] snapshotListNames​(int flags)
      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
      void undefine​(int flags)
      Undefines this domain but does not stop if it 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, getClass, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • 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:
        ignore (always 0)
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • blockCopy

        public void blockCopy​(java.lang.String diskPath,
                      java.lang.String xmlDesc,
                      TypedParameter[] params,
                      int flags)
               throws LibvirtException
        This function migrates domain's live block device (disk) to another block device.
        Parameters:
        diskPath - Path to current disk
        xmlDesc - XML description of destination disk
        params - Hypervisor-specific tuning parameters
        flags - Bitwise OR'ed values of Domain.BlockCopyFlags
        Throws:
        LibvirtException
        See Also:
        virDomainBlockCopy

      • 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
        Throws:
        LibvirtException

      • blockPeek

        public void blockPeek​(java.lang.String disk,
                      long offset,
                      java.nio.ByteBuffer buffer)
               throws LibvirtException
        Read the contents of a domain's disk device.

        Typical uses for this are to determine if the domain has written a Master Boot Record (indicating that the domain has completed installation), or to try to work out the state of the domain's filesystems.

        (Note that in the local case you might try to open the block device or file directly, but that won't work in the remote case, nor if you don't have sufficient permission. Hence the need for this call).

        The disk parameter can either be an unambiguous source name of the block device (the <source file='...'/> sub-element, such as "/path/to/image"), or (since 0.9.5) the device target shorthand (the <target dev='...'/> sub-element, such as "xvda").

        Valid names can be found by calling getXMLDesc(int) and inspecting elements within //domain/devices/disk.

        This method always reads the number of bytes remaining in the buffer, that is, buffer.remaining() at the moment this method is invoked. Upon return the buffer's position will be equal to the limit, the limit itself will not have changed.

        Parameters:
        disk - the path to the block device, or device shorthand
        offset - the offset within block device
        buffer - the buffer receiving the data
        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 <target dev='...'> 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

      • blockResize

        public void blockResize​(java.lang.String disk,
                        long size,
                        int flags)
                 throws LibvirtException
        Resize a block device of domain while the domain is running.
        Parameters:
        disk - path to the block image, or shorthand (like vda)
        size - the new size of the block devices
        flags - bitwise OR'ed values of Domain.BlockResizeFlags
        Throws:
        LibvirtException

      • blockCommit

        public void blockCommit​(java.lang.String disk,
                        java.lang.String base,
                        java.lang.String top,
                        long bandwidth,
                        int flags)
                 throws LibvirtException
        Commit changes that were made to temporary top-level files within a disk image backing file chain into a lower-level base file.
        Parameters:
        disk - path to the block device, or device shorthand
        base - path to backing file to merge into, or device shorthand, or NULL for default
        top - path to file within backing chain that contains data to be merged, or device shorthand, or NULL to merge all possible data
        bandwidth - (optional) specify bandwidth limit; flags determine the unit
        flags - bitwise-OR of Domain.BlockCommitFlags
        Throws:
        LibvirtException
        See Also:
        virDomainBlockCommit

      • 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.
        Returns:
        ignore (always 0)
        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.
        Returns:
        ignore (always 0)
        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)
        Throws:
        LibvirtException

      • getAutostart

        public boolean getAutostart()
                     throws LibvirtException
        Provides a boolean value indicating whether the domain 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

      • getMetadata

        public java.lang.String getMetadata​(int type,
                                    java.lang.String uri,
                                    int flags)
                             throws LibvirtException
        Retrieves the appropriate domain element given by type.
        Parameters:
        type - type of metadata, see Domain.MetadataType
        uri - XML namespace identifier if type == MetadataType.ELEMENT, null otherwise
        flags - bitwise-OR of Domain.ModificationImpact
        Returns:
        the metadata string
        Throws:
        LibvirtException

      • getName

        public java.lang.String getName()
                         throws LibvirtException
        Gets the public name for this domain
        Returns:
        the name, null if there is no name
        Throws:
        LibvirtException - never

      • getSchedulerType

        public java.lang.String getSchedulerType()
                                  throws LibvirtException
        Gets the scheduler type.
        Returns:
        the type of the scheduler
        Throws:
        LibvirtException

      • getSecurityLabel

        public SecurityLabel getSecurityLabel()
                               throws LibvirtException
        Get the security label of an active domain.
        Returns:
        the SecurityLabel or null if the domain is not running under a security model
        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

      • 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:
        Libvirt Documentation

      • interfaceAddresses

        public java.util.Collection<DomainInterface> interfaceAddresses​(int source,
                                                                int flags)
                                                         throws LibvirtException
        Retrieves a list of the network interfaces present in given domain along with their IP and MAC addresses. Note that single interface can have multiple or even 0 IP addresses. If source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE, the DHCP lease file associated with any virtual networks will be examined to obtain the interface addresses. This only returns data for interfaces which are connected to virtual networks managed by libvirt. If source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT, a configured guest agent is needed for successful return from this API. Moreover, if guest agent is used then the interface name is the one seen by guest OS. To match such interface with the one from dom XML use MAC address or IP range. If source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP, the host ARP table will be check to obtain the interface addresses. As the arp cache refreshes in time, the returned ip address may be unreachable. Depending on the route table config of the guest, the returned mac address may be duplicated. Note that for some source values some pieces of returned ifaces might be unset (e.g. VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP does not set IP address prefix as ARP table does not have any notion of that). name and hwaddr of the returned interfaces are never NULL.
        Parameters:
        source - one of the Domain.InterfaceAddressesSource constants
        flags - currently unused, pass zero
        Returns:
        the interfaces of this domain
        Throws:
        LibvirtException - if something goes wrong

      • 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
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • memoryPeek

        public void memoryPeek​(long start,
                       java.nio.ByteBuffer buffer,
                       MemoryAddressMode mode)
                throws LibvirtException
        Read the contents of a domain's memory.

        If mode is MemoryAddressMode.VIRTUAL the 'start' parameter is interpreted as virtual memory address for whichever task happens to be running on the domain at the moment. Although this sounds haphazard it is in fact what you want in order to read Linux kernel state, because it ensures that pointers in the kernel image can be interpreted coherently.

        This method always reads the number of bytes remaining in the buffer, that is, buffer.remaining() at the moment this method is invoked. Upon return the buffer's position will be equal to the limit, the limit itself will not have changed.

        Parameters:
        start - the start address of the memory to peek
        mode - the mode which determines whether the given addresses are interpreted as virtual or physical addresses
        Throws:
        LibvirtException

      • 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
        Throws:
        LibvirtException

      • migrate

        public Domain migrate​(Connect dconn,
                      long flags,
                      java.lang.String dxml,
                      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 bitwise OR'ed values of MigrateFlags.

        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 exception.

        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.

        The maximum bandwidth (in Mbps) that will be used to do migration can be specified with the bandwidth parameter. 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.

        If the hypervisor supports it, dxml can be used to alter host-specific portions of the domain XML that will be used on the destination.

        Parameters:
        dconn - destination host (a Connect object)
        dxml - (optional) XML config for launching guest on target
        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. Note that the new domain object exists in the scope of the destination connection (dconn).
        Throws:
        LibvirtException - if the migration fails

      • 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.MigrateFlags.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. Note that the new domain object exists in the scope of the destination connection (dconn).
        Throws:
        LibvirtException

      • migrate

        public Domain migrate​(Connect dconn,
                      TypedParameter[] params,
                      long flags)
               throws LibvirtException
        Migrate the domain object from its current host to the destination host given by dconn (a connection to the destination host). See VIR_MIGRATE_PARAM_* and virDomainMigrateFlags for detailed description of accepted migration parameters and flags. See virDomainMigrateFlags documentation for description of individual flags. VIR_MIGRATE_TUNNELLED and VIR_MIGRATE_PEER2PEER are not supported by this API, use virDomainMigrateToURI3 instead.
        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. virDomainFree should be used to free the resources after the returned domain object is no longer needed.

        For more informations, please @see virDomainMigrate3
        Parameters:
        dconn - destination host (a Connect object)
        params - (optional) migration parameters
        flags - bitwise-OR of virDomainMigrateFlags
        Returns:
        the new domain object if the migration was successful. 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:
        always 0
        Throws:
        LibvirtException
        See Also:
        LIbvirt Documentation

      • migrateToURI

        public int migrateToURI​(java.lang.String dconnuri,
                        java.lang.String miguri,
                        java.lang.String dxml,
                        long flags,
                        java.lang.String dname,
                        long bandwidth)
                 throws LibvirtException
        Migrate the domain object from its current host to the destination denoted by a given URI.

        The destination is given either in dconnuri (if the PEER2PEER is flag set), or in miguri (if neither the PEER2PEER nor the TUNNELED migration flag is set in flags).

        Parameters:
        dconnuri - (optional) URI for target libvirtd if @flags includes PEER2PEER
        miguri - (optional) URI for invoking the migration, not if @flags includs TUNNELED
        dxml - (optional) XML config for launching guest on target
        flags - Controls the migrate
        dname - The name at the destnation
        bandwidth - Specify the migration bandwidth
        Returns:
        0 if successful
        Throws:
        LibvirtException
        See Also:
        virDomainMigrateToURI

      • 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

      • PMsuspendFor

        public void PMsuspendFor​(SuspendTarget target,
                         long duration,
                         java.util.concurrent.TimeUnit unit)
                  throws LibvirtException
        Enter the given power management suspension target level for the given duration.
        Throws:
        LibvirtException

      • 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

      • 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, see Domain.RebootFlags
        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

      • removeBlockJobListener

        public void removeBlockJobListener​(BlockJobListener cb)
                            throws LibvirtException
        Removes BlockJobListener from the event framework, so it no longer receives events
        Parameters:
        cb - The BlockJobListener
        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

      • setMetadata

        public void setMetadata​(int type,
                        java.lang.String metadata,
                        java.lang.String key,
                        java.lang.String uri,
                        int flags)
                 throws LibvirtException
        Sets the appropriate domain element given by type to the value of metadata. A type of MetadataType.DESCRIPTION is free-form text; MetadataType.TITLE is free-form, but no newlines are permitted, and should be short (although the length is not enforced). For these two options key and uri are irrelevant and must be set to null. For type MetadataType.ELEMENT metadata must be well-formed XML belonging to namespace defined by uri with local name key. Passing null for metadata says to remove that element from the domain XML (passing the empty string leaves the element present).
        Parameters:
        type - see Domain.MetadataType
        metadata - the new metadata content
        key - XML namespace prefix for type MetadataType.ELEMENT, null otherwise
        uri - XML namespace URI for typeMetadataType.ELEMENT, null otherwise
        flags - see Domain.ModificationImpact
        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

      • setUserPassword

        public void setUserPassword​(java.lang.String user,
                            java.lang.String password,
                            int flags)
                     throws LibvirtException
        Sets the user password to the value specified by password. If flags contain DomainSetUserPasswordFlags.DOMAIN_PASSWORD_ENCRYPTED, the password is assumed to be encrypted by the method required by the guest OS.
        Parameters:
        user - the username that will get a new password
        password - the password to set
        flags - see Domain.DomainSetUserPasswordFlags
        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 privileged access to the hypervisor.
        Parameters:
        nvcpus - the new number of virtual CPUs for this domain
        Throws:
        LibvirtException

      • setVcpusFlags

        public void setVcpusFlags​(int nvcpus,
                          int flags)
                   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 privileged access to the hypervisor.
        Parameters:
        nvcpus - the new number of virtual CPUs for this domain
        flags - Domain.VcpuFlags
        Throws:
        LibvirtException

      • sendKey

        public void sendKey​(KeycodeSet codeset,
                    int holdtime,
                    int... keys)
             throws LibvirtException
        Send key(s) to the guest.
        Parameters:
        codeset - the set of keycodes
        holdtime - the duration that the keys will be held (in milliseconds)
        keys - the key codes to be send
        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.

        This is just a convenience method, it has the same effect as calling snapshotCreateXML(xmlDesc, 0);.

        Parameters:
        xmlDesc - string containing an XML description of the domain
        Returns:
        the snapshot, or null on Error
        Throws:
        LibvirtException
        See Also:
        snapshotCreateXML(String, int), 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​(int flags)
              throws LibvirtException
        Undefines this domain but does not stop if it it is running. With option for passing flags
        Parameters:
        flags - flags for undefining the domain. See virDomainUndefineFlagsValues for more information
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • 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:
        always 0
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • qemuAgentCommand

        public java.lang.String qemuAgentCommand​(java.lang.String cmd,
                                         int timeout,
                                         int flags)
                                  throws LibvirtException
        Commands for Qemu Guest Agent helper daemon
        Parameters:
        cmd - the guest agent command string
        timeout - timeout seconds
        flags - execution flags
        Returns:
        result strings if success, NULL in failure.
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • qemuMonitorCommand

        public java.lang.String qemuMonitorCommand​(java.lang.String cmd,
                                           int flags)
                                    throws LibvirtException
        Qemu Monitor Command - it will only work with hypervisor connections to the QEMU driver.
        Parameters:
        cmd - the qemu monitor command string
        flags - bitwise-or of supported virDomainQemuMonitorCommandFlags
        Returns:
        result a string returned by @cmd
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation