Virtual Machine API Reference

Methods

hosting.vm.can_migrate(apikey, vm_id)
Check if a vm can migrate between datacenters.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – migration capabilities for vm
hosting.vm.count(apikey[, opts=nil])

Count virtual machines.

Parameters:
Returns:

int – number of VMs
hosting.vm.create(apikey, vm_spec)
Create a new virtual machine using attributes specified by vm_spec.
Disk, iface, and vm must be in the same datacenter.
Parameters:
Returns:

list of struct – iface_create operation if an iface was created, vm_create operation
hosting.vm.create_from(apikey, vm_spec, disk_spec, src_disk_id)
Create a disk and a virtual machine.
This is a convenient method to do the disk.create and vm.create in a single API call.
Parameters:
Returns:

list of struct – disk_create, iface_create and vm_create operation
hosting.vm.delete(apikey, vm_id)
Delete a VM.
Delete the disk attached in position 0, i.e. the disk used as system disk.
Also delete the first network interface.
Detach all extra disks and network interfaces.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_delete operation
hosting.vm.disk_attach(apikey, vm_id, disk_id[, options=nil])
Attach a disk to a virtual machine.
To access the disk data inside the VM, it MUST be attached to the VM.
When options.position is 0, swaps position with current disk 0.
A disk can be attached to only one VM.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • disk_id (int) – unique identifier of the disk to attach
  • options (struct) – options for the disk attachment
Returns:

struct – disk_attach operation
hosting.vm.disk_detach(apikey, vm_id, disk_id)
Detach a disk from a virtual machine.
If the disk position is 0, i.e. the system disk, the virtual machine must be halted to detach the disk.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • disk_id (int) – unique identifier of the disk to attach
Returns:

struct – disk_detach operation
hosting.vm.disk_rollback(apikey, snapshot_id)
Helper method to rollback a disk (instead of hosting.disk.rollback_from()).

Rollbacking a disk is done by creating a new disk using the given snapshot as source, the old disk is deleted afterwards. So, if the disk you try to rollback is attached to the VM, this method will create operations to stop the VM, detach the old disk, create and attach the new one, and start the VM.

Parameters:
  • apikey (string) – API connection key
  • snapshot_id (int) – snapshot unique identifier
Returns:

list of struct – operations
hosting.vm.iface_attach(apikey, vm_id, iface_id)
Attach a network interface to the VM.
No magic update is made on the interface bandwidth when attaching.
You have to manually update interface bandwidth as you desire.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • iface_id (int) – network interface unique identifier
Returns:

struct – iface_attach operation
hosting.vm.iface_detach(apikey, vm_id, iface_id)
Detach a network interface from the VM.
There is no restriction on detaching every interface.
The VM will be unreachable if you choose to detach all interfaces.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • iface_id (int) – network interface unique identifier
Returns:

struct – iface_detach operation
hosting.vm.info(apikey, vm_id)

Get information about a virtual machine.

Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – VM information
hosting.vm.list(apikey[, opts=nil])

List virtual machines.

Parameters:
Returns:

struct – list of VMs descriptions
hosting.vm.migrate(apikey, vm_id[, finalize_migration=False])
Migrate a vm between datacenters.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • finalize_migration (boolean) – finalize migration
Returns:

struct – hosting_migration_vm operation
hosting.vm.reboot(apikey, vm_id)
Reboot a Virtual Machine.
A reboot message is sent to the VM. If it does not reboot properly after 2 minutes, it is hard-reset (“power cycled”).
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_reboot operation
hosting.vm.start(apikey, vm_id[, params=nil])

Start a virtual machine.

Parameters:
Returns:

struct – vm_start operation
hosting.vm.stop(apikey, vm_id)
Stop a virtual machine.
A stop message is sent to the VM. If it does not shutdown properly after two stop messages and 5 minutes, the VM is “power switched”.
Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
Returns:

struct – vm_stop operation
hosting.vm.update(apikey, vm_id, update_spec)

Update a virtual machine using attributes specified by update_spec.

Parameters:
  • apikey (string) – API connection key
  • vm_id (int) – VM unique identifier
  • update_spec (struct) – specifications of the virtual machine to update
Returns:

struct – vm_update operation

Parameters

Disk

