====== Gandi Hosting XML-RPC API specification ======



 ===== Documents version: 1.0 =====


 ====== Table of contents ======




 ==== Introduction ====
  * [[hosting#Description|Description]]
  * [[hosting#UC|User cases]]




 ==== XML Methods ====

  * Session methods
    * [[hosting#login|login]]

  * Account methods
    * [[hosting#account_currency|account_currency]]
    * [[hosting#account_balance|account_balance]]

  * Hosting account methods
    * [[hosting#hosting_account_info|hosting_account_info]]
    * [[hosting#hosting_account_product_add|hosting_account_product_add]]
    * [[hosting#hosting_account_product_renew|hosting_account_product_renew]]
    * [[hosting#hosting_account_product_remove|hosting_account_product_remove]]
    * [[hosting#hosting_account_product_update|hosting_account_product_update]]

  * Servers methods
    * [[hosting#vm_create|vm_create]]
    * [[hosting#vm_info|vm_info]]
    * [[hosting#vm_list|vm_list]]
    * [[hosting#vm_update|vm_update]]
    * [[hosting#vm_delete|vm_delete]]
    * [[hosting#vm_start|vm_start]]
    * [[hosting#vm_stop|vm_stop]]
    * [[hosting#vm_reboot|vm_reboot]]
    * [[hosting#vm_disk_list|vm_disk_list]]
    * [[hosting#vm_disk_link|vm_disk_link]]

  * Disk methods
    * [[hosting#disk_create|disk_create]]
    * [[hosting#disk_info|disk_info]]
    * [[hosting#disk_delete|disk_delete]]
    * [[hosting#disk_attach|disk_attach]]
    * [[hosting#disk_detach|disk_detach]]
    * [[hosting#disk_list|disk_list]]


  * Operations methods
    * [[hosting#operation_list|operation_list]]
    * [[hosting#operation_details|operation_details]]
    * [[hosting#operation_cancel|operation_cancel]]
   
  * Misc methods
    * [[hosting#os_list|os_list]]
			
  * Error codes format
    * [[hosting#error_description|Description]]
    * [[hosting#error_qualification_server|Qualification 1 - Server]]
    * [[hosting#error_qualification_data|Qualification 2 - Data]]

----





======== Introduction ========


===== Description =====
Gandi hosting API XML will allow you to remotely manage your servers. It is freely available to all of Gandi's resellers.





===== User Cases =====
Creation of a Gandi server:
  * step 1: add resources via the hosting_account_product_add method
  * step 2: verify that your shares are available via the hosting_account_info method
  * step 3: choose the OS of your choice via the method os_list and create your server with the vm_create method
  * step 4: create a data disk via the disk_create method 
  * step 5: attach your disk to your server using the disk_attach method





======== XML methods ========

====== Session methods ======

 ===== login =====

 === Signature === 
string login(string **login**, string **password** [, boolean **safe**])

 === Description ===

Log in to the XML-RPC interface and retrieve a session id.
<note>Sessions ID are sensitive information and therefore must be kept secret. If a session ID was to be disclosed a malicious user would be able to execute commands with your credentials during 12 hours.
</note>

 === Parameters ===
  * string **login**: the user login
  * string **password**: the user password
 === Optional parameter === 
  * boolean **safe**: whether or not log in [[domain#glossary_safe_mode|safe mode]]. Be sure to understand what you are doing before setting it to False.
    * True: Default. Log in safe mode. You will need to [[#su|su]].
    * False: Do not log in safe mode.

 === Returns ===
The XML-RPC response will contain a session id (string) if the login procedure is successful or a fault describing the problem.
Possible faults are described in section [[error-codes|Error Codes Format]].

 === Sample code ===

  * **Python** logging in with safe mode 
<code python>
import sys 
import xmlrpclib
proxy  = xmlrpclib.ServerProxy("https://api.gandi.net/xmlrpc/")
try:
    session  = proxy.login("AA1234-GANDI", "mypassword", True)
except xmlrpclib.Fault, e:
    print "could not login because: " + e.faultString
    sys.exit(67)
</code>

  * **Php** logging in with safe mode  
<code php>
<?php
require_once("xmlrpc.inc");

$proxy  = new xmlrpc_client("https://api.gandi.net/xmlrpc/");
$msg  = new xmlrpcmsg(
    "login",
    array(new xmlrpcval("AA1234-GANDI"),
    new xmlrpcval("mypassword"),
    new xmlrpcval(True, "boolean"))
);

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    echo "could not login because: " . $reply->faultString() . "\n";
    exit(67);
}
$session  = $reply->value();
?>
</code>

  * **perl** logging in with safe mode 
<code perl>
my $safe_mode  = XMLRPC::Data->type('boolean')->value(1);
my $proxy  = XMLRPC::Lite->proxy("https://api.gandi.net/xmlrpc/");
my $reply  = $proxy->call("login", "AA1234-GANDI", "mypassword", $safe_mode);
my $session  = $reply->result();

die "could not login because: " . $reply->faultstring . "\n" unless defined $session;
</code>

\\
----

====== Account methods ======

 ====== account_currency ======

 === Signature ===
string account_currency(string **session**)

 === Description ===

Retrieve the currency name used with this prepaid account.

 === Parameters ===

  * string **session**: the session id (returned by login)

 === Returns ===
The XML-RPC response will contain the ISO 4217 currency name (string) used for this account.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
print "prepaid account currency: %s" % proxy.account_currency(session)
</code>


  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("account_currency", array($session));
$reply  = $proxy->send($msg);
$val  = $reply->value();
$val  = $val->scalarval();
print "prepaid account currency: " . $val . "\n";
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("account_currency", $session);
my $currency  = $reply->result();
print "prepaid account currency: " . $currency . "\n";
</code>

\\
----

 ====== account_balance ======

 === Signature ===
double account_balance(string session)

 === Description ===

Retrieve the prepaid account balance.

 === Parameters ===
  * string session: the session id (returned by login)

 === Returns ===
The XML-RPC response will contain the balance of the account (double).
Possible faults are described in section [[error-codes|Error Codes Format.]]

 === Sample code ===
  * Sample code (python)
<code python>
print "prepaid account balance: %d"  % proxy.account_balance(session)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("account_balance", array($session));
$reply  = $proxy->send($msg);
$val  = $reply->value();
$val  = $val->scalarval();
print "prepaid account currency: " . $val . "\n";
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("account_balance", $session);
my $balance  = $reply->result();
print "prepaid account balance: " . $balance . "\n";
</code>

====== Hosting account methods ======

 ====== hosting_account_info ======

 === Signature ===
struct hosting_account_info(string **session**)

 === Description ===

Return the informations linked to the user hosting account (number of shares, used shares, etc.).

 === Parameters ===

  * string **session**: the session id (returned by login)

 === Returns ===
The XML-RPC response will be the informations for this account.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
import pprint

try:
    info  = proxy.hosting_account_info(session)
    pprint.pprint(info)
except xmlrpclib.Fault, e:
    print "could not get information for hosting account: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("hosting_account_info", array($session));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not get information for hosting account: %s\n", $reply->faultString());
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("hosting_account_info", $session);
my $info  = $reply->result();
unless (defined $opid) {
    printf "could not get information for hosting account: %s\n", $reply->faultstring;
}
else {
    print Dumper($info);
}
</code>

\\
----

 ====== hosting_account_product_add ======

 === Signature ===
int hosting_account_product_add(string **session**, string **product_name**, int **quantity**, string **duration**)

 === Description ===

Create a 'hosting_account_product_add' operation that will add a hosting product to the logged user hosting account.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * string **product_name**: the product name, one of:
    * shares: flexible shares (ie. a product you can update, renew and release)
    * shares_fixed: fixed shares (ie. a share you can renew but cannot update nor release)
    * disk: optional disk (ie. a product you can update, renew and release)
  * int **quantity**: the number of units (eg. 4 shares, or 1024MB of disk)
  * string **duration**: the duration of the product (eg. '1m' for a month, '1y' for a year etc.)

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
try:
    opid  = proxy.hosting_account_product_add(session, 'shares', 4, '1m')
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a hosting_account_product_add operation: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("hosting_account_product_add", array($session, new xmlrpcval("shares"), new xmlrpcval(4), new xmlrpcval("1m")));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a hosting_account_product_add operation because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("hosting_account_product_add", $session, "shares", 4, "1m");
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a hosting_account_product_add operation because: %s\n", $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== hosting_account_product_renew ======

 === Signature ===
int hosting_account_product_renew(string **session**, int **product_id**, string **duration**)

 === Description ===

Create a 'hosting_account_product_renew' operation that will renew a hosting product for a specified duration.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **product_id**: the id of the product
  * string **duration**: the duration to renew this product for (eg. '1m' to renew for a month, '1y' for a year etc.)

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
try:
    opid  = proxy.hosting_account_product_renew(session, 1234, '1m')
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a hosting_account_product_renew operation: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("hosting_account_product_renew", array($session, new xmlrpcval(1234), new xmlrpcval("1m")));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a hosting_account_product_renew operation because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("hosting_account_product_renew", $session, 1234, "1m");
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a hosting_account_product_renew operation because: %s\n", $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>


\\
----

 ====== hosting_account_product_remove ======

 === Signature ===
int hosting_account_product_remove(string **session**, int **product_id**)

 === Description ===

Create a 'hosting_account_product_remove' operation that will remove a hosting product from the user hosting account.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **product_id**: the id of the product

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
try:
    opid  = proxy.hosting_account_product_remove(session, 1234)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a hosting_account_product_remove operation: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("hosting_account_product_remove", array($session, new xmlrpcval(1234)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a hosting_account_product_remove operation because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("hosting_account_product_remove", $session, 1234);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a hosting_account_product_remove operation because: %s\n", $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== hosting_account_product_update ======

 === Signature ===
int hosting_account_product_update(string **session**, int **product_id**, int **quantity**)

 === Description ===

Create a 'hosting_account_product_update' operation that will update the quantity of a hosting product.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **product_id**: the id of the product
  * int **quantity**: the new quantity for the product

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
try:
    opid  = proxy.hosting_account_product_update(session, 1234, 5)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a hosting_account_product_update operation: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("hosting_account_product_update", array($session, new xmlrpcval(1234), new xmlrpcval(5)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a hosting_account_product_update operation because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("hosting_account_product_update", $session, 1234, 5);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a hosting_account_product_update operation because: %s\n", $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

====== VM methods ======



 ====== vm_create ======

 === Signature ===
int vm_create(string **session**, string **hostname**, string **password**, int **os_id**, int **shares**, int **cpu**, struct **specs**)

 === Description ===

Create a 'vm_create' operation that will create a VM and return its id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * string **hostname**: the hostname of the VM
  * string **password**: the root (or eventually the user) account password
  * int **os_id**: the selected OS for the VM
  * int **shares**: the number of shares to attribute to this VM
  * int **cpu**: the number of CPUs for this VM

  * struct **specs**: a struct containing the following keys:
    * string **login**: create a user account for login

 === Returns ===
The XML-RPC response will be a VM ID.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
hostname  = 'vmtest1'
password  = 'my_password'
os_id  = 111
shares  = 4
cpu  = 1
specs = {'login': 'gandi'}

try:
    vm_id  = proxy.vm_create(session, hostname, password, os_id, shares, cpu, specs)
    print "creating VM#%d" % (vm_id,)
except xmlrpclib.Fault, e:
    print "could not create VM because: %s" % (e.faultString,)
</code>


  * Sample code (php)

<code php>
$hostname  = new xmlrpcval("vmtest1");
$password  = new xmlrpcval("my_password");
$os_id  = new xmlrpcval(111);
$shares  = new xmlrpcval(4);
$cpu  = new xmlrpcval(1);
$specs["login"]  = new xmlrpcval("gandi");
$specs  = php_xmlrpc_encode($specs);

$msg  = new xmlrpcmsg("vm_create", array($session, $hostname, $password, $os_id, $shares, $cpu, $specs));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create VM because: %s\n", $reply->faultString());
}
else {
    $val  = $reply->value();
    $val  = $val->scalarval();
    printf("creating VM#%d\n", $val);
}
</code>

  * Sample code (perl)

<code perl>
my $hostname  = "vmtest1";
my $password  = "my_password";
my $os_id  = 111;
my $shares  = 4;
my $cpu  = 1;
my $specs = {};
$specs["login"]  = "gandi";

my $reply  = $proxy->call("vm_create", $session, $hostname, $password, $os_id, $shares, $cpu, $specs);

my $vm_id  = $reply->result();
unless (defined $opid) {
    printf "could not create VM because: %s\n", $reply->faultstring;
}
else {
    printf "creating VM#%d\n", $vm_id;
}
</code>

\\
----

 ====== vm_info ======

 === Signature ===
struct vm_info(string **session**, int **vm_id**)

 === Description ===

Return the informations of the specified VM.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the id of the VM 

 === Returns ===
The XML-RPC response will be the informations for the specified VM.
Possible faults are described in section [[error-codes|Error Codes Format]]

  * Sample code (python)
<code python>
import pprint
vm_id  = 456
try:
    vm_info  = proxy.vm_info(session, vm_id)
    print "informations for VM#%s" % (vm_id,)
    pprint.pprint(vm_info)
except xmlrpclib.Fault, e:
    print "could not retrieve informations of VM#%s because: %s" % (vm_id, e.faultString)
</code>

  * Sample code (php)
<code php>
$vm_id  = 456;
$msg  = new xmlrpcmsg("vm_info", array($session, new xmlrpcval($vm_id)));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not retrieve informations of VM#%s because: %s\n", $vm_id, $reply->faultString());
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("informations for VM#%s\n", $vm_id);
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $vm_id  = 456;
my $reply  = $proxy->call("vm_info", $session, $vm_id);
my $info  = $reply->result();
unless (defined $info) {
    printf "could not retrieve informations of VM#%s because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "informations for VM#%s\n", $vm_id;
    print Dumper($info);
}
</code>

\\
----

 ====== vm_list ======

 === Signature ===
array vm_list(string **session**)

 === Description ===

Return the list of VMs associated to a hosting account.

 === Parameters ===

  * string **session**: the session id (returned by login)

 === Returns ===
The XML-RPC response will be an array of VM ids.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
import pprint
try:
    vms  = proxy.vm_list(session)
    print "VMs:"
    pprint.pprint(vms)
except xmlrpclib.Fault, e:
    print "could not retrieve the list of VMs because: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("vm_list", array($session));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not retrieve the list of VMs because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("vm_list", $session);
my $vms  = $reply->result();
unless (defined $vms) {
    print "could not retrieve the list of VMs because: " . $reply->faultstring . "\n";
}
else {
    print Dumper($vms);
}
</code>

\\
----


 ====== vm_update ======

 === Signature ===
int vm_update(string **session**, int **vm_id**, struct **specs**)

 === Description ===

Create a 'vm_update' operation that will update a VM and returns the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the hostname of the VM
  * struct **specs**: a struct containing the following keys:
    * int **shares**: the number of shares to give to the VM
    * int **cpu**: the number of CPUs for the VM
    * int **vm_max_memory**: the maximum amount of memory this server can be granted without having to be rebooted

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
vm_id  = 1234
shares  = 5

try:
    opid  = proxy.vm_update(session, vm_id, {'shares': shares})
    print "updating VM#%d is operation id#%s" % (vm_id, opid)
except xmlrpclib.Fault, e:
    print "could not update VM#%s because: %s" % (opid, e.faultString,)
</code>


  * Sample code (php)

<code php>
$vm_id  = 1234;
$specs["shares"]  = new xmlrpcval(5);
$specs  = php_xmlrpc_encode($specs);

$msg  = new xmlrpcmsg("vm_update", array($session, new xmlrpcval($vm_id), $specs));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not update VM#%s because: %s\n", $vm_id, $reply->faultString());
}
else {
    $val  = $reply->value();
    $val  = $val->scalarval();
    printf("updating VM#%d is operation id#%s\n", $vm_id, $val);
}
</code>


  * Sample code (perl)

<code perl>
my $vm_id  = 1234;
my $specs = {};
$specs["shares"]  = 5;

my $reply  = $proxy->call("vm_update", $session, $vm_id, $specs);

my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not update VM#%s because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "updating VM#%d is operation id#%s\n", $vm_id, $opid;
}
</code>

\\
----

 ====== vm_delete ======

 === Signature ===
int vm_delete(string **session**, int **vm_id**)

 === Description ===

Create a 'vm_delete' operation to delete a stopped VM, and return the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the id of the VM to delete

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
vm_id = 9876
try:
    opid  = proxy.vm_delete(session, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a vm_delete operation for VM#%s because: %s" % (vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$vm_id = 9876;
$msg  = new xmlrpcmsg("vm_delete", array($session, new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a vm_delete operation for VM#%d because: %s\n", $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $vm_id = 9876;
my $reply  = $proxy->call("vm_delete", $session, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a vm_delete for VM#%s operation because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----


 ====== vm_start ======

 === Signature ===
int vm_start(string **session**, int **vm_id**)

 === Description ===

Create a 'vm_start' operation that will start (boot or unpause) a VM and returns the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the id of the VM to start

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
vm_id = 9876
try:
    opid  = proxy.vm_start(session, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a vm_start operation for VM#%s because: %s" % (vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$vm_id = 9876;
$msg  = new xmlrpcmsg("vm_start", array($session, new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a vm_start operation for VM#%d because: %s\n", $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $vm_id = 9876;
my $reply  = $proxy->call("vm_start", $session, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a vm_start for VM#%s operation because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== vm_stop ======

 === Signature ===
int vm_stop(string **session**, int **vm_id**)

 === Description ===

Create a 'vm_stop' operation that will shutdown a VM and returns the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the id of the VM to stop

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
vm_id = 9876
try:
    opid  = proxy.vm_stop(session, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a vm_stop operation for VM#%s because: %s" % (vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$vm_id = 9876;
$msg  = new xmlrpcmsg("vm_stop", array($session, new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a vm_stop operation for VM#%d because: %s\n", $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $vm_id = 9876;
my $reply  = $proxy->call("vm_stop", $session, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a vm_stop for VM#%s operation because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== vm_reboot ======

 === Signature ===
int vm_reboot(string **session**, int **vm_id**)

 === Description ===

Create a 'vm_reboot' operation that will reboot (soft) a VM and returns the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **vm_id**: the id of the VM to reboot

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
vm_id = 9876
try:
    opid  = proxy.vm_reboot(session, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a vm_reboot operation for VM#%s because: %s" % (vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$vm_id = 9876;
$msg  = new xmlrpcmsg("vm_reboot", array($session, new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a vm_reboot operation for VM#%d because: %s\n", $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $vm_id = 9876;
my $reply  = $proxy->call("vm_reboot", $session, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a vm_reboot for VM#%s operation because: %s\n", $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

====== Disk methods ======


 ====== disk_create ======

 === Signature ===
int disk_create(string **session**, struct **specs**)

 === Description ===

Create a 'disk_create' operation that will create a disk on the hosting side and returns the ID of the disk created.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * struct **specs**: a struct containing the following keys:
    * int **size**: the size of the disk to create in MB (eg. 1024 for 1GB)
    * string **name**: the label of the disk
    * string **fstype**: the filesystem of the disk, one of:
      * ext3
      * reiserfs
      * xfs
      * jfs

 === Returns ===
The XML-RPC response will be a disk ID.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)

<code python>
size = 2048
name = 'disk2GB'
fstype = 'ext3'

try:
    disk_id  = proxy.disk_create(session, {'size': size, 'name': name, 'fstype': fstype})
    print "creating disk#%d" % (disk_id,)
except xmlrpclib.Fault, e:
    print "could not create disk because: %s" % (e.faultString,)
</code>


  * Sample code (php)

<code php>
$specs["size"]  = new xmlrpcval("2048");
$specs["name"]  = new xmlrpcval("disk2GB");
$specs["fstype"]  = new xmlrpcval("ext3");
$specs  = php_xmlrpc_encode($specs);

$msg  = new xmlrpcmsg("disk_create", array($session, $specs));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create disk because: %s\n", $reply->faultString());
}
else {
    $val  = $reply->value();
    $val  = $val->scalarval();
    printf("creating disk#%d\n", $val);
}
</code>


  * Sample code (perl)

<code perl>
my $specs = {};
$specs["size"]  = 2048;
$specs["name"]  = "disk2GB";
$specs["fstype"]  = "ext3";

my $reply  = $proxy->call("disk_create", $session, $specs);

my $disk_id  = $reply->result();
unless (defined $opid) {
    printf "could not create disk because: %s\n", $reply->faultstring;
}
else {
    printf "creating disk#%d\n", $disk_id;
}
</code>

\\
----

 ====== disk_info ======

 === Signature ===
struct disk_info(string **session**, int **disk_id**)

 === Description ===

Return the informations of the specified disk.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **disk_id**: the id of the disk

 === Returns ===
The XML-RPC response will be the informations for the specified disk.
Possible faults are described in section [[error-codes|Error Codes Format]]

  * Sample code (python)
<code python>
import pprint
disk_id  = 123
try:
    disk_info  = proxy.disk_info(session, disk_id)
    print "informations for disk#%s" % (disk_id,)
    pprint.pprint(disk_info)
except xmlrpclib.Fault, e:
    print "could not retrieve informations for disk#%s because: %s" % (disk_id, e.faultString)
</code>

  * Sample code (php)
<code php>
$disk_id  = 123;
$msg  = new xmlrpcmsg("disk_info", array($session, new xmlrpcval($disk_id)));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not retrieve informations of disk#%s because: %s\n", $disk_id, $reply->faultString());
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("informations for disk#%s\n", $disk_id);
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $disk_id  = 123;
my $reply  = $proxy->call("disk_info", $session, $disk_id);
my $info  = $reply->result();
unless (defined $info) {
    printf "could not retrieve informations of disk#%s because: %s\n", $disk_id, $reply->faultstring;
}
else {
    printf "informations for disk#%s\n", $disk_id;
    print Dumper($info);
}
</code>

\\
----

 ====== disk_delete ======

 === Signature ===
int disk_delete(string **session**, int **disk_id**)

 === Description ===

Create a 'disk_delete' operation to delete an unattached disk and return the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **disk_id**: the id of the disk to delete

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
disk_id = 1928
try:
    opid  = proxy.disk_delete(session, disk_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a disk_delete operation for disk#%s because: %s" % (disk_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$disk_id = 1928;
$msg  = new xmlrpcmsg("disk_delete", array($session, new xmlrpcval($disk_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a disk_delete operation for disk#%d because: %s\n", $disk_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $disk_id = 1928;
my $reply  = $proxy->call("disk_delete", $session, $disk_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a disk_delete for disk#%s operation because: %s\n", $disk_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== disk_attach ======

 === Signature ===
int disk_attach(string **session**, int **disk_id**, int **vm_id**)

 === Description ===

Create a 'disk_attach' operation to attach a disk to a VM and return the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **disk_id**: the id of the disk to attach to a VM
  * int **vm_id**: the id of the VM to attach the disk to

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
disk_id = 1928
vm_id = 9876
try:
    opid  = proxy.disk_attach(session, disk_id, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a disk_attach operation for disk#%s on VM#%s because: %s" % (disk_id, vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$disk_id = 1928;
$vm_id = 9876;
$msg  = new xmlrpcmsg("disk_attach", array($session, new xmlrpcval($disk_id), new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a disk_attach operation for disk#%d on VM#%s because: %s\n", $disk_id, $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $disk_id = 1928;
my $vm_id = 9876;
my $reply  = $proxy->call("disk_attach", $session, $disk_id, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a disk_attach for disk#%s on VM#%s operation because: %s\n", $disk_id, $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== disk_detach ======

 === Signature ===
int disk_detach(string **session**, int **disk_id**, int **vm_id**)

 === Description ===

Create a 'disk_detach' operation to detach a disk from a VM and return the operation id.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **disk_id**: the id of the disk to detach from a VM
  * int **vm_id**: the id of the VM to detach the disk from

 === Returns ===
The XML-RPC response will be an operation id.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
disk_id = 1928
vm_id = 9876
try:
    opid  = proxy.disk_detach(session, disk_id, vm_id)
    print "created operation#%s" % (opid,)
except xmlrpclib.Fault, e:
    print "could not create a disk_detach operation for disk#%s on VM#%s because: %s" % (disk_id, vm_id, e.faultString,)
</code>

  * Sample code (php)
<code php>
$disk_id = 1928;
$vm_id = 9876;
$msg  = new xmlrpcmsg("disk_detach", array($session, new xmlrpcval($disk_id), new xmlrpcval($vm_id)));

$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not create a disk_detach operation for disk#%d on VM#%s because: %s\n", $disk_id, $vm_id, $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    printf("created operation#%s\n", $val);
}
</code>

  * Sample code (perl)
<code perl>
my $disk_id = 1928;
my $vm_id = 9876;
my $reply  = $proxy->call("disk_detach", $session, $disk_id, $vm_id);
my $opid  = $reply->result();
unless (defined $opid) {
    printf "could not create a disk_detach operation for disk#%s on VM#%s operation because: %s\n", $disk_id, $vm_id, $reply->faultstring;
}
else {
    printf "created operation#%s\n", $opid;
}
</code>

\\
----

 ====== disk_list ======

 === Signature ===
array disk_list(string **session**)

 === Description ===

Return the list of disks associated to a hosting account.

 === Parameters ===

  * string **session**: the session id (returned by login)

 === Returns ===
The XML-RPC response will be an array of disk ids.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
import pprint
try:
    disks  = proxy.disk_list(session)
    print "disks:"
    pprint.pprint(disks)
except xmlrpclib.Fault, e:
    print "could not retrieve the list of disks because: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("disk_list", array($session));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not retrieve the list of disks because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("disk_list", $session);
my $disks  = $reply->result();
unless (defined $disks) {
    print "could not retrieve the list of disks because: " . $reply->faultstring . "\n";
}
else {
    print Dumper($disks);
}
</code>

\\
----

====== OS methods ======

 ====== os_list ======

 === Signature ===
array os_list(string **session**)

 === Description ===

Return the list of OS images that can be installed on a VM.

 === Parameters ===

  * string **session**: the session id (returned by login)

 === Returns ===
The XML-RPC response will be an array of struct, describing the OS images.
Possible faults are described in section [[error-codes|Error Codes Format]]

 === Sample code ===
  * Sample code (python)
<code python>
import pprint
try:
    oslst  = proxy.os_list(session)
    print "OS images:"
    pprint.pprint(oslst)
except xmlrpclib.Fault, e:
    print "could not retrieve the list of OS images because: %s" % (e.faultString,)
</code>

  * Sample code (php)
<code php>
$msg  = new xmlrpcmsg("os_list", array($session));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not retrieve the list of OS images because: %s\n", $reply->faultString()); 
}
else {
    $val  = php_xmlrpc_decode($reply->value());
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $reply  = $proxy->call("os_list", $session);
my $oslst  = $reply->result();
unless (defined $oslst) {
    print "could not retrieve the list of OS images because: " . $reply->faultstring . "\n";
}
else {
    print Dumper($oslst);
}
</code>

\\
----

====== Operations methods ======



 ===== operation_list =====

 === Signature ===
array operation_list(string **session** [, struct **filter** ])

 === Description ===

Retrieves the last 300 operation IDs matching the specified criterias.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * struct **filter**: a filter struct, containing some or all of the following fields:
    * string **type**: the operation type (for instance: ''vm_create'')
    * string **state**: only get operations in the following state:
      * ALL: all operations
      * PENDING: queued operations
      * RUN: operations being processed
      * ERROR: operations that ended in error and must be modified or canceled
      * CANCEL: operations canceled and terminated
      * DONE: successfully completed operations
    * dateTime.iso8601 **created_after**: select operations created after this date
    * dateTime.iso8601 **created_before**: select operations created before this date
    * dateTime.iso8601 **updated_after**: select operations updated after this date
    * dateTime.iso8601 **updated_before**: select operations updated before this date


 === Returns ===
The XML-RPC response will contain an array of operations IDs (int) or a fault describing the problem.
Possible faults are described in section [[error-codes|Error Codes Format.]]

  * Sample code (python)
<code python>
import pprint
try:
    updated_after  = xmlrpclib.DateTime("2006-01-01")
    updated_before  = xmlrpclib.DateTime("2006-02-01")
    state  = "DONE"
    type  = "vm_create"
    filter  = { "updated_after": updated_after, "updated_before": updated_before, "state": state, "type": vm_create }
    oplist  = proxy.operation_list(session, filter)
    print "operations list:"

    pprint.pprint(oplist)
except xmlrpclib.Fault, e:
    print "could not retrieve operations list because: %s" % e.faultString
</code>

  * Sample code (php)
<code php>
$filter  = new xmlrpcval(array(
    "updated_after"  => new xmlrpcval("20060101T00:00:00", "dateTime.iso8601"),
    "updated_before"  => new xmlrpcval("20060201T00:00:00", "dateTime.iso8601"),
    "state"  => new xmlrpcval("DONE"),
    "type"  => new xmlrpcval("vm_create"),
    ), "struct");

$msg  = new xmlrpcmsg("operation_list", array($session, $filter));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
   printf("could not retrieve operations list because: %s\n", $reply->faultString());
}
else {
   $val  = php_xmlrpc_decode($reply->value());
    print("operations list:\n");
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $filter  = {}
$filter["updated_after"]  = XMLRPC::Data->type("datetime")->value("20060101T00:00:00");
$filter["updated_before"]  = XMLRPC::Data->type("datetime")->value("20060201T00:00:00");
$filter["state"]  = "DONE";
$filter["type"]  = "vm_create";
my $reply  = $proxy->call("operation_list", $session, $filter);
my $oplist  = $reply->result();
unless (defined $oplist) {
    printf "could not retrieve operations list because: %s\n", $reply->faultstring;
}
else {
    print "operations list:\n";
    print Dumper($oplist);
}
</code>

\\
----


 ===== operation_details =====

 === Signature ===
struct operation_details(string **session**, int **opid**)

 === Description ===

Retrieve an operation details.

 === Parameters ===


  * string **session**: the session id (returned by login)
  * int **opid**: the operation ID

 === Returns ===
The XML-RPC response will contain an operation details (struct) or a fault describing the problem.
The returned struct contains the following keys:

  * int **uid**: the operation Unique ID
  * string **type**: the operation type
  * string **state**: the current state of the operation
  * dateTime.iso8601 **date_create**: the date the operation was created
  * dateTime.iso8601 **date_update**: the date the operation was last updated
  * struct **param**: a struct containing the parameters that were used to create the operation. Parameters vary with the state and the operation type.
    * string param_type: Always present, precise the object on which the operation applies. Valid values include:
      * vm: the parameter describe a vm. A "vm_id" field is present.
      * disk: the parameter describe a disk. A "disk_id" field is present.
  * string **comment**: if the operation is in the <i>ERROR</i> state, contains the underlying error message.

Possible faults are described in section [[error-codes|Error Codes Format.]]

  * Sample code (python)
<code python>
import pprint
opid  = 1234
try:
    opdetails  = proxy.operation_details(session, opid)
    pprint.pprint(opdetails)
except xmlrpclib.Fault, e:
    print "could not retrieve operation #%d details because: %s" % (opid, e.faultString)
</code>

  * Sample code (php)
<code php>
$opid  = 1234;
$msg  = new xmlrpcmsg("operation_details", array($session, new xmlrpcval($opid, "int")));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
   printf("could not retrieve operation #%d details because: %s\n", ($opid, $reply->faultString()));
}
else {
   $val  = php_xmlrpc_decode($reply->value());
    print_r($val);
}
</code>

  * Sample code (perl)
<code perl>
my $opid  = 1234;
my $reply  = $proxy->call("operation_details", $session, $opid);
my $opdetails  = $reply->result();
unless (defined $opdetails) {
    printf "could not retrieve operation #%d details because: %s\n", $opid, $reply->faultstring;
}
else {
    print Dumper($opdetails);
}
</code>

\\
----

 ===== operation_cancel =====

 === Signature ===
boolean operation_cancel(string **session**, int **opid**)

 === Description ===

Cancel an operation.

 === Parameters ===

  * string **session**: the session id (returned by login)
  * int **opid**: the operation to cancel

 === Returns ===
The XML-RPC response will return True (boolean) or a fault describing the problem.
Possible faults are described in section [[error-codes|Error Codes Format.]]

  * Sample code (python)
<code python>
opid  = 1234
try:
    proxy.operation_cancel(session, opid)
except xmlrpclib.Fault, e:
    print "could not cancel operation #%d because: %s" % (opid, e.faultString)
</code>

  * Sample code (php)
<code php>
$opid  = 1234;
$msg  = new xmlrpcmsg("operation_cancel", array($session, new xmlrpcval($opid, "int")));
$reply  = $proxy->send($msg);
if ($reply->faultCode()) {
    printf("could not cancel operation #%d because: %s\n", $opid, $reply->faultString());
}
</code>

  * Sample code (perl)
<code perl>
my $opid  = 1234;
my $reply  = $proxy->call("operation_cancel", $session, $opid);
my $result  = $reply->result();
unless (defined $result) {
    printf "could not cancel operation #%d because: %s\n", $opid, $reply->faultstring;
}
</code>