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 /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 /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 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. 
POST /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 /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 /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 /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 /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 Enterprise 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 /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 /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 Enterprise 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 /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 /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

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 /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 /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="/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="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <link rel="replay"
      href="/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 /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 /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 Enterprise 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 /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 Enterprise Virtualization Virtual Machine Management Guide.