Class: Connection

Connection

new Connection()

Hypervisor Connection
Source:
See:

Methods

(static) open(name) → {Connection}

This function should be called first to get a connection to the Hypervisor and xen store

If name is null or undefined, if the LIBVIRT_DEFAULT_URI environment variable is set, then it will be used. Otherwise if the client configuration file has the "uri_default" parameter set, then it will be used. Finally probing will be done to determine a suitable default driver to activate. This involves trying each hypervisor in turn until one successfully opens.

If connecting to an unprivileged hypervisor driver which requires the libvirtd daemon to be active, it will automatically be launched if not already running. This can be prevented by setting the environment variable LIBVIRT_AUTOSTART=0

URIs are documented at http://libvirt.org/uri.html

Connection#close() should be used to release the resources after the connection is no longer needed.

Parameters:
Name Type Description
name String URI of the hypervisor, optional
Source:
Throws:
Error
Returns:
a hypervisor connection
Type
Connection

(static) openAuth(name, auth, flags) → {Connection}

This function should be called first to get a connection to the Hypervisor. If necessary, authentication will be performed fetching credentials via the callback

See Connection#open() for notes about environment variables which can have an effect on opening drivers and freeing the connection resources

URIs are documented at http://libvirt.org/uri.html

Parameters:
Name Type Description
name String URI of the hypervisor, optional
auth ConnectionAuth authenticate callback parameters
flags Number bitwise-OR of virConnectFlags
Source:
See:
  • VIR_CONNECT_RO
  • VIR_CONNECT_NO_ALIASES
Throws:
Error
Returns:
the hypervisor connection
Type
Connection

(static) openReadOnly(name) → {Connection}

This function should be called first to get a restricted connection to the library functionalities. The set of APIs usable are then restricted on the available methods to control the domains.

See Connection#open() for notes about environment variables which can have an effect on opening drivers and freeing the connection resources

URIs are documented at http://libvirt.org/uri.html

Parameters:
Name Type Description
name String URI of the hypervisor, optional
Source:
Throws:
Error
Returns:
the hypervisor connection
Type
Connection

addEventListener(event, listener)

Registers a callback to be invoked when the connection event occurred
Parameters:
Name Type Description
event String the name of event
listener function the callback function
Source:

allocNodePages(allocations, startCell, cellCount, flags)

Sometimes, when trying to start a new domain, it may be necessary to reserve some huge pages in the system pool which can be then allocated by the domain. This API serves that purpose.
Parameters:
Name Type Description
allocations Array An array of PageAllocation
startCell Number index of first cell to allocate pages on
cellCount Number number of consecutive cells to allocate pages on
flags Number extra flags; binary-OR of virNodeAllocPagesFlags
Source:
Throws:
Error
Returns:
the number of nodes successfully adjusted

baselineCPU(xmlCPUs, flags) → {String}

Computes the most feature-rich CPU which is compatible with all given host CPUs.
Parameters:
Name Type Description
xmlCPUs Array array of XML descriptions of host CPUs
flags Number bitwise-OR of virConnectBaselineCPUFlags
Source:
See:
  • VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES
  • VIR_CONNECT_BASELINE_CPU_MIGRATABLE
Returns:
XML description of the computed CPU (caller frees) or {@code undefined} on error.
Type
String

changeInterfaceBegin()

Creates a restore point
Source:
Throws:
Error

changeInterfaceCommit()

Commits the changes made to interfaces
Source:
Throws:
Error

changeInterfaceRollback()

Cancels changes made to interfaces settings by restoring previous state
Source:
Throws:
Error

close() → {Number}

This function closes the connection to the Hypervisor.
Source:
Returns:
a positive number if at least 1 reference remains on success. The returned value should not be assumed to be the total reference count. A return of 0 implies no references remain and the connection is closed and memory has been freed.
Type
Number

compareCPU(xmlDesc, flags) → {Number}

Compares the given CPU description with the host CPU
Parameters:
Name Type Description
xmlDesc String XML describing the CPU to compare with host CPU
flags Number bitwise-OR of virConnectCompareCPUFlags
Source:
See:
  • VIR_CPU_COMPARE_ERROR
  • VIR_CPU_COMPARE_INCOMPATIBLE
  • VIR_CPU_COMPARE_IDENTICAL
  • VIR_CPU_COMPARE_SUPERSET
  • VIR_CPU_COMPARE_LAST
Returns:
comparison result
Type
Number

createDomainXML(xml, flags) → {Domain}

Launch a new guest domain, based on an XML description
Parameters:
Name Type Description
xml String string containing an XML description of the domain
flags Number bitwise-OR of supported virDomainCreateFlags
Source:
Throws:
Error
Returns:
Type
Domain

createDomainXMLWithFiles(xml, files, flags) → {Domain}

Launch a new guest domain, based on an XML description
Parameters:
Name Type Description
xml String string containing an XML description of the domain
files Array list of file descriptors
flags Number bitwise-OR of supported virDomainCreateFlags
Source:
Throws:
Error
Returns:
Type
Domain

