13.6. Actions

The following sections describe the actions associated with vm resources.
The API contains a number of possible actions for virtual machines: start, stop, shutdown, suspend, detach, migrate, export, move and ticket.
Information on the action for importing virtual machines is found in Section 11.2, “ Export Storage Domains ”.

13.6.1.  Start Action

The start action launches a virtual machine.

Example 13.16. 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. These settings persist until a user stops the virtual machine.

Example 13.17. 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>
        <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

Only virtual machines running Windows operating systems use the domain element when 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 (see Chapter 16, Domains), 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.