Get List of VSs

There are several ways to request the list of VSs. Below you can find the following examples:

To get the list of virtual servers with all related resources, use the following request:

GET /virtual_machines.xml
GET /virtual_machines.json

XML Request example

curl -i -X GET -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:password --url http://onapp.test/virtual_machines.xml

JSON Request example

curl -i -X GET -H 'Accept: application/json' -H 'Content-type: application/json' -u user:password --url http://onapp.test/virtual_machines.json


XML Output example

<?xml version="1.0" encoding="UTF-8"?>
<virtual_machines>
<virtual_machine>
<add_to_marketplace nil="true"></add_to_marketplace>
<admin_note nil="true"></admin_note>
<allowed_hot_migrate type="boolean">true</allowed_hot_migrate>
<allowed_swap type="boolean">true</allowed_swap>
<booted type="boolean">true</booted>
<built type="boolean">true</built>
<cores_per_socket type="integer">0</cores_per_socket>
<cpu_shares type="integer">1</cpu_shares>
<cpu_sockets nil="true"/>
<cpu_threads nil="true"/>
<cpu_units type="integer">200</cpu_units>
<cpus type="integer">1</cpus>
<created_at type="datetime">2011-11-01T17:11:58+03:00</created_at>
<customer_network_id nil="true"/>
<deleted_at nil="true"/>
<edge_server_type nil="true"/>
<enable_autoscale type="boolean">true</enable_autoscale>
<enable_monitis type="boolean">true</enable_monitis>
<firewall_notrack type="boolean">false</firewall_notrack>
<fqdn>autobackup</fqdn>
<hot_add_cpu nil="true"/>
<hot_add_memory nil="true"/>
<hypervisor_id type="integer">2</hypervisor_id>
<id type="integer">000</id>
<identifier>iskngs9dve0hdg</identifier>
<initial_root_password>791791</initial_root_password>
<initial_root_password_encrypted type="boolean">false</initial_root_password_encrypted>
<instance_package_id nil="true"/>
<iso_id nil="true"/>
<label>YR_autobackup</label>
<local_remote_access_ip_address>000.000.00.00</local_remote_access_ip_address>
<local_remote_access_port type="integer">0000</local_remote_access_port>
<locked type="boolean">false</locked>
<memory type="integer">1632</memory>
<min_disk_size type="integer">5</min_disk_size>
<note nil="true"></note>
<operating_system>linux</operating_system>
<operating_system_distro>rhel</operating_system_distro>
<preferred_hvs type="array"/>
<recovery_mode type="boolean">false</recovery_mode>
<remote_access_password>os3ajolb1buj</remote_access_password>
<service_password nil="true"/>
<state>new</state>
<storage_server_type nil="true"/>
<strict_virtual_machine_id nil="true"></strict_virtual_machine_id>
<suspended type="boolean">false</suspended>
<template_id type="integer">8</template_id>
<template_label>CentOS 5.6 x86</template_label>
<template_version>1.5</template_version>
<time_zone>Atlantic Time (Canada)</time_zone>
<updated_at type="datetime">2015-03-04T12:06:21+02:00</updated_at>
<user_id type="integer">5</user_id>
<vip nil="true"></vip>
<xen_id type="integer">12</xen_id>
<virsh_console type="boolean">false</virsh_console>
<ip_addresses type="array">
<ip_address>
<address>000.000.000.000</address>
<broadcast>000.000.000.000</broadcast>
<created_at type="datetime">2011-10-10T12:31:12+03:00</created_at>
<customer_network_id nil="true"/>
<disallowed_primary type="boolean">false</disallowed_primary>
<gateway>000.000.000.000</gateway>
<hypervisor_id nil="true"/>
<id type="integer">2</id>
<ip_address_pool_id nil="true"/>
<network_address>000.000.000.000</network_address>
<network_id type="integer">1</network_id>
<pxe type="boolean">false</pxe>
<updated_at type="datetime">2011-11-01T17:39:13+03:00</updated_at>
<user_id nil="true"/>
<free type="boolean">false</free>
<netmask>000.000.000.000</netmask>
</ip_address>
</ip_addresses>
<monthly_bandwidth_used>0</monthly_bandwidth_used>
<total_disk_size type="integer">6</total_disk_size>
<price_per_hour type="float">0.0</price_per_hour>
<price_per_hour_powered_off type="float">0.0</price_per_hour_powered_off>
<support_incremental_backups type="boolean">false</support_incremental_backups>
<cpu_priority type="integer">1</cpu_priority>
<built_from_iso type="boolean">true</built_from_iso>
<acceleration type="boolean">false</acceleration>
<hypervisor_type>kvm</hypervisor_type>
</virtual_machine>
...
<virtual_machine></virtual_machine>
...
</virtual_machine>

