PHP Manual

# Libvirt

# Introduction

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.

# Installing/Configuring

## Table of Contents

- Requirements
- Installation

## Requirements

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.

## Installation

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

This will create modules/libvirt.so which you can copy to your modules directory or use

    #make install

Now you need to enable the extension in your php.ini:

    extension=libvirt.so

# Predefined Constants

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.

`VIR_DOMAIN_XML_SECURE` (integer)
`VIR_DOMAIN_XML_INACTIVE` (integer)
`VIR_DOMAIN_NOSTATE` (integer)
`VIR_DOMAIN_RUNNING` (integer)
`VIR_DOMAIN_BLOCKED` (integer)
`VIR_DOMAIN_PAUSED` (integer)
`VIR_DOMAIN_SHUTDOWN` (integer)
`VIR_DOMAIN_SHUTOFF` (integer)
`VIR_DOMAIN_CRASHED` (integer)
`VIR_MEMORY_VIRTUAL` (integer)
`VIR_CRED_USERNAME` (integer)
`VIR_CRED_AUTHNAME` (integer)
`VIR_CRED_LANGUAGE` (integer)
`VIR_CRED_CNONCE` (integer)
`VIR_CRED_PASSPHRASE` (integer)
`VIR_CRED_ECHOPROMPT` (integer)
`VIR_CRED_NOECHOPROMP` (integer)
`VIR_CRED_REALM` (integer)
`VIR_CRED_EXTERNAL` (integer)
`VIR_DOMAIN_JOB_NONE` (integer)
`VIR_DOMAIN_JOB_BOUNDED` (integer)
`VIR_DOMAIN_JOB_UNBOUNDED` (integer)
`VIR_DOMAIN_JOB_COMPLETED` (integer)
`VIR_DOMAIN_JOB_FAILED` (integer)
`VIR_DOMAIN_JOB_CANCELLED` (integer)
`VIR_MIGRATE_LIVE` (integer)
`VIR_MIGRATE_PEER2PEER` (integer)
`VIR_MIGRATE_TUNNELLED` (integer)
`VIR_MIGRATE_PERSIST_DEST` (integer)
`VIR_MIGRATE_UNDEFINE_SOURCE` (integer)
`VIR_MIGRATE_PAUSED` (integer)
`VIR_MIGRATE_NON_SHARED_DISK` (integer)
`VIR_MIGRATE_NON_SHARED_INC` (integer)

# Interger ranges between libvirt and PHP

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:

1. If you need to output the value, you can safely print the string and there will be no difference

2. 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

3. 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

4. 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.

# Examples

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
    )
    ....

# Libvirt Functions

# libvirt_connect

(php-libvirt 0.1)

libvirt_connect — Get a connection to the Hypervisor

### Description

resource libvirt_connect ([ string `$url`= NULL [, bool `$readonly`= true [, array `$credentials`= Array() ]]] )

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

### Parameters

`url`

  URL of the hypervisor to connect to. Can be for example `qemu:///system` or `qemu+tcp:///system` .

`readonly`

  If `TRUE` (default) connection is made readonly.

`credentials`

  Credentials to authenticate with. See authentication for more details.

### Return Values

Returns `FALSE` on failure and connection resource on success. This connection resource must be used for all subsequent calls.

### Errors/Exceptions

This function returns errors via PHP E_* error mechanism.

### Notes

> 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");`

### Examples

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

# libvirt_domain_block_stats

(php-libvirt 0.3)

libvirt_domain_block_stats — provide block device statistics for the block device on domain.

### Description

array libvirt_domain_block_stats ( resource `$domain` , string `$path` )

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.

Members of the array returned by libvirt_domain_interface_stats
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.

### Parameters

`domain`

  Domain resource of domain the block device is attached to

`path`

  Path to the block device, i.e. "hda"

### Return Values

Array with statistics.

### Examples

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
    )

### See Also

- libvirt_domain_memory_stats() - provide memory statistics for the domain.
- libvirt_domain_interface_stats() - provide interface statistics for the virtual network interface on domain.

# libvirt_domain_create_xml

(php-libvirt 0.1)

libvirt_domain_create_xml — Launch a new guest domain, based on an XML description

### Description

resource libvirt_domain_create_xml ( resource `$connection` , string `$xml` )

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).

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`xml`

  XML description of the domain. For more details see » http://www.libvirt.org/formatdomain.html

