Package org.libvirt

Class Connect

java.lang.Object
org.libvirt.Connect

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

  • Constructor Details

  • Method Details

    • connectionForDomain

      public static Connect connectionForDomain(Domain domain)
      Creates a new connection object from the domain. If all you want is the existing domain's connection, use the getConnection method directly. Thie method returns a new connection.
      Parameters:
      domain -
      Returns:
      a new connection
    • connectionForNetwork

      public static Connect connectionForNetwork(Network network)
      Creates a new connection object from the network. If all you want is the existing network's connection, use the getConnection method directly. Thie method returns a new connection.
      Parameters:
      network -
      Returns:
      a new connection
    • connectionForSecret

      public static Connect connectionForSecret(Secret secret)
      Creates a new connection object from the network. If all you want is the existing network's connection, use the getConnection method directly. Thie method returns a new connection.
      Parameters:
      secret -
      Returns:
      a new connection
    • connectionVersion

      public static long connectionVersion(Connect conn)
      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:
    • 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
    • setErrorCallback

      public static void setErrorCallback(Libvirt.VirErrorCallback callback) throws LibvirtException
      Sets the error function to a user defined callback
      Parameters:
      callback - a Class to perform the callback
      Throws:
      LibvirtException
    • baselineCPU

      public String baselineCPU(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 references left (>= 0) for success, -1 for failure.
      Throws:
      LibvirtException
    • compareCPU

      public CPUCompareResult compareCPU(String xmlDesc) throws LibvirtException
      Compares the given CPU description with the host CPU
      Parameters:
      xmlDesc -
      Returns:
      comparison result according to enum CPUCompareResult
      Throws:
      LibvirtException
      See Also:
    • deviceCreateXML

      public Device deviceCreateXML(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(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(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:
    • domainCreateXML

      public Domain domainCreateXML(String xmlDesc, int flags) throws LibvirtException
      Launch a new guest domain, based on an XML description
      Parameters:
      xmlDesc -
      Returns:
      the Domain object
      Throws:
      LibvirtException
      See Also:
    • domainDefineXML

      public Domain domainDefineXML(String xmlDesc) throws LibvirtException
      Defines a domain, but does not start it
      Parameters:
      xmlDesc -
      Returns:
      the Domain object
      Throws:
      LibvirtException
      See Also:
    • domainEventDeregisterAny

      public int domainEventDeregisterAny(int callbackID) throws LibvirtException
      Removes an event callback.
      Parameters:
      callbackID - the callback to deregister
      Returns:
      0 on success, -1 on failure
      Throws:
      LibvirtException
      See Also:
    • domainEventRegisterAny

      public int domainEventRegisterAny(Domain domain, int eventId, Libvirt.VirConnectDomainEventGenericCallback cb) throws LibvirtException
      Adds a callback to receive notifications of arbitrary domain events occurring on a domain.
      Parameters:
      domain - option domain to limit the events monitored
      eventId - the events to monitor
      cb - the callback function to use.
      Returns:
      . The return value from this method is a positive integer identifier for the callback. -1 if an error
      Throws:
      LibvirtException
      See Also:
    • 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(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(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(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 String domainXMLFromNative(String nativeFormat, 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 String domainXMLToNative(String nativeFormat, 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
    • finalize

      public void finalize() throws LibvirtException
      Overrides:
      finalize in class Object
      Throws:
      LibvirtException
    • findStoragePoolSources

      public String findStoragePoolSources(String type, 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
    • getCapabilities

      public String getCapabilities() throws LibvirtException
      Provides capabilities of the hypervisor / driver.
      Returns:
      an XML String describing the capabilities.
      Throws:
      LibvirtException
      See Also:
    • getCellsFreeMemory

      public long getCellsFreeMemory(int startCells, int maxCells) throws LibvirtException
      NUMA Support
      Throws:
      LibvirtException
    • getFreeMemory

      public long getFreeMemory() throws LibvirtException
      Returns the free memory for the connection
      Throws:
      LibvirtException
    • getHostName

      public 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

      public long getHypervisorVersion(String type) throws LibvirtException
      Returns the version of the hypervisor against which the library was compiled. The type parameter specified which hypervisor's version is returned
      Parameters:
      type -
      Returns:
      major * 1,000,000 + minor * 1,000 + release
      Throws:
      LibvirtException
    • getLibVirVersion

      public long getLibVirVersion() throws LibvirtException
      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(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 element of the XML.
      Parameters:
      type -
      Returns:
      the number of CPUs
      Throws:
      LibvirtException
    • getType

      public String getType() throws LibvirtException
      Gets the name of the Hypervisor software used.
      Returns:
      the name
      Throws:
      LibvirtException
    • getURI

      public 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(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(String mac) throws LibvirtException
      Try to lookup an interface on the given hypervisor based on its MAC.
      Throws:
      LibvirtException
    • interfaceLookupByName

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

      public int isEncrypted() throws LibvirtException
      Determine if the connection is encrypted
      Returns:
      1 if encrypted, 0 if not encrypted, -1 on error
      Throws:
      LibvirtException
      See Also:
    • isSecure

      public int isSecure() throws LibvirtException
      Determine if the connection is secure
      Returns:
      1 if secure, 0 if not secure, -1 on error
      Throws:
      LibvirtException
      See Also:
    • listDefinedDomains

      public 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 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 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 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 String[] listDevices(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 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 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 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 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 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(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:
    • networkDefineXML

      public Network networkDefineXML(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:
    • networkFilterDefineXML

      public NetworkFilter networkFilterDefineXML(String xmlDesc) throws LibvirtException
      Defines a networkFilter
      Parameters:
      xmlDesc - the descirption of the filter
      Returns:
      the new filer
      Throws:
      LibvirtException
      See Also:
    • networkFilterLookupByName

      public NetworkFilter networkFilterLookupByName(String name) throws LibvirtException
      Fetch a network filter based on its unique name
      Parameters:
      name - name of network filter to fetch
      Returns:
      network filter object
      Throws:
      LibvirtException
      See Also:
    • 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(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(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(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(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(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
    • nodeInfo

      public NodeInfo nodeInfo() throws LibvirtException
      Returns a NodeInfo object describing the hardware configuration of the node.
      Returns:
      a NodeInfo object
      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(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
    • processError

      protected void processError() throws LibvirtException
      call the error handling logic. Should be called after every libvirt call
      Throws:
      LibvirtException
    • restore

      public void restore(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(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(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(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
    • setConnectionErrorCallback

      public void setConnectionErrorCallback(Libvirt.VirErrorCallback callback) throws LibvirtException
      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(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(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(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(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(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(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(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