Package org.libvirt

Class Connect

  • public class Connect
extends java.lang.Object
    The Connect object represents a connection to a local or remote hypervisor/driver.
    Author:
    stoty

    • Method Detail

      • connectionVersion

        @Deprecated
public static long connectionVersion​(Connect conn)
        Deprecated.
        Use getLibVersion() instead.
        Get the version of a connection.
        Parameters:
        conn - the connection to use.
        Returns:
        -1 in case of failure, versions have the format major * 1,000,000 + minor * 1,000 + release.
        See Also:
        Libvirt Documentation

      • convertUUIDBytes

        public static int[] convertUUIDBytes​(byte[] bytes)
        Helper function to convert bytes into ints for the UUID calls

      • createUUIDBytes

        public static byte[] createUUIDBytes​(int[] uuid)
        Helper function to convert UUIDs into a stirng for the uuid calls

      • getLibVersion

        public long getLibVersion()
                   throws LibvirtException
        Get the libvirt library version of this connection.
        Returns:
        The version of libvirt used by the daemon running on the connected host in the format major * 1,000,000 + minor * 1,000 + release.
        Throws:
        LibvirtException
        See Also:
        Libvirt Documentation

      • 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

      • baselineCPU

        public java.lang.String baselineCPU​(java.lang.String[] xmlCPUs)
                             throws LibvirtException
        Computes the most feature-rich CPU which is compatible with all given host CPUs.
        Parameters:
        xmlCPUs - array of XML descriptions of host CPUs
        Returns:
        XML description of the computed CPU or NULL on error.
        Throws:
        LibvirtException

      • close

        public int close()
          throws LibvirtException
        Closes the connection to the hypervisor/driver. Calling any methods on the object after close() will result in an exception.
        Returns:
        number of remaining references (>= 0)
        Throws:
        LibvirtException

      • registerCloseListener

        public void registerCloseListener​(ConnectionCloseListener l)
                           throws LibvirtException
        Register the specified connection close listener to receive notifications when this connection is closed.

        Note: There can only be at most one registered listener at a time.

        Parameters:
        l - the connection close listener
        Throws:
        LibvirtException - on failure
        See Also:
        unregisterCloseListener()

      • deviceCreateXML

        public Device deviceCreateXML​(java.lang.String xmlDesc)
                       throws LibvirtException
        Create a new device on the VM host machine, for example, virtual HBAs created using vport_create.
        Parameters:
        xmlDesc - the device to create
        Returns:
        the Device object
        Throws:
        LibvirtException

      • deviceLookupByName

        public Device deviceLookupByName​(java.lang.String name)
                          throws LibvirtException
        Fetch a device based on its unique name
        Parameters:
        name - name of device to fetch
        Returns:
        Device object
        Throws:
        LibvirtException

      • domainCreateLinux

        public Domain domainCreateLinux​(java.lang.String xmlDesc,
                                int flags)
                         throws LibvirtException
        Launches a new Linux guest domain. The domain is based on an XML description similar to the one returned by virDomainGetXMLDesc(). This function may require priviledged access to the hypervisor.
        Parameters:
        xmlDesc - the Domain description in XML
        flags - an optional set of flags (unused)
        Returns:
        the Domain object
        Throws:
        LibvirtException
        See Also:
        The XML format description

      • domainLookupByID

        public Domain domainLookupByID​(int id)
                        throws LibvirtException
        Finds a domain based on the hypervisor ID number.
        Parameters:
        id - the hypervisor id
        Returns:
        the Domain object
        Throws:
        LibvirtException

      • domainLookupByName

        public Domain domainLookupByName​(java.lang.String name)
                          throws LibvirtException
        Looks up a domain based on its name.
        Parameters:
        name - the name of the domain
        Returns:
        the Domain object
        Throws:
        LibvirtException

      • domainLookupByUUID

        public Domain domainLookupByUUID​(int[] uuid)
                          throws LibvirtException
        Looks up a domain based on its UUID in array form. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.
        Parameters:
        uuid - the uuid as an unpacked int array
        Returns:
        the Domain object
        Throws:
        LibvirtException

      • domainLookupByUUID

        public Domain domainLookupByUUID​(java.util.UUID uuid)
                          throws LibvirtException
        Fetch a domain based on its globally unique id
        Parameters:
        uuid - a java UUID
        Returns:
        a new domain object
        Throws:
        LibvirtException

      • domainLookupByUUIDString

        public Domain domainLookupByUUIDString​(java.lang.String uuid)
                                throws LibvirtException
        Looks up a domain based on its uuid in String form.
        Parameters:
        uuid - the uuid in canonical String representation
        Returns:
        the Domain object
        Throws:
        LibvirtException

      • domainXMLFromNative

        public java.lang.String domainXMLFromNative​(java.lang.String nativeFormat,
                                            java.lang.String nativeConfig,
                                            int flags)
                                     throws LibvirtException
        Reads a native XML configuration document, and generates generates a domain configuration file describing the domain. The format of the native data is hypervisor dependant.
        Returns:
        domain XML as String, or null on error
        Throws:
        LibvirtException

      • domainXMLToNative

        public java.lang.String domainXMLToNative​(java.lang.String nativeFormat,
                                          java.lang.String domainXML,
                                          int flags)
                                   throws LibvirtException
        Reads a domain XML configuration document, and generates generates a native configuration file describing the domain. The format of the native data is hypervisor dependant.
        Returns:
        domain XML as String, or null on error
        Throws:
        LibvirtException

      • findStoragePoolSources

        public java.lang.String findStoragePoolSources​(java.lang.String type,
                                               java.lang.String srcSpecs,
                                               int flags)
                                        throws LibvirtException
        Talks to a storage backend and attempts to auto-discover the set of available storage pool sources. e.g. For iSCSI this would be a set of iSCSI targets. For NFS this would be a list of exported paths. The srcSpec (optional for some storage pool types, e.g. local ones) is an instance of the storage pool's source element specifying where to look for the pools. srcSpec is not required for some types (e.g., those querying local storage resources only)
        Parameters:
        type - type of storage pool to discover
        srcSpecs - XML document specifying discovery sourc
        flags - unused
        Returns:
        an xml document consisting of a SourceList element containing a source document appropriate to the given pool type for each discovered source.
        Throws:
        LibvirtException

      • getHostName

        public java.lang.String getHostName()
                             throws LibvirtException
        Returns the system hostname on which the hypervisor is running. (the result of the gethostname(2) system call) If we are connected to a remote system, then this returns the hostname of the remote system.
        Returns:
        the hostname
        Throws:
        LibvirtException

      • getHypervisorVersion

        @Deprecated