### Return Values

Returns `FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_define_xml() - Define a domain, but does not start it.

# libvirt_domain_create

(php-libvirt 0.1)

libvirt_domain_create — Launch a defined domain.

### Description

bool libvirt_domain_create ( resource `$domain` )

Launch a defined domain. If the call succeed the domain moves from the defined to the running domains pools.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_list_domains() - List all domains
- libvirt_domain_lookup_by_uuid() - Try to look up a domain by its UUID (binary)
- libvirt_domain_lookup_by_uuid_string() - Try to look up a domain by its UUID (textual)
- libvirt_domain_lookup_by_id() - Try to look up a domain based on the hypervisor ID number
- libvirt_domain_lookup_by_name() - Try to look up a domain by its name.
- libvirt_domain_create_xml() - Launch a new guest domain, based on an XML description
- libvirt_domain_define_xml() - Define a domain, but does not start it.

# libvirt_domain_define_xml

(php-libvirt 0.1)

libvirt_domain_define_xml — Define a domain, but does not start it.

### Description

resource libvirt_domain_define_xml ( resource `$connection` , string `$xml` )

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.

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`xml`

  XML description of the domain. For more details see » http://www.libvirt.org/formatdomain.html

### Return Values

Returns `FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_undefine() - Undefine a domain
- libvirt_domain_create() - Launch a defined domain.

# libvirt_domain_destroy

(php-libvirt 0.1)

libvirt_domain_destroy — Destroy the domain object

### Description

bool libvirt_domain_destroy ( resource `$domain` )

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.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_create() - Launch a defined domain.
- libvirt_domain_create_xml() - Launch a new guest domain, based on an XML description

# libvirt_domain_get_connect

(php-libvirt 0.4)

libvirt_domain_get_connect — Returns connection resource for a domain

### Description