parameter of disk.create_from(), disk.delete(), disk.info(), disk.migrate(), disk.rollback_from(), disk.update(), hosting.disk.create_from(), hosting.disk.delete(), hosting.disk.info(), hosting.disk.migrate(), hosting.disk.rollback_from(), hosting.disk.update(), hosting.vm.create_from(), hosting.vm.disk_attach(), hosting.vm.disk_detach(), hosting.vm.disk_rollback(), vm.create_from(), vm.disk_attach(), vm.disk_detach() and vm.disk_rollback()

used by VMDescription

Iface

parameter of hosting.iface.delete(), hosting.iface.info(), hosting.iface.migrate(), hosting.iface.update(), hosting.vm.iface_attach(), hosting.vm.iface_detach(), iface.delete(), iface.info(), iface.migrate(), iface.update(), vm.iface_attach() and vm.iface_detach()

used by VMCreateFromDescription and VMDescription

IPVersion

used by IPCountOptions, IPListOptions, IfaceDescription, VMCreateFromDescription and VMDescription

Name Description
4 ipv4
6 ipv6
4 ipv4
6 ipv6
VM

parameter of hosting.vm.can_migrate(), hosting.vm.delete(), hosting.vm.disk_attach(), hosting.vm.disk_detach(), hosting.vm.iface_attach(), hosting.vm.iface_detach(), hosting.vm.info(), hosting.vm.migrate(), hosting.vm.reboot(), hosting.vm.start(), hosting.vm.stop(), hosting.vm.update(), vm.delete(), vm.disk_attach(), vm.disk_detach(), vm.iface_attach(), vm.iface_detach(), vm.info(), vm.migrate(), vm.reboot(), vm.start(), vm.stop() and vm.update()

VMCountOptions

parameter of hosting.vm.count() and vm.count()

Name Default Type Mandatory
cores   int or array of int no
datacenter_id   int or array of int no
date_created   string no
farm   array of string or string no
hostname   array of string or string no
id   int or array of int no
memory   int or array of int no
state   string no
~hostname   string no
VMCreateFromDescription

parameter of hosting.vm.create_from() and vm.create_from()

Changed in version 3.3.36: key ai_active is deprecated and will be removed in the next major release.
.

Changed in version 3.3.34: keys farm, ssh_key have changed.
farm optional parameter added.
ssh_key might also be a List.

Changed in version 3.3.28: key hostname has changed.
hostname parameter is now optional.

Changed in version 3.3.0: key shares is deprecated and will be removed in the next major release.
.

Name Default Type Mandatory
datacenter_id   int yes
id of the datacenter
ai_active 0 int no
this parameter has no effect, keep for compatibility
bandwidth 102400 double no
network bandwidth in bit/s used to create the VM’s first
cores 1 int no
number of cpu
farm   string no
hostname   string no
hostname of the VM
iface_id   int no
id of the interface the vm will be
ip_version 4 string no
version of the created ip if iface_id is provided
keys   array of int no
ids of existing ssh keys to use
login   string no
login to create on the VM
memory 512 int no
quantity of RAM in Megabytes to allocate. multiple of 64
password   string no
password to set to the root account and the created
run   string no
shell command that will run at the first startup of a VM.
script   string no
script contents, that will run at the first startup of a
script_args   string no
shares   int no
this parameter has no effect, keep for compatibility
ssh_key   array of string or string no
ssh public key to authorize to connect to the root
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate
VMDescription

parameter of hosting.vm.create() and vm.create()

Changed in version 3.3.36: key ai_active is deprecated and will be removed in the next major release.
.

Changed in version 3.3.34: key farm has changed.
farm optional parameter added.

Changed in version 3.3.28: key hostname has changed.
hostname parameter is now optional.

Changed in version 3.3.0: key shares is deprecated and will be removed in the next major release.
.

Name Default Type Mandatory
datacenter_id   int yes
id of the datacenter
sys_disk_id   int yes
id of the system disk used to
ai_active 0 int no
this parameter has no effect, keep for compatibility
bandwidth 102400 double no
network bandwidth in bit/s used to create the VM’s first
cores 1 int no
number of cpu
farm   string no
hostname   string no
hostname of the VM
iface_id   int no
id of the interface the vm will be
ip_version 4 string no
version of the created ip if iface_id is provided
keys   array of int no
ids of existing ssh keys to use
login   string no
login to create on the VM
memory 512 int no
quantity of RAM in Megabytes to allocate. multiple of 64
password   string no
password to set to the root account and the created
run   string no
shell command that will run at the first startup of a VM.
script   string no
script contents, that will run at the first startup of a
script_args   string no
shares   int no
this parameter has no effect, keep for compatibility
ssh_key   array of string or string no
ssh public key to authorize to connect to the root
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate
VMDiskAttachOptions