defineDomainXML(xml) → {Domain}

Define a domain, but does not start it. This definition is persistent, until explicitly undefined with Domain#undefine()
Parameters:
Name Type Description
xml String the XML description for the domain, preferably in UTF-8
Source:
Throws:
Error
Returns:
Type
Domain

defineDomainXMLFlags(xml, flags) → {Domain}

Define a domain, but does not start it. This definition is persistent, until explicitly undefined with Domain#undefine()
Parameters:
Name Type Description
xml String the XML description for the domain, preferably in UTF-8
flags Number bitwise OR of the virDomainDefineFlags constants
Source:
Throws:
Error
Returns:
Type
Domain

defineInterfaceXML(xml) → {Interface}

Define an inactive persistent physical host interface or modify an existing persistent one from the XML description
Parameters:
Name Type Description
xml String
Source:
Throws:
Error
Returns:
Type
Interface

getCapabilities() → {String}

Get the capabilities of the hypervisor / driver.
Source:
Returns:
a XML string defining the capabilities.
Type
String

getCPUModelNames(arch, models, flags) → {Number}

Get the list of supported CPU models for a specific architecture.
Parameters:
Name Type Description
arch String architecture
models Array the CPU models supported for the specified architecture
flags Number extra flags; not used yet, so callers should always pass 0
Source:
Returns:
-1 on error, number of elements in models on success
Type
Number

getHostname(conn) → {String}

This returns a system hostname on which the hypervisor is running (based on the result of the gethostname system call, but possibly expanded to a fully-qualified domain name via getaddrinfo). If we are connected to a remote system, then this returns the hostname of the remote system.
Parameters:
Name Type Description
conn Connection hypervisor connection
Source:
Throws:
Error
Returns:
the hostname which must be freed by the caller
Type
String

getLibVersion(conn) → {Number}

Returns the version of libvirt used by the daemon running on the host
Parameters:
Name Type Description
conn Connection hypervisor connection
Source:
Throws:
Error
Returns:
libvirt library version used on the connection
Type
Number

getMaxVcpus(type) → {Number}

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:
Name Type Description
type String value of the 'type' attribute in the element
Source:
Throws:
Error
Returns:
the maximum of virtual CPU
Type
Number

getNodeCellsFreeMemory(startCell)

Returns the free memory in one or more NUMA cells
Parameters:
Name Type Description
startCell Number index of first cell
Source:
Throws:
Error
Returns:
the free memory

getNodeCPUMap() → {Array}

Get CPU map of host node CPUs
Source:
Throws:
Error
Returns:
CPUs present on the host node
Type
Array

getNodeCPUStats(cpuNum) → {Object}

This function provides individual cpu statistics of the node. If you want to get total cpu statistics of the node, you must specify VIR_NODE_CPU_STATS_ALL_CPUS to cpuNum.
Parameters:
Name Type Description
cpuNum Number number of node cpu
Source:
Throws:
Error
Returns:
Type
Object

getNodeFreeMemory()

Returns the free memory available on the Node
Source:
Throws:
Error
Returns:
the available free memory in bytes

getNodeFreePages(pages, startCell, cellCount) → {PageAllocation}

Queries the host system on free pages of specified size
Parameters:
Name Type Description
pages Array page sizes to query
startCell Number index of first cell
cellCount Number maximum number of cells
Source:
Throws:
Error
Returns:
the free pages
Type
PageAllocation

getNodeInfo() → {NodeInfo}

Extract hardware information about the node.
Source:
Throws:
Error
Returns:
Type
NodeInfo

getNodeMemoryParameters() → {Array}

Get all node memory parameters (parameters unsupported by OS will be omitted)
Source:
Throws:
Error
Returns:
Type
Array

getNodeMemoryStats(cellNum) → {Object}

Returns the memory stats of the node
Parameters:
Name Type Description
cellNum Number number of node cell
Source:
Throws:
Error
Returns:
Type
Object

getNodeSecurityModel() → {Object}

Returns the security model of a hypervisor
Source:
Throws:
Error
Returns:
Type
Object

getNumberOfDefinedDomains() → {Number}

Returns he number of defined but inactive domains
Source:
Throws:
Error
Returns:
Type
Number

getNumberOfDefinedInterfaces() → {Number}

Returns the number of defined (inactive) interfaces on the physical host
Source:
Throws:
Error
Returns:
Type
Number

getNumberOfDomains() → {Number}

Returns the number of active domains
Source:
Throws:
Error
Returns:
Type
Number

getSysinfo(flags) → {String}

This returns the XML description of the sysinfo details for the host on which the hypervisor is running, in the same format as the element of a domain XML. This information is generally available only for hypervisors running with root privileges.
Parameters:
Name Type Description
flags Number
Source:
Throws:
Error
Returns:
the XML string
Type
String

getType() → {String}

