Chapter 15. Templates

15.1. Export Action
15.2. Import Action

The templates collection provides information about the virtual machine templates in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="templates" link obtained from the entry point URI (see Chapter 4, Entry Point).

The following table shows specific elements contained in a virtual machine template resource representation.

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”

Element	Type	Description
`name`	string	A user-supplied human readable name for the template. The `name` is unique across all template resources.
`description`	string	A free-form user-supplied human readable description of the template
`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="permissions"`	string	A link to the sub-collection for virtual machine permissions. See Section 8.3.9, “ Permissions ”
`type`	enumerated	The type of virtual machine the template provides. A list of enumerated values are available in `capabilities`. See Section 7.1.8, “Virtual Machine Types”
`status`	One of `ILLEGAL`, `LOCKED` or `OK`	The template 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 template 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 kernel above
`cluster id`	complex	A reference to the cluster on which an instance of this template will run. See Chapter 10, Host Clusters
`vm`	complex	A reference to the VM on which this template is based. See Chapter 14, Virtual Machines
`creation_time`	`xsd:dateTime` format: `YYYY-MM-DDThh:mm:ss`	The date and time at which this template was created
`origin`	One of `rhev`, `vmware` or `xen`	The system from which this template originated
`high_availability`	complex	Set `enabled` to `true` if the VM should be automatically restarted if the host crashes. A `priority` element controls the order in which VMs are re-started
`display`	complex	The display `type` (either `vnc` or `spice`), port, and the number of `monitors`
`stateless`	boolean: true or false	A stateless template has a snapshot of its disk image taken at boot and deleted at shutdown, meaning state changes will not persist after a reboot
`timezone`	tz database format: `Area/Location`	The timezone for this VM. Only certain timezones are allowed as specified in Appendix B, Timezones

Example 15.1. An XML representation of a virtual machine template

<template id="00000000-0000-0000-0000-000000000000"
  href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000">
    <name>Blank</name>
    <description>Blank template</description>
    <actions>
        <link rel="export"
          href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000/export"/>
    </actions>
    <link rel="disks"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000/disks"/>
    <link rel="nics"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000/nics"/>
    <link rel="cdroms"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000/cdroms"/>
    <link rel="permissions"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000/permissions"/>
    <type>server</type>
    <status>OK</status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os>
        <boot dev="hd"/>
        <kernel/>
        <initrd/>
        <cmdline/>
    </os>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>rhev</origin>
    <highly_available>
        <enabled>true</enabled>
        <priority>100</priority>
    </highly_available>
    <display>
        <type>vnc</type>
        <port>5910</port>
        <monitors>1</monitors>
    </display>
    <stateless>false</stateless>
    <timezone>Europe/London</timezone>
</template>

Templates contains a number of read-only device collections that follow the same representation structure as devices in the vms collection:

disks - See Section 14.1, “ Disks Sub-Collection ”.
nics - See Section 14.2, “ Network Interfaces Sub-Collection ”.
cdroms - See Section 14.3, “ CD-ROMs Sub-Collection ”.

There are two possible actions for templates: export and import.

15.1. Export Action

The export action exports a template to an Export storage domain. A destination storage domain must be specified with a storage_domain reference. By default, the export action will overwrite any existing template by the same name in the destination domain, but this may be avoided by setting the exclusive parameter to true.

Example 15.2. Action to export a template to an export storage domain

POST /rhevm-api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1
Content-type: application/xml

<action>
    <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    <exclusive>true<exclusive/>
</action>