parameter of hosting.vm.disk_attach() and vm.disk_attach()

Name Default Type Mandatory
access   string no
read or read/write
position   int no
the desired position of the disk
VMGraphURLs

used by ServerReturn and VMReturn

Name Default Type Mandatory
vcpu   array of string yes
vdi   array of string yes
vif   array of string yes
VMListOptions

parameter of hosting.vm.list() and vm.list()

Name Default Type Mandatory
cores   int or array of int no
datacenter_id   int or array of int no
date_created   string no
farm   array of string or string no
hostname   array of string or string no
id   int or array of int no
items_per_page 100 int no
number of items returned for the pagination
memory   int or array of int no
page 0 int no
page number for pagination offset
sort_by   string no
used to sort returned items: cores, datacenter_id, date_created, farm, hostname, id, memory, state
state   string no
~hostname   string no
VMStart

parameter of hosting.vm.start() and vm.start()

Changed in version 3.3.34: key ssh_key has changed.
ssh_key might also be a List.

Name Default Type Mandatory
farm   string no
keys   array of int no
login   string no
password   string no
run   string no
script   string no
script_args   string no
ssh_key   array of string or string no
VMState

used by VMCountOptions, VMListOptions and VMReturn

Name Description
paused vm is alive but not running
running vm is alive and running
halted vm is stopped
locked vm is paused by Gandi for a legal reason
being_created vm does not exist yet
deleted vm is deleted
being_migrated vm is being migrated to another DC
VMUpdate

parameter of hosting.vm.update() and vm.update()

Name Default Type Mandatory
console   boolean no
activate the console
cores   int no
number of cpu
memory   int no
quantity of RAM in megabytes. A multiple of 64
password   string no
shares   int no
compatibility reason, do nothing
vm_max_memory   int no
maximum quantity of RAM in megabytes to allocate
ProbeReturn

used by VMReturn

Name Type
datasource string
probe device datasource in:
date_created dateTime.iso8601
probe creation date
device_type string
probe device type in: ‘cpu’, ‘iface’,
id int
id of the probe
name string
name of the probe
status string
the probe is active and should be used
HVMState

used by VMReturn

Name Description
running vm is alive and running
halted vm is stopped
unknown vm stat unavailable

Returns

PublicVMCanMigrate

returned by hosting.vm.can_migrate()

VMReturn

returned by hosting.vm.info(), hosting.vm.list(), vm.info() and vm.list()

Changed in version 3.3.36: key is_migrating has been added.
is_migrating parameter.

Changed in version 3.3.34: key farm has been added.
farm parameter.

Changed in version 3.3.30: key hvm_state has been added.
hvm_state parameter.

Changed in version 3.3.3: keys flex_shares, triggers are deprecated and will be removed in the next major release.
.
.

Changed in version 3.3.25: key graph_urls is deprecated and will be removed in the next major release.
.

Name Type
ai_active int
console int
console_url string
only returned with method hosting.vm.info() and vm.info()
cores int
datacenter_id int
date_created dateTime.iso8601
date_updated dateTime.iso8601
description string
disks array of struct
only returned with method hosting.vm.info() and vm.info()
disks_id struct
entity_id string
farm string
flex_shares int
graph_urls struct
only returned with method hosting.vm.info() and vm.info()
hostname string
hvm_state string
only returned with method hosting.vm.info() and vm.info()
id int
ifaces array of struct
only returned with method hosting.vm.info() and vm.info()
ifaces_id struct
is_migrating boolean
memory int
probes struct
only returned with method hosting.vm.info() and vm.info()
state string
triggers array of struct
only returned with method hosting.vm.info() and vm.info()
vm_max_memory int
VMTriggersReturn

used by VMReturn

Name Type
datasource string
date_created dateTime.iso8601
device_number int
device_type string
duration int
id int
max_value int
min_value int
recovery_duration int
vm_id int