Where:

acceleration - true if acceleration is enabled for the VS ; otherwise false

add_to_marketplace - empty for VSs; used for edge servers only

admin_note - an optional note of the administrator

allowed_hot_migrate - true if the template, on which the VS is based, supports hot migration; otherwise false

allowed_swap - true if swap disk is allowed (depends on the template the VS is based on); otherwise false

booted - true if the VS is running, otherwise false

built - true if the VS is built, otherwise false

built_from_iso - true if the VS is built from ISO; otherwise false

cores_per_socket - the amount of cores per socket

cpu_shares CPU priority in percent's

cpu_sockets - the amount of CPU sockets per core. This parameter can be set for KVM compute resources only by those users who have Enable CPU topology permission granted

cpu_threads - the amount of CPU threads per core. This parameter can be set for KVM compute resources only by those users who have Enable CPU topology permission granted

cpu_units - the amount of CPU units per core if the CPU priority is replaced with CPU units in user bucket.

cpus - the number of allocated CPU cores

created_at - the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format

customer_network_id - ID of a customer network

deleted_at - time when the VS was deleted

edge_server_type - true if this is the edge server 

enable_autoscale - true if autoscaling is allowed for this VS

enable_monitis - deprecated attribute; will be removed in upcoming release

firewall_notrack - true if the NOTRACK rule is set in iptables

fqdn the name of your host

hot_add_cpu - true, if the CPU parameter can be changed without rebooting the VS, otherwise false

hot_add_memory - true, if the memory parameter can be changed without rebooting the VS, otherwise false

hypervisor_id - the ID of the compute resource used by this VS

hypervisor_type - the type of the compute resource the VS is built on (for example: xen, kvm, vcloud, vmware)

id - the VS ID

identifier - the VS identifier

initial_root_password - the VS root password

initial_root_password_encrypted - true, if the root password is encrypted, otherwise false.

instance_package_id - ID of the instance package

iso_id - the ID of the ISO the VS is based on

label - the VS label

local_remote_access_ip_address IP address used for remote access

local_remote_access_port - the port ID used for console access

locked - true if the VS is locked; otherwise false

memory - the RAM size allocated to this VS

min_disk_size - the minimum disk size required to build a VS from a specified template

note - an optional reminder for this VS made by a user account

operating_system - operating system used by the VS

operating_system_distro - the distribution of the OS from which this VS is built

preferred_hvs - the array of preferable compute resources based on compute zone that meet some VS configuration settings

recovery_mode - true if recovery mode allowed. Otherwise false

remote_access_password - the password for the remote access

service_password - service account password

state – parameter reserved for future use

storage_server_type - true if this is a storage server

strict_virtual_machine_id - the ID of a virtual server that will never reside on the same compute resource with this VS

suspended true if VS is suspended, otherwise false

template_id - the ID of the template the VS is based on

template_label - the name of the template from which this VS is built

template_version - the version of the template from which this VS is built

 time_zone - the time zone set for the VS. This parameter is applicable only to Windows KVM and XEN virtual servers.

Currently, the time zone is set at the Compute resource side only. Therefore, users need to set the target time zone inside a Windows VS manually. Setting correct time zone at the Compute resource side helps to keep correct time inside a VS after starting it if time synchronization is not completed for some reason.

updated_at - the date when the VS was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format

user_id - the ID of a user assigned to this VS

vip - true if the VS has VIP status (gives migration priority)

xen_id - the VS ID set by the virtualization engine

(lightbulb) virsh_console - true, if Virsh console is enabled for the VS, otherwise, false