public long getHypervisorVersion​(java.lang.String type)
                          throws LibvirtException
        Deprecated.
        To get the version of the running hypervisor use getVersion() instead.
        Returns the version of the hypervisor against which the library was compiled. Since libvirt 0.9.3 this simply returns the same version number as Library.getVersion().
        Parameters:
        type - The type of connection/driver to look at. See getType(). May be null.
        Returns:
        major * 1,000,000 + minor * 1,000 + release
        Throws:
        LibvirtException

      • getLibVirVersion

        @Deprecated
public long getLibVirVersion()
                      throws LibvirtException
        Deprecated.
        use Library.getVersion() instead
        Gets the version of the native libvirt library that the JNI part is linked to.
        Returns:
        major * 1,000,000 + minor * 1,000 + release
        Throws:
        LibvirtException

      • getMaxVcpus

        public int getMaxVcpus​(java.lang.String type)
                throws LibvirtException
        Provides the maximum number of virtual CPUs supported for a guest VM of a specific type. The 'type' parameter here corresponds to the 'type' attribute in the <domain> element of the XML.
        Parameters:
        type -
        Returns:
        the number of CPUs
        Throws:
        LibvirtException

      • getSysinfo

        public java.lang.String getSysinfo()
                            throws LibvirtException
        Returns the XML description of the sysinfo details for the host on which the hypervisor is running.

        This information is generally available only for hypervisors running with root privileges.

        Returns:
        sysinfo details in the same format as the <sysinfo> element of a domain XML.
        Throws:
        LibvirtException
        Since:
        1.5.2

      • getURI

        public java.lang.String getURI()
                        throws LibvirtException
        Returns the URI (name) of the hypervisor connection. Normally this is the same as or similar to the string passed to the virConnectOpen/virConnectOpenReadOnly call, but the driver may make the URI canonical.
        Returns:
        the URI
        Throws:
        LibvirtException

      • getVersion

        public long getVersion()
                throws LibvirtException
        Gets the version level of the Hypervisor running. This may work only with hypervisor call, i.e. with priviledged access to the hypervisor, not with a Read-Only connection. If the version can't be extracted by lack of capacities returns 0.
        Returns:
        major * 1,000,000 + minor * 1,000 + release
        Throws:
        LibvirtException

      • interfaceDefineXML

        public Interface interfaceDefineXML​(java.lang.String xmlDesc)
                             throws LibvirtException
        Define an interface (or modify existing interface configuration)
        Parameters:
        xmlDesc - the interface to create
        Returns:
        the Interface object
        Throws:
        LibvirtException

      • interfaceLookupByMACString

        public Interface interfaceLookupByMACString​(java.lang.String mac)
                                     throws LibvirtException
        Try to lookup an interface on the given hypervisor based on its MAC.
        Throws:
        LibvirtException

      • interfaceLookupByName

        public Interface interfaceLookupByName​(java.lang.String name)
                                throws LibvirtException
        Try to lookup an interface on the given hypervisor based on its name.
        Throws:
        LibvirtException

      • listDefinedDomains

        public java.lang.String[] listDefinedDomains()
                                      throws LibvirtException
        Lists the names of the defined but inactive domains
        Returns:
        an Array of Strings that contains the names of the defined domains currently inactive
        Throws:
        LibvirtException

      • listDefinedInterfaces

        public java.lang.String[] listDefinedInterfaces()
                                         throws LibvirtException
        Provides the list of names of defined interfaces on this host
        Returns:
        an Array of Strings that contains the names of the interfaces on this host
        Throws:
        LibvirtException

      • listDefinedNetworks

        public java.lang.String[] listDefinedNetworks()
                                       throws LibvirtException
        Lists the inactive networks
        Returns:
        an Array of Strings that contains the names of the inactive networks
        Throws:
        LibvirtException

      • listDefinedStoragePools

        public java.lang.String[] listDefinedStoragePools()
                                           throws LibvirtException
        Provides the list of names of inactive storage pools.
        Returns:
        an Array of Strings that contains the names of the defined storage pools
        Throws:
        LibvirtException

      • listDevices

        public java.lang.String[] listDevices​(java.lang.String capabilityName)
                               throws LibvirtException
        List the names of the devices on this node
        Parameters:
        capabilityName - optional capability name
        Throws:
        LibvirtException

      • listDomains

        public int[] listDomains()
                  throws LibvirtException
        Lists the active domains.
        Returns:
        and array of the IDs of the active domains
        Throws:
        LibvirtException

      • listInterfaces

        public java.lang.String[] listInterfaces()
                                  throws LibvirtException
        Provides the list of names of interfaces on this host
        Returns:
        an Array of Strings that contains the names of the interfaces on this host
        Throws:
        LibvirtException

      • listNetworkFilters

        public java.lang.String[] listNetworkFilters()
                                      throws LibvirtException
        Lists the names of the network filters
        Returns:
        an Array of Strings that contains the names network filters
        Throws:
        LibvirtException

      • listNetworks

        public java.lang.String[] listNetworks()
                                throws LibvirtException
        Lists the active networks.
        Returns:
        an Array of Strings that contains the names of the active networks
        Throws:
        LibvirtException

      • listSecrets

        public java.lang.String[] listSecrets()
                               throws LibvirtException
        Retrieve the List UUIDs of defined secrets
        Returns:
        an Array of Strings that contains the uuids of the defined secrets
        Throws:
        LibvirtException

      • listStoragePools

        public java.lang.String[] listStoragePools()
                                    throws LibvirtException
        Provides the list of names of active storage pools.
        Returns:
        an Array of Strings that contains the names of the defined storage pools
        Throws:
        LibvirtException

      • networkCreateXML

        public Network networkCreateXML​(java.lang.String xmlDesc)
                         throws LibvirtException
        Creates and starts a new virtual network. The properties of the network are based on an XML description similar to the one returned by virNetworkGetXMLDesc()
        Parameters:
        xmlDesc - the Network Description
        Returns:
        the Network object representing the created network
        Throws:
        LibvirtException
        See Also:
        The XML format description

      • networkDefineXML

        public Network networkDefineXML​(java.lang.String xmlDesc)
                         throws LibvirtException
        Defines a network, but does not create it. The properties of the network are based on an XML description similar to the one returned by virNetworkGetXMLDesc()
        Parameters:
        xmlDesc -
        Returns:
        the resulting Network object
        Throws:
        LibvirtException
        See Also:
        The XML format description

      • networkFilterLookupByUUID

        public NetworkFilter networkFilterLookupByUUID​(int[] uuid)
                                        throws LibvirtException
        Looks up a network filter based on its UUID in array form. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.
        Parameters:
        uuid - the uuid as an unpacked int array
        Returns:
        the network filter object
        Throws:
        LibvirtException

      • networkFilterLookupByUUID

        public NetworkFilter networkFilterLookupByUUID​(java.util.UUID uuid)
                                        throws LibvirtException
        Fetch a network filter based on its globally unique id
        Parameters:
        uuid - a java UUID
        Returns:
        a new network filter object
        Throws:
        LibvirtException

      • networkFilterLookupByUUIDString

        public NetworkFilter networkFilterLookupByUUIDString​(java.lang.String uuid)
                                              throws LibvirtException
        Looks up a network filter based on its uuid in String form.
        Parameters:
        uuid - the uuid in canonical String representation
        Returns:
        the Network Filter object
        Throws:
        LibvirtException

      • networkLookupByName

        public Network networkLookupByName​(java.lang.String name)
                            throws LibvirtException
        Looks up a network on the based on its name.
        Parameters:
        name - name of the network
        Returns:
        The Network object found
        Throws:
        LibvirtException

      • networkLookupByUUID

        @Deprecated