resource libvirt_domain_get_connect ( resource `$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.

### Parameters

`domain`

  Domain resource of domain to get connection resource.

### Return Values

`FALSE` on failure and connection resource on success.

# libvirt_domain_get_id

(php-libvirt 0.1)

libvirt_domain_get_id — Get the hypervisor ID number for the domain

### Description

integer libvirt_domain_get_id ( resource `$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.

### Parameters

`domain`

  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.

### Return Values

Hypervisor ID of the domain.

### See Also

- libvirt_domain_get_name() - Get the public name for that domain
- libvirt_domain_get_uuid() - Get the UUID for a domain as binary string.
- libvirt_domain_get_uuid_string() - Get the UUID for a domain as string.

# libvirt_domain_get_info

(php-libvirt 0.1)

libvirt_domain_get_info — Extract information about a domain

### Description

Array libvirt_domain_get_info ( resource `$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.

### Parameters

`domain`

  Domain resource of domain to get information for.

### Return Values

`FALSE` is returned on failure. On success associative array containing information is returned.

The array contains these values:

- maxMem - the maximum memory in KBytes allowed
- memory - the memory in KBytes used by the domain
- nrVirtCpu - the number of virtual CPUs for the domain
- cpuUsed - the CPU time used in seconds
- state - the running state (one of `VIR_DOMAIN_NOSTATE`, `VIR_DOMAIN_RUNNING`, `VIR_DOMAIN_BLOCKED`, `VIR_DOMAIN_PAUSED`, `VIR_DOMAIN_SHUTDOWN`, `VIR_DOMAIN_SHUTOFF` or `VIR_DOMAIN_CRASHED`)

### Examples

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
    )

### See Also

- libvirt_domain_get_name() - Get the public name for that domain
- libvirt_domain_get_uuid() - Get the UUID for a domain as binary string.
- libvirt_domain_get_uuid_string() - Get the UUID for a domain as string.

# libvirt_domain_get_job_info

(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.

### Description

array libvirt_domain_get_job_info ( resource `$domain` )

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.

### Parameters

`domain`

  Domain resource of domain to get job information of

### Return Values

Associative array on success and `FALSE` on failure.

### Examples

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
    )

### See Also

- libvirt_domain_migrate() - Migrate the domain object from its current host to the destination host defined by a connection
- libvirt_domain_migrate_to_uri() - Migrate the domain object from its current host to the destination host defined by URI

# libvirt_domain_get_name

(php-libvirt 0.1)

libvirt_domain_get_name — Get the public name for that domain

### Description

string libvirt_domain_get_name ( resource `$domain` )

Get the public name for that domain

### Parameters

`domain`

  Domain resource of domain to get name of.

### Return Values

Name of the domain.

### See Also

- libvirt_domain_get_info() - Extract information about a domain
- libvirt_domain_get_uuid() - Get the UUID for a domain as binary string.
- libvirt_domain_get_uuid_string() - Get the UUID for a domain as string.

# libvirt_domain_get_uuid_string

(php-libvirt 0.1)

libvirt_domain_get_uuid_string — Get the UUID for a domain as string.

### Description

string libvirt_domain_get_uuid_string ( resource `$domain` )

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().

### Parameters

`domain`

  Domain resource of domain to get UUID of.

### Return Values

String with textual representation of UUID.

### See Also

- libvirt_domain_get_info() - Extract information about a domain
- libvirt_domain_get_name() - Get the public name for that domain
- libvirt_domain_get_uuid() - Get the UUID for a domain as binary string.

# libvirt_domain_get_uuid

(php-libvirt 0.1)

libvirt_domain_get_uuid — Get the UUID for a domain as binary string.

### Description

string libvirt_domain_get_uuid ( resource `$domain` )

Get the UUID for a domain as a binary string. For textual representation use libvirt_domain_get_uuid_string().

### Parameters

`domain`

  Domain resource of domain to get UUID of.

### Return Values

String with binary representation of UUID.

### See Also

- libvirt_domain_get_info() - Extract information about a domain
- libvirt_domain_get_name() - Get the public name for that domain
- libvirt_domain_get_uuid_string() - Get the UUID for a domain as string.

# libvirt_domain_get_xml_desc

(php-libvirt 0.1)

libvirt_domain_get_xml_desc — Provide an XML description of the domain

### Description

string libvirt_domain_get_xml_desc ( resource `$domain` [, integer `$flags`= 0 ] )

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().

### Parameters

`domain`

  Domain resource of domain to get XML description.

`flags`

  Logical OR of any of these flags:

  - `VIR_DOMAIN_XML_SECURE` - dump security sensitive information too
  - `VIR_DOMAIN_XML_INACTIVE` - dump inactive domain information

### Return Values

String with XML description of domain. For more details see » http://www.libvirt.org/formatdomain.html.

### See Also

- libvirt_domain_create_xml() - Launch a new guest domain, based on an XML description
- libvirt_domain_define_xml() - Define a domain, but does not start it.

# libvirt_domain_interface_stats

(php-libvirt 0.3)

libvirt_domain_interface_stats — provide interface statistics for the virtual network interface on domain.

### Description

array libvirt_domain_interface_stats ( resource `$domain` , string `$path` )

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.

Members of the array returned by libvirt_domain_interface_stats
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.

### Parameters

`domain`

  Domain resource of domain the interface is attached to

`path`

  Path to the interface, i.e. "vnet1"

### Return Values

Array with statistics.

### Examples

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
    )

### See Also

- libvirt_domain_memory_stats() - provide memory statistics for the domain.
- libvirt_domain_block_stats() - provide block device statistics for the block device on domain.

# libvirt_domain_lookup_by_id

(php-libvirt 0.1)

libvirt_domain_lookup_by_id — Try to look up a domain based on the hypervisor ID number

### Description

resource libvirt_domain_lookup_by_id ( resource `$connection` , integer `$ID` )

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.

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`ID`

  Hypervisor ID of a domain.

### Return Values

`FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_lookup_by_name() - Try to look up a domain by its name.
- libvirt_domain_lookup_by_uuid() - Try to look up a domain by its UUID (binary)
- libvirt_domain_lookup_by_uuid_string() - Try to look up a domain by its UUID (textual)

# libvirt_domain_lookup_by_name

(php-libvirt 0.1)

libvirt_domain_lookup_by_name — Try to look up a domain by its name.

### Description

resource libvirt_domain_lookup_by_name ( resource `$connection` , string `$name` )

Try to look up a domain on the given hypervisor based on its name.

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`name`

  Name of a domain.

### Return Values

`FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_lookup_by_id() - Try to look up a domain based on the hypervisor ID number
- libvirt_domain_lookup_by_uuid() - Try to look up a domain by its UUID (binary)
- libvirt_domain_lookup_by_uuid_string() - Try to look up a domain by its UUID (textual)

# libvirt_domain_lookup_by_uuid_string

(php-libvirt 0.1)

libvirt_domain_lookup_by_uuid_string — Try to look up a domain by its UUID (textual)

### Description

resource libvirt_domain_lookup_by_uuid_string ( resource `$connection` , string `$uuid` )

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().

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`uuid`

  UUID of a domain to look up (in textual representation).

### Return Values

`FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_lookup_by_id() - Try to look up a domain based on the hypervisor ID number
- libvirt_domain_lookup_by_uuid() - Try to look up a domain by its UUID (binary)
- libvirt_domain_lookup_by_name() - Try to look up a domain by its name.

# libvirt_domain_lookup_by_uuid

(php-libvirt 0.1)

libvirt_domain_lookup_by_uuid — Try to look up a domain by its UUID (binary)

### Description

resource libvirt_domain_lookup_by_uuid ( resource `$connection` , string `$uuid` )

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().

### Parameters

`connection`

  Libvirt connection obtained by calling libvirt_connect().

`uuid`

  UUID of a domain to look up (in binary representation).

### Return Values

`FALSE` on failure and domain resource on success

### See Also

- libvirt_domain_lookup_by_id() - Try to look up a domain based on the hypervisor ID number
- libvirt_domain_lookup_by_uuid_string() - Try to look up a domain by its UUID (textual)
- libvirt_domain_lookup_by_name() - Try to look up a domain by its name.

# libvirt_domain_memory_peek

(php-libvirt 0.1)

libvirt_domain_memory_peek — Read the contents of a domain's memory

### Description

string libvirt_domain_memory_peek ( resource `$domain` , integer `$start` , integer `$size` , integer `$flags` )

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.

### Return Values

String containing requested memory

# libvirt_domain_memory_stats

(php-libvirt 0.3)

libvirt_domain_memory_stats — provide memory statistics for the domain.

### Description

array libvirt_domain_memory_stats ( resource `$domain` [, integer `$flags`= 0 ] )

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.

Possible members of the array returned by libvirt_domain_memory_stats
`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.

### Parameters

`domain`

  Domain resource of domain to get memory stats.

`flags`

  unused, always pass 0 (or ommit the parameter as 0 is default value

### Return Values

Array containig Up to `VIR_DOMAIN_MEMORY_STAT_NR` elements with statistics.

### See Also

- libvirt_domain_block_stats() - provide block device statistics for the block device on domain.
- libvirt_domain_interface_stats() - provide interface statistics for the virtual network interface on domain.

# libvirt_domain_migrate_to_uri

(php-libvirt 0.4)

libvirt_domain_migrate_to_uri — Migrate the domain object from its current host to the destination host defined by URI

### Description

bool libvirt_domain_migrate_to_uri ( resource `$domain` , string `$duri` , int `$flags` , string `$dname` , string `$uri` , integer `$bandwith` )

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.

### Return Values

`TRUE` on success and `FALSE` on failure.

### Examples

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");
}
?>`

### See Also

- libvirt_domain_migrate() - Migrate the domain object from its current host to the destination host defined by a connection
- 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.

# libvirt_domain_migrate

(php-libvirt 0.4)

libvirt_domain_migrate — Migrate the domain object from its current host to the destination host defined by a connection

### Description

resource libvirt_domain_migrate ( resource `$domain` , resource `$dconn` , int `$flags` , string `$dname` , string `$uri` , integer `$bandwith` )

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.

### Return Values

Resource to new domain on success and `FALSE` on failure. Please note that the resource of the domain is in the context of dconn.

### Examples

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");
}
?>`

### See Also

- libvirt_domain_migrate_to_uri() - Migrate the domain object from its current host to the destination host defined by URI
- 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.

# libvirt_domain_reboot

(php-libvirt 0.1)

libvirt_domain_reboot — Reboot a domain

### Description

bool libvirt_domain_reboot ( resource `$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.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_resume() - Resume an suspended domain
- libvirt_domain_shutdown() - Shutdown a domain
- libvirt_domain_suspend() - Suspend a domain
- libvirt_domain_create() - Launch a defined domain.

# libvirt_domain_resume

(php-libvirt 0.1)

libvirt_domain_resume — Resume an suspended domain

### Description

bool libvirt_domain_resume ( resource `$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

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_reboot() - Reboot a domain
- libvirt_domain_shutdown() - Shutdown a domain
- libvirt_domain_suspend() - Suspend a domain
- libvirt_domain_create() - Launch a defined domain.

# libvirt_domain_shutdown

(php-libvirt 0.1)

libvirt_domain_shutdown — Shutdown a domain

### Description

bool libvirt_domain_shutdown ( resource `$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.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_reboot() - Reboot a domain
- libvirt_domain_resume() - Resume an suspended domain
- libvirt_domain_suspend() - Suspend a domain
- libvirt_domain_create() - Launch a defined domain.

# libvirt_domain_suspend

(php-libvirt 0.1)

libvirt_domain_suspend — Suspend a domain

### Description

bool libvirt_domain_suspend ( resource `$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.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_reboot() - Reboot a domain
- libvirt_domain_resume() - Resume an suspended domain
- libvirt_domain_shutdown() - Shutdown a domain
- libvirt_domain_create() - Launch a defined domain.

# libvirt_domain_undefine

(php-libvirt 0.1)

libvirt_domain_undefine — Undefine a domain

### Description

bool libvirt_domain_undefine ( resource `$domain` )

Undefine a domain but does not stop it if it is running.

### Parameters

`domain`

  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()).

### Return Values

`TRUE` on success and `FALSE` on failure

### See Also

- libvirt_domain_define()

# libvirt_get_active_domain_count

(php-libvirt 0.1)

libvirt_get_active_domain_count — Get the number of active domains.

### Description

integer libvirt_get_active_domain_count ( resource `$connection` )

Provides the number of active domains.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Number of active domains.

### Examples

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

### See Also

- libvirt_get_inactive_domain_count() - get the number of defined domains
- libvirt_get_domain_count() - Get the number of all domains

# libvirt_get_domain_count

(php-libvirt 0.1)

libvirt_get_domain_count — Get the number of all domains

### Description

Integer libvirt_get_domain_count ( resource `$connection` )

Get the number of active and inactive domains.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Number of active and inactive domains. The result is the same as libvirt_get_inactive_domain_count()+libvirt_get_active_domain_count().

### Examples

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

### See Also

- libvirt_get_active_domain_count() - Get the number of active domains.
- libvirt_get_inactive_domain_count() - get the number of defined domains

# libvirt_get_hostname

(php-libvirt 0.1)

libvirt_get_hostname — Get hostname on which the hypervisor is running

### Description

string libvirt_get_hostname ( resource `$connection` )

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.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Host name of the hypervisor.

### See Also

- libvirt_node_get_info() - Extract hardware information about the node

# libvirt_get_inactive_domain_count

(php-libvirt 0.1)

libvirt_get_inactive_domain_count — get the number of defined domains

### Description

Integer libvirt_get_inactive_domain_count ( resource `$connection` )

Provides the number of defined but inactive domains.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Number of defined but inactive domains.

### Examples

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

### See Also

- libvirt_get_active_domain_count() - Get the number of active domains.
- libvirt_get_domain_count() - Get the number of all domains

# libvirt_get_last_error

(php-libvirt 0.1)

libvirt_get_last_error — Get the last libvirt error

### Description

string libvirt_get_last_error ( void )

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.

### Return Values

String with last libvirt error

# libvirt_list_active_domains

(php-libvirt 0.1)

libvirt_list_active_domains — Get active domains

### Description

array libvirt_list_active_domains ( resource `$connection` )

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.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

`FALSE` on failure and Array of integers containing hypervisor IDs.

### See Also

- libvirt_list_defined_domains() - Get inactive domains
- libvirt_list_domains() - List all domains

# libvirt_list_defined_domains

(php-libvirt 0.1)

libvirt_list_defined_domains — Get inactive domains

### Description

array libvirt_list_defined_domains ( resource `$connection` )

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.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

`FALSE` on failure and Array of strings containing domain names.

### See Also

- libvirt_list_active_domains() - Get active domains
- libvirt_list_domains() - List all domains

# libvirt_list_domains

(php-libvirt 0.1)

libvirt_list_domains — List all domains

### Description

array libvirt_list_domains ( resource `$connection` )

This function returns array of domain resources for all domains defined and/or running on the hypervisor.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Array of domain resources for all domains. `FALSE` on failure

### Examples

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

### See Also

- libvirt_list_active_domains() - Get active domains
- libvirt_list_defined_domains() - Get inactive domains

# libvirt_list_storagepools

(No version information available, might only be in CVS)

libvirt_list_storagepools — List all storagepools

### Description

array libvirt_list_storagepools ( resource `$connection` )

This function returns array of storagepool names for the connection resource.

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

Array of storagepool names. `FALSE` on failure

### Examples

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"
    }

### See Also

- libvirt_storagepool_lookup_by_name() - Lookup storagepool resource by name
- libvirt_storagepool_get_info() - Get storagepool information
- libvirt_list_volumes() - List all volumes in a storagepool

# libvirt_list_volumes

(No version information available, might only be in CVS)

libvirt_list_volumes — List all volumes in a storagepool

### Description

array libvirt_list_volumes ( resource `$storagepool resource` )

This function returns array of volume names in a storagepool.

### Parameters

`connection`

  Storagepool reousrce.

### Return Values

Array of volume names. `FALSE` on failure

### Examples

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"
    }

### See Also

- libvirt_storagepool_lookup_by_name() - Lookup storagepool resource by name
- libvirt_storagepool_get_info() - Get storagepool information
- libvirt_list_storagepools() - List all storagepools

# libvirt_node_get_info

(php-libvirt 0.1)

libvirt_node_get_info — Extract hardware information about the node

### Description

Array libvirt_node_get_info ( resource `$connection` )

Extract hardware information about the node (machine running the hypervisor).

### Parameters

`connection`

  Connection resource of hypervisor.

### Return Values

`FALSE` is returned on failure. On success associative array containing information is returned.

The array contains these values:

- model - string indicating the CPU model
- memory - memory size in kilobytes
- cpus - the number of active CPUs
- mhz - expected CPU frequency
- nodes - the number of NUMA cell, 1 for uniform mem access
- sockets - number of CPU socket per node
- cores - number of core per socket
- threads - number of threads per core

### Examples

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
    )

# libvirt_storagepool_get_info

(php-libvirt 0.4)

libvirt_storagepool_get_info — Get storagepool information

### Description

array libvirt_storagepool_get_info ( resource `$connection` )

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.

### Parameters

`connection`

  Connection resource of storagepool

### Return Values

Array with storagepool information. `FALSE` on failure

### Examples

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)
    }

### See Also

- libvirt_list_storagepools() - List all storagepools
- libvirt_storagepool_lookup_by_name() - Lookup storagepool resource by name
- libvirt_list_volumes() - List all volumes in a storagepool

# libvirt_storagepool_lookup_by_name

(php-libvirt 0.4)

libvirt_storagepool_lookup_by_name — Lookup storagepool resource by name

### Description

array libvirt_storagepool_lookup_by_name ( resource `$connection` , string `$storagepool name` )

This function returns the storagepool resource for the given name.

### Parameters

`connection`

  Connection resource of hypervisor.

`storagepool name`

  Name of a storagepool

### Return Values

Storagepool resource identiefier. `FALSE` on failure

### Examples

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)

### See Also

- libvirt_list_storagepools() - List all storagepools
- libvirt_storagepool_get_info() - Get storagepool information
- libvirt_list_volumes() - List all volumes in a storagepool

# libvirt_storagevolume_create_xml

(php-libvirt 0.4)

libvirt_storagevolume_create_xml — Create a new storage volume based on XML input

### Description

array libvirt_storagevolume_create_xml ( resource `$storagepool resource` , string `$xml` )

This function returns string containing volume information in XML format

### Parameters

`storagepool resource`

  Connection resource of the storagepool

`xml`

  XML information to base the new volume on

### Return Values

Volume resource of the newly created volume. `FALSE` on failure

### Examples

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)

### See Also

- libvirt_storagevolume_lookup_by_name() - Lookup volume resource by name
- libvirt_storagevolume_get_info() - Get storagevolume information
- libvirt_storagevolume_get_xml_desc() - Get storagevolume information in XML format

# libvirt_storagevolume_get_info

(php-libvirt 0.4)

libvirt_storagevolume_get_info — Get storagevolume information

### Description

array libvirt_storagevolume_get_info ( resource `$volume resource` )

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.

### Parameters

`volume resource`

  Connection resource of volume

### Return Values

Array with volume information. `FALSE` on failure

### Examples

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)
    }

### See Also

- libvirt_storagevolume_lookup_by_name() - Lookup volume resource by name
- libvirt_storagevolume_get_xml_desc() - Get storagevolume information in XML format
- libvirt_storagevolume_create_xml() - Create a new storage volume based on XML input

# libvirt_storagevolume_get_xml_desc

(php-libvirt 0.4)

libvirt_storagevolume_get_xml_desc — Get storagevolume information in XML format

### Description

array libvirt_storagevolume_get_xml_desc ( resource `$volume resource` )

This function returns string containing volume information in XML format

### Parameters

`volume resource`

  Connection resource of volume

### Return Values

String with volume information in XML format. `FALSE` on failure

### Examples

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>

### See Also

- libvirt_storagevolume_lookup_by_name() - Lookup volume resource by name
- libvirt_storagevolume_get_info() - Get storagevolume information
- libvirt_storagevolume_create_xml() - Create a new storage volume based on XML input

# libvirt_storagevolume_lookup_by_name

(php-libvirt 0.4)

libvirt_storagevolume_lookup_by_name — Lookup volume resource by name

### Description

array libvirt_storagevolume_lookup_by_name ( resource `$connection` , string `$volume name` )

This function returns the volume resource for the given name.

### Parameters

`connection`

  Connection resource of the storagepool.

`volume name`

  Name of a volume

### Return Values

Volume resource identiefier. `FALSE` on failure

### Examples

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)

### See Also

- libvirt_storagevolume_get_info() - Get storagevolume information
- libvirt_storagevolume_get_xml_desc() - Get storagevolume information in XML format
- libvirt_storagevolume_create_xml() - Create a new storage volume based on XML input
- libvirt_list_volumes() - List all volumes in a storagepool

# libvirt_version

(php-libvirt 0.1)

libvirt_version — Get libvirt version

### Description

array libvirt_version ([ string `$type`= null ] )

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

### Parameters

`type`

  Hypervisor type against which the library was compiled. If `type` is NULL, "Xen" is assumed.

### Return Values

Associative array containing version information. It cointains these members:

- libvirt.release
- libvirt.major
- libvirt.minor
- type.release
- type.major
- type.minor

### Examples

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
    )

## Table of Contents

- libvirt_connect — Get a connection to the Hypervisor
- libvirt_domain_block_stats — provide block device statistics for the block device on domain.
- libvirt_domain_create_xml — Launch a new guest domain, based on an XML description
- libvirt_domain_create — Launch a defined domain.
- libvirt_domain_define_xml — Define a domain, but does not start it.
- libvirt_domain_destroy — Destroy the domain object
- libvirt_domain_get_connect — Returns connection resource for a domain
- libvirt_domain_get_id — Get the hypervisor ID number for the domain
- libvirt_domain_get_info — Extract information about a domain
- 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.
- libvirt_domain_get_name — Get the public name for that domain
- libvirt_domain_get_uuid_string — Get the UUID for a domain as string.
- libvirt_domain_get_uuid — Get the UUID for a domain as binary string.
- libvirt_domain_get_xml_desc — Provide an XML description of the domain
- libvirt_domain_interface_stats — provide interface statistics for the virtual network interface on domain.
- libvirt_domain_lookup_by_id — Try to look up a domain based on the hypervisor ID number
- libvirt_domain_lookup_by_name — Try to look up a domain by its name.
- libvirt_domain_lookup_by_uuid_string — Try to look up a domain by its UUID (textual)
- libvirt_domain_lookup_by_uuid — Try to look up a domain by its UUID (binary)
- libvirt_domain_memory_peek — Read the contents of a domain's memory
- libvirt_domain_memory_stats — provide memory statistics for the domain.
- libvirt_domain_migrate_to_uri — Migrate the domain object from its current host to the destination host defined by URI
- libvirt_domain_migrate — Migrate the domain object from its current host to the destination host defined by a connection
- libvirt_domain_reboot — Reboot a domain
- libvirt_domain_resume — Resume an suspended domain
- libvirt_domain_shutdown — Shutdown a domain
- libvirt_domain_suspend — Suspend a domain
- libvirt_domain_undefine — Undefine a domain
- libvirt_get_active_domain_count — Get the number of active domains.
- libvirt_get_domain_count — Get the number of all domains
- libvirt_get_hostname — Get hostname on which the hypervisor is running
- libvirt_get_inactive_domain_count — get the number of defined domains
- libvirt_get_last_error — Get the last libvirt error
- libvirt_list_active_domains — Get active domains
- libvirt_list_defined_domains — Get inactive domains
- libvirt_list_domains — List all domains
- libvirt_list_storagepools — List all storagepools
- libvirt_list_volumes — List all volumes in a storagepool
- libvirt_node_get_info — Extract hardware information about the node
- libvirt_storagepool_get_info — Get storagepool information
- libvirt_storagepool_lookup_by_name — Lookup storagepool resource by name
- libvirt_storagevolume_create_xml — Create a new storage volume based on XML input
- libvirt_storagevolume_get_info — Get storagevolume information
- libvirt_storagevolume_get_xml_desc — Get storagevolume information in XML format
- libvirt_storagevolume_lookup_by_name — Lookup volume resource by name
- libvirt_version — Get libvirt version

- Introduction
- Installing/Configuring
  - Requirements
  - Installation
- Predefined Constants
- Interger ranges between libvirt and PHP
- Examples
- Libvirt Functions
  - libvirt_connect — Get a connection to the Hypervisor
  - libvirt_domain_block_stats — provide block device statistics for the block device on domain.
  - libvirt_domain_create_xml — Launch a new guest domain, based on an XML description
  - libvirt_domain_create — Launch a defined domain.
  - libvirt_domain_define_xml — Define a domain, but does not start it.
  - libvirt_domain_destroy — Destroy the domain object
  - libvirt_domain_get_connect — Returns connection resource for a domain
  - libvirt_domain_get_id — Get the hypervisor ID number for the domain
  - libvirt_domain_get_info — Extract information about a domain
  - 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.
  - libvirt_domain_get_name — Get the public name for that domain
  - libvirt_domain_get_uuid_string — Get the UUID for a domain as string.
  - libvirt_domain_get_uuid — Get the UUID for a domain as binary string.
  - libvirt_domain_get_xml_desc — Provide an XML description of the domain
  - libvirt_domain_interface_stats — provide interface statistics for the virtual network interface on domain.
  - libvirt_domain_lookup_by_id — Try to look up a domain based on the hypervisor ID number
  - libvirt_domain_lookup_by_name — Try to look up a domain by its name.
  - libvirt_domain_lookup_by_uuid_string — Try to look up a domain by its UUID (textual)
  - libvirt_domain_lookup_by_uuid — Try to look up a domain by its UUID (binary)
  - libvirt_domain_memory_peek — Read the contents of a domain's memory
  - libvirt_domain_memory_stats — provide memory statistics for the domain.
  - libvirt_domain_migrate_to_uri — Migrate the domain object from its current host to the destination host defined by URI
  - libvirt_domain_migrate — Migrate the domain object from its current host to the destination host defined by a connection
  - libvirt_domain_reboot — Reboot a domain
  - libvirt_domain_resume — Resume an suspended domain
  - libvirt_domain_shutdown — Shutdown a domain
  - libvirt_domain_suspend — Suspend a domain
  - libvirt_domain_undefine — Undefine a domain
  - libvirt_get_active_domain_count — Get the number of active domains.
  - libvirt_get_domain_count — Get the number of all domains
  - libvirt_get_hostname — Get hostname on which the hypervisor is running
  - libvirt_get_inactive_domain_count — get the number of defined domains
  - libvirt_get_last_error — Get the last libvirt error
  - libvirt_list_active_domains — Get active domains
  - libvirt_list_defined_domains — Get inactive domains
  - libvirt_list_domains — List all domains
  - libvirt_list_storagepools — List all storagepools
  - libvirt_list_volumes — List all volumes in a storagepool
  - libvirt_node_get_info — Extract hardware information about the node
  - libvirt_storagepool_get_info — Get storagepool information
  - libvirt_storagepool_lookup_by_name — Lookup storagepool resource by name
  - libvirt_storagevolume_create_xml — Create a new storage volume based on XML input
  - libvirt_storagevolume_get_info — Get storagevolume information
  - libvirt_storagevolume_get_xml_desc — Get storagevolume information in XML format
  - libvirt_storagevolume_lookup_by_name — Lookup volume resource by name
  - libvirt_version — Get libvirt version