Libvirt is a toolkit to interact with the virtualization capabilities of recent versions of Linux (and other OSes). This is PHP language binding for it. For more details see » libvirt homepage.
Many of functions here is only PHP binding to Libvirt C function however in some cases argument types are modified to reflect PHP nature.
Libvirt is required. Version 0.6.2 and greater are tested and should work. Version prior to 0.6.2 are not supported and using phplibvirt with libvirt prior to 0.6.2 will probably cause problems. Phplibvirt will refuse to connect to libvirt if the version is not at least 0.6.2.
This ZEND extension uses default instaltion method via phpize. All you need to do is download the source code and compile it using:
#phpize #./configure --enable-libvirt #make clean all
#make install
extension=libvirt.so
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
A few basic examples
Example #1 Libvirt Example
<?php
$uri="qemu+tcp:///system";
$credentials=Array(VIR_CRED_AUTHNAME=>"fred",VIR_CRED_PASSPHRASE=>"fred");
echo ("Connecting to libvirt (URI:$uri)\n");
$conn=libvirt_connect($uri,false,$credentials);
if ($conn==false)
{
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
exit;
}
else
{
$hostname=libvirt_get_hostname($conn);
echo ("hostname:$hostname\n");
echo ("Domain count: Active ".libvirt_get_active_domain_count($conn).",Inactive ".libvirt_get_inactive_domain_count($conn).", Total ".libvirt_get_domain_count($conn)."\n");
$domains=libvirt_list_domains($conn);
foreach ($domains as $dom)
{
echo ("Name:\t".libvirt_domain_get_name($dom)."\n");
echo("UUID:\t".libvirt_domain_get_uuid_string($dom)."\n");
$dominfo=libvirt_domain_get_info($dom);
print_r($dominfo);
}
}
?>
The above example will output something similar to:
Connecting to libvirt (URI:qemu+tcp:///system)
hostname:kvmtest
Domain count: Active 2,Inactive 5, Total 7
Name: zlobsd1
UUID: 16890be9-bcb0-ef35-3d43-c2553ea972ea
Array
(
[maxMem] => 1048576
[memory] => 524288
[state] => 1
[nrVirtCpu] => 2
[cpuUsed] => 98718.23
)
Name: node4
UUID: 25ab2490-7c4c-099f-b647-45ff8efa73f6
Array
(
[maxMem] => 524288
[memory] => 524288
[state] => 1
[nrVirtCpu] => 1
[cpuUsed] => 2323601.51
)
Name: test1
UUID: 355fcd8f-ca53-e5e7-5935-47382ba754a0
Array
(
[maxMem] => 1053696
[memory] => 1053696
[state] => 5
[nrVirtCpu] => 1
[cpuUsed] => 0
)
....
(php-libvirt 0.1)
libvirt_connect — Get a connection to the Hypervisor
This function should be called first to get a connection to the Hypervisor. If necessary, authentication will be performed using supplied credentials.
URL of the hypervisor to connect to. Can be for example qemu:///system
or qemu+tcp:///system
.
If TRUE (default) connection is made readonly.
Credentials to authenticate with. See authentication for more details.
Returns FALSE on failure and connection resource on success. This connection resource must be used for all subsequent calls.
This function returns errors via PHP E_* error mechanism.
Note: Libvirt version
Version prior to 0.6.2 are not supported and using phplibvirt with libvirt prior to 0.6.2 will probably cause problems. libvirt_connect() will refuse to connect to libvirt daemon if the version is not at least 0.6.2.
Note: Authentication
You can authenticate to the libvirt daemon in several ways. If you are using policy kit and you are connecting locally, you can set it up to allow nonroot users. Just add to /etc/PolicyKit/PolicyKit.conf:<match action="org.libvirt.unix.manage"> <match user="httpduser"> <return result="yes"/> </match> </match>
If you are connecting to the TCP socket, you need to provide credentials. These credentials must be set beforehand using SASL. See » http://libvirt.org/auth.html#ACL_server_username for more details. You can You can specify the creentials as third argument. It is supposed to be an array in form of credential_type=>credential value. In example:Array(VIR_CRED_AUTHNAME=>"fred",VIR_CRED_PASSPHRASE=>"fred");
Example #1 libvirt_connect() example
This example connects to the hypervisor in various ways.
<?php
//Anonymous readonly connection
$res1=libvirt_connect("qemu:///system");
print_r($res1); printf ("\n");
//Anonymous read-write connection
$res2=libvirt_connect("qemu:///system",false);
print_r($res2); printf ("\n");
//Read-write connection with authentication
$res3=libvirt_connect("qemu:///system",false,Array(VIR_CRED_AUTHNAME=>"fred",VIR_CRED_PASSPHRASE=>"fred"));
print_r($res3); printf ("\n");
?>
The above example will output something similar to:
Resource id #4 Resource id #5 Resource id #6
(php-libvirt 0.3)
libvirt_domain_block_stats — provide block device statistics for the block device on domain.
This function returns block device (disk) stats for block devices attached to the domain. The path parameter is the name of the block device. 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 stats structure may be returned as -1, which indicates that the hypervisor does not support that particular statistic.
The returned array contains members in accoridng to the libvirt structure virDomainBlockStatsStruct.
| rd_req | number of read requests |
| rd_bytes | number of read bytes |
| wr_req | number of write requests |
| wr_bytes | number of written bytes |
| errs | In Xen this returns the mysterious 'oo_req'. |
Note: Warning
This is the first implementation of this function in phplibvirt. There are some unsolved issues regarding integer ranges between PHP and Libvirt. We may change the beahviour of this function in future.
Domain resource of domain the block device is attached to
Path to the block device, i.e. "hda"
Array with statistics.
Example #1 libvirt_domain_block_stats() example
Get interface statistics on blockdevice hda on domain test
<?php
$dom=libvirt_domain_lookup_by_name($res,"test");
print_r(libvirt_domain_block_stats($dom,"hda"));
?>
The above example will output something similar to:
Array
(
[rd_req] => 0
[rd_bytes] => 0
[wr_req] => 0
[wr_bytes] => 0
[errs] => -1
)
(php-libvirt 0.1)
libvirt_domain_create_xml — Launch a new guest domain, based on an XML description
Launch a new guest domain, based on an XML description similar to the one returned by libvirt_domain_get_xml_desc(). This function may requires privileged access to the hypervisor. The domain is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted (see libvirt_domain_define_xml() to define persistent domains).
Libvirt connection obtained by calling libvirt_connect().
XML description of the domain. For more details see » http://www.libvirt.org/formatdomain.html
Returns FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_create — Launch a defined domain.
Launch a defined domain. If the call succeed the domain moves from the defined to the running domains pools.
Domain resource of domain to be launched. You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_define_xml — Define a domain, but does not start it.
Define a domain, but does not start it. This definition is persistent, until explicitly undefined with libvirt_domain_undefine(). The domain is defined using XML description provided.
Libvirt connection obtained by calling libvirt_connect().
XML description of the domain. For more details see » http://www.libvirt.org/formatdomain.html
Returns FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_destroy — Destroy the domain object
Destroy the domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor. This function may require privileged access.
Domain resource of domain to be destroyed. You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_get_id — Get the hypervisor ID number for the domain
Get the hypervisor ID number for the domain. Is valid only for running domains. For more unique ID use libvirt_domain_get_uuid_string() or libvirt_domain_get_uuid(). These functions are valid for all domains not only for active ones.
Domain resource of domain to look up. You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()). Valid only for running (active) domains.
Hypervisor ID of the domain.
(php-libvirt 0.1)
libvirt_domain_get_info — Extract information about a domain
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.
Domain resource of domain to get information for.
FALSE is returned on failure. On success associative array containing information is returned.
The array contains these values:
Example #1 libvirt_domain_get_info() example
Example of getting domain info for domain named test
.
<?php
$dom=libvirt_domain_lookup_by_name($connection,"test");
$dominfo=libvirt_domain_get_info($dom);
print_r($dominfo);
?>
The above example will output something similar to:
Array
(
[maxMem] => 1048576
[memory] => 524288
[state] => 1
[nrVirtCpu] => 2
[cpuUsed] => 98718.23
)
(php-libvirt 0.1)
libvirt_domain_get_name — Get the public name for that domain
Get the public name for that domain
Domain resource of domain to get name of.
Name of the domain.
(php-libvirt 0.1)
libvirt_domain_get_uuid_string — Get the UUID for a domain as string.
Get the UUID for a domain as string (i.e. 25ab2490-7c4c-099f-b647-45ff8efa73f6 ). For more information about UUID see RFC4122. For binary representation use libvirt_domain_get_uuid().
Domain resource of domain to get UUID of.
String with textual representation of UUID.
(php-libvirt 0.1)
libvirt_domain_get_uuid — Get the UUID for a domain as binary string.
Get the UUID for a domain as a binary string. For textual representation use libvirt_domain_get_uuid_string().
Domain resource of domain to get UUID of.
String with binary representation of UUID.
(php-libvirt 0.1)
libvirt_domain_get_xml_desc — Provide an XML description of the domain
Provide an XML description of the domain. The description may be reused later to relaunch the domain with libvirt_domain_create_xml() or defined with libvirt_domain_define_xml().
Domain resource of domain to get XML description.
Logical OR of any of these flags:
String with XML description of domain. For more details see » http://www.libvirt.org/formatdomain.html.
(php-libvirt 0.3)
libvirt_domain_interface_stats — provide interface statistics for the virtual network interface on domain.
This function returns network interface stats for interfaces attached to the domain. The path parameter is the name of the network interface. Domains may have more than one network interface. To get stats for each you should make multiple calls to this function. Individual fields within the stats structure may be returned as -1, which indicates that the hypervisor does not support that particular statistic.
The returned array contains members in accoridng to the libvirt structure virDomainInterfaceStatsStruct.
| rx_bytes | Bytes received |
| rx_packets | Packets received |
| rx_errs | Errors on receive |
| rx_drop | Drops on receive |
| rx_bytes | Bytes transmitted |
| rx_packets | Packets transmitted |
| rx_errs | Errors on transmit |
| rx_drop | Drops on transmit |
Note: Warning
This is the first implementation of this function in phplibvirt. There are some unsolved issues regarding integer ranges between PHP and Libvirt. We may change the beahviour of this function in future.
Domain resource of domain the interface is attached to
Path to the interface, i.e. "vnet1"
Array with statistics.
Example #1 libvirt_domain_interface_stats() example
Get interface statistics on interface vnet1 on domain test
<?php
$dom=libvirt_domain_lookup_by_name($res,"test");
print_r(libvirt_domain_interface_stats($dom,"vnet1"));
?>
The above example will output something similar to:
Array
(
[rx_bytes] => 94699317
[rx_packets] => 794389
[rx_errs] => 0
[rx_drop] => 0
[tx_bytes] => 0
[tx_packets] => 0
[tx_errs] => 0
[tx_drop] => 0
)
(php-libvirt 0.1)
libvirt_domain_lookup_by_id — Try to look up a domain based on the hypervisor ID number
Try to look up 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.
Libvirt connection obtained by calling libvirt_connect().
Hypervisor ID of a domain.
FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_lookup_by_name — Try to look up a domain by its name.
Try to look up a domain on the given hypervisor based on its name.
Libvirt connection obtained by calling libvirt_connect().
Name of a domain.
FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_lookup_by_uuid_string — Try to look up a domain by its UUID (textual)
Try to look up a domain on the given hypervisor based on its UUID (in textual representation). For lookup based on binary UUID use libvirt_domain_lookup_by_uuid().
Libvirt connection obtained by calling libvirt_connect().
UUID of a domain to look up (in textual representation).
FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_lookup_by_uuid — Try to look up a domain by its UUID (binary)
Try to look up a domain on the given hypervisor based on its UUID (in binary representation). For lookup based on textual UUID use libvirt_domain_lookup_by_uuid_string().
Libvirt connection obtained by calling libvirt_connect().
UUID of a domain to look up (in binary representation).
FALSE on failure and domain resource on success
(php-libvirt 0.1)
libvirt_domain_memory_peek — Read the contents of a domain's memory
This function allows you to read the contents of a domain's memory. The memory which is read is controlled by the 'start', 'size' and 'flags' parameters. If 'flags' is VIR_MEMORY_VIRTUAL then the 'start' and 'size' parameters are interpreted as virtual memory addresses 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. 'buffer' is the return buffer and must be at least 'size' bytes. 'size' may be 0 to test if the call would succeed. NB. The remote driver imposes a 64K byte limit on 'size'. For your program to be able to work reliably over a remote connection you should split large requests to <= 65536 bytes.
This function is experimental and untested.
String containing requested memory
(php-libvirt 0.3)
libvirt_domain_memory_stats — provide memory statistics for the domain.
This function provides memory statistics for the domain. Up to VIR_DOMAIN_MEMORY_STAT_NR elements will be populated in the returned array with memory statistics from the domain. Only statistics supported by the domain, the driver, and this version of libvirt will be returned. The array is indexed by the numerical values of appropriate constants.
| VIR_DOMAIN_MEMORY_STAT_SWAP_IN | The total amount of data read from swap space (in kb) |
| VIR_DOMAIN_MEMORY_STAT_SWAP_OUT | The total amount of memory written out to swap space (in kb) |
| VIR_DOMAIN_MEMORY_STAT_MAJOR_FAULT | The number of page faults that required disk IO to service. |
| VIR_DOMAIN_MEMORY_STAT_MINOR_FAULT | The number of page faults serviced without disk IO. |
| VIR_DOMAIN_MEMORY_STAT_UNUSED | The amount of memory which is not being used for any purpose (in kb). |
| VIR_DOMAIN_MEMORY_STAT_AVAILABLE | The total amount of memory available to the domain's OS (in kb). |
| VIR_DOMAIN_MEMORY_STAT_NR | . |
Note: Warning
This is the first implementation of this function in phplibvirt. There are some unsolved issues regarding integer ranges between PHP and Libvirt. We may change the beahviour of this function in future.
Note: Libvirt version
This function has been added to Libvirt in version 0.7.5. You need this or newer version of Libvirt to be able to use this function.
Domain resource of domain to get memory stats.
unused, always pass 0 (or ommit the parameter as 0 is default value
Array containig Up to VIR_DOMAIN_MEMORY_STAT_NR elements with statistics.
(php-libvirt 0.1)
libvirt_domain_reboot — Reboot a domain
Reboot a 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.
Domain resource of domain to reboot.You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_resume — Resume an suspended domain
Resume an suspended domain, the process is restarted from the state where it was frozen by calling libvirt_domain_suspend(). This function may requires privileged access
Domain resource of domain to resume.You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_shutdown — Shutdown a domain
Shutdown a 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.
Domain resource of domain to shutdown.You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_suspend — Suspend a domain
Suspends an 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 libvirt_domain_resume() to reactivate the domain. This function may requires privileged access.
Domain resource of domain to suspend.You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_domain_undefine — Undefine a domain
Undefine a domain but does not stop it if it is running.
Domain resource of domain to undefine.You can get domain resource using various functions (i.e. libvirt_domain_lookup_by_uuid() or libvirt_list_domains()).
TRUE on success and FALSE on failure
(php-libvirt 0.1)
libvirt_get_active_domain_count — Get the number of active domains.
Provides the number of active domains.
Connection resource of hypervisor.
Number of active domains.
Example #1 libvirt_get_domain_count(),libvirt_get_active_domain_count() and libvirt_get_inactive_domain_count() example
Get count of all, active and inactive domains.
<?php
echo ("Domain count: Active ".libvirt_get_active_domain_count($conn).",Inactive ".libvirt_get_inactive_domain_count($conn).", Total ".libvirt_get_domain_count($conn)."\n");
?>
The above example will output something similar to:
Domain count: Active 1,Inactive 6, Total 7
(php-libvirt 0.1)
libvirt_get_domain_count — Get the number of all domains
Get the number of active and inactive domains.
Connection resource of hypervisor.
Number of active and inactive domains. The result is the same as libvirt_get_inactive_domain_count()+libvirt_get_active_domain_count().
Example #1 libvirt_get_domain_count(),libvirt_get_active_domain_count() and libvirt_get_inactive_domain_count() example
Get count of all, active and inactive domains.
<?php
echo ("Domain count: Active ".libvirt_get_active_domain_count($conn).",Inactive ".libvirt_get_inactive_domain_count($conn).", Total ".libvirt_get_domain_count($conn)."\n");
?>
The above example will output something similar to:
Domain count: Active 1,Inactive 6, Total 7
(php-libvirt 0.1)
libvirt_get_hostname — Get hostname on which the hypervisor is running
This 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.
Connection resource of hypervisor.
Host name of the hypervisor.
(php-libvirt 0.1)
libvirt_get_inactive_domain_count — get the number of defined domains
Provides the number of defined but inactive domains.
Connection resource of hypervisor.
Number of defined but inactive domains.
Example #1 libvirt_get_domain_count(),libvirt_get_active_domain_count() and libvirt_get_inactive_domain_count() example
Get count of all, active and inactive domains.
<?php
echo ("Domain count: Active ".libvirt_get_active_domain_count($conn).",Inactive ".libvirt_get_inactive_domain_count($conn).", Total ".libvirt_get_domain_count($conn)."\n");
?>
The above example will output something similar to:
Domain count: Active 1,Inactive 6, Total 7
(php-libvirt 0.1)
libvirt_get_last_error — Get the last libvirt error
Returns the last error produced by libvirt library. Does not reset it so you can read the same error multiple times. TODO: maybe would be better to reset the error.
String with last libvirt error
(php-libvirt 0.1)
libvirt_list_active_domains — Get active domains
Get the list of active domains. Their hypervisor IDs are returned. You can use libvirt_domain_lookup_by_id() to get domain resource from hypervisor ID.
In most cases it is better to use libvirt_list_domains() as it returns the domain resources.
Connection resource of hypervisor.
FALSE on failure and Array of integers containing hypervisor IDs.
(php-libvirt 0.1)
libvirt_list_defined_domains — Get inactive domains
Get the names of defined but inactive domains. You can use libvirt_domain_lookup_by_name() to get domain resource from name.
In most cases it is better to use libvirt_list_domains() as it returns the domain resources.
Connection resource of hypervisor.
FALSE on failure and Array of strings containing domain names.
(php-libvirt 0.1)
libvirt_list_domains — List all domains
This function returns array of domain resources for all domains defined and/or running on the hypervisor.
Connection resource of hypervisor.
Array of domain resources for all domains. FALSE on failure
Example #1 libvirt_list_domains() example
List all domains and get their names
<?php
$conn=libvirt_connect($uri,true);
$domains=libvirt_list_domains($conn);
foreach ($domains as $dom)
{
echo ("Name:\t".libvirt_domain_get_name($dom)."<br/>");
}
?>
The above example will output something similar to:
Name: test1 Name: node5 Name: ovirt-appliance Name: node3 Name: node4
(php-libvirt 0.1)
libvirt_node_get_info — Extract hardware information about the node
Extract hardware information about the node (machine running the hypervisor).
Connection resource of hypervisor.
FALSE is returned on failure. On success associative array containing information is returned.
The array contains these values:
Example #1 libvirt_node_get_info() example
Example of getting hardware info for active hypervisor.
<?php
$nodeinfo=libvirt_node_get_info($res);
print_r($nodeinfo);
?>
The above example will output something similar to:
(
[model] => x86_64
[memory] => 3077804
[cpus] => 2
[nodes] => 1
[sockets] => 1
[cores] => 2
[threads] => 1
[mhz] => 1700
)
(php-libvirt 0.1)
libvirt_version — Get libvirt version
Provides two information back, libvirt is the version of the library while type will be the version of the hypervisor type against which the library was compiled
Hypervisor type against which the library was compiled. If type is NULL, "Xen" is assumed.
Associative array containing version information. It cointains these members:
Example #1 libvirt_version() example
Get version of libvirt and xen driver.
<?php
$version=libvirt_version("xen")
print_r($version);
?>
The above example will output something similar to:
Array
(
[libvirt.release] => 0
[libvirt.minor] => 6
[libvirt.major] => 0
[type.release] => 1
[type.minor] => 0
[type.major] => 3
)