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.
This page address the integer range conflict between PHP and Libvirt. You should read this if you do use functions that could return numbers bigger than 2^31 (i.e. 2GB in case of functions returning bytes).
Problem description: A lot of libvirt functions do return unsigned long long values (64bit unsigned). On the other hand, PHP does use long for all integers. This means that the largest number on 32bit systems is 2147483647. In case of bytes it means only 2GB. What happen when you try to return larger number may vary a lot. It seems that on 64bit platforms PHP can handle 64 bit signed numbers but this is not confirmed.
Because of this many functions will return possibly large numbers as string. As PHP uses implicit type conversion this is not a big issue (and you can disable it via php.ini option). You can encounter these basic situations:
If you need to output the value, you can safely print the string and there will be no difference
If you are sure that the returned number is within the range, you can use it as number and PHP will cast it for you when needed
If you are sure that your platform will handle 64bit numbers correctly, you can disable this behaviour via php.ini libvirt.longlong_to_string option
In all the other cases you can uses gm functions for multiprecision arithmetics. You will probably convert the string to gmp number, divide it and use as number.
Example #1 Handling of large numbers using multiprecision library
<?php
// suppose that we have number of I/O reads in $reads
$reads_div_int=gmp_intval(gmp_div($reads,1024)) ; //note the implicit convertsion from string to gmp_number.
}
?>
GMP does of course provide more arithmetic operations than division but converting bytes to kilobytes or megabytes is probably the most common operation.
If you are sure that you platform can handle 64bit numbers and you do not want to use conversion to string, you can disable this behaviour in php.ini via option libvirt.longlong_to_string. By default it is set to 1 (convert long long to string), setting it to 0 will force php-libvirt to return long long as long.
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 function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
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.4)
libvirt_domain_get_connect — Returns connection resource for a domain
Returns the connection resource for a domain.
Note: Notice
. You should not rely on this function. It is better to keep your own reference of the connections and domains.
Domain resource of domain to get connection resource.
FALSE on failure and connection resource on success.
(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.4)
libvirt_domain_get_job_info — Extract information about progress of a background job on a domain. Will return an error if the domain is not active.
Extract information about progress of a background job on a domain. Will return an error if the domain is not active. For exact description of returned values see » original documentation.
Note: Libvirt version
. This function has been added to Libvirt in version 0.7.7. You need this or newer version of Libvirt to be able to use this function..
Note: Warning
. This function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
Domain resource of domain to get job information of
Associative array on success and FALSE on failure.
Example #1 libvirt_domain_get_job_info() example
Get info about live migration of domain.
<?php
$dom=@libvirt_domain_lookup_by_name($conn,"f13_exper");
if ($dom==false)
{
echo ("Domain not found\n");
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
exit;
}
echo ("Domain found\n");
echo ("Getting job info for the domain\n");
$info=libvirt_domain_get_job_info($dom);
?>
The above example will output something similar to:
Domain found
Getting job info for the domain
Array
(
[type] => 2
[time_elapsed] => 24036
[time_remaining] => 0
[data_total] => 554041344
[data_processed] => 244097024
[data_remaining] => 313507840
[mem_total] => 554041344
[mem_processed] => 244097024
[mem_remaining] => 313507840
[file_total] => 0
[file_processed] => 0
[file_remaining] => 0
)
(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 function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
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 function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
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.4)
libvirt_domain_migrate_to_uri — Migrate the domain object from its current host to the destination host defined by URI
Performs migration of the domain from one host to another. For description of parameters and flags see » original documentation.
Please note that the function returns after the migration is complete. It may take a lot of time to migrate a host. Be sure to configure PHP maximum execution time.
TRUE on success and FALSE on failure.
Example #1 libvirt_domain_migrate_to_uri() example
Live migrate domain (f13_exper) to another node
<?php
echo ("Looking up f13_exper domain\n");
$dom=@libvirt_domain_lookup_by_name($conn,"f13_exper");
if ($dom==false)
{
echo ("Domain not found\n");
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
exit;
}
echo ("Domain found\n");
echo ("Migrating domain to $duri\n");
$rv=libvirt_domain_migrate_to_uri($dom,$duri,VIR_MIGRATE_LIVE | VIR_MIGRATE_PEER2PEER | VIR_MIGRATE_PERSIST_DEST | VIR_MIGRATE_UNDEFINE_SOURCE);
if ($rv==false)
{
echo ("Failure!");
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
}
else
{
echo ("Success\n");
}
?>
(php-libvirt 0.4)
libvirt_domain_migrate — Migrate the domain object from its current host to the destination host defined by a connection
Performs migration of the domain from one host to another. For description of parameters and flags see » original documentation.
Please note that the function returns after the migration is complete. It may take a lot of time to migrate a host. Be sure to configure PHP maximum execution time.
Resource to new domain on success and FALSE on failure. Please note that the resource of the domain is in the context of dconn.
Example #1 libvirt_domain_migrate() example
Live migrate domain (f13_exper) to another node
<?php
echo ("Looking up f13_exper domain\n");
$dom=@libvirt_domain_lookup_by_name($conn,"f13_exper");
if ($dom==false)
{
echo ("Domain not found\n");
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
exit;
}
echo ("Domain found\n");
echo ("Connecting to libvirt (URI:$duri)\n");
$dconn=libvirt_connect($duri,false,$credentials);
if ($dconn==false)
{
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
exit;
}
echo ("Connected\n");
echo ("Migrating domain to $duri\n");
$ddom=libvirt_domain_migrate($dom,$dconn,VIR_MIGRATE_LIVE | VIR_MIGRATE_PEER2PEER | VIR_MIGRATE_PERSIST_DEST | VIR_MIGRATE_UNDEFINE_SOURCE);
if ($ddom==false)
{
echo ("Failure!");
echo ("Libvirt last error: ".libvirt_get_last_error()."\n");
}
else
{
echo ("Success\n");
echo ("DDom is resource ($ddom) to migrated domain in context of destination connection\n");
}
?>
(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
(No version information available, might only be in CVS)
libvirt_list_storagepools — List all storagepools
This function returns array of storagepool names for the connection resource.
Connection resource of hypervisor.
Array of storagepool names. FALSE on failure
Example #1 libvirt_list_storagepools() example
List all storagepools
<?php
$conn=libvirt_connect($uri,true);
$pools=libvirt_list_storagepools($conn);
var_dump($pools);
?>
The above example will output something similar to:
array(2) {
[0]=>
string(7) "default"
[1]=>
string(4) "data"
}
(No version information available, might only be in CVS)
libvirt_list_volumes — List all volumes in a storagepool
This function returns array of volume names in a storagepool.
Storagepool reousrce.
Array of volume names. FALSE on failure
Example #1 libvirt_list_volumes() example
List all volumes
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepools_lookup_by_name($conn,'default');
$volumes=listvirt_list_volumes($pool);
var_dump($volumes);
?>
The above example will output something similar to:
array(3) {
[0]=>
string(7) "server1"
[1]=>
string(7) "server2"
[2]=>
string(7) "server3"
}
(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.4)
libvirt_storagepool_get_info — Get storagepool information
This function returns array containing storagepool information
Note: Warning
. This function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
Connection resource of storagepool
Array with storagepool information. FALSE on failure
Example #1 libvirt_storagepool_get_info() example
Connection resource of storagepool
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepools_lookup_by_name($conn,'default');
$poolInfo = libvirt_storagepool_get_info($pool)
var_dump($poolInfo);
?>
The above example will output something similar to:
array(4) {
["state"]=>
int(2)
["capacity"]=>
int(118996598784)
["allocation"]=>
int(34414264320)
["available"]=>
int(84582334464)
}
(php-libvirt 0.4)
libvirt_storagepool_lookup_by_name — Lookup storagepool resource by name
This function returns the storagepool resource for the given name.
Connection resource of hypervisor.
Name of a storagepool
Storagepool resource identiefier. FALSE on failure
Example #1 libvirt_storagepool_lookup_by_name() example
Return storagepool resource identifier
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepool_lookup_by_name($conn, 'default');
var_dump($pool);
?>
The above example will output something similar to:
resource(3) of type (Libvirt storagepool)
(php-libvirt 0.4)
libvirt_storagevolume_create_xml — Create a new storage volume based on XML input
This function returns string containing volume information in XML format
Connection resource of the storagepool
XML information to base the new volume on
Volume resource of the newly created volume. FALSE on failure
Example #1 libvirt_storagevolume_create_xmlc() example
Create a new volume in a storagepool
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepools_lookup_by_name($conn,'default');
$xml = "<volume>
<name>volume2</name>
<key>b10fa7e2-5e48-4c97-a7a0-42ca197d400c</key>
<capacity unit='M'>100</capacity>
</volume>";
$volumeNew=libvirt_storagevolume_create_xml($pool,$xml);
var_dump($volumeNew);
?>
The above example will output something similar to:
resource(3) of type (Libvirt volume)
(php-libvirt 0.4)
libvirt_storagevolume_get_info — Get storagevolume information
This function returns array containing volume information
Note: Warning
. This function returns values that may be bigger than 32bit integer limit. Please read this note for more details.
Connection resource of volume
Array with volume information. FALSE on failure
Example #1 libvirt_storagevolume_get_info() example
Array with volume information
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepools_lookup_by_name($conn,'default');
$volume=libvirt_storagevolume_lookup_by_name($pool,'volume1');
$volumeInfo=libtvirt_storagevolume_get_info($volue);
var_dump($volumeInfo);
?>
The above example will output something similar to:
array(3) {
["type"]=>
int(1)
["capacity"]=>
int(2147483648)
["allocation"]=>
int(2147483648)
}
(php-libvirt 0.4)
libvirt_storagevolume_get_xml_desc — Get storagevolume information in XML format
This function returns string containing volume information in XML format
Connection resource of volume
String with volume information in XML format. FALSE on failure
Example #1 libvirt_storagevolume_get_xml_desc() example
String with volume information in XML format
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepools_lookup_by_name($conn,'default');
$volume=libvirt_storagevolume_lookup_by_name($pool,'volume1');
$volumeXML=libtvirt_storagevolume_get_xml_desc($volume);
var_dump($volumeXML);
?>
The above example will output something similar to:
string(451) "<volume>
<name>volume1</name>
<key>mQ3tpH-dAjE-IdHi-iafe-QElg-X2r7-Pv59e6</key>
<source>
<device path='/dev/sdb'>
<extent start='27971813376' end='30119297024'/>
</device>
</source>
<capacity>2147483648</capacity>
<allocation>2147483648</allocation>
<target>
<path>/dev/data/volume1</path>
<permissions>
<mode>0660</mode>
<owner>0</owner>
<group>6</group>
</permissions>
</target>
</volume>
(php-libvirt 0.4)
libvirt_storagevolume_lookup_by_name — Lookup volume resource by name
This function returns the volume resource for the given name.
Connection resource of the storagepool.
Name of a volume
Volume resource identiefier. FALSE on failure
Example #1 libvirt_storagevolume_lookup_by_name() example
Return volume resource identifier
<?php
$conn=libvirt_connect($uri,true);
$pool=libvirt_storagepool_lookup_by_name($conn, 'default');
$volume=libvirt_storagevolume_lookup_by_name($pool, 'volume1');
var_dump($volume);
?>
The above example will output something similar to:
resource(3) of type (Libvirt storagevolume)
(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
)