• Description
• User cases

• Session methods
  • login

• Account methods
  • account_currency
  • account_balance

• Hosting account methods
  • hosting_account_info
  • hosting_account_product_add
  • hosting_account_product_renew
  • hosting_account_product_remove
  • hosting_account_product_update

• Servers methods
  • vm_create
  • vm_info
  • vm_list
  • vm_update
  • vm_delete
  • vm_start
  • vm_stop
  • vm_reboot
  • vm_disk_list
  • vm_disk_link

• Disk methods
  • disk_create
  • disk_info
  • disk_delete
  • disk_attach
  • disk_detach
  • disk_list

• Operations methods
  • operation_list
  • operation_details
  • operation_cancel

• Misc methods
• os_list

• Error codes format
• Description
• Qualification 1 - Server
• Qualification 2 - Data

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

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

string login(string login, string password [, boolean safe])

Log in to the XML-RPC interface and retrieve a session id.

• string login: the user login
• string password: the user password

• boolean safe: whether or not log in 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.
  • False: Do not log in safe mode.

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

• Python logging in with safe mode

import sys 
import xmlrpclib
proxy  = xmlrpclib.ServerProxy("https://api.gandi.net/hosting/")
try:
    session  = proxy.login("AA1234-GANDI", "mypassword", True)
except xmlrpclib.Fault, e:
    print "could not login because: " + e.faultString
    sys.exit(67)

• Php logging in with safe mode

<?php
require_once("xmlrpc.inc");
 
$proxy  = new xmlrpc_client("https://api.gandi.net/hosting/");
$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();
?>

• perl logging in with safe mode

my $safe_mode  = XMLRPC::Data->type('boolean')->value(1);
my $proxy  = XMLRPC::Lite->proxy("https://api.gandi.net/hosting/");
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;

string account_currency(string session)

Retrieve the currency name used with this prepaid account.

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

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

• Sample code (python)

print "prepaid account currency: %s" % proxy.account_currency(session)

• Sample 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";

• Sample code (perl)

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

double account_balance(string session)

Retrieve the prepaid account balance.

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

The XML-RPC response will contain the balance of the account (double). Possible faults are described in section Error Codes Format.

• Sample code (python)

print "prepaid account balance: %d"  % proxy.account_balance(session)

• Sample 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";

• Sample code (perl)

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

struct hosting_account_info(string session)

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

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

The XML-RPC response will be the informations for this account. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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);
}

int hosting_account_product_add(string session, string product_name, int quantity, string duration)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int hosting_account_product_renew(string session, int product_id, string duration)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int hosting_account_product_remove(string session, int product_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int hosting_account_product_update(string session, int product_id, int quantity)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

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

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

• 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

The XML-RPC response will be a VM ID. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

struct vm_info(string session, int vm_id)

Return the informations of the specified VM.

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

The XML-RPC response will be the informations for the specified VM. Possible faults are described in section Error Codes Format

• Sample 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)

• Sample 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);
}

• Sample 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);
}

array vm_list(string session)

Return the list of VMs associated to a hosting account.

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

The XML-RPC response will be an array of VM ids. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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);
}

int vm_update(string session, int vm_id, struct specs)

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

• 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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int vm_delete(string session, int vm_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int vm_start(string session, int vm_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int vm_stop(string session, int vm_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int vm_reboot(string session, int vm_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int disk_create(string session, struct specs)

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

• 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

The XML-RPC response will be a disk ID. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

struct disk_info(string session, int disk_id)

Return the informations of the specified disk.

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

The XML-RPC response will be the informations for the specified disk. Possible faults are described in section Error Codes Format

• Sample 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)

• Sample 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);
}

• Sample 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);
}

int disk_delete(string session, int disk_id)

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

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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int disk_attach(string session, int disk_id, int vm_id)

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

• 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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

int disk_detach(string session, int disk_id, int vm_id)

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

• 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

The XML-RPC response will be an operation id. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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;
}

array disk_list(string session)

Return the list of disks associated to a hosting account.

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

The XML-RPC response will be an array of disk ids. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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);
}

array os_list(string session)

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

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

The XML-RPC response will be an array of struct, describing the OS images. Possible faults are described in section Error Codes Format

• Sample 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,)

• Sample 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);
}

• Sample 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);
}

array operation_list(string session [, struct filter ])

Retrieves the last 300 operation IDs matching the specified criterias.

• 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

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

• Sample 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

• Sample 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);
}

• Sample 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);
}

struct operation_details(string session, int opid)

Retrieve an operation details.

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

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

• Sample 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)

• Sample 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);
}

• Sample 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);
}

boolean operation_cancel(string session, int opid)

Cancel an operation.

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

The XML-RPC response will return True (boolean) or a fault describing the problem. Possible faults are described in section Error Codes Format.

• Sample 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)

• Sample 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());
}

• Sample 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;
}