15.7. Actions
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 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 Note The domain element is used for Windows systems only for overriding parameters on boot with the start action. The domain element determines the domain that the Windows virtual machine joins. If the domain does not exist in the domains collection, this element requires additional user authentication details, including a user_name and password . If the domain exists in the domains collection, the action requires no additional user authentication 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. 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 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 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 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 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 ovirt-guest-agent-gdm-plugin and the ovirt-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 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 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 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 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 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 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 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 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 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 .
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> 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> 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> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1 Content-Type: application/json Content-Length: 2 {} POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> 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> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> 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> 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> 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> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/freezefilesystems HTTP/1.1 Accept: application/xml Content-type: application/xml <action/> POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/thawfilesystems HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>