15.7. Actions
15.7.1. Start Virtual Machine Action
The start action launches a stopped, shutdown, or suspended virtual machine.
Example 15.46. Action to start a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The start action allows a
vm element to be provided as a parameter. If a vm element is provided, the virtual machine uses the values from the provided element and overrides system settings at start time. Using the start action with the vm element in REST API is equivalent to using the Run Once window in the Administration or User Portal. These settings persist until a user stops the virtual machine. Examples of these elements include os, domain, placement_policy, cdroms, stateless and display type.
Example 15.47. Action to start a virtual machine with overridden parameters
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<pause>true</pause>
<vm>
<stateless>true</stateless>
<display>
<type>spice</type>
</display>
<os>
<boot dev="cdrom"/>
</os>
<cdroms>
<cdrom>
<file id="windows-xp.iso"/>
</cdrom>
</cdroms>
<floppies>
<floppy>
<file id="virtio-win_x86.vfd"/>
</floppy>
</floppies>
<domain>
<name>domain.example.com</name>
<user>
<user_name>domain_user</user_name>
<password>domain_password</password>
</user>
</domain>
<placement_policy>
<host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>
</placement_policy>
</vm>
</action>
Note
- The
domainelement is used for Windows systems only for overriding parameters on boot with thestartaction. Thedomainelement determines the domain that the Windows virtual machine joins. If the domain does not exist in thedomainscollection, this element requires additionaluserauthentication details, including auser_nameandpassword. If the domain exists in thedomainscollection, the action requires no additionaluserauthentication details. - The CD image and floppy disk file must be available in the ISO domain already. If not, use the ISO uploader tool to upload the files. See The ISO Uploader Tool for more information.
15.7.2. Start Virtual Machine with Cloud-Init Action
Cloud-Init is a tool for automating the initial setup of virtual machines. You can use the tool to configure the host name, network interfaces, the DNS service, authorized keys, and set user names and passwords. You can also use the
custom_script tag to specify a custom script to run on the virtual machine when it boots.
Note
The
cloud-init element can only be used to start virtual machines with the cloud-init package installed. When the cloud-init element is used, any element within the initialization element but outside the cloud-init element will be ignored.
Example 15.48. Action to start a virtual machine using Cloud-Init
This example shows you how to start a virtual machine using the Cloud-Init tool to set the host name, change the root password, set a static IP for the
eth0 interface, configure DNS, and add an SSH key for the root user.
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<vm>
<initialization>
<cloud_init>
<host>
<address>MyHost.MyDomain.com</address>
</host>
<users>
<user>
<user_name>root</user_name>
<password>p@55w0rd!</password>
</user>
</users>
<network_configuration>
<nics>
<nic>
<name>eth0</name>
<boot_protocol>static</boot_protocol>
<network>
<ip address="192.168.122.31" netmask="255.255.255.0" gateway="192.168.122.1"/>
</network>
<on_boot>true</on_boot>
</nic>
</nics>
<dns>
<servers>
<host>
<address>192.168.122.1</address>
</host>
</servers>
<search_domains>
<host>
<address>MyDomain.com</address>
</host>
</search_domains>
</dns>
</network_configuration>
<authorized_keys>
<authorized_key>
<user>
<user_name>root</user_name>
</user>
<key>ssh-rsa AAAAB3Nza[...]75zkdD root@MyDomain.com</key>
</authorized_key>
</authorized_keys>
</cloud_init>
<custom_script><![CDATA[your script]]></custom_script>
</initialization>
</vm>
</action>
15.7.3. Stop Virtual Machine Action
The stop action forces a virtual machine to power-off.
Example 15.49. Action to stop a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.4. Shutdown Virtual Machine Action
The shutdown action sends a shutdown request to a virtual machine.
Example 15.50. Action to send a shutdown request to a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.5. Suspend Virtual Machine Action
The suspend action saves the virtual machine state to disk and stops it. Start a suspended virtual machine and restore the virtual machine state with the start action.
Example 15.51. Action to save virtual machine state and suspend the machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.6. Reboot Virtual Machine Action
The reboot action sends a reboot request to a virtual machine.
Example 15.52. Action to send a reboot request to a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.7. Enable user logon to access a virtual machine from an external console
The logon action enables users to access a virtual machine from consoles outside of the Red Hat Virtualization environment.
This action requires the rhevm-guest-agent-gdm-plugin and the rhevm-guest-agent-pam-module packages to be installed and the
ovirt-guest-agent service to be running on the virtual machine.
Users require the appropriate user permissions for the virtual machine in order to access the virtual machine from an external console.
Example 15.53. Logging onto a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1
Content-Type: application/json
Content-Length: 2
{}
15.7.8. Detach Virtual Machine from Pool Action
The detach action detaches a virtual machine from a pool.
Example 15.54. Action to detach a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.9. Migrate Virtual Machine Action
The migrate action migrates a virtual machine to another physical host. The destination
host element is an optional element as Red Hat Virtualization Manager automatically selects a default host for migration. If an API user requires a specific host, the user can specify the host with either an id or name parameter.
Example 15.55. Action to migrate a virtual machine to another host
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
15.7.10. Cancel Virtual Machine Migration Action
The cancel migration action stops any migration of a virtual machine to another physical host.
Example 15.56. Action to cancel migration of a virtual machine to another host
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
15.7.11. Export Virtual Machine Action
Note
The export storage domain is deprecated. Storage data domains can be unattached from a data center and imported to another data center in the same environment, or in a different environment. Virtual machines, floating virtual disk images, and templates can then be uploaded from the imported storage domain to the attached data center. See the Importing Existing Storage Domains section in the Red Hat Virtualization Administration Guide for information on importing storage domains.
The export action exports a virtual machine to an
export storage domain. A destination storage domain must be specified with a storage_domain reference.
The export action reports a failed action if a virtual machine of the same name exists in the destination domain. Set the
exclusive parameter to true to change this behavior and overwrite any existing virtual machine.
If snapshots of the virtual machine are not included with the exported virtual machine, set the
discard_snapshots parameter to true.
Example 15.57. Action to export a virtual machine to an export storage domain
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>export1</name>
</storage_domain>
<exclusive>true</exclusive>
<discard_snapshots>true</discard_snapshots>
</action>
15.7.12. Virtual Machine Ticket Action
The ticket action generates a time-sensitive authentication token for accessing a virtual machine's display. The client-provided
action optionally includes a ticket representation containing a value (if the token string needs to take on a particular form) and/or an expiry time in minutes. In any case, the response specifies the actual ticket value and expiry used.
Example 15.58. Action to generate authentication token for a virtual machine
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<ticket>
<expiry>120</expiry>
</ticket>
</action>
200 OK
Content-Type: application/xml
<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
94e07552-14ba-4c27-8ce6-2cc75190d3ef">
<status>
<state>complete</state>
</status>
<ticket>
<value>5c7CSzK8Sw41</value>
<expiry>120</expiry>
</ticket>
<link rel="parent"
href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
<link rel="replay"
href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>
15.7.13. Force Remove Virtual Machine Action
An API user forces the removal of a faulty virtual machine with the
force action. This action requires a DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.
Example 15.59. Force remove action on a virtual machine
DELETE /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<force>true</force>
</action>
15.7.14. Freeze Virtual Machine Filesystems Action
The
freezefilesystems action freezes a virtual machine's filesystems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the Manager, but this must be executed manually with the REST API for virtual machines using OpenStack Volume (Cinder) disks.
Freezing the filesystems on the guest operating system ensures a consistent snapshot. Once the snapshot is finished, the guest filesystems must then be thawed. On virtual machines not using a OpenStack Volume disk, the freezing and thawing actions can also be invoked manually using the REST API, which can be useful in the case of a failure during the snapshot process.
Example 15.60. Action to freeze a virtual machine's filesystems
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/freezefilesystems HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
For more information on snapshots, see Section 15.6.5.1, “Snapshots Sub-Collection” or the Snapshots section in the Red Hat Virtualization Virtual Machine Management Guide.
15.7.15. Thaw Virtual Machine Filesystems Action
The
thawfilesystems action thaws a virtual machine's filesystems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the Manager, but this must be executed manually with the REST API for virtual machines using OpenStack Volume (Cinder) disks.
Freezing the filesystems on the guest operating system ensures a consistent snapshot. Once the snapshot is finished, the guest filesystems must then be thawed. On virtual machines not using a OpenStack Volume disk, the freezing and thawing actions can also be invoked manually using the REST API, which can be useful in the case of a failure during the snapshot process. For example, if the virtual machine became unresponsive during thaw, you can execute the thaw operation again manually; otherwise the virtual machine may remain unresponsive.
Example 15.61. Action to thaw a virtual machine's filesystems
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/thawfilesystems HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
For more information on snapshots, see Section 15.6.5.1, “Snapshots Sub-Collection” or the Snapshots section in the Red Hat Virtualization Virtual Machine Management Guide.
