vms collection provides information about virtual machines in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="vms" link obtained from the entry point URI (see Chapter 4, Entry Point).
| Element | Type | Description | Properties |
|---|---|---|---|
name
| string |
A user-supplied human readable name for the virtual machine. The name is unique across all virtual machine resources.
|
|
description
| string | A free-form user-supplied human readable description of the virtual machine | |
link rel="disks"
| string | A link to the disks sub-collection for virtual machine resources |
|
link rel="nics"
| string | A link to the network interface sub-collection for virtual machine resources |
|
link rel="cdroms"
| string | A link to the cdroms sub-collection for virtual machine resources |
|
link rel="snapshots"
| string | A link to the snapshots sub-collection for virtual machine resources |
|
link rel="users"
| string | A link to the users sub-collection for virtual machine resources |
|
link rel="tags"
| string | A link to the tags sub-collection for virtual machine resources |
|
link rel="permissions"
| string | A link to the sub-collection for virtual machine permissions. See Section 8.3.9, “ Permissions ” |
|
link rel="statistics"
| string | A link to the statistics sub-collection for virtual machine resources |
|
type
| enumerated |
The virtual machine type. A list of enumerated values are available in capabilities. See Section 7.1.8, “Virtual Machine Types”
|
|
status
| See below | The virtual machine status |
|
memory
| integer | The amount of memory allocated to the guest in bytes | |
cpu
| complex |
The CPU topology i.e. number of sockets and cores available to the guest
| |
os type
|
string, e.g. RHEL5 or WindowsXP
| The guest operating system type | |
os boot dev=
| enumerated |
A list of boot devices described by a dev attribute on a boot element. A list of enumerated values are available in capabilities. See Section 7.1.9, “Boot Devices”
| |
os kernel
| string | A path to a kernel image which the virtual machine is configured to boot from | |
os initrd
| string | A path to an initrd image to be used with the kernel above | |
os cmdline
| string | A kernel command line parameter string to be used with the defined kernel | |
high_availability
| complex |
Set enabled to true if the virtual machine should be automatically restarted if the host crashes. A priority element controls the order in which Virtual Machines are re-started
|
|
display
| complex |
The display type (either vnc or spice), port, and the number of monitors
|
|
cluster
| complex | A reference to the cluster on which this virtual machine will run. See Chapter 10, Host Clusters |
|
template
| complex | A reference to the template on which this virtual machine is based. |
|
start_time
|
xsd:dateTime format: YYYY-MM-DDThh:mm:ss
| The date and time at which this virtual machine was started |
|
creation_time
|
xsd:dateTime format: YYYY-MM-DDThh:mm:ss
| The date and time at which this virtual machine was created |
|
timezone
|
tz database format: Area/Location
| The timezone for this virtual machine. Only certain timezones are allowed as specified in Appendix B, Timezones | |
origin
|
One of rhev, vmware or xen
| The system from which this virtual machine originated |
|
stateless
| boolean: true or false |
true if the virtual machine is stateless. A stateless virtual machine has a snapshot of its disk image taken at boot and deleted at shutdown, meaning state changes will not persist after a reboot. One of true or false.
| |
placement_policy
| complex |
Sets the placement policy for virtual machine migration. Requires a default host and an affinity (one of migratable, user_migratable or pinned).
| |
memory_policy
| complex |
Sets the memory policy for virtual machines. Defines the minimum amount of guaranteed memory on a host in order for the virtual machine to run.
| |
custom_properties
| complex |
A set of user-defined environment variable passed as parameters to custom scripts. Each custom_property contains name and value attributes. A list of enumerated values are available in capabilities. See Section 7.1.16, “Custom Properties”
| |
guest_info
| complex |
A reference to the guest client information. Includes an ip element with an address attribute.
|
|
vmpool
| complex | A reference to the pool for this virtual machine. See Chapter 16, Virtual Machine Pools |
|
status contains one of the following enumerative values: UNASSIGNED, DOWN, UP, POWERING_UP, POWERED_DOWN, PAUSED, MIGRATING_FROM, MIGRATING_TO, UNKNOWN, NOT_RESPONDING, WAIT_FOR_LAUNCH, REBOOT_IN_PROGRESS, SAVING_STATE, RESTORING_STATE, SUSPENDED, IMAGE_ILLEGAL, IMAGE_LOCKED or POWERING_DOWN.
<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
<name>vm1</name>
<description>Virtual Machine 1</description>
<actions>
<link rel="start"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/start"/>
<link rel="stop"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/stop"/>
<link rel="shutdown"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/shutdown"/>
<link rel="suspend"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/suspend"/>
<link rel="detach"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/detach"/>
<link rel="migrate"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/migrate"/>
<link rel="export"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/export"/>
<link rel="import"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
<link rel="move"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move"/>
<link rel="ticket"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/ticket"/>
</actions>
<link rel="disks"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks"/>
<link rel="nics"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics"/>
<link rel="cdroms"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/cdroms"/>
<link rel="snapshots"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/snapshots"/>
<link rel="users"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/users"/>
<link rel="tags"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/tags"/>
<link rel="permissions"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/permissions"/>
<link rel="statistics"
href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/statistics"/>
<type>desktop</type>
<status>UP</status>
<memory>536870912</memory>
<cpu>
<topology cores="1" sockets="1"/>
</cpu>
<os>
<boot dev="hd"/>
<kernel/>
<initrd/>
<cmdline/>
</os>
<highly_available>
<enabled>true</enabled>
<priority>20</priority>
</highly_available>
<display>
<type>vnc</type>
<port>5910</port>
<monitors>1</monitors>
</display>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<template id="00000000-0000-0000-0000-000000000000"
href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
<start_time>2010-18-16T13:14:15</start_time>
<creation_time>2010-08-16T14:24:29</creation_time>
<origin>rhev</origin>
<stateless>false</stateless>
<placement_policy>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
<affinity>migratable</affinity>
</placement_policy>
<memory_policy>
<guaranteed>536870912</guaranteed>
</memory_policy>
<custom_properties>
<custom_property value="124" name="sndbuf"/>
</custom_properties>
<guest_info>
<ip address="192.168.0.25"/>
</guest_info>
<timezone>Europe/London</timezone>
</vm>
name, template and cluster elements are required. The template and cluster are identified with id or name. See Section 8.3.2, “ Creating a Resource ” for more information.
POST /rhevm-api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm2</name>
<description>Virtual Machine 2</description>
<type>desktop</type>
<memory>536870912</memory>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<os>
<boot dev="hd"/>
</os>
</vm>
name, description, type, memory, cpu topology, os and stateless properties are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.
PUT /rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<memory>1073741824</memory>
</vm>
disks sub-collection represents all virtual hard disk devices on a virtual machine. A disks representation contains the following properties:
| Element | Type | Description | Properties |
|---|---|---|---|
size
| integer | Size of the disk in bytes |
|
type
| enumerated |
The type (function) of the disk device. A list of enumerated values is available in capabilities. See Section 7.1.12, “Disk Types”
|
|
status
|
One of ILLEGAL, INVALID, LOCKED or OK
| The status of the disk device |
|
interface
| enumerated |
The type of interface driver used to connect to the disk device. A list of enumerated values is available in capabilities. See Section 7.1.14, “Disk Interfaces”
| |
format
| enumerated |
The underlying storage format. A list of enumerated values is available in capabilities. See Section 7.1.13, “Disk Formats”. Copy On Write (COW) allows snapshots, with a small performance overhead. Raw does not allow snapshots, but offers improved performance.
|
|
sparse
| boolean: true or false |
true if the physical storage for the disk should not be preallocated
|
|
bootable
| boolean: true or false |
true if this disk is to be marked as bootable
| |
wipe_after_delete
| boolean: true or false |
true if the underlying physical storage for the disk should be zeroed when the disk is deleted
| |
propagate_errors
| boolean: true or false |
true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS
| |
storage_domain
| GUID | The ID of the associated storage domain, only used when adding the first disk to a virtual machine that was not itself created from a template |
[a]
|
[a]
Only required when the first disk is being added to a virtual machine that was not itself created from a template.
| |||
size property is required. Also the storage_domain ID is needed in the case of the first disk being added to a virtual machine that was not itself created from a template.
<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/
ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
<size>10737418240</size>
<type>system</type>
<status>OK</status>
<interface>virtio</interface>
<format>raw</format>
<bootable>true</bootable>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
</disk>