public Network networkLookupByUUID​(int[] uuid)
                            throws LibvirtException
        Deprecated.
        use the UUIDString or UUID API.
        Looks up a network based on its UUID represented as an int array. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.
        Parameters:
        uuid - the uuid as an unpacked int array
        Returns:
        The Network object found
        Throws:
        LibvirtException

      • networkLookupByUUID

        public Network networkLookupByUUID​(java.util.UUID uuid)
                            throws LibvirtException
        Fetch a network based on its globally unique id
        Parameters:
        uuid - a java UUID
        Returns:
        a new network object
        Throws:
        LibvirtException

      • networkLookupByUUIDString

        public Network networkLookupByUUIDString​(java.lang.String uuid)
                                  throws LibvirtException
        Looks up a network based on its uuid represented as a String.
        Parameters:
        uuid - the uuid in canonical String representation
        Returns:
        The Network object found
        Throws:
        LibvirtException

      • numOfDefinedDomains

        public int numOfDefinedDomains()
                        throws LibvirtException
        Provides the number of inactive domains.
        Returns:
        the number of inactive domains
        Throws:
        LibvirtException

      • numOfDefinedInterfaces

        public int numOfDefinedInterfaces()
                           throws LibvirtException
        Provides the number of defined interfaces.
        Returns:
        the number of interfaces
        Throws:
        LibvirtException

      • numOfDefinedNetworks

        public int numOfDefinedNetworks()
                         throws LibvirtException
        Provides the number of inactive networks.
        Returns:
        the number of inactive networks
        Throws:
        LibvirtException

      • numOfDefinedStoragePools

        public int numOfDefinedStoragePools()
                             throws LibvirtException
        Provides the number of inactive storage pools
        Returns:
        the number of pools found
        Throws:
        LibvirtException

      • numOfDevices

        public int numOfDevices​(java.lang.String capabilityName)
                 throws LibvirtException
        Provides the number of node devices.
        Returns:
        the number of inactive domains
        Throws:
        LibvirtException

      • numOfDomains

        public int numOfDomains()
                 throws LibvirtException
        Provides the number of active domains.
        Returns:
        the number of active domains
        Throws:
        LibvirtException

      • numOfInterfaces

        public int numOfInterfaces()
                    throws LibvirtException
        Provides the number of interfaces.
        Returns:
        the number of interfaces
        Throws:
        LibvirtException

      • numOfNetworkFilters

        public int numOfNetworkFilters()
                        throws LibvirtException
        Provides the number of network filters
        Returns:
        the number of network filters
        Throws:
        LibvirtException

      • numOfNetworks

        public int numOfNetworks()
                  throws LibvirtException
        Provides the number of active networks.
        Returns:
        the number of active networks
        Throws:
        LibvirtException

      • numOfSecrets

        public int numOfSecrets()
                 throws LibvirtException
        Fetch number of currently defined secrets.
        Returns:
        the number of secrets
        Throws:
        LibvirtException

      • numOfStoragePools

        public int numOfStoragePools()
                      throws LibvirtException
        Provides the number of active storage pools
        Returns:
        the number of pools found
        Throws:
        LibvirtException

      • restore

        public void restore​(java.lang.String from)
             throws LibvirtException
        Restores a domain saved to disk by Domain.save().
        Parameters:
        from - the path of the saved file on the remote host
        Throws:
        LibvirtException

      • secretDefineXML

        public Secret secretDefineXML​(java.lang.String xmlDesc)
                       throws LibvirtException
        If XML specifies a UUID, locates the specified secret and replaces all attributes of the secret specified by UUID by attributes specified in xml (any attributes not specified in xml are discarded). Otherwise, creates a new secret with an automatically chosen UUID, and initializes its attributes from xml.
        Parameters:
        xmlDesc - the secret to create
        Returns:
        the Secret object
        Throws:
        LibvirtException

      • secretLookupByUUID

        public Secret secretLookupByUUID​(int[] uuid)
                          throws LibvirtException
        Looks up a secret based on its UUID in array form. The UUID Array contains an unpacked representation of the UUID, each int contains only one byte.
        Parameters:
        uuid - the uuid as an unpacked int array
        Returns:
        the Secret object
        Throws:
        LibvirtException

      • secretLookupByUUID

        public Secret secretLookupByUUID​(java.util.UUID uuid)
                          throws LibvirtException
        Fetch a secret based on its globally unique id
        Parameters:
        uuid - a java UUID
        Returns:
        a new domain object
        Throws:
        LibvirtException

      • secretLookupByUUIDString

        public Secret secretLookupByUUIDString​(java.lang.String uuid)
                                throws LibvirtException
        Looks up a secret based on its uuid in String form.
        Parameters:
        uuid - the uuid in canonical String representation
        Returns:
        the Domain object
        Throws:
        LibvirtException

      • setDom0Memory

        public void setDom0Memory​(long memory)
                   throws LibvirtException
        change the amount of memory reserved to Domain0. Domain0 is the domain where the application runs. This function may requires priviledged access to the hypervisor.
        Parameters:
        memory - in kilobytes
        Throws:
        LibvirtException

      • storagePoolCreateXML

        public StoragePool storagePoolCreateXML​(java.lang.String xmlDesc,
                                        int flags)
                                 throws LibvirtException
        Create a new storage based on its XML description. The pool is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted
        Parameters:
        xmlDesc - XML description for new pool
        flags - future flags, use 0 for now
        Returns:
        StoragePool object
        Throws:
        LibvirtException

      • storagePoolDefineXML

        public StoragePool storagePoolDefineXML​(java.lang.String xml,
                                        int flags)
                                 throws LibvirtException
        Define a new inactive storage pool based on its XML description. The pool is persistent, until explicitly undefined.
        Parameters:
        xml - XML description for new pool
        flags - flags future flags, use 0 for now
        Returns:
        StoragePool object
        Throws:
        LibvirtException

      • storagePoolLookupByName

        public StoragePool storagePoolLookupByName​(java.lang.String name)
                                    throws LibvirtException
        Fetch a storage pool based on its unique name
        Parameters:
        name - name of pool to fetch
        Returns:
        StoragePool object
        Throws:
        LibvirtException

      • storagePoolLookupByUUID

        @Deprecated
