A Xen PHP API for managment of Hypervisor and Citrix Server and their Virtual Machines for Laravel
A Xen PHP API for managment of Hypervisor and Citrix Server and their Virtual Machines for PHP, it works on Laravel 4, Laravel 5, Codeigniter and other PHP framework.
Before install this library make sure to have installed xmlrpc php module
API in PHP to communicate with Xen Server .
This packages is available on Composer’s repositories .
The package Allows to completely Manage an Hypervisvor Citrix .
With this , you can clone , start , stop and reboot any VPS of your Hypervisor
Also, this APi allow you toi have a realtime graph of your Hypervisor’s VPS!
I’ve create the Method that obtain XML realtime stats of Machine and convert it to RRD file, needed for the FlotJS library to draw the graph.
This API is available for all the major PHP Frameworks, such as Laravel, Symfony or Codeigniter.
Package is available on Packagist,
you can install it using Composer.
In the require key of composer.json file add the following:
"sircamp/xenapi": "2.1"
Or type this command from your project folder
composer require sircamp/xenapi
Sircamp\Xenapi is namespaced, but you can make your life easier by importing
a single class into your context:
use Sircamp\Xenapi\Xen as Xen;
Make sure that you have IP, User and Password of your hypervisor:
$ip = "123.123.123.123";
$user = "username";
$password = "password";
$xen = new Xen($ip,$user,$password); //OK now you have an open connection to Hypervisor
This serves to have a virtual machine (by the hostname) that is on selected hypervisor :
$vm = $xen->getVMByNameLabel("virtual.machine.hostaname");
Now you have the an XenVirtualMachine object that map your virtual machine, so we are ready to manage the VM
This method starts a stopped VM
$vm->start();
You can, also, pass two parameters at this method:
$pause = true; // start VM in pause status , dafault is false
$force = true; // force the boot of VM, default is true
$vm->start($pause, $force);
This method starts the specified VM on a particular host. This function can only be called with the VM is in the Halted State.
This method needs an XenHost object as parameter, but if you want you can pass a UUID host string
$host // this is a XenHost object istance or a string istance
$hostRef = $host;
$pause = true; // start VM in pause status , dafault is false
$force = true; // force the boot of VM, default is true
$vm->startOn($hostRef,$pause, $force);
This method sends a shutdown command to the Virtual Machine
$vm->cleanShutdown();
This method immediatly a shutdown the Virtual Machine
$vm->hardShutdown();
This method sends a reboot command to the Virtual Machine
$vm->cleanShutdown();
This method immediatly restarts the Virtual Machine
$vm->hardShutdown();
This method puts Virtual Machine in a suspend mode (read the Citrix manual)
$vm->suspend();
This method resumes a Virtual Machine that is in a suspend mode (read the Citrix manual)
$vm->resume();
This method awaken the specified VM and resume it on a particular Host. This can only be called when the specified VM is in the Suspended state.
This method needs an XenHost object as parameter, but if you want you can pass a UUID host string
$host // this is a XenHost object istance or a string istance
$hostRef = $host;
$vm->resumeOn($hostRef);
This method puts a Virtual Machine in pause
$vm->pause();
This method restores a Virtual Machine that is in pause
$vm->unpause();
This method clones the selected Virtual Machine into another ( please check if your hypervisor supports another machine).
before this, you must stop the virtual machine that you want clone
$name = "new_cloned_vm"; // name of cloned vm
$vm->cleanShudown(); // stop vm
$vm->clonevm($name);
This method gets the power status of the selected Virtual Machine
$vm->getPowerState();
Reset the power-state of the VM to halted in the database only. (Used to recover from slave failures in pooling scenarios by resetting the power-states of VMs running on dead slaves to halted.) This is a potentially dangerous operation; use with care.
$vm->powerStateReset();
This method obtains the UUID of the selected Virtual Machine.
$vm->getUUID();
This method returns the all console instances of selected Virtual Machine.
The console istance allows you to have and manage a SSH or RDP session of Virtual Machine
$vm->getConsoles()
This method returns the UUID of selected Virtual Machine’s console.
The UUID is very usefull for console istance mangement.
$vm->getConsoleUUID($console)
This method returns the guest metrics of selected Virtual Machine.
This metrics contains:
in the future, i will write an example
$vm->getGuestMetrics()
This method returns the metrics of selected Virtual Machine.
This metrics contains:
as for guest metrics, in the future, i will write an example
$vm->getMetrics()
This method returns the current stats of the running selected Virtual Machine.
With this method, you can obtain the stats of CPUs, RAM and DISK I/O in realtime!
However, this method return an response object that contains a XML string in the value attribute.
Inside this XML string you find the required statistics.
as for last two methods, in the future, i will write an example. Also, i would to show you how to obtain a realtime stats graph, stay tuned 😉
$vm->getStats()
This method returns the total amount of Virtual Machine’s Disks space.
Actually this method return the total in bytes.
$vm->getDiskSpace()
Also, you can pass an argument:
$format = "GB";
$vm->getDiskSpace($format);
This allow you to have the disk space in the format as you want.
NB: this feature is not yet implemented
This method returns the name of VM
$vm->getName()
This method returns a list of all the VMs known to the system.
$vm->getAll()
Migrate a VM to another Host. This can only be called when the specified VM is in the Running state.
This method needs an XenHost object as parameter, but if you want you can pass a UUID host string
The optionsMap parameter is a map that contains the options for pool migrating.
$optionsMap = array(
'option1' => "option first",
'option2' => "option second"
)
$host // this is a XenHost object istance or a string istance
$hostRef = $host;
$vm->poolMigrate($refHost, $optionsMap);
Assert whether a VM can be migrated to the specified destination.
In this method the first parameter, dest, is the result of a Host.migrate receive call.
The vdiMap parameter is the map of source VDI to destination SR.
The vifMap parameter is the map of VIF to destination network.
The optionsMap Extra configuration operations.
The live parameter allows to migrate the VM in live mode or nothing, on default this paramter is set to false.
$dest // Host.migrate call result
$vdiMap //map of source VDI
$vifMap //map of source VFI
$options = array(
'option1' => "option first",
'option2' => "option second"
);
$live = true;
$vm->migrateSend($dest,$vdiMap,$vifMap,$options,$live)
NB: this method is still in testing mode
Assert whether a VM can be migrated to the specified destination.
In this method the first parameter, dest, is the result of a Host.migrate receive call.
The vdiMap parameter is the map of source VDI to destination SR.
The vifMap parameter is the map of VIF to destination network.
The optionsMap Extra configuration operations.
The live parameter allows to migrate the VM in live mode or nothing, on default this paramter is set to false.
$dest // Host.migrate call result
$vdiMap //map of source VDI
$vifMap //map of source VFI
$options = array(
'option1' => "option first",
'option2' => "option second"
);
$live = true;
$vm->assertCanMigrate($dest,$vdiMap,$vifMap,$options,$live)
NB: this method is still in testing mode
Snapshots the specified VM, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored
$name = "name of snapshot";
$vm->snapshot($name)
Snapshots the specified VM with quiesce, making a new VM.
Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored
$name = "name of snapshot";
$vm->snapshotWithQuiesce($name)
Get the snapshot info field of the given VM.
$vm->getSnapshotInfo()
Reverts the specified VM to a previous state
$snapshotID // the snaoshot id
$vm->revert($snapshotID)
Copied the specified VM, making a new VM. Unlike clone, copy does not exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored. Instead, copy guarantees that the disk images of the newly created VM will be ’full disks’ - i.e. not part of a CoW chain. This function can only be called when the VM is in the Halted State
$name = "nameOfCopy";
$vm->copy($name);
Destroy the specified VM. The VM is completely removed from the system. This function can only be called when the VM is in the Halted State.
$vm->destroy();
Checkpoints the specified VM, making a new VM. Checkpoint automatically exploits the capabil-ities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy on Write) and saves the memory image as well
$name = "nameOfVM";
$vm->checkpoint($name);
Set this VM’s start delay in seconds.
$seconds = 5;
$vm->setStartDelay($seconds);
Set this VM’s start delay in seconds.
$seconds = 5;
$vm->setShutdownDelay($seconds);
Get this VM’s start delay in seconds.
$vm->getStartDelay();
Get this VM’s start delay in seconds.
$vm->getShutdownDelay();
Get the current operations field of the given VM.
$vm->getCurrentOperations();
Get the allowed operations field of the given VM.
$vm->getAllowedOperations();
Get the name/description field of the given VM.
$vm->getNameDescription();
Set the name/description field of the given VM.
$description = "description";
$vm->setNameDescription($description);
Get the is a template field of the given VM.
$vm->getIsATemplate();
Set the is a template field of the given VM.
$template = false;
$vm->setIsATemplate($template);
Get the resident on field of the given VM.
In the response of this method you’ll find a XenHost object that you can use.
$vm->getResidentOn();
Get the platform field of the given VM.
$vm->getPlatform();
Set the platform field of the given VM.
$array = array(
'data'=>'value',
'data2'=>'value'
);
$vm->setPlatform($array);
Get the other config field of the given VM.
$vm->getOtherConfig();
Set the other config field of the given VM.
$array = array(
'config'=>'value',
'config2'=>'value'
);
$vm->setOtherConfig($array);
Set the other config field of the VM given key-value pair to the other config field of the given vm.
$key = "key";
$value = "value"
$vm->addToOtherConfig($key, value);
Remove the given key and its corresponding value from the other config field of the given vm. If the key is not in that Map, then do nothing.
$key = "key";
$value = "value"
$vm->removeFromOtherConfig($key);
Get name label VM.
$vm->getNameLabel();
This serves to obtain the target host (by the hostname) :
$host = $xen->getHOSTByNameLabel("host.machine.hostaname");
Now you have the an XenHost object that map your hypervisor, so we are ready to manage the HOST
Puts the host into a state in which no new VMs can be started. Currently active VMs on the host continue to execute.
$host->disable()
Puts the host into a state in which new VMs can be started.
$host->enable()
Shutdown the host. (This function can only be called if there are no currently running VMs on the host and it is disabled.).
$host->shutdown()
Reboot the host. (This function can only be called if there are no currently running VMs on the host and it is disabled.).
$host->reboot()
Get the host xen dmesg.
$host->dmesg()
Get the host xen dmesg, and clear the buffer
$host->dmesgClear()
Get the host’s log file.
$host->getLog()
List all supported methods.
$host->listMethods()
Apply a new license to a host.
The default value of $license is an empty string
$file = file_get_contents("/path/license/file");
$license = base64_encode($file);
$host->licenseApply($license)
NB: $license must be an base64 encoded file
Check this host can be evacuated.
$host->assertCanEvacuate()
Migrate all VMs off of this host, where possible.
$host->evacuate()
This call queries the host’s clock for the current time.
$host->getServertime()
This call queries the host’s clock for the current time in the host’s local timezone.
$host->getServerLocaltime()
Get the installed server SSL certificate.
$host->getServerCertificate()
NB: This method returns the SSL certificate in .pem format
Change to another edition, or reactivate the current edition after a license has expired. This may be subject to the successful checkout of an appropriate license.
Default $force param is false, this means which you want force an update edition.
$edition = "newedition";
$force = true;
$host->getServerCertificate()
Refresh the list of installed Supplemental Packs.
$host->refreshPackInfo()
Enable the use of a local SR for caching purposes.
$srRef = "srReferID";
$host->enableLocalStorageCaching($srRef);
Disable the use of a local SR for caching purposes.
$host->disableLocalStorageCaching();
Prepare to receive a VM, returning a token which can be passed to VM->migrate().
The $features is an associative array that cotains the configuration value that you need to run the migrating machine, it default value is an empty array.
$networkRef = "networkRef" // shorty you can pass the obeject that map network
$features = array(
'options1'=>"youroption",
'options2'=>"youroption",
);
$host->migrateReceive($networkRef, $features);
Get the uuid field of the given host.
$host->getUUID()
Get the name/label field of the given host.
$host->getNameLabel()
Set the name/label field of the given host.
$name = "server.yourname.com";
$host->setNameLabel($name);
Get the name/description field of the given HOST.
$host->getNameDescription()
Set the name/description field of the given HOST.
$description = "long long text";
$host->setNameDescription($description)
Set the name/description field of the given HOST.
$description = "long long text";
$host->setNameDescription($description)
Get the allowed operations field of the given HOST.
$host->getAllowedOperations()
Get the software version field of the given host.
$host->getSoftwareVersion()
Get the other config field of the given HOST.
$host->getOtherConfig()
Set the other config field of the given HOST.
$config = array(
'config1' => "first config",
'config2' => "second config"
);
$host->setOtherConfig($config)
Add the given key-value pair to the other config field of the given host.
$key = "config1";
$value = "first config";
$host->addOtherConfig($key,$value)
Remove the given key and its corresponding value from the other config field of the given host. If the key is not in that Map, then do nothing.
$key = "config1";
$host->removeOtherConfig($key)
Get the supported bootloaders field of the given host.
$host->getSupportedBootloaders()
Get the resident VMs field of the given host.
In the response of this method you’ll find, if there exists at least a VM inside this Host, an array of VMs object that you can use.
$host->getResidentVMs()
Get the patches field of the given host.
$host->getPatches()
Get the host CPUs field of the given host.
$host->getHostCPUs()
Get the cpu info field of the given host.
$host->getCPUInfo()
Get the hostname of the given host.
$host->getHostname()
Set the hostname of the given host.
$name = "new.hostname.com"
$host->setHostname($name);
Get the address field of the given host.
$host->getAddress()
Set the address field of the given host.
$address = "123.123.123.123"
$host->setAddress($address);
Get the metrics field of the given host.
$host->getMetrics()
Get the license params field of the given host.
$host->getLicenseParam()
Get the edition field of the given host.
$host->getEdition()
Get the license server field of the given host.
$host->getLicenseServer()
Set the license server field of the given host.
$license = "newlicense"
$host->setLicenseServer($license);
Add the given key-value pair to the license server field of the given host.
$key = "licenseName";
$value = "licenseValue";
$host->addToLicenseServer($key,$value);
Remove the given key and its corresponding value from the license server field of the given host. If the key is not in that Map, then do nothing.
$key = "licenseName";
$host->removeFromLicenseServer($key);
Get the chipset info field of the given host.
$host->getChipsetInfo()
Every method return an istance of XenResponse class.
This object contains three attributes:
This attribute contains the value of response, sach as message, XML string or something else.
use this method to obtain it:
$response = $vm->hardReboot();
$response->getValue();
This attribute contains the status of response.
If status is Success the request is OK.
Otherwise is request is KO, use this for check the result of your operations
use this method to obtain it:
$response = $vm->hardReboot();
$response->getStatus();
This attribute contains message of KO response.
Just take the value of this attribute and check why the response isn’t OK.
For example if your connection credentials are wrong:
$console = "wrong_console";
$response = $vm->getConsolesUUID($console);
$response->getStatus(); //return Failure
$response->getErrorDescription(); // return an array with some error message
This is exaplained the custom excetions
This exception is launched when you try to connect to a hypervisor with a wrong credentials.
To catch this exception, remember to use the namespace of this class:
use Sircamp\Xenapi\Exception\XenConnectionException as XenConnectionException;