ip_addresses  - an array of IP addresses assigned to this VS and their details:

address - IP address

 broadcast - broadcast address

 created_at - the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format

customer_network_id - the ID of the customer VLAN the IP address belongs to

disallowed_primary - true if not allowed to be used as primary, otherwise false

gateway - gateway address

hypervisor_id - the ID of a compute resource the IP address is associated with

id - the ID of the IP address

ip_address_pool_id - ID of the IP address pool the IP address is associated with

network_address - the address of the network

network_id - the ID of the network

pxe - true, if this address can be used for cloudbooting a compute resource

updated_at - the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format

user_id - the ID of the user this IP address is assigned to

free - true if free, otherwise, false

netmask - netmask for the IP address

monthly_bandwidth_used - VS monthly bandwidth in KB

total_disk_size - the total disk size in GB of all disks assigned to VS

price_per_hour - server's price per hour

price_per_hour_powered_off - price per hour when server is powered off

support_incremental_backups - 1, if virtual server supports incremental backups, and 0 if it does not

cpu_priority  - this is a new parameter reserved for further use; currently will have the same value as cpu_shares


To get the list of VSs, use the following request:

GET /virtual_machines.xml?short
GET /virtual_machines.json?short

XML Output example

<virtual_machines type="array">
<virtual_machine>
<add_to_marketplace nil="true" />
<admin_note nil="true" />
<allowed_hot_migrate type="boolean">false</allowed_hot_migrate>
<allowed_swap type="boolean">true</allowed_swap>
<booted type="boolean">false</booted>
<built type="boolean">false</built>
<cores_per_socket type="integer">0</cores_per_socket>
<cpu_shares type="integer">100</cpu_shares>
<cpu_sockets nil="true" />
<cpu_threads nil="true" />
<cpu_units type="integer">1000</cpu_units>
<cpus type="integer">1</cpus>
<created_at type="datetime">2015-06-16T19:41:01+00:00</created_at>
<customer_network_id nil="true" />
<deleted_at nil="true" />
<edge_server_type nil="true" />
<enable_autoscale nil="true" />
<enable_monitis type="boolean">false</enable_monitis>
<firewall_notrack type="boolean">false</firewall_notrack>
<fqdn>example.onappdemo.com</fqdn>
<hot_add_cpu nil="true" />
<hot_add_memory nil="true" />
<hypervisor_id type="integer">1</hypervisor_id>
<id type="integer">1</id>
<identifier>s34b4zqkkh3gki</identifier>
<initial_root_password>ycW50dZ0ryjj</initial_root_password>
<initial_root_password_encrypted type="boolean">false</initial_root_password_encrypted>
<instance_package_id nil="true" />
<iso_id nil="true" />
<label>example.onappdemo.com</label>
<local_remote_access_ip_address nil="true" />
<local_remote_access_port nil="true" />
<locked type="boolean">false</locked>
<memory type="integer">512</memory>
<min_disk_size type="integer">5</min_disk_size>
<note nil="true" />
<operating_system>linux</operating_system>
<operating_system_distro>centos</operating_system_distro>
<preferred_hvs type="array" />
<recovery_mode nil="true" />
<remote_access_password nil="true" />
<service_password nil="true" />
<state>new</state>
<storage_server_type nil="true" />
<strict_virtual_machine_id nil="true" />
<suspended type="boolean">false</suspended>
<template_id type="integer">4</template_id>
<template_label>CentOS 5.3</template_label>
<template_version>1.5</template_version>
<time_zone nil="true" />
<updated_at type="datetime">2015-06-16T19:41:02+00:00</updated_at>
<user_id type="integer">3</user_id>
<vip nil="true" />
<xen_id nil="true" />
</virtual_machine>
</virtual_machines>

Page History

v.6.1 Edge 2

Added the virsh_console parameter. 

v.6.0

Removed the acceleration_status parameter.

v.5.8

Replaced the hostname parameter with fqdn parameter

v.5.3

Added the template_version parameter

v.4.3

Added the hypervisor_type parameter.

v.4.2

Added the following parameters:

  • acceleration
  • acceleration_status
  • built_from_iso

v.4.1 

Added the time_zone parameter.