Get the name of the Hypervisor driver used. This is merely the driver name; for example, both KVM and QEMU guests are serviced by the driver for the qemu:// URI, so a return of "QEMU" does not indicate whether KVM acceleration is present. For more details about the hypervisor, use virConnectGetCapabilities
Source:
Throws:
Error
Returns:
the name of the Hypervisor driver used
Type
String

getURI() → {String}

This returns the URI (name) of the hypervisor connection. Normally this is the same as or similar to the string passed to the Connection#open() / {@link virConnectOpenReadOnly} call, but the driver may make the URI canonical. If name is null was passed to Connection#open(), then the driver will return a non-NULL URI which can be used to connect to the same hypervisor later.
Source:
Throws:
Error
Returns:
the URI string
Type
String

getVersion() → {Number}

Get the version level of the Hypervisor running. This may work only with hypervisor call, i.e. with privileged access to the hypervisor, not with a Read-Only connection.
Source:
Throws:
Error
Returns:
the version of the running hypervisor
Type
Number

isAlive() → {Boolean}

Determine if the connection to the hypervisor is still alive
Source:
Returns:
true if alive, false if dead
Type
Boolean

isEncrypted() → {Boolean}

Determine if the connection to the hypervisor is encrypted
Source:
Returns:
true if encrypted, false if not encrypted
Type
Boolean

isSecure() → {Boolean}

Determine if the connection to the hypervisor is secure
Source:
Returns:
true if secure, false if not secure
Type
Boolean

listAllDomains(flags) → {Array}

Returns a possibly-filtered list of all domains
Parameters:
Name Type Description
flags Number
Source:
Throws:
Error
Returns:
Type
Array

listAllInterfaces(flags) → {Array}

Returns the list of interfaces
Parameters:
Name Type Description
flags bitwise-OR of virConnectListAllInterfacesFlags
Source:
Throws:
Error
Returns:
Type
Array

listDefinedDomains() → {Array}

Returns the defined but inactive domains
Source:
Throws:
Error
Returns:
Type
Array

listDefinedInterfaces() → {Array}

Returns the list of defined (inactive) physical host interfaces
Source:
Throws:
Error
Returns:
Type
Array

listDomains() → {Array}

Returns the list of active domains
Source:
Throws:
Error
Returns:
Type
Array

listInterfaces() → {Array}

Returns the name of interfaces
Source:
Throws:
Error
Returns:
Type
Array

lookupDomainById(id) → {Domain}

Try to find a domain based on the hypervisor ID number Note that this won't work for inactive domains which have an ID of -1, in that case a lookup based on the Name or UUId need to be done instead.
Parameters:
Name Type Description
id Number the domain ID number
Source:
Throws:
Error
Returns:
Type
Domain

lookupDomainByName(name) → {Domain}

Try to lookup a domain on the given hypervisor based on its name.
Parameters:
Name Type Description
name String the domain name
Source:
Throws:
Error
Returns:
Type
Domain

lookupDomainByUUID(uuid) → {Domain}

Try to lookup a domain on the given hypervisor based on its UUID.
Parameters:
Name Type Description
uuid String the UUID string for the domain
Source:
Throws:
Error
Returns:
Type
Domain

lookupInterfaceByMACString(mac) → {Interface}

Try to lookup an interface on the given hypervisor based on its MAC.
Parameters:
Name Type Description
mac String the MAC for the interface (null-terminated ASCII format)
Source:
Throws:
Error
Returns:
Type
Interface

lookupInterfaceByName(name) → {Interface}

Try to lookup an interface on the given hypervisor based on its name.
Parameters:
Name Type Description
name String name for the interface
Source:
Throws:
Error
Returns:
Type
Interface

ref()

Increment the reference count on the connection. For each additional call to this method, there shall be a corresponding call to Connection#close() to release the reference count, once the caller no longer needs the reference to this object.

This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. ie, each new thread using a connection would increment the reference count.

Source:
Throws:
Error

removeEventListener(event, listener)

Unregisters the callback previously set with the Connection#addEventListener()
Parameters:
Name Type Description
event String the name of event
listener function the callback function
Source:

setKeepAlive(interval, count) → {Boolean}

Start sending keepalive messages after interval seconds of inactivity and 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.
Parameters:
Name Type Description
interval Number number of seconds of inactivity before a keepalive message is sent
count Number number of messages that can be sent in a row
Source:
Throws:
Error
Returns:
true on success, false when remote party doesn't support keepalive messages
Type
Boolean

setNodeMemoryParameters(params)

Change all or a subset of the node memory tunables
Parameters:
Name Type Description
params Array scheduler parameter objects
Source:
Throws:
Error

suspendNodeForDuration(target, duration)

Attempt to suspend the node (host machine) for the given duration of time in the specified state (Suspend-to-RAM, Suspend-to-Disk or Hybrid-Suspend). Schedule the node's Real-Time-Clock interrupt to resume the node after the duration is complete
Parameters:
Name Type Description
target Number the state to which the host must be suspended to
duration Number the time duration in seconds for which the host has to be suspended
Source:
Throws:
Error