public StoragePool storagePoolLookupByUUID​(int[] uuid)
                                    throws LibvirtException
        Deprecated.
        Use the UUIDString or UUID APIs.
        Fetch a storage pool based on its globally unique id
        Parameters:
        uuid - globally unique id of pool to fetch
        Returns:
        a new network object
        Throws:
        LibvirtException

      • storagePoolLookupByUUID

        public StoragePool storagePoolLookupByUUID​(java.util.UUID uuid)
                                    throws LibvirtException
        Fetch a storage pool based on its globally unique id
        Parameters:
        uuid - a java UUID
        Returns:
        a new network object
        Throws:
        LibvirtException

      • storagePoolLookupByUUIDString

        public StoragePool storagePoolLookupByUUIDString​(java.lang.String uuid)
                                          throws LibvirtException
        Fetch a storage pool based on its globally unique id
        Parameters:
        uuid - globally unique id of pool to fetch
        Returns:
        VirStoragePool object
        Throws:
        LibvirtException

      • storageVolLookupByKey

        public StorageVol storageVolLookupByKey​(java.lang.String key)
                                 throws LibvirtException
        Fetch a a storage volume based on its globally unique key
        Parameters:
        key - globally unique key
        Returns:
        a storage volume
        Throws:
        LibvirtException

      • storageVolLookupByPath

        public StorageVol storageVolLookupByPath​(java.lang.String path)
                                  throws LibvirtException
        Fetch a storage volume based on its locally (host) unique path
        Parameters:
        path - locally unique path
        Returns:
        a storage volume
        Throws:
        LibvirtException

      • streamNew

        public Stream streamNew​(int flags)
                 throws LibvirtException
        Creates a new stream object which can be used to perform streamed I/O with other public API function.
        Parameters:
        flags - use Stream.VIR_STREAM_NONBLOCK if non-blocking is required
        Returns:
        the new object
        Throws:
        LibvirtException

      • isConnected

        public boolean isConnected()
                    throws LibvirtException
        Verify the connect is active.
        Returns:
        boolean The true connected, or false not.
        Throws:
        LibvirtException

      • isAlive

        public boolean isAlive()
                throws LibvirtException
        Determine if the connection to the hypervisor is still alive.

        A connection will be classed as alive if it is either local, or running over a channel (TCP or UNIX socket) which is not closed.

        Returns:
        true if alive, false otherwise.
        Throws:
        LibvirtException

      • setKeepAlive

        public boolean setKeepAlive​(int interval,
                            int count)
                     throws LibvirtException
        Start sending keepalive messages. After interval seconds of inactivity, consider the connection to be broken when no response is received after count keepalive messages sent in a row.

        In other words, sending count + 1 keepalive message results in closing the connection.

        When interval is <= 0, no keepalive messages will be sent.

        When count is 0, the connection will be automatically closed after interval seconds of inactivity without sending any keepalive messages.

        Note: client has to implement and run event loop to be able to use keepalive messages. Failure to do so may result in connections being closed unexpectedly.

        Note: This API function controls only keepalive messages sent by the client. If the server is configured to use keepalive you still need to run the event loop to respond to them, even if you disable keepalives by this function.

        Parameters:
        interval - number of seconds of inactivity before a keepalive message is sent
        count - number of messages that can be sent in a row
        Returns:
        true when successful, false otherwise.
        Throws:
        LibvirtException