Red Hat Enterprise Virtualization REST API 0.9

REST API Guide

A RESTful API for Red Hat Enterprise Virtualization

Edition 0

Mark McLoughlin

Red Hat Engineering

markmc@redhat.com

Eoghan Glynn

Red Hat Engineering

eglynn@redhat.com

David Jorm

Red Hat Engineering Content Services

djorm@redhat.com

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

All other trademarks are the property of their respective owners.

1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701

Abstract

This document describes the REST API for Red Hat Enterprise Virtualization.

Preface

1. Document Conventions

1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings

2. We Need Feedback!

1. Introduction

1.1. Resources
1.2. Collections
1.3. URIs
1.4. Representations
1.5. Requests
1.6. Methods
1.7. Headers
1.8. Message Entities
1.9. Actions

2. Example

2.1. Access API Entry Point
2.2. List Data Center Collection
2.3. List Host Cluster Collection
2.4. List Logical Networks Collection
2.5. List Host Collection
2.6. Approve Host
2.7. Create NFS Data Storage
2.8. Create NFS ISO Storage
2.9. Attach Storage Domains to Data Center
2.10. Activate Storage Domains
2.11. Create Virtual Machine
2.12. Attach NIC to Virtual Machine
2.13. Attach Storage Disk to Virtual Machine
2.14. Attach ISO Image to Virtual Machine
2.15. Start Virtual Machine
2.16. Check System Events
2.17. Error Handling

3. Authentication

4. Entry Point

4.1. Link elements
4.2. Special object elements
4.3. Summary element

5. Localization

6. Compatibility Level Versions

7. Capabilities

7.1. Version-Dependent Capabilities

7.1.1. Current Version
7.1.2. Features
7.1.3. CPUs
7.1.4. Power Managers
7.1.5. Fence Types
7.1.6. Storage Types
7.1.7. Storage Domain Types
7.1.8. Virtual Machine Types
7.1.9. Boot Devices
7.1.10. Display Types
7.1.11. NIC Types
7.1.12. Disk Types
7.1.13. Disk Formats
7.1.14. Disk Interfaces
7.1.15. Virtual Machine Affinities
7.1.16. Custom Properties
7.1.17. Boot Protocols
7.1.18. Error Handling
7.1.19. Storage Formats

7.2. Permits

7.3. Scheduling Policies

7.4. Capabilities Example

8. Common Features

8.1. Representations

8.2. Collections

8.2.1. Listing All Resources in a Collection
8.2.2. Listing Extended Resource Sub-Collections
8.2.3. Search Queries

8.3. Resources

8.3.1. Retrieving a Resource
8.3.2. Creating a Resource
8.3.3. Creating a Resource Asynchronously
8.3.4. Updating a Resource
8.3.5. Deleting a Resource
8.3.6. Sub-Collection Relationships
8.3.7. XML Element Relationships
8.3.8. Actions
8.3.9. Permissions
8.3.10. Handling Errors

9. Data Centers

9.1. Storage Domains Sub-Collection

9.1.1. Activate Action
9.1.2. Deactivate Action
9.1.3. Export Storage Domains

10. Host Clusters

10.1. Networks Sub-Collection

11. Networks

12. Storage Domains

12.1. Storage types

12.1.1. NFS
12.1.2. iSCSI and FCP
12.1.3. LOCAL

12.2. Files Sub-Collection

12.3. Import Existing Storage Domain

12.4. Delete Storage Domain

13. Hosts

13.1. Power Management

13.2. Memory Management

13.3. Network Interface Sub-Collection

13.3.1. Bonded Interfaces
13.3.2. Attach Action
13.3.3. Detach Action

13.4. Storage Sub-Collection

13.5. Actions

13.5.1. Install Action
13.5.2. Activate Action
13.5.3. Fence Action
13.5.4. Deactivate Action
13.5.5. Approve Action
13.5.6. iSCSI Login Action
13.5.7. iSCSI Discover Action
13.5.8. Commit Network Configuration Action

14. Virtual Machines

14.1. Disks Sub-Collection

14.2. Network Interfaces Sub-Collection

14.3. CD-ROMs Sub-Collection

14.4. Snapshots Sub-Collection

14.5. Users Sub-Collection

14.6. Actions

14.6.1. Start Action
14.6.2. Stop Action
14.6.3. Shutdown Action
14.6.4. Suspend Action
14.6.5. Detach Action
14.6.6. Migrate Action
14.6.7. Export Action
14.6.8. Import Action
14.6.9. Move Action
14.6.10. Ticket Action

15. Templates

15.1. Export Action
15.2. Import Action

16. Virtual Machine Pools

17. Roles

17.1. Permits Sub-Collection

18. Users

19. Domains

19.1. Domain Users Sub-Collection
19.2. Domain Groups Sub-Collection

20. Tags

20.1. Associating Tags With a Host, User or VM
20.2. Parent Tags

C. Revision History

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:

Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session.

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.

Output sent to a terminal is set in mono-spaced roman and presented thus:

books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs

Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:

package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a ticket in Track: https://fedorahosted.org/rhevm-api/newticket/ or send a report by email to the project mailing list (rhevm-api@lists.fedorahosted.org ).

Red Hat Enterprise Virtualization Manager provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their Red Hat Enterprise Virtualization environment outside of the standard web interface. The REST API is useful for developers and administrators who aim to integrate the functionality of a Red Hat Enterprise Virtualization environment with custom scripts or client-side applications that are able to send Hypertext Transfer Protocol (HTTP) requests and interpret responses.

Other benefits of the REST API include:

The ability to customize features of your Red Hat Enterprise Virtualization environment.
The potential to automatically complete tasks, such a system maintenance and error checking.
Repetitive tasks in a Red Hat Enterprise Virtualization environment are completed with simple scripts.
The API is cross-platform and any system that accesses HTTP fulfils the basic requirements to access the REST API.

This documentation acts as a reference to the Red Hat Enterprise Virtualization Manager REST API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their Red Hat Enterprise Virtualization environment through the REST API.

Explaining the Red Hat Enterprise Virtualization Manager REST API requires an examination of REST architectural style and RESTful web services in the context of a virtualization environment. The following sections provide an overview of REST architecture through explanations of the key REST terms.

1.1. Resources

A REST API focuses primarily on resources of a specific service. A resource is a key abstraction of information and in the context of virtualization represents an individual component, capability or data set in the virtualizaion infrastructure.

1.2. Collections

Red Hat Enterprise Virtualization Manager's REST API groups resources into individual collections based on the management infrastructure types in a Red Hat Enterprise Virtualization environment. Examples of collections include data centers, clusters, storage domains, hosts, and virtual machines.

Some resources contain additional sub-collections that relate to the resource in question. For example, a virtual machine contains sub-collections for resources such as network interfaces, storage disks, and CD-ROMs.

This establishes a layered relationship model using collections, resources and sub-collections in a Red Hat Enterprise Virtualization environment.

1.3. URIs

A user performs a request on any part of the API model to control the virtualization environment. For example, access to all resources in a collection requires only a request to the collection itself. Access to a specific resource requires a request to the resource within the context of its collection. An API user targets these requests to a specific location called a Uniform Resource Identifier (URI).

The REST API combines our virtualization model with the use of HTTP to construct a series of Uniform Resource Identifiers (URIs) for collections and resources. This means an API user accesses collections and resources in a manner similar to loading a webpage on the internet. For example, an API user accesses a collection group called collection from a REST API installed at www.example.com with the following URI:

http://www.example.com/collection

Access to a resource called resource within collection requires the following URI:

http://www.example.com/collection/resource

In the context of a Red Hat Enterprise Virtualization environment, the API provides access to a virtual machine resource with an identication code of 6efc0cfa-8495-4a96-93e5-ee490328cf48 within the vms collection installed at http://www.example.com/rhevm-api/ with the following URI:

http://www.example.com/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48

1.4. Representations

Access to a resource URI in a RESTful web service does not mean direct access to the resource itself but to an abstraction of the resource. This abstraction is called a representation. The API constructs representations using various formats but this documentation focuses primarily on XML representations.

When working with a specific resource, the API constructs a representation using elements. When an API user accesses http://www.example.com/collection/resource, an XML resource representation structures elements in the following way:

<resource>
    <element_one>value one</element_one>
    <element_two>value two</element_two>
    <element_three>value three</element_three>
    ...
</resource>

Elements can also contain attributes, which provide information about the element itself:

<resource>
    <element attribute="value"/>
    ...
</resource>

A virtual machine resource contains elements such as machine type, operational status, memory in bytes, CPUs and creation time. These elements form a basic XML structure for a virtual machine resource representation:

<vm>
    <type>server</type>
    <status>UP</status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <creation_time>2011-01-25T13:53:15.103+10:00</creation_time>
</vm>

This example shows how the resource representation portrays complex elements, such as cpu and topology information. Complex elements contain sub-elements to depict multiple properties of a single element. This demonstrates how REST representations use XML to depict very specific aspects of resources and their elements.

1.5. Requests

The REST API uses HTTP as a protocol to transfer a request for a resource representation from a client to the Red Hat Enterprise Virtualization Manager server:

GET /collection/resource HTTP/1.1
Host: www.example.com
Accept: application/xml

This follows the standard HTTP request message format including:

A Request-Line, which requires:
- a method e.g. GET;
- a URI e.g /collection/resource; and
- a HTTP version e.g HTTP/1.1.
A Header with fields to define parameters that process a request e.g. Host: and Accept:; and
An optional Message Entity depending on the request method.

Requests from a client to a server contain all necessary information to process the request without depending on any previous request or stored context on the server, which makes the REST API a stateless communication.

1.6. Methods

The benefit of using HTTP to communicate with the REST API is the ability to use a method to access Red Hat Enterprise Virtualization resources. A method defines the type of request to a resource. The REST API uses four HTTP methods:

Method	Decription
`GET`	Retrieve a resource or collection representation
`POST`	Create a resource based upon a user-defined representation
`PUT`	Update a resource based upon a user-defined representation
`DELETE`	Remove a resource

The default method is GET but an API user has a choice of any of the four methods to access and control resources in their virtualization environment.

1.7. Headers

The HTTP request contains a header to define HTTP parameters. The header uses specific header fields to define these parameters. All are optional except for two requried in the context of the REST API:

Header	Decription
`Host:`	The target host of the URI i.e. the location of the Red Hat Enterprise Virtualization environment and REST API
`Accept:`	The accepted format for the representation. This documentation uses the `application/xml` to define the representation structure as XML format.

This documentation defines optional header fields in later chapters.

1.8. Message Entities

It is possible for a HTTP request to contain a message entity. Use of POST or PUT methods often requires an additional message entity in the request:

POST /collection HTTP/1.1
Host: www.example.com
Accept: application/xml

<resource>
    <element>value</element>
</resource>

The message entity accepts a user-defined resource representation sent to the URI. POSTing this message entity creates a new resource with value in element to represent a resource setting. PUTing a message entity updates element in the resource with value. This means a user can define properties for new or existing resources using a resource representation in the message entity of a request. In the context of a Red Hat Enterprise Virtualization environment, an API user creates a new VM with the following request:

POST /rhevm-api/vms HTTP/1.1
Host: www.example.com
Accept: application/xml

<vm>
    <name>vm1</type>
    <description>vm1</description>
    <memory>536870912</memory>
    <cluster>
        <name>Default</name>
    </cluster>
    <template>
        <name>blank</name>
    </template>    
</vm>

A request result also uses an XML resource representation in the message entity to provide the user with the required abstracted information.

1.9. Actions

Some resources provide specialized URIs for actions. An API user performs a request on a resource's action, which launches a task specific to that resource.

A virtual machine contains functions to start, stop and shutdown. The API abstracts these function as actions specific to each virtual machine resource:

<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48" href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
    <actions>
        <link rel="start"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
        <link rel="stop"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
        <link rel="shutdown"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
        ...
    </actions>
</vm>

Chapter 2. Example

2.1. Access API Entry Point
2.2. List Data Center Collection
2.3. List Host Cluster Collection
2.4. List Logical Networks Collection
2.5. List Host Collection
2.6. Approve Host
2.7. Create NFS Data Storage
2.8. Create NFS ISO Storage
2.9. Attach Storage Domains to Data Center
2.10. Activate Storage Domains
2.11. Create Virtual Machine
2.12. Attach NIC to Virtual Machine
2.13. Attach Storage Disk to Virtual Machine
2.14. Attach ISO Image to Virtual Machine
2.15. Start Virtual Machine
2.16. Check System Events
2.17. Error Handling

This chapter provides an example to demonstrate the REST API's ability to create virtual machine within a basic Red Hat Enterprise Virtualization environment. This example is intended for users with some proficiency with REST architectural style and some experience with Red Hat Enterprise Virtualization infrastructure.

This example requires the following:

A networked installation of Red Hat Enterprise Virtualization Manager;
A networked and configured host containing Red Hat Enterprise Virtualization Hypervisor;
An ISO file containing a desired virtual machine operating system to install. This chapter uses Red Hat Enterprize Linux Server 6 for our installation ISO example; and
Red Hat Enterprise Virtualization Platform's uploader tool to upload your chosen operating system ISO file.

Identifier Codes

Red Hat Enterprise Virtualization Manager generates an opaque identifier code, or id, for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.

2.1. Access API Entry Point

The following request retrieves a representation of the main entry point of the API.

Example 2.1. Access the API entry point

GET /rhevm-api HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Content-Type: application/xml

<api>
    <link rel="capabilities" href="/rhevm-api/capabilities"/>
    <link rel="clusters" href="/rhevm-api/clusters"/>
    <link rel="clusters/search" href="/rhevm-api/clusters?search={query}"/>
    <link rel="datacenters" href="/rhevm-api/datacenters"/>
    <link rel="datacenters/search" href="/rhevm-api/datacenters?search={query}"/>
    <link rel="events" href="/rhevm-api/events"/>
    <link rel="events/search" href="/rhevm-api/events?search={query}"/>
    <link rel="hosts" href="/rhevm-api/hosts"/>
    <link rel="hosts/search" href="/rhevm-api/hosts?search={query}"/>
    <link rel="networks" href="/rhevm-api/networks"/>
    <link rel="roles" href="/rhevm-api/roles"/>
    <link rel="storagedomains" href="/rhevm-api/storagedomains"/>
    <link rel="storagedomains/search" href="/rhevm-api/storagedomains?search={query}"/>
    <link rel="tags" href="/rhevm-api/tags"/>
    <link rel="templates" href="/rhevm-api/templates"/>
    <link rel="templates/search" href="/rhevm-api/templates?search={query}"/>
    <link rel="users" href="/rhevm-api/users"/>
    <link rel="groups" href="/rhevm-api/groups"/>
    <link rel="domains" href="/rhevm-api/domains"/>
    <link rel="vmpools" href="/rhevm-api/vmpools"/>
    <link rel="vmpools/search" href="/rhevm-api/vmpools?search={query}"/>
    <link rel="vms" href="/rhevm-api/vms"/>
    <link rel="vms/search" href="/rhevm-api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/rhevm-api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <system_version revision="0" build="0" minor="0" major="3"/>
    <summary>
        <vms>
            <total>5</total>
            <active>0</active>
        </vms>
        <hosts>
            <total>1</total>
            <active>1</active>
        </hosts>
        <users>
            <total>1</total>
            <active>1</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

The entry point provides a user with links to the collections in a virtualization environment. The rel= attribute of each collection link provides a reference point for each link. The next step in this example examines the datacenter collection, which is available through the rel="datacenter" link.

2.2. List Data Center Collection

Red Hat Enteprise Virtualization Manager creates a Default data center on installation. This example uses the Default data center as the basis for our virtual environment.

The following request retrieves a representation of the data center collection:

Example 2.2. List data center collection

GET /rhevm-api/datacenters HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Content-Type: application/xml

<data_centers>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
          storagedomains"/>
        <link rel="permissions"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/>
        <storage_type>nfs</storage_type>
        <storage_format>v1</storage_format>
        <version minor="0" major="3"/>
        <supported_versions>
            <version minor="0" major="3"/>
        </supported_versions>
        <status>UP</status>
    </data_center>
</data_centers>

Note the id code of your Default data center. This code indentifies this data center in relation to other resources of your virtual environment.

2.3. List Host Cluster Collection

Red Hat Enteprise Virtualization Manager creates a Default host cluster on installation. This example uses the Default cluster to group virtual machines in your Red Hat Enteprise Virtualization environment.

The following request retrieves a representation of the cluster collection:

Example 2.3. List host clusters collection

GET /rhevm-api/clusters HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Content-Type: application/xml

<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <memory_policy>
            <overcommit percent="100"/>
            <transparent_hugepages>
                <enabled>false</enabled>
            </transparent_hugepages>
        </memory_policy>
        <scheduling_policy/>
        <version minor="0" major="3"/>
        <error_handling>
            <on_error>migrate</on_error>
        </error_handling>
    </cluster>
</clusters>

Note the id code of your Default host cluster. This code indentifies this host cluster in relation to other resources of your virtual environment.

The Default cluster is associated with the Default data center through a relationship using the data center's id code.

The networks sub-collection contains a list of associated network resources for this cluster. The next section examines the networks collection in more detail.

2.4. List Logical Networks Collection

Red Hat Enteprise Virtualization Manager creates a default rhevm network on installation. This network is associated with our Default cluster and is a member of the Default data center. This example uses the rhevm network to connect our virtual machines.

The following request retrieves a representation of the logical networks collection:

Example 2.4. List logical networks collection

GET /rhevm-api/networks HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Content-Type: application/xml

<networks>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/rhevm-api/networks/00000000-0000-0000-0000-000000000009">
        <name>rhevm</name>
        <description>Management Network</description>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <stp>false</stp>
        <status>OPERATIONAL</status>
        <display>false</display>
    </network>
</networks>

The rhevm network is attached to the Default data center through a relationship using the data center's id code.

The rhevm network is also attached to the Default cluster through a relationship in the cluster's network sub-collection.

2.5. List Host Collection

This example uses a Red Hat Enteprise Virtualization Hypervisor host. Red Hat Enteprise Virtualization Manager automatically registers any configured Red Hat Enteprise Virtualization Hypervisor. This example retrieves a representation of the hosts collection and shows a Red Hat Enteprise Virtualization Hypervisor host named hypervisor registered with the virtualization environment.

Example 2.5. List hosts collection

GET /rhevm-api/hosts HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Accept: application/xml

<hosts>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
        <name>hypervisor</name>
        <actions>
            <link rel="install"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
            <link rel="activate"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
            <link rel="fence"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
            <link rel="deactivate"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
            <link rel="approve"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
            <link rel="iscsilogin"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
            <link rel="iscsidiscover"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
            <link rel="commitnetconfig"
              href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
              commitnetconfig"/>
        </actions>
        <link rel="storage"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
        <link rel="nics"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
        <link rel="tags"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
        <link rel="permissions"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
        <link rel="statistics"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
        <address>10.64.14.110</address>
        <status>NON OPERATIONAL</status>
        <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
        <port>54321</port>
        <storage_manager>true</storage_manager>
        <power_management>
            <enabled>false</enabled>
            <options/>
        </power_management>
        <ksm>
            <enabled>false</enabled>
        </ksm>
        <transparent_hugepages>
            <enabled>true</enabled>
        </transparent_hugepages>
        <iscsi>
            <initiator>iqn.1994-05.com.example:644949fe81ce</initiator>
        </iscsi>
        <cpu>
            <topology cores="2"/>
            <name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
            <speed>2993</speed>
        </cpu>
        <summary>
            <active>0</active>
            <migrating>0</migrating>
            <total>0</total>
        </summary>
    </host>
</hosts>

Note the id code of your Default host. This code indentifies this host in relation to other resources of your virtual environment.

This host is a member of the Default cluster and accessing the nics sub-collection shows this host has a connection to the rhevm network.

2.6. Approve Host

The hypervisor host resource contains an approve action. A user accesses this action's URI with a POST request.

Example 2.6. Approve a pre-configured Red Hat Enterprise Virtualization Hypervisor host

POST /rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve HTTP/1.1
Accept: application/xml
Content-type: application/xml

This approves and activates the host for use in your virtual environment. The status for hypervisor changes from NON OPERATIONAL to UP.

2.7. Create NFS Data Storage

An NFS data storage domain is a mounted NFS share attached to a data center and provides storage for virtualized guest images.

Example 2.7. Create an NFS data storage domain

POST /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/data1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

The API creates a NFS data storage domain called data1 with an export path of 192.168.0.10:/data1 and sets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domains>
    <storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
      href="/rhevm-api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
        <name>data1</name>
        <link rel="permissions"
          href="/rhevm-api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
          permissions"/>
        <link rel="files"
          href="/rhevm-api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/>
        <type>data</type>
        <master>false</master>
        <storage>
            <type>nfs</type>
            <address>192.168.0.10</address>
            <path>/data1</path>
        </storage>
        <available>175019917312</available>
        <used>27917287424</used>
        <committed>10737418240</committed>
        <storage_format>v1</storage_format>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
    </storage_domain>
</storage_domains>

2.8. Create NFS ISO Storage

An NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage for CD-ROM and DVD image files.

Example 2.8. Create an NFS ISO storage domain

POST /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/iso1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

The API creates a NFS data storage domain called iso1 with an export path of 192.168.0.10:/iso1 and sets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domains>
    <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
      href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
        <name>iso1</name>
        <link rel="permissions"
          href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
          permissions"/>
        <link rel="files"
          href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/>
        <type>iso</type>
        <host id="" href="">
        <master>false</master>
        <storage>
            <type>nfs</type>
            <address>192.168.0.10</address>
            <path>/iso1</path>
        </storage>
        <available>82678120448</available>
        <used>18253611008</used>
        <committed>0</committed>
        <storage_format>v1</storage_format>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988">        
    </storage_domain>
</storage_domains>

2.9. Attach Storage Domains to Data Center

The following example attaches the data1 and iso1 storage domains to the Default data center.

Example 2.9. Attach data1 storage domain to the Default data center

POST /rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
</storage_domain>

Example 2.10. Attach iso1 storage domain to the Default data center

POST /rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
</storage_domain>

2.10. Activate Storage Domains

This example activates the data1 and iso1 storage domains for the Red Hat Enterprise Virtualization Manager's use.

Example 2.11. Activate data1 storage domain

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

Example 2.12. Activate iso1 storage domain

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

2.11. Create Virtual Machine

The following example creates a virtual machine called vm1 on the Default cluster using the virtualization environment's Blank template as a basis. The request also defines the virtual machine's memory as 512 MB and sets the boot device to a virtual hard disk.

Example 2.13. Create a virtual machine

POST /rhevm-api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
 	  	
<vm>
  <name>vm1</name>
  <cluster>
    <name>default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory> 
  <os>
    <boot dev="hd"/>
  </os>
</vm>

The API returns the following representation of the newly created virtual machine resource:

HTTP/1.1 200 OK
Accept: application/xml    

<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
  href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
    <name>vm1</name>
    <actions>
        <link rel="shutdown"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
        <link rel="start"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
        <link rel="stop"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
        <link rel="suspend"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
        <link rel="detach"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
        <link rel="export"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
        <link rel="move"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
        <link rel="ticket"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
        <link rel="migrate"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
    </actions>
    <link rel="disks"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
    <link rel="nics"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
    <link rel="cdroms"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
    <link rel="snapshots"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
    <link rel="tags"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
    <link rel="permissions"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
    <link rel="statistics"
      href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
    <type>desktop</type>
    <status>DOWN</status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os type="Unassigned">
        <boot dev="cdrom"/>
    </os>
    <high_availability>
        <enabled>false</enabled>
        <priority>0</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
    </display>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
    <start_time>2011-06-15T04:48:02.167Z</start_time>
    <creation_time>2011-06-15T14:48:02.078+10:00</creation_time>
    <origin>rhevm</origin>
    <stateless>false</stateless>
    <placement_policy>
        <affinity>MIGRATABLE</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
    </memory_policy>
</vm>

2.12. Attach NIC to Virtual Machine

The following example creates a virtual network interface to connect the example virtual machine to the rhevm network.

Example 2.14. Attach a NIC to the virtual machine

POST /rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
  <name>nic1</name>
  <network>
    <name>rhevm</name>
  </network>
</nic>

2.13. Attach Storage Disk to Virtual Machine

The following example creates an 8 GB storage disk for the example virtual machine.

Example 2.15. Create a Storage Disk on the virtual machine

POST /rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
  <size>8589934592</size>
  <type>system</type>
  <interface>virtio</interface>
  <format>raw</format>
  <bootable>true</bootable>
</disk>

2.14. Attach ISO Image to Virtual Machine

The boot media for our example virtual machine requires an CD-ROM or DVD ISO image for an operating system installation. This example uses a Red Hat Enterprise Server 6 ISO image for installation.

ISO images must be available in the iso1 ISO domain for the virtual machines to use. Red Hat Enterprise Virtualization Platform provides an uploader tool that ensures that the ISO images are uploaded into the correct directory path with the correct user permissions.

Once the ISO is uploaded, an API user requests the ISO storage domain's files sub-collection to view the file resource:

Example 2.16. View the files sub-collection in an ISO storage domain

GET /rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

The API returns the following representation of the files sub-collection:

<files>
    <file id="rhel-server-6.0-x86_64-dvd.iso"
      href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      files/rhel-server-6.0-x86_64-dvd.iso.iso">
        <name>rhel-server-6.0-x86_64-dvd.iso.iso</name>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>

An API user attaches the rhel-server-6.0-x86_64-dvd.iso to our example virtual machine.

Example 2.17. Attach an ISO image to the virtual machine

POST /rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cdrom>
  <file id="rhel-server-6.0-x86_64-dvd.iso"/>
</cdrom>

2.15. Start Virtual Machine

The virtual environment is complete and the virtual machine contains all necessary components to function. This example starts the virtual machine using the start action.

Example 2.18. Start the virtual machine

POST /rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
  <os>
    <boot dev="cdrom"/>
  </os>
</vm>

The additional message entity sets the virtual machine's boot device to CD-ROM for this boot only. This enables the virtual machine to install Red Hat Enterprise Server 6 from the attached ISO image. The boot device reverts back to disk for all future boots.

2.16. Check System Events

The start action for the vm1 creates several entries in the events collection. This example lists the events collection and identifies events specific to the API starting a virtual machine.

Example 2.19. List the events collection

GET /rhevm-api/events HTTP/1.1
Accept: application/xml

The API returns a representation that includes the following:

<events>
    ...
    <event id="103" href="/rhevm-api/events/103">
        <description>User admin logged out.</description>
        <code>31</code>
        <severity>NORMAL</severity>
        <time>2011-06-29T17:42:41.544+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73" 
          href="/rhevm-api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="102" href="/rhevm-api/events/102">
        <description>vm1 was started by admin (Host: hypervisor).</description>
        <code>153</code>
        <severity>NORMAL</severity>
        <time>2011-06-29T17:42:41.499+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/rhevm-api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
        <vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
          href="/rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/rhevm-api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
    </event>
    <event id="101" href="/rhevm-api/events/101">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>NORMAL</severity>
        <time>2011-06-29T17:42:40.505+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/rhevm-api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    ...
</events>

The following events have occured:

id="101" - The API authenticates with the admin user's username and password.
id="102" - The API, acting as the admin user, starts vm1 on the hypervisor host.
id="103" - The API logs out of the admin user account.

2.17. Error Handling

The following example attempts to update a read-only property, which creates an error.

Example 2.20. Update the virtual machine's id code and create an error

PUT /rhevm-api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm id="01010101-0101-0101-0101-010101010101"/>

The API returns the following error:

<fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
</fault>

Chapter 3. Authentication

An API user provides a valid Red Hat Enterprise Virtualization Manager username and password with all invocations on the API and uses HTTP Basic Authentication ^[1] to encode these credentials. If an invocation on the API does not include an appropriate Authorization header then the API sends a 401 Authorization Required as a result:

HEAD {base} HTTP/1.1
Host: {host}

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. The Red Hat Enterprise Virtualization Manager domain and user should be encoded in the supplied credentials with the username@domain convention.

Example 3.1. Encoding authentication credentials

Type	Value
username	rhevmadmin
domain	domain.example.com
password	123456
unencoded credentials	rhevmadmin@domain.example.com:123456
base64 encoded credentials	cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

We would encode the credentials as shown:

HEAD {base} HTTP/1.1
Host: {host}
Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK
...

Confidentiality

Basic authentication involves potentially sensistive information such as passwords being sent in plain text, hence it is recommended that confidentiality is ensured via transport-level encryption.

^[1] Basic Authentication is described in RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.

Chapter 4. Entry Point

4.1. Link elements
4.2. Special object elements
4.3. Summary element

A user begins interacting with the API through a GET request on the entry point URI consisting of a {host} and {base}.

GET {base} HTTP/1.1
Host: {host}

HTTP/1.1 200 OK
Link: <http://{host}/{base}/hosts>; rel=hosts, <http://{host}/{base}/vms>; rel=vms
Content-Type: application/xml

<api>
    <link rel="hosts" href="{base}/hosts"/>
    <link rel="vms" href="{base}/vms"/>
    ...
    <special_objects>
        <link rel="templates/blank" href="..."/>
        <link rel="tags/root" href="..."/>
    </special_objects>
    <summary>
        <vms>
            <total>10</total>
            <active>3</active>
        </vms>
        <hosts>
            <total>2</total>
            <active>2</active>
        </hosts>
        <users>
            <total>8</total>
            <active>2</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

Note

For simplicity, all other examples omit the Host request header and assume {base} is the default /rhevm-api. This base path will differ depending on your implementation.

4.1. Link elements

Access to the Entry Point provides the Link header ^[2] , link elements and URIs for all of the resource collections exposed by the API. Each collection uses a relation type to identify the URI a client needs. The following relation types are available:

Relationship	Description
`capabilities`	Information about the supported capabilities of the Red Hat Enterprise Virtualization Manager
`datacenters`	Data centers
`clusters`	Host clusters
`networks`	Virtual networks
`storagedomains`	Storage domains
`hosts`	Hosts
`vms`	Virtual machines
`templates`	Templates
`vmpools`	Virtual machine pools
`roles`	Roles
`users`	Users
`domain`	Identity domain
`tags`	Tags
`events`	Events
`statistics`	Statistics

Figure 4.1. The relationship between the API entry point and the resource collections exposed by the API

URIs

All URIs shown in example responses are purely illustrative. The format of all URIs returned by the server is opaque. Clients must navigate to any specific resources through the entry point URI and use the relationship types to access the URIs.

The server may choose to include absolute URIs or absolute paths ^[3] in the link element href attribute, so clients should be prepared to handle either form. Link headers will only contain absolute URIs.

In addition to the literal URIs described above, the Link header also contains a set of URI templates ^[4] , which describe the form of URI used for sending search queries to the collections. Each URI template is identified by a relation type, named according to the convention "collection/search".

URI Templates

The purpose of the URI template is to accept a search expression using the natural HTTP pattern of a query parameter. The client does not require prior knowledge of the URI structure. Thus clients should treat these templates as being opaque and instantiate them via a URI template library such as the Google Code uri-templates Python package or the Apache Abdera support for Java templates.

The following relation types are associated with query URI templates:

Relationship	Description
`datacenters/search`	Query data centers
`clusters/search`	Query host clusters
`storagedomains/search`	Query storage domains
`hosts/search`	Query hosts
`vms/search`	Query virtual machines
`templates/search`	Query templates
`vmpools/search`	Query virtual machine pools
`events/search`	Query events
`users/search`	Query users

4.2. Special object elements

Special object elements define relationships to special fixed resources within the virtualization environment. These special objects include:

Relationship	Description
`templates/blank`	The default `blank` virtual machine template for your virtualization environment
`tags/root`	The `root` tag that acts a base for tag hierarchy in your virtualization environment

4.3. Summary element

The summary element shows a high level summary of the system's statistics. It includes the following elements:

Element	Description
`vms`	Total number of vms and total number of active vms
`hosts`	Total number of hosts and total number of active hosts
`users`	Total number of users and total number of active users
`storage_domains`	Total number of storage domains and total number of active storage domains

^[2] The Internet-Draft describing the format of the Link header is available at http://tools.ietf.org/html/draft-nottingham-http-link-header-10.

^[3] The RFC describing Uniform Resource Locator Generic Syntax provides a Collected ABNF for URI that explains the difference between these forms.

^[4] The Internet-Draft describing the format of a URI Template is available at http://tools.ietf.org/html/draft-gregorio-uritemplate-03.

Chapter 5. Localization

The API supports localization of error messages and other content returned as part of a HTTP response. A client can request that content be localized into a particular language by providing the Accept-Language header with a request. ^[5] The Accept-Language header allows languages to be identified by standard tags. ^[6]

Localization support is currently available for:

Language Code	Language
`de`	German
`nl`	Dutch
`it`	Italian

Example 5.1. Using Accept-Language to request German localization

GET {base} HTTP/1.1
Host: {host}
Accept-Language: de

^[5] The Accept-Language header is described in section 14.4 of RFC 2616

^[6] The format for language tags is described in RFC 1766

Chapter 6. Compatibility Level Versions

Each hosts connected to Red Hat Enterprise Virtualization Manager has a version of VDSM installed. A current version of the Manager controls hosts with current or older versions of VDSM.

Virtual machines are migrated from host to host within a cluster. This means the Manager excludes certain features from a current version of VDSM until all hosts within a cluster have the same VDSM version, or more recent, installed.

This concept is represented in the API as a compatibility level for each host, corresponding to the version of VDSM installed. A version element containing major and minor attributes describes a compatibility level.

Once all hosts within a cluster have been upgraded to a certain level, that level's version will appear under a supported_versions element. This indicates the cluster's version is now updatable to that level. Once all clusters within a data center are updated to a given level, the data center is updatable to that level.

Example 6.1. Upgrading compatibility levels from Red Hat Enterprise Virtualization Manager 2.2 to 3.0

The API reports the following compatibility levels for Red Hat Enterprise Virtualization Manager 2.2 instance:

<host ...>
    ...
    <version major="2" minor="2"/>
    ...
</host>

<cluster ...>
    ...
    <version major="2" minor="2"/>
    <supported_versions/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="2" minor="2"/>
    <supported_versions/>
    ...
</data_center>

All hosts within a cluster are updated to VDSM 3.0 and the API reports:

<host ...>
    ...
    <version major="3" minor="0"/>
    ...
</host>

<cluster ...>
    ...
    <version major="2" minor="2"/>
    <supported_versions>
        <version major="3" minor="0"/>
    </supported_versions>
    ...
</cluster>

<data_center ...>
    ...
    <version major="2" minor="2"/>
    <supported_versions/>
    ...
</data_center>

The cluster is now updatable to 3.0 and the API reports:

<cluster ...>
    ...
    <version major="3" minor="0"/>
    <supported_versions/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="2" minor="2"/>
    <supported_versions>
        <version major="3" minor="0"/>
    </supported_versions>
    ...
</data_center>

The API user updates the data center to 3.0. Once upgraded, the API exposes features available in Red Hat Enterprise Virtualization 3.0

Chapter 7. Capabilities

The capabilities collection provides information about the supported capabilities of a Red Hat Enterprise Virtualization Manager. These capabilities include active features and available enumerated values for specific properties. An API user accesses this information through the rel="capabilities" link obtained from the entry point URI (see Chapter 4, Entry Point).

7.1. Version-Dependent Capabilities

The capabilities element contains any number of version elements which describe capabilities that are dependent on a compatiblity level.

The version element includes attributes for major and minor version numbers. This indicates the current version level, which this document discusses in Chapter 6, Compatibility Level Versions.

The following representation shows capabilities specific to Red Hat Enterprise Virtualization Manager 3.0 and 2.2 respectively:

<capabilities>
    <version major="3" minor="0">
        ...
    </version>
    <version major="2" minor="2">
        ...
    </version>
    ...
</capabilities>

Each version contains a series of capabilities dependent on the version specified. This includes:

Capability Element	Description
`current`	Signifies if this `version` most recent supported compatibility level
`features`	The list of features the version supports.
`cpus`	List of supported CPU types.
`power_managers`	List of supported fence agents and their configuration options.
`fence_types`	Supported fence actions for hosts
`storage_types`	Supported storage types for a version
`storage_domain_types`	List of all domain types
`vm_types`	List of all virtual machine types
`boot_devices`	Boot devices for a virtual machine
`display_types`	Available display protocols for a virtual machine
`nic_types`	Network interface types for a virtual machine
`disk_types`	List of storage device types
`disk_formats`	List of storage device formats
`disk_interfaces`	List of interfaces for storage devices
`vm_affinities`	Affinities for a host's placement policy
`custom_properties`	Environment variables for a virtual machine's custom scripts
`boot_protocols`	List of available protocols for IP assignment
`error_handling`	Options to determine virtual machine handling when a host in a cluster becomes non-operational
`storage_formats`	The format versions for storage meta-data

7.1.1. Current Version

The current element signifies if the version specified is the most recent supported compatibility level. The value is either a boolean true or false.

<capabilities>
    <version major="3" minor="0">
	      ...
        <current>true</current>
        ...
    </version>
</capabilities>

7.1.2. Features

Each version contains a list of compatible features.

Feature Element	Type	Description
`transparent_hugepages`	boolean: true or false	Defines the availablity of Transparent Hugepages for hosts

<capabilities>
    <version major="3" minor="0">
	      ...
        <features>
            <transparent_hugepages>true</transparent_hugepages>
        </features>
        ...
    </version>
</capabilities>

7.1.3. CPUs

Each cluster is configured with a minimal CPU type that all hosts in that cluster must support. Guests running on hosts within the cluster all run on this CPU type, ensuring that every guest can be live migrated to any host within the cluster.

Red Hat Enterprise Virtualization has a set of supported CPU types to choose from when configuring a cluster. Each CPU has the following properties:

Element	Description
`id`	An opaque identifier for the CPU model
`level`	An indication as to the relative priority/preference for the CPUs in the list. Higher is better

<capabilities>
    <version major="3" minor="0">
        ...
        <cpus>
            <cpu id="Intel Xeon w/o XD/NX">
                <level>2</level>
            </cpu>
            <cpu id="Intel Xeon">
                <level>3</level>
            </cpu>
            ...
        </cpus>
        ...
    </version>
</capabilities>

7.1.4. Power Managers

Red Hat Enterprise Virtualization platform provides a list of supported power_managers for host fencing configuration. Each power_management option contains the following properties:

Element	Description
`type`	The supported fencing device type
`options`	A list of options available to the supported fencing device. Options include a `name` and a value `type`.

<capabilities>
    <version major="3" minor="0">
        ...
        <power_managers>
            <power_management type="alom">
                <options>
                    <option type="bool" name="secure"/>
                    <option type="int" name="port"/>
                </options>
            </power_management>
            <power_management type="apc">
                <options>
                    <option type="bool" name="secure"/>
                    <option type="int" name="port"/>
                    <option type="int" name="slot"/>
                </options>
            </power_management>
            <power_management type="bladecenter">
                <options>
                    <option type="bool" name="secure"/>
                    <option type="int" name="port"/>
                    <option type="int" name="slot"/>
                </options>
            </power_management>
            ...
        </power_managers>
        ...
    </version>
</capabilities>

7.1.5. Fence Types

The fence_types element defines fence_type options to fence a troublesome host and reduce power usage.

<capabilities>
    <version major="3" minor="0">
	      ...
        <fence_types>
            <fence_type>manual</fence_type>
            <fence_type>restart</fence_type>
            <fence_type>start</fence_type>
            <fence_type>stop</fence_type>
            <fence_type>status</fence_type>
        </fence_types>
        ...
    </version>
</capabilities>

7.1.6. Storage Types

The storage_types element defines the available physical storage_type options.

<capabilities>
    <version major="3" minor="0">
	      ...
        <storage_types>
            <storage_type>iscsi</storage_type>
            <storage_type>fcp</storage_type>
            <storage_type>nfs</storage_type>
            <storage_type>local</storage_type>
        </storage_types>
        ...
    </version>
</capabilities>

7.1.7. Storage Domain Types

The storage_domain_types element shows the available storage_domain_type options a user creates in a virtualization environment.

<capabilities>
    <version major="3" minor="0">
	      ...
        <storage_domain_types>
            <storage_domain_type>data</storage_domain_type>
            <storage_domain_type>iso</storage_domain_type>         
            <storage_domain_type>export</storage_domain_type>          
        </storage_domain_types>
        ...
    </version>
</capabilities>

7.1.8. Virtual Machine Types

The vm_types element defines each virtual machine type (vm_type) available for creation in a virtual environment.

<capabilities>
    <version major="3" minor="0">
	      ...
        <vm_types>
            <vm_type>desktop</vm_type>
            <vm_type>server</vm_type>
        </vm_types>
        ...
    </version>
</capabilities>

7.1.9. Boot Devices

Each virtual machine boots from a selected device. The boot_devices element lists such boot_device options.

<capabilities>
    <version major="3" minor="0">
	      ...
        <boot_devices>
            <boot_device>cdrom</boot_device>
            <boot_device>hd</boot_device>
            <boot_device>network</boot_device>
        </boot_devices>
        ...
    </version>
</capabilities>

7.1.10. Display Types

Access to a virtual machine through Red Hat Enterprise Virtualization Manager requires a display protocol. The display_types element lists each display_type protocol.

<capabilities>
    <version major="3" minor="0">
	      ...
        <display_types>
            <display_type>vnc</display_type>
            <display_type>spice</display_type>
        </display_types>
        ...
    </version>
</capabilities>

7.1.11. NIC Types

A virtual machine requires a network interface to connect to a network. The nic_types element defines the supported NIC types available. Each nic_type depends on the drivers available for different types of virtual machines. VirtIO drivers are available for Red Hat Enterprise Linux 4.8 and above, and for Windows virtual machines. Windows supports rtl8139 without the need for drivers. Other Linux machines, or earlier versions of Red Hat Enterprise Linux, use e1000 or rtl8139.

<capabilities>
    <version major="3" minor="0">
	      ...
        <nic_types>
            <nic_type>e1000</nic_type>
            <nic_type>virtio</nic_type>
            <nic_type>rtl8139</nic_type>
            <nic_type>rtl8139_virtio</nic_type>
        </nic_types>
        ...
    </version>
</capabilities>

7.1.12. Disk Types

Each virtual machine requires a virtual disk for storage. The disk_types element lists the available virtual disk_type options.

<capabilities>
    <version major="3" minor="0">
	      ...
	      <disk_types>
            <disk_type>data</disk_type>
            <disk_type>shared</disk_type>
            <disk_type>swap</disk_type>
            <disk_type>system</disk_type>
            <disk_type>temp</disk_type>
        <disk_types
        ...
    </version>
</capabilities>

7.1.13. Disk Formats

An API user selects the format for virtual disks. The disk_formats element defines the format types. The disk_format types include pre-allocated (raw) or thin-provisioned (Copy-On-Write or cow).

<capabilities>
    <version major="3" minor="0">
	      ...
        <disk_formats>
            <disk_format>cow</disk_format>
            <disk_format>raw</disk_format>
        </disk_formats>
        ...
    </version>
</capabilities>

7.1.14. Disk Interfaces

The disk_interfaces element lists disk_interface options for emulated protocols to interface with virtual disks.

<capabilities>
    <version major="3" minor="0">
	      ...
        <disk_interfaces>
            <disk_interface>ide</disk_interface>
            <disk_interface>scsi</disk_interface>
            <disk_interface>virtio</disk_interface>
        </disk_interfaces>
        ...
    </version>
</capabilities>

7.1.15. Virtual Machine Affinities

Virtual machines migrate between hosts in a cluster. The vm_affinities element defines each available migration affinity for virtual machines.

<capabilities>
    <version major="3" minor="0">
	      ...
        <vm_affinities>
            <affinity>migratable</affinity>
            <affinity>user_migratable</affinity>
            <affinity>pinned</affinity>
        </vm_affinities>
        ...
    </version>
</capabilities>

7.1.16. Custom Properties

The custom_properties element lists a set of environment variables for a virtual environment. The virtual environment uses these variables as parameters for event-triggered VDSM scripts. Each custom_property includes attributes for a property name and a regular expression (regexp) to define the format of the property value.

<capabilities>
    <version major="3" minor="0">
	      ...
        <custom_properties>
            <custom_property name="sap_agent" regexp="^(true|false)$"/>
            <custom_property name="sndbuf" regexp="^[0-9]+$"/>
            <custom_property name="vhost"
              regexp="^(([a-zA-Z0-9_]*):(true|false))(,(([a-zA-Z0-9_]*):(true|false)))*$"/>
            <custom_property name="viodiskcache"
              regexp="^(none|writeback|writethrough)$"/>
        </custom_properties>
        ...
    </version>
</capabilities>

7.1.17. Boot Protocols

The boot_protocol element lists each possible IP assignment boot_protocol for hosts when booting.

<capabilities>
    <version major="3" minor="0">
	      ...
        <boot_protocols>
            <boot_protocol>dhcp</boot_protocol>
            <boot_protocol>static</boot_protocol>
        </boot_protocols>
        ...
    </version>
</capabilities>

7.1.18. Error Handling

A Red Hat Enterprise Virtualization Manager determines whether to migrate virtual machines on a non-operational host using one of the on_error options the in the error_handling element.

<capabilities>
    <version major="3" minor="0">
	      ...
        <error_handling>
            <on_error>migrate</on_error>
            <on_error>do_not_migrate</on_error>
            <on_error>migrate_highly_available</on_error>
        </error_handling>
        ...
    </version>
</capabilities>

7.1.19. Storage Formats

The storage_formats element lists the available format versions for storage meta-data.

<capabilities>
    <version major="3" minor="0">
	      ...
        <storage_formats>
            <format>v1</format>
            <format>v2</format>
        </storage_formats>
        ...
    </version>
</capabilities>

7.2. Permits

Permits are allowable actions a user assigns to a role. Each permit contains:

Element	Type	Description
`id=`	integer	The opaque identifier for a permit
`name`	string	The name of the permit
`administrative`	boolean: true or false	The permit is assigned to only administrative roles

<capabilities>
    ...  
    <permits>
	      <permit id="1">
            <name>CREATE_VM</name>
            <administrative>false</administrative>
        </permit>
        <permit id="2">
            <name>DELETE_VM</name>
            <administrative>false</administrative>
        </permit>
        ...
    </permits>
    ...
</capabilities>

7.3. Scheduling Policies

The scheduling_policies element defines the load-balancing and power sharing modes for hosts in the cluster.

<capabilities>
    ...  
    <scheduling_policies>
        <policy>evenly_distributed</policy>
        <policy>power_saving</policy>
    </scheduling_policies>
    ...
</capabilities>

7.4. Capabilities Example

The following example demonstrates a sample representation of capabilities.

Example 7.1. XML representation of capabilities

An API user performs the following request:

GET /rhevm-api/capabilities HTTP/1.1
Accept: application/xml

The API returns the following representation:

HTTP/1.1 200 OK
Content-Type: application/xml

<capabilities>
    <version minor="0" major="3">
        <current>true</current>
        <features>
            <transparent_hugepages>true</transparent_hugepages>
        </features>
        <cpus>
            <cpu id="Intel Conroe Family">
                <level>3</level>
            </cpu>
            <cpu id="Intel Penryn Family">
                <level>4</level>
            </cpu>
            ...
        </cpus>
        <power_managers>
            <power_management type="alom">
                <options>
                    <option type="bool" name="secure"/>
                    <option type="int" name="port"/>
                </options>
            </power_management>
            <power_management type="apc">
                <options>
                    <option type="bool" name="secure"/>
                    <option type="int" name="port"/>
                    <option type="int" name="slot"/>
                </options>
            </power_management>
            ...
        </power_managers>
        <fence_types>
            <fence_type>manual</fence_type>
            <fence_type>restart</fence_type>
            <fence_type>start</fence_type>
            <fence_type>stop</fence_type>
            <fence_type>status</fence_type>
        </fence_types>
        <storage_types>
            <storage_type>iscsi</storage_type>
            <storage_type>fcp</storage_type>
            <storage_type>nfs</storage_type>
            <storage_type>local</storage_type>
        </storage_types>
        <storage_domain_types>
            <storage_domain_type>data</storage_domain_type>
            <storage_domain_type>iso</storage_domain_type>
            <storage_domain_type>export</storage_domain_type>
        </storage_domain_types>
        <vm_types>
            <vm_type>desktop</vm_type>
            <vm_type>server</vm_type>
        </vm_types>
        <boot_devices>
            <boot_device>cdrom</boot_device>
            <boot_device>hd</boot_device>
            <boot_device>network</boot_device>
        </boot_devices>
        <display_types>
            <display_type>vnc</display_type>
            <display_type>spice</display_type>
        </display_types>
        <nic_types>
            <nic_type>e1000</nic_type>
            <nic_type>virtio</nic_type>
            <nic_type>rtl8139</nic_type>
            <nic_type>rtl8139_virtio</nic_type>
        </nic_types>
        <disk_types>
            <disk_type>data</disk_type>
            <disk_type>shared</disk_type>
            <disk_type>swap</disk_type>
            <disk_type>system</disk_type>
            <disk_type>temp</disk_type>
        </disk_types>
        <disk_formats>
            <disk_format>cow</disk_format>
            <disk_format>raw</disk_format>
        </disk_formats>
        <disk_interfaces>
            <disk_interface>ide</disk_interface>
            <disk_interface>scsi</disk_interface>
            <disk_interface>virtio</disk_interface>
        </disk_interfaces>
        <vm_affinities>
            <affinity>migratable</affinity>
            <affinity>user_migratable</affinity>
            <affinity>pinned</affinity>
        </vm_affinities>
       <custom_properties>
            <custom_property name="sap_agent" regexp="^(true|false)$"/>
            <custom_property name="sndbuf" regexp="^[0-9]+$"/>
            ...
        </custom_properties>
        <boot_protocols>
            <boot_protocol>dhcp</boot_protocol>
            <boot_protocol>static</boot_protocol>
        </boot_protocols>
        <error_handling>
            <on_error>migrate</on_error>
            <on_error>do_not_migrate</on_error>
            <on_error>migrate_highly_available</on_error>
        </error_handling>
        <storage_formats>
            <format>v1</format>
            <format>v2</format>
        </storage_formats>
    </version>
    <permits>
        <permit id="1">
            <name>CREATE_VM</name>
            <administrative>false</administrative>
        </permit>
        <permit id="2">
            <name>DELETE_VM</name>
            <administrative>false</administrative>
        </permit>
        ...
    </permits>
    <scheduling_policies>
        <policy>evenly_distributed</policy>
        <policy>power_saving</policy>
    </scheduling_policies>
</capabilities>

Chapter 8. Common Features

8.1. Representations

8.2. Collections

8.2.1. Listing All Resources in a Collection
8.2.2. Listing Extended Resource Sub-Collections
8.2.3. Search Queries

8.3. Resources

8.3.1. Retrieving a Resource
8.3.2. Creating a Resource
8.3.3. Creating a Resource Asynchronously
8.3.4. Updating a Resource
8.3.5. Deleting a Resource
8.3.6. Sub-Collection Relationships
8.3.7. XML Element Relationships
8.3.8. Actions
8.3.9. Permissions
8.3.10. Handling Errors

This chapter examines features common to resources and collections.

Element property icons

Throughout this guide, the elements of each resource are detailed in tables. These tables include a properties column, displaying icons depicting element properties. The meaning of these icons is shown in Table 8.1, “Element property icons”

Table 8.1. Element property icons

Property	Description	Icon
Required for creation	These elements must be included in the client-provided representation of a resource on creation, but are not mandatory for an update of a resource.
Non-updateable	These elements cannot have their value changed when updating a resource. They are only included in a client-provided representation on update if their values are not altered. Otherwise they are omitted from an update action.
Read-only	These elements are read-only. Values for read-only elements are not created or modified.

8.1. Representations

The API structures resource representations in the following XML document structure:

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>Resource-Name</name>
    <description>A description of the resource</description>
    ...
</{resource}>

In the context of a virtual machine, the representation appears as follows:

<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
  href="/rhevm-api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprize Linux 6 Virtual Machine</description>
    ...
</vm>

The following attributes are common to all resource descriptions:

Element	Type	Description	Properties
`id`	GUID	An opaque server-generated identifier for the resource, which is guaranteed to be unique across all resources in this Red Hat Enterprise Virtualization Manager instance
`href`	string	The canonical location of the resource as an absolute path

8.2. Collections

This section examines common features for collections.

8.2.1. Listing All Resources in a Collection

A listing of the resources in a collection is obtained by issuing a GET request on the collection URI obtained from the entry point.

GET /rhevm-api/{collection} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<{collection}>
    <{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </{resource}>
    ...
</{collection}>

8.2.2. Listing Extended Resource Sub-Collections

Collection requests extend resource representations to include sub-collections using the detail parameter in the Accept header.

GET /rhevm-api/{collection} HTTP/1.1
Accept: application/xml; detail={subcollection}

This includes multiple sub-collection requests using either seperated detail parameters:

GET /rhevm-api/{collection} HTTP/1.1
Accept: application/xml; detail={subcollection 1}; detail={subcollection 2}

Or one detail parameter that seperates the sub-collection with the + operator:

GET /rhevm-api/{collection} HTTP/1.1
Accept: application/xml; detail={subcollection 1}+{subcollection 2}+{subcollection 3}

The API only supports the statistics sub-collection listings for vms and hosts. For example:

GET /rhevm-api/vms HTTP/1.1
Accept: application/xml; detail=statistics

8.2.3. Search Queries

A collection is queried using a GET request on an appropriate "collection/search" URI template, instantiated with a query constraint expressed in the Red Hat Enterprise Virtualization Manager query language. Only those resources in the collection satisfying the constraint will be returned.

GET /rhevm-api/{collection}?search={query} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<{collection}>
    <{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
        ...
    </{resource}>
    ...
</{collection}>

8.2.3.1. Query Syntax

The API uses the following syntax to perform search queries with a GET request:

GET /rhevm-api/{collection}?search={query} HTTP/1.1
Accept: application/xml

The query refers to the search query the API directs to the collection. This query takes the following form:

{property} {operator} {value}

The property refers to any element within the collection that contains a searchable value. For example, a search for a virtual machine name in the vms collection requires the name property.

The operator is a comparison operation between your chosen value and the property value. The API requires this operator to be URL encoded. The following table lists the API's supported operators and their URL encoded equivalents:

Description	Operator	URL Encoded
is equal to	`=`	`%3D`

The value refers to the value contained within the chosen property. For example, to search for a virtual machine named "vm1", the value would need to be vm1.

The combined collection and query examples produce the following search query:

GET /rhevm-api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml

8.2.3.2. Wildcards

Search queries substitute part of a value with an asterisk as a wildcard. For example:

GET /rhevm-api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
Content-Type: application/xml

This query would result in all virtual machines with names beginning with vm, such as vm1, vm2, vma or vm-webserver.

GET /rhevm-api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

This query would result in all virtual machines with names beginning with v and ending with 1, such as vm1, vr1 or virtualmachine1.

8.3. Resources

This section examines common features for resources.

8.3.1. Retrieving a Resource

The state of a resource is retrieved using GET request on a URI obtained from the listing above.

GET /rhevm-api/{collection}/{resource_id} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    ...
</{resource}>

8.3.2. Creating a Resource

A new resource is created with a POST request to collection URI containing a representation of the new resource.

Each resource type has its own specific required properties. The client supplies these properties when creating a new resource. Refer to the indiviual resource type documentation for more details. If a required property is absent, the creation will fail with a fault representation indicating the missing elements.

POST /rhevm-api/{collection} HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<{resource}>
    <name>Resource-Name</name>
</{resource}>

HTTP/1.1 201 Created
Location: http://{host}/rhevm-api/{collection}/{resource_id}
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>Resource-Name</name>
    ...
</{resource}>

The Location header in the response gives the URI of the queried resource. The response body contains either a complete representation, partial representation or no representation of the resource. It is recommended that clients rely only on fetching the representation via the URI in the response header.

8.3.3. Creating a Resource Asynchronously

Certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resources results in a 202 Accepted status. The initial document structure for a 202 Accepted resource also contains a creation_status element and link for creation status updates. For example:

POST /rhevm-api/{collection} HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<{resource}>
    <name>Resource-Name</name>
</{resource}>

HTTP/1.1 202 Accepted
Location: http://{host}/rhevm-api/{collection}/{resource_id}
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>Resource-Name</name>
    <creation_status>PENDING</creation status>
    <link rel="creation_status" 
      href="/rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id}"/>
      ...
</{resource}>

A GET request to the creation_status link provides a creation status update:

GET /rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<creation id="{creation_status_id}"
  href="/rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id}">
    <status>COMPLETE</status>
</creation>

Overriding the asynchronous resource creation requires an Expect: 201-created header:

POST /rhevm-api/{collection} HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<{resource}>
    <name>Resource-Name</name>
</{resource}>

8.3.4. Updating a Resource

Some resource properties are modified with a PUT request containing an updated description for the resource URI. Details on modifiable properties are found in the individual resource type documentation.

PUT /rhevm-api/{collection}/{resource_id} HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<{resource}>
    <name>New-Resource-Name</name>
</{resource}>

HTTP/1.1 200 OK
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>New-Resource-Name</name>
    ...
</{resource}>

If an attempt is made to modify a strictly immutable resource property, this is reported as 409 Conflict error with a fault representation in the response body. Other non-modifiable properties specified in the request entity-body are to be ignored.

8.3.5. Deleting a Resource

A resource is deleted by issuing a DELETE request to its URI.

DELETE /rhevm-api/{collection}/{resource_id} HTTP/1.1

HTTP/1.1 204 No Content

8.3.6. Sub-Collection Relationships

A sub-collection relationship defines hierarchical link between a resource and a sub-collection. The sub-collection exists, or at least has some meaning, in the context of a parent resource. For example, a virtual machine contains network interfaces, which means the API maps the relationship between the virtual machine resource and the network interfaces sub-collection.

The API defines a relationship between a resource and a sub-collection using the link rel= attribute:

GET /rhevm-api/{collection}/{resource_id} HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    ...
    <link rel="{subcollection}"
      href="/rhevm-api/{collection}/{resource_id}/{subcollection}"/>
    ...
</{resource}>

This means an API user queries the sub-collection at /rhevm-api/{collection}/{resource_id}/{subcollection}:

GET /rhevm-api/{collection}/{resource_id}/{subcollection} HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/xml

<{subcollection}>
    <{subresource} id="{subresource_id}"
      href="/rhevm-api/{collection}/{resource_id}/{subcollection}/{subresource_id}">
        ...
    </{subresource}>
    ...
</{subcollection}>

8.3.7. XML Element Relationships

XML element links define relationships between resources. These resources include:

Backlinks from a resource in a sub-collection to a parent resource; or
Links between resources with an arbitrary relationship.

An element link in a resource requires a special XML element tag to refer to another resource:

GET /rhevm-api/{collection}/{resource_id}/{subcollection}/{subresource_id} HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/xml

<{subcollection}>
    <{subresource} id="{subresource_id}"
      href="/rhevm-api/{collection}/{resource_id}/{subcollection}/{subresource_id}">
        <{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}"/>
        ...
    </{subresource}>
</{subcollection}>

8.3.8. Actions

Most resources include a list of action links.

<{resource}>
    ...
    <actions>
        <link rel="start" href="/rhevm-api/{collection}/{resource_id}/start"/>
        <link rel="stop" href="/rhevm-api/{collection}/{resource_id}/stop"/>
        ...
    </actions>
    ...
</resource>

An action is invoked with a POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and/or task-specific parameters. Common action parameters include:

`async`	`true` if the server should respond immediately with `202 Accepted` and an action representation contains a `href` link to be polled for completion.
`grace_period`	a grace period in milliseconds, which must expire before the action is initiated.

Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a fault response.

When the action is initiated asychronously, the immediate 202 Accepted response provides a link to monitor the status of the task:

POST /rhevm-api/{collection}/{resource_id}/{action} HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<action>
    <async>true</async>
</action>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<action id="{action_id}"
  href="/rhevm-api/{collection}/{resource_id}/{action}/{action_id}">
    <async>true</async>
    ...
<action>

A subsequent GET on the action URI provides an indication of the status of the asynchronous task:

`PENDING`	task has not yet started.
`IN_PROGRESS`	task is in flight.
`COMPLETE`	task has completed successfully.
`FAILED`	task has failed. The returned `action` representation would contain a `fault` describing the failure.

Once the task has completed, the Action is retained for an indeterminate period. Once this has expired, subsequent GETs are 301 Moved Permanently redirected back to the target resource.

GET /rhevm-api/{collection}/{resource_id}/{action}/{action_id} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<action id="{action_id}"
  href="/rhevm-api/{collection}/{resource_id}/{action}/{action_id}">
    <status>{PENDING|IN_PROGRESS|COMPLETE|FAILED}</status>
    <link rel="parent" /rhevm-api/{collection}/{resource_id}"/>
    <link rel="replay" href="/rhevm-api/{collection}/{resource_id}/{action}"/>
<action>

An action representation also includes some links that are identified by the rel attribute:

`parent`	A link back to the resource of this action
`replay`	A link back to the original action URI. POSTing to this URI will causing the action to be re-initiated

8.3.9. Permissions

Each resource contains a permissions sub-collection. Each permission contains a user, an assigned role and the specified resource. For example:

GET /rhevm-api/{collection}/{resource_id}/permissions HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<permissions>
    <permission id="{permission-id}"
      href="/rhevm-api/{collection}/{resource_id}/permissions/{permission_id}">
        <role id="{role_id}" href="/rhevm-api/roles/{role_id}"/>
        <user id="{user_id}" href="/rhevm-api/users/{user_id}"/>
        <{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}"/>
    </permission>
    ...
</permissions>

A resource acquires a new permission when POSTed to its permissions sub-collection. Each new permission requires a role and a user:

POST /rhevm-api/{collection}/{resource_id}/permissions HTTP/1.1
Accept: application/xml

<permission">
    <role id="{role_id}"/>
    <user id="{user_id}"/>
</permission>

HTTP/1.1 201 Created
Content-Type: application/xml

<permission id="{permission_id}"
  href="/rhevm-api/resources/{id}/permissions/{permission_id}">
    <role id="{role_id}" href="/rhevm-api/roles/{role_id}"/>
    <user id="{user_id}" href="/rhevm-api/users/{user_id}"/>
    <{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}"/>
</permission>

8.3.10. Handling Errors

Some errors require further explanation beyond that provided by a standard HTTP status code. For example, an unsuccessful resource state update or action is reported with a fault representation in the response entity-body. The fault contains reason and detail strings, which are also localized depending on the Accept-Language HTTP header. Clients initiating a request that fails in this way are to unmarshal either a fault or the expected resource representation, depending on the response status code. Such cases are clearly indicated in the individual resource documentation.

PUT /rhevm-api/{collection}/{resource_id} HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<{resource}>
    <id>id-update-test</id>
</{resource}>

HTTP/1.1 409 Conflict
Content-Type: application/xml

<fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
</fault>

Chapter 9. Data Centers

9.1. Storage Domains Sub-Collection

9.1.1. Activate Action
9.1.2. Deactivate Action
9.1.3. Export Storage Domains

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

The following table shows specific elements contained in a data center 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 data center. The `name` is unique across all data center resources.
`description`	string	A free-form user-supplied human readable description of the data center
`link rel="storagedomains"`	string	A link to the sub-collection for storage domains attached to this data center
`link rel="permissions"`	string	A link to the sub-collection for data center permissions. See Section 8.3.9, “ Permissions ”
`storage_type`	enumerated	Describes the storage type in this datacenter. A list of enumerated values is available in `capabilities`. See Section 7.1.6, “Storage Types”
`storage_format`	enumerated	Describes the storage format version for the data center. A list of enumerated values are available in `capabilities`. See Section 7.1.19, “Storage Formats”
`version`	complex	The compatibility level of the data center. See Chapter 6, Compatibility Level Versions
`supported_versions`	complex	A list of possible `version` levels for the data center. See Chapter 6, Compatibility Level Versions
`status`	see below	The data center status

The status contains one of the following enumerative values: DOWN, ERROR, INITIALIZING, INSTALLING, INSTALL_FAILED, MAINTENANCE, NON_OPERATIONAL, NON_RESPONSIVE, PENDING_APPROVAL, PREPARING_FOR_MAINTENANCE, PROBLEMATIC, REBOOT, UNASSIGNED or UP.

Example 9.1. An XML representation of a data center

<data_centers>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
          storagedomains"/>
        <link rel="permissions"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/>
        <storage_type>nfs</storage_type>
        <storage_format>v1</storage_format>
        <version minor="0" major="3"/>
        <supported_versions>
            <version minor="0" major="3"/>
        </supported_versions>
        <status>UP</status>
    </data_center>
</data_centers>

When creating a new data center, the name, storage_type and version elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 9.2. Creating a data center

POST /rhevm-api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>NewDatacenter</name>
    <storage_type>nfs</storage_type>
    <version minor="0" major="3"/>
</data_centers>

The name and description elements are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 9.3. Updating a data center

PUT /rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>UpdatedName</name>
    <description>An updated description for the data center</description>
</data_centers>

9.1. Storage Domains Sub-Collection

Each data center contains a sub-collection for attached storages domain. A data center is only ready for use when at least one storage domain is attached, which an API user accomplishes when POSTing a representation of the desired storage domain to the data center's storage domains sub-collection.

An attached storage domain has a similar representation to a top-level storage domain, with the exception that it has a data center specific status and set of actions.

When attaching a storage domain, its ID or name must be supplied. An example of attaching a storage domain to a data center:

Example 9.4. Attach a storage domain to a data center

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Content-type: application/xml

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

HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
  fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>images0</name>
    <type>data</type>
    <status>INACTIVE</status>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <actions>
        <link rel="activate"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
        <link rel="deactivate"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
    </actions>
</storage_domain>

There are two possible actions for attached storage domains: activate and deactivate.

9.1.1. Activate Action

An attached storage domain is activated on a data center before use. The activate action does not take any action specific parameters.

Example 9.5. Action to active a storage domain on a datacenter

POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1
Content-type: application/xml

9.1.2. Deactivate Action

An attached storage domain is deactivated on a data center before removal. The deactivate action does not take any action specific parameters.

Example 9.6. Action to deactive a storage domain on a datacenter

  POST /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1
  Content-type: application/xml

9.1.3. Export Storage Domains

Storage domains with type set to export contain vms and templates sub-collections which list the import candidate VMs and templates stored on that particular storage domain.

VMs and templates in these collections have a similar representation to their counterparts in the top-level VMs and templates collection, except they also contain a storage_domain reference and an import action (see Section 14.6.8, “ Import Action ”).

Example 9.7. Listing the virtual machines sub-collection of an export storage domain on a datacenter

GET /rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml

<vms>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
      fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
        <name>vm1</name>
        ...
        <storage_domain id="082c794b-771f-452f-83c9-b2b5a19c0399"
          href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
        <actions>
            <link rel="import" href="/rhevm-api/datacenters/
              d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
              fabe0451-701f-4235-8f7e-e20e458819ed/vms/
              082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        </actions>
    </vm>
</vms>

Chapter 10. Host Clusters

10.1. Networks Sub-Collection

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

The following table shows specific elements contained in a host cluster 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 cluster. The `name` is unique across all cluster resources.
`description`	string	A free-form user-supplied human readable description of the cluster
`link rel="networks"`	string	A link to the sub-collection for networks associated with this cluster
`link rel="permissions"`	string	A link to the sub-collection for cluster permissions. See Section 8.3.9, “ Permissions ”
`cpu`	complex	A server CPU reference that defines the CPU type all hosts must support in the cluster. See Section 7.1.3, “CPUs”
`data_center id`	complex	A reference to the data center membership of this cluster. See Chapter 9, Data Centers
`memory_policy`	complex	Defines the cluster's policy on host memory utilization. See below.
`scheduling_policy`	complex	Defines the load-balancing or power sharing modes for hosts in the cluster. See below.
`version`	complex	The compatibility level of the cluster (see Chapter 6, Compatibility Level Versions)
`supported_versions`	complex	A list of possible `version` levels for the cluster. See Chapter 6, Compatibility Level Versions
`error_handling`	complex/enumerated	Defines virtual machine handling when a host within a cluster becomes non-operational. Requires a single `on_error` element containing an enumerated type property listed in `capabilities`. See Section 7.1.18, “Error Handling”

The memory_policy element can contain the following specific elements:

Element	Type	Description	Properties
`overcommit`	complex	The percentage of host memory allowed in use before no more virtual machines can start on a host. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include `100` (None), `150` (Server Load) and `200` (Desktop Load).
`transparent_hugepages`	complex	Define the `enabled` status of Transparent Hugepages. The status is either true or false. Check `capabilities` feature set (see ) to ensure your version supports `transparent hugepages`.

The scheduling_policy element can contain the following specific elements:

Element	Type	Description	Properties
`policy`	enumerated	The VM scheduling mode for hosts in the cluster. A list of enumerated types are listed in `capabilities`. See Section 7.3, “Scheduling Policies”
`thresholds`	complex	Defines CPU limits for the host. The `high` attribute controls the highest CPU usage percentage the host can have before being considered overloaded. The `low` attribute controls the lowest CPU usage percentage the host can have before being considered underutilized. The `duration` attribute refers to the number of seconds the host needs to be overloaded before the scheduler starts and moves the load to another host.

Example 10.1. An XML representation of a host cluster

<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <memory_policy>
            <overcommit percent="100"/>
            <transparent_hugepages>
                <enabled>false</enabled>
            </transparent_hugepages>
        </memory_policy>
        <scheduling_policies>
          <policy>evenly_distributed</policy>
          <thresholds low="10" high="75" duration="120"/>
        </scheduling_policies>
        <version minor="0" major="3"/>
        <supported_versions>
            <version minor="0" major="3"/>
        </supported_versions>
        <error_handling>
            <on_error>migrate</on_error>
        </error_handling>
    </cluster>
</clusters>

When creating a new cluster, the name, cpu id and datacenter properties are required. The datacenter is identified with either name or id. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 10.2. Creating a host cluster

POST /rhevm-api/cluster HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <name>cluster1</name>
    <cpu id="Intel Penryn Family"/>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"/>
</cluster>

The name, description and cpu id elements are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 10.3. Updating a host cluster

PUT /rhevm-api/cluster/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <description>Cluster 1</description>
</cluster>

10.1. Networks Sub-Collection

Networks are associated with clusters and are represented with the networks sub-collection. Every host within the cluster must have a network interface attached to that network in order for the network to be operational.

The representation of a cluster's network sub-collection is the same as a standard network resource with an additional cluster id to signify a relationship to the cluster.

An API user manipulates the networks sub-collection as described in Chapter 8, Common Features. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.

Example 10.4. Associating a network resource with a cluster

POST /rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <name>rhevm</name>
</network>

HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
  href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>rhevm</name>
    <status>OPERATIONAL</status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
</network>

An association is removed with a DELETE request to the appropriate element in the collection.

Example 10.5. Removing an network association to a cluster

DELETE /rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1

HTTP/1.1 204 No Content

Chapter 11. Networks

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

The following table shows specific elements contained in a network 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 network. The `name` is unique across all network resources.
`description`	string	A free-form user-supplied human readable description of the network
`data_center id`	complex	A reference to the data center of which this cluster is a member. See Chapter 9, Data Centers
`ip address= netmask= gateway=`	complex	Static IP configuration for the network
`vlan id=`	GUID	A VLAN tag
`stp`	boolean: true or false	`true` if Spanning Tree Protocol is enabled on this network
`status`	One of `OPERATIONAL` or `NON_OPERATIONAL`	The status of the network
`display`	boolean: true or false	`true` if this network is the display network

Example 11.1. An XML representation of a network resource

<network id="00000000-0000-0000-0000-000000000009"
  href="/rhevm-api/networks/00000000-0000-0000-0000-000000000009">
    <name>rhevm</name>
    <description>Management Network</description>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/rhevm-api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
    <stp>false</stp>
    <status>OPERATIONAL</status>
    <display>false</display>
</network>

When creating a new data center, the name and datacenter are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 11.2. Creating a network resource

POST /rhevm-api/networks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <name>network 1</name>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"/>
</network>

the name, description, ip, vlan, stp and display elements are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 11.3. Updating a network resource

PUT /rhevm-api/networks/e6575a87-377c-4f67-9c1b-7b94eff76b17 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <description>Network 1</description>
</network>

Chapter 12. Storage Domains

12.1. Storage types

12.1.1. NFS
12.1.2. iSCSI and FCP
12.1.3. LOCAL

12.2. Files Sub-Collection

12.3. Import Existing Storage Domain

12.4. Delete Storage Domain

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

The following table shows specific elements contained in a storage domain 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 storage domain. The `name` is unique across all storage domain resources.
`link rel="permissions"`	string	A link to the sub-collection for storage domain permissions. See Section 8.3.9, “ Permissions ”
`link rel="files"`	string	A link to the files sub-collection for this storage domains
`type`	enumerated	The storage domain type. A list of enumerated values are available in `capabilities`. See Section 7.1.7, “Storage Domain Types”.
`master`	boolean: true or false	`true` if this is the master storage domain of a data center
`host`	complex	A reference to the host on which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified.
`storage`	complex	Describes the underlying storage of the storage domain. For more information see Section 12.1, “ Storage types ”.
`available`	integer	Space available in bytes
`used`	integer	Space used in bytes
`committed`	integer	Space committed in bytes
`storage_format`	enumerated	Describes the storage format version for the storage domain. A list of enumerated values are available in `capabilities`. See Section 7.1.19, “Storage Formats”

Example 12.1. An XML representation of a storage domain

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/rhevm-api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/rhevm-api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
    <type>data</type>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <available>156766306304</available>
    <used>433791696896</used>
    <committed>617401548800</committed>
    <storage_format>v1</storage_format>
</storage_domain>

When creating a new storage domain, the name, type and storage elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 12.2. Creating a storage domain

POST /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

Only the name element may be updated post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 12.3. Updating a storage domain

PUT /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

The API user attaches the storage domain to a data center after creation. See Section 9.1, “ Storage Domains Sub-Collection ” for instructions.

12.1. Storage types

The storage element contains a type element, which is an enumerated value found under the capabilities collection. See Section 7.1.6, “Storage Types”.

The storage element also contains additional elements specific to each storage type. The next few section examine these additional storage type elements.

12.1.1. NFS

The nfs specific elements in a storage description are:

Element	Type	Description	Properties
`address`	string	The host name or IP address of the NFS server
`path`	string	The path of NFS mountable directory on the server

12.1.2. iSCSI and FCP

The iscsi and fcp specific elements in a storage description are:

Element	Type	Description	Properties
`logical_unit id`	complex	A storage domain may be composed of multiple iSCSI or FCP logical units
`volume_group id`	complex	Alternatively, a storage domain may be based on a single LVM Volume Group which, in turn, may be composed of multiple iSCSI or FCP logical units

See Section 13.4, “ Storage Sub-Collection ” for more details.

In the case of iSCSI, if a logical_unit description also contains details of the iSCSI target containing the LUN in question, the target will be automatically logged into when the storage domain is created.

12.1.3. LOCAL

The local specific elements in a storage description are:

Element	Type	Description	Properties
`path`	string	The path of local storage domain on the host

A local storage domain requires a data center with storage_type set to LOCAL (see Chapter 9, Data Centers). This data center only contains a single host cluster, and the host cluster only contains a single host.

12.2. Files Sub-Collection

The files sub-collection under each storage domain provides a way for clients to list available files. This sub-collection is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads through Red Hat Enterprise Virtualization Manager.

The addition of a CD-ROM device to a VM requires an ISO image from the files sub-collection of an ISO storage domain.

Example 12.4. Listing the files sub-collection of an ISO storage domain

GET /rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

<files>
    <file id="en_winxp_pro_with_sp2.iso"
      href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      en_winxp_pro_with_sp2.iso">
        <name>en_winxp_pro_with_sp2.iso</name>
        <type>iso</type>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
    <file id="boot.vfd"
      href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      boot.vfd">
        <name>boot.vfd</name>
        <type>vfd</type>
        <storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/rhevm-api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>

Like other resources, files have opaque id and href attributes. The name element actually contains the filename.

12.3. Import Existing Storage Domain

API provides a user with the ability to remove an ISO or Export storage domain from one Red Hat Enterprise Virtualization Manager instance without re-formatting the underlying storage and import it into another instance. Importing is achieved similarly to adding a new storage domain, except that the name is ignored and not required.

Example 12.5. Importing an Exisiting Export Storage Domain

POST /rhevm-api/storagedomains HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<storage_domain>
    <type>export</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/export-domain</path>
    </storage>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</storage_domain>

HTTP/1.1 201 Created
Location: http://{host}/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>export1</name>
    ...
</storage_domain>

12.4. Delete Storage Domain

A storage_domain reference must be passed in the body of a DELETE request for a storage domain. The storage_domain reference must be in the form:

<storage_domain>
    <host id="..."/>
</storage_domain>

<storage_domain>
    <host>
        <name>...</name>
    </host>
</storage_domain>

Optionally, a format element may be passed to specify whether or not to format the storage domain after deletion.

Example 12.6. Formating a Storage Domain after Deletion

<storage_domain>
    <host id="..."/>
    <format>true</format>
</storage_domain>

If no format element is passed, the storage domain will not be formatted.

Chapter 13. Hosts

13.1. Power Management

13.2. Memory Management

13.3. Network Interface Sub-Collection

13.3.1. Bonded Interfaces
13.3.2. Attach Action
13.3.3. Detach Action

13.4. Storage Sub-Collection

13.5. Actions

13.5.1. Install Action
13.5.2. Activate Action
13.5.3. Fence Action
13.5.4. Deactivate Action
13.5.5. Approve Action
13.5.6. iSCSI Login Action
13.5.7. iSCSI Discover Action
13.5.8. Commit Network Configuration Action

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

The following table shows specific elements contained in a host 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 host. The `name` is unique across all host resources.
`link rel="storage"`	string	A link to the sub-collection for host storage.
`link rel="nics"`	string	A link to the sub-collection for host network interfaces.
`link rel="tags"`	string	A link to the sub-collection for host tags.
`link rel="permissions"`	string	A link to the sub-collection for host permissions. See Section 8.3.9, “ Permissions ”
`link rel="statistics"`	string	A link to the sub-collection for host statistics.
`type`	One of `rhel` or `rhev-h`	The host type
`address`	string	The IP address or hostname of the host
`status`	See below	The host status
`cluster id`	complex	The cluster that includes this host
`port`	integer	The listen port of the VDSM daemon running on this host
`storage_manager`	boolean: true or false	`true` if the host is the storage pool manager (SPM)
`power_management`	complex	Fencing options for host power management. (see Section 13.1, “Power Management”)
`ksm`	boolean: true or false	`true` if Kernel SamePage Merging (KSM) is enabled. Is disabled if `transparent_hugepages` is enabled. (see Section 13.2, “Memory Management”)
`transparent_hugepages`	boolean: true or false	`true` if transparent hugepages is enabled. (see Section 13.2, “Memory Management”)
`iscsi`	complex	The SCSI `initiator` for the host
`cpu`	complex	Statistics for the host CPU. Includes sub-elements for the CPU's `name`, `topology cores` and `speed`
`summary`	complex	Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of `active`, `migrating` and `total` VMs
`version`	complex	The compatibility level of the host (see Chapter 6, Compatibility Level Versions)
`root_password`	string	The root password of this host, by convention only included in the client-provided host representation on creation

Example 13.1. An XML representation of a host

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    <actions>
        <link rel="install"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/install"/>
        <link rel="activate"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/activate"/>
        <link rel="fence"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/fence"/>
        <link rel="deactivate"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/deactivate"/>
        <link rel="approve"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/approve"/>
        <link rel="iscsilogin"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsilogin"/>
        <link rel="iscsidiscover"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsidiscover"/>
        <link rel="commitnetconfig"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/commitnetconfig"/>
    </actions>
    <link rel="storage"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage"/>
    <link rel="nics"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics"/>
    <link rel="tags"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/tags"/>
    <link rel="permissions"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/permissions"/>
    <link rel="statistics"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/statistics"/>
    <type>rhev-h</type>
    <address>host1.example.com</address>
    <status>UP</status>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <port>54321</port>
    <storage_manager>true</storage_manager>
    <power_management>
        <enabled>false</enabled>
        <options/>
    </power_management>
    <ksm>
        <enabled>false</enabled>
    </ksm>
    <transparent_hugepages>
        <enabled>true</enabled>
    </transparent_hugepages>
    <iscsi>
        <initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
    </iscsi>
    <cpu>
        <topology cores="2"/>
        <name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
        <speed>2993</speed>
    </cpu>
    <summary>
        <active>2</active>
        <migrating>0</migrating>
        <total>3</total>
    </summary>
    <version major="3" minor="0"/>
</host>

When creating a new host, the name, address and root_password elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 13.2. Creating a host

POST /rhevm-api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>host2</host>
  <address>host2.example.com</address>
  <root_password>p@55w0Rd!</root_password>
</host>

The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent GETs and UPDATEs.

The name element is updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 13.3. Updating a host

POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>host3</host>
</host>

13.1. Power Management

A recommended feature of the Red Hat Virtualization platform is the option to fence a host with a power_management configuration. Certain sub-elements are required when configuring power_management.

Element	Type	Description
`type=`	fencing device code	A list of valid fencing device codes are available in the `capabilities` collection. See Section 7.1.4, “Power Managers”.
`enabled`	boolean: true or false	Indicates whether power management configuration is enabled or disabled
`address`	string	The host name or IP address of the host
`username`	string	A valid user name for power management
`password`	string	A valid, robust password for power management
`options`	complex	Fencing options for the selected `type=`

The options element requires a list of option sub-elements. Each option requires a name and type attributes. Certain options are only available for specific fencing types as defined in the capabilities collection (see Section 7.1.4, “Power Managers”) but can include options such as:

name=	type=	Values	Description
`secure`	`bool`	boolean: true or false	Defines if SSH is enabled for power management device connection
`port`	`int`	integer	Defines the port for power management device connection
`slot`	`int`	integer	Defines the slot to use, specifically when using a Blade server

A new host can include a power_management configuration when POSTing to the host resource. The power_management configuration can also update using PUT.

Example 13.4. An XML representation of a host's power management configuration

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    ...
    <power_management type="ilo">
        <enabled>true</enabled>
        <address>192.168.1.107</address>
        <username>admin</username>
        <password>p@55w0Rd!</password>
        <options>
            <option name="secure" value="true"/>
            <option name="port" value="54345"/>
            <option name="slot" value="3"/>
        </options>
    </power_management>
    ...
</host>

13.2. Memory Management

The API provides two choices for a host's memory management:

Kernel SamePage Merging (KSM) - The host kernel reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density.
Transparent Hugepage support - Hugepage support expands the size of memory pages beyond the standard 4kB limit. This reduces memory consumption and increases host performance.

Kernel SamePage Merging (KSM) uses the ksm element, which is a read-only element.

Example 13.5. KSM memory management

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>zig</name>
    <status>UP</status>
    ...
    <ksm>true</ksm>
</host>

Transparent Hugepage support uses the transparent_hugepages element and updates with a PUT request:

Example 13.6. Transparent Hugepage memory management

PUT /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host>
    <transparent_hugepages>true</transparent_hugepages>
</host>

This request also sets the status of ksm to the opposite status. For example, if transparent_hugepages is set to true, the API sets ksm to false.

Example 13.7. Transparent Hugepage set to true, which sets KSM to false

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>zig</name>
    <status>UP</status>
    ...
    <transparent_hugepages>true</transparent_hugepages>
    <ksm>false</ksm>
</host>

If transparent_hugepages is set to false, the API sets ksm to true.

Example 13.8. Transparent Hugepage set to false, which sets KSM to true

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>zig</name>
    <status>UP</status>
    ...
    <transparent_hugepages>false</transparent_hugepages>
    <ksm>true</ksm>
</host>

Availability of Transparent Hugepage support is found in the capabilities collection. See Section 7.1.2, “Features”.

13.3. Network Interface Sub-Collection

The nics sub-collection represents a host's physical network interfaces. Each host_nic element in the representation acts as a network interface and contains the following properties:

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	Properties
`name`	string	The name of the host network interface, e.g. `eth0`	^[a]
`host id`	GUID	A reference to the host
`network id`	GUID	A reference to the network, if any, that the interface is attached to	^[b]
`mac address`	string	The MAC address of the interface
`ip`	complex	The IP level configuration of the interface. Contains `address`, `netmask` and `gateway` attributes.
`boot_protocol`	enumerated	The protocol for IP address assignment when the host is booting. A list of enumerated values is available in `capabilities`. See Section 7.1.17, “Boot Protocols”
`speed`	integer	The network interface speed in bits per second
`status`	integer	The link status for the network interface
`vlan id`	GUID	The VLAN which this interface represents, if any
`bonding`	complex	A list of `options` and `slave` NICs for bonded interfaces	^[c]
`link rel="master"`	complex	A reference to the master bonded interface, if this is a slave interface
^[a] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added. ^[b] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added. ^[c] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.

Example 13.9. An XML representation of a network interface on a host

<host_nic id="e8f02fdf-3d7b-4135-86e1-1bf185570cd8"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
  e8f02fdf-3d7b-4135-86e1-1bf185570cd8">
    <name>bond0</name>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <network id="e657d631-657d-42bb-a536-73501a085d85"
      href="/rhevm-api/networks/e657d631-657d-42bb-a536-73501a085d85"/>
    <mac address="D6:76:F1:3A:AF:74"/>
    <ip address="192.168.0.128" netmask="255.255.255.0" gateway="192.168.0.1"/>
    <boot_protocol>dhcp</boot_protocol>
    <speed>1000000000</speed>
    <status>UP</status>
    <bonded>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonded>
    <actions>
        <link rel="attach"
          href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach"/>
        <link rel="detach"
          href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach"/>
    </actions>
</host_nic>

An API user creates only bonded interfaces (see Section 13.3.1, “ Bonded Interfaces ”). All other network interfaces contain updatable network, ip and boot_protocol properties using a PUT request.

13.3.1. Bonded Interfaces

A bonded interface is represented as a host_nic resource containing a bonded element, which contains the following properties:

Element	Type	Description	Properties
`options`	complex	A list of `option` elements for a bonded interface. Each `option` contains property `name` and `value` attributes.	^[a]
`slaves`	complex	A list of slave `host_nic` elements for a bonded interface	^[b]
^[a] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added. ^[b] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.

An API user creates a new bond when POSTing to a host_nic with bonding options and slave interfaces. The name, network and bonded elements are required when creating a new bonded interface. The network and slave host_nics may be identified by id or name.

Example 13.10. Creating a bonded interface

POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host_nic>
    <name>bond4</name>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
    <bonded>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonded>
</host_nic>

Note

bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.

Like other resources, a bonded interface may be deleted by issuing a DELETE request to its URI.

Warning

Changes to bonded interface configuration must be explicitly committed. See Section 13.5.8, “ Commit Network Configuration Action ”.

13.3.2. Attach Action

A host network interface may be attached to a network, indicating that the given network is accessible over the interface. The network may be identified by id or name.

Example 13.11. Action to attach a host network interface to a network

POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

Warning

This networking configuration change must be explicitly committed. See Section 13.5.8, “ Commit Network Configuration Action ”.

13.3.3. Detach Action

Detach an interface from a network. The network may be identified by id or name.

Example 13.12. Action to deattach a host network interface to a network

POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

Warning

This networking configuration change must be explicitly committed. See Section 13.5.8, “ Commit Network Configuration Action ”.

13.4. Storage Sub-Collection

The storage sub-collection provides a list of the iSCSI and FCP storage representations available on the host. This storage may be used to create storage domains, as described in Chapter 12, Storage Domains.

Each storage representation in the sub-collection represents either a SCSI LUN or an LVM volume group. A logical_unit representation contains:

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
`id`	GUID	An opaque identifier for the logical unit
`address`	string	The address of the iSCSI portal containing the LUN, in the case of iSCSI
`port`	integer	The port number of the iSCSI portal
`target`	string	The iSCSI target IQN
`username`	string	A CHAP user name for logging into an iSCSI target
`password`	string	A CHAP password for logging into an iSCSI target

A volume_group representation contains:

Element	Type	Description
`id`	GUID	An opaque identifier for the volume group
`name`	string	An volume group name
`logical_unit`	complex	Details of any SCSI LUNs on which the volume group is based

Example 13.13. An XML representation of the storage sub-collection on a host

<host_storage>
    <storage id="82fb123b-321e-40a1-9889-95dcd2654463"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
      82fb123b-321e-40a1-9889-95dcd2654463">
        <name>LUN0</name>
        <type>iscsi</type>
        <logical_unit id="LUN0">
            <address>mysan.example.com</address>
            <target>iqn.2009-08.com.example:mysan.foobar</target>
        </logical_unit>
    </storage>
    <storage id="f1d0ced5-d727-4217-8f2a-a514dff14bd5"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
      f1d0ced5-d727-4217-8f2a-a514dff14bd5">
        <name>FooVG</name>
        <type>iscsi</type>
        <volume_group id="5432">
            <name>FooVG</name>
            <logical_unit id="LUN1">
                <address>mysan.example.com</address>
                <target>iqn.2009-08.com.example:mysan.foobar</target>
            </logical_unit>
            <logical_unit id="LUN2">
                <address>mysan.example.com</address>
                <target>iqn.2009-08.com.example:mysan.foobar</target>
            </logical_unit>
        </volume_group>
    </storage>
</host_storage>

Note

The host_storage collection is read-only.

13.5. Actions

The following sections describe the actions associated with host resources.

The API contains a number of possible actions for hosts: install, activate, fence, deactivate, approve, iscsilogin, iscsidiscover and commitnetconfig.

13.5.1. Install Action

Install VDSM and related software on the host. This requires the root password for the host to be supplied using the root_password element.

Example 13.14. Action to install VDSM to a host

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
  Content-type: application/xml

  <action>
      <root_password>p@55w0Rd!</root_password>
  </action>

13.5.2. Activate Action

Activate the host, allowing it to be used for e.g. running VMs.

Example 13.15. Action to activate a host

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/activate HTTP/1.1
  Content-type: application/xml

13.5.3. Fence Action

The fence action enables the system to fence a troublesome host and reduce power usage. See Section 7.1.4, “Power Managers” for details on configuring a fencing device for a host.

The fence_type is one of manual, start, status, stop, or restart.

Example 13.16. Action to fence a host

POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fence
Content-Type: application/xml

<action>
    <fence_type>start</fence_type>
</action>

13.5.4. Deactivate Action

Deactivate the host, allowing maintenance tasks to be performed.

Example 13.17. Action to deactivate a host

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/deactivate HTTP/1.1
  Content-type: application/xml

13.5.5. Approve Action

Example 13.18. Action to approve a host

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/approve HTTP/1.1
  Content-type: application/xml

13.5.6. iSCSI Login Action

The iscsilogin action enables a host to login to an iSCSI target. Logging into a target makes the LUNs it contains available in the host_storage collection. See Section 13.4, “ Storage Sub-Collection ”.

Example 13.19. Action to enable a host to login to iSCSI target

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1
  Content-Type: application/xml
  Accept: application/xml

  <action>
      <iscsi>
          <address>mysan.example.com</address>
          <target>iqn.2009-08.com.example:mysan.foobar</target>
          <username>jimmy</username>
          <password>s3kr37</password>
      </iscsi>
  </action>

13.5.7. iSCSI Discover Action

The iscsidiscover action enables an iSCSI portal to be query for its list of LUNs.

Example 13.20. Action to query a list of LUNs for iSCSI portal

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1
  Content-Type: application/xml
  Accept: application/xml

  <action>
      <iscsi>
          <address>mysan.example.com</address>
      </iscsi>
  </action>

  HTTP/1.1 202 Accept
  Content-Type: application/xml

  <action id="e9126d04-0f74-4e1a-9139-13f11fcbb4ab"
    href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover/
    e9126d04-0f74-4e1a-9139-13f11fcbb4ab">
      <iscsi_target>iqn.2009-08.com.example:mysan.foobar</iscsi_target>
      ...
  <action>

13.5.8. Commit Network Configuration Action

An API user commits the network configuration to persist a host network interface attachment or detachment, or persist the creation/deletion of a bonded interface.

Example 13.21. Action to commit network configuration

  POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/commitnetconfig HTTP/1.1
  Content-type: application/xml

Warning

Networking configuration should only be committed after it has been established that host connectivity has not been lost as a result of the configuration changes. If host connectivity has been lost, the host should be rebooted and will automatically revert to the previous networking configuration.

Chapter 14. Virtual Machines

14.1. Disks Sub-Collection

14.2. Network Interfaces Sub-Collection

14.3. CD-ROMs Sub-Collection

14.4. Snapshots Sub-Collection

14.5. Users Sub-Collection

14.6. Actions

14.6.1. Start Action
14.6.2. Stop Action
14.6.3. Shutdown Action
14.6.4. Suspend Action
14.6.5. Detach Action
14.6.6. Migrate Action
14.6.7. Export Action
14.6.8. Import Action
14.6.9. Move Action
14.6.10. Ticket Action

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

The following table shows specific elements contained in a virtual machine 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 virtual machine. The `name` is unique across all virtual machine resources.
`description`	string	A free-form user-supplied human readable description of the virtual machine
`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="snapshots"`	string	A link to the snapshots sub-collection for virtual machine resources
`link rel="users"`	string	A link to the users sub-collection for virtual machine resources
`link rel="tags"`	string	A link to the tags 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 ”
`link rel="statistics"`	string	A link to the statistics sub-collection for virtual machine resources
`type`	enumerated	The virtual machine type. A list of enumerated values are available in `capabilities`. See Section 7.1.8, “Virtual Machine Types”
`status`	See below	The virtual machine 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 virtual machine 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 defined kernel
`high_availability`	complex	Set `enabled` to `true` if the virtual machine should be automatically restarted if the host crashes. A `priority` element controls the order in which Virtual Machines are re-started
`display`	complex	The display `type` (either `vnc` or `spice`), port, and the number of `monitors`
`cluster`	complex	A reference to the cluster on which this virtual machine will run. See Chapter 10, Host Clusters
`template`	complex	A reference to the template on which this virtual machine is based.
`start_time`	`xsd:dateTime` format: `YYYY-MM-DDThh:mm:ss`	The date and time at which this virtual machine was started
`creation_time`	`xsd:dateTime` format: `YYYY-MM-DDThh:mm:ss`	The date and time at which this virtual machine was created
`timezone`	tz database format: `Area/Location`	The timezone for this virtual machine. Only certain timezones are allowed as specified in Appendix B, Timezones
`origin`	One of `rhev`, `vmware` or `xen`	The system from which this virtual machine originated
`stateless`	boolean: true or false	`true` if the virtual machine is stateless. A stateless virtual machine has a snapshot of its disk image taken at boot and deleted at shutdown, meaning state changes will not persist after a reboot. One of true or false.
`placement_policy`	complex	Sets the placement policy for virtual machine migration. Requires a default `host` and an `affinity` (one of `migratable`, `user_migratable` or `pinned`).
`memory_policy`	complex	Sets the memory policy for virtual machines. Defines the minimum amount of `guaranteed` memory on a host in order for the virtual machine to run.
`custom_properties`	complex	A set of user-defined environment variable passed as parameters to custom scripts. Each `custom_property` contains `name` and `value` attributes. A list of enumerated values are available in `capabilities`. See Section 7.1.16, “Custom Properties”
`guest_info`	complex	A reference to the guest client information. Includes an `ip` element with an `address` attribute.
`vmpool`	complex	A reference to the pool for this virtual machine. See Chapter 16, Virtual Machine Pools

The status contains one of the following enumerative values: UNASSIGNED, DOWN, UP, POWERING_UP, POWERED_DOWN, PAUSED, MIGRATING_FROM, MIGRATING_TO, UNKNOWN, NOT_RESPONDING, WAIT_FOR_LAUNCH, REBOOT_IN_PROGRESS, SAVING_STATE, RESTORING_STATE, SUSPENDED, IMAGE_ILLEGAL, IMAGE_LOCKED or POWERING_DOWN.

Example 14.1. An XML representation of a virtual machine

<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
  href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
    <name>vm1</name>
    <description>Virtual Machine 1</description>
    <actions>
        <link rel="start"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/start"/>
        <link rel="stop"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/stop"/>
        <link rel="shutdown"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/shutdown"/>
        <link rel="suspend"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/suspend"/>
        <link rel="detach"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/detach"/>
        <link rel="migrate"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/migrate"/>
        <link rel="export"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/export"/>
        <link rel="import"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        <link rel="move"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move"/>
        <link rel="ticket"
          href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/ticket"/>
    </actions>
    <link rel="disks"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks"/>
    <link rel="nics"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics"/>
    <link rel="cdroms"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/cdroms"/>
    <link rel="snapshots"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/snapshots"/>
    <link rel="users"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/users"/>
    <link rel="tags"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/tags"/>
    <link rel="permissions"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/permissions"/>
    <link rel="statistics"
      href="/rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/statistics"/>
    <type>desktop</type>
    <status>UP</status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os>
        <boot dev="hd"/>
        <kernel/>
        <initrd/>
        <cmdline/>
    </os>
    <highly_available>
        <enabled>true</enabled>
        <priority>20</priority>
    </highly_available>
    <display>
        <type>vnc</type>
        <port>5910</port>
        <monitors>1</monitors>
    </display>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
    <start_time>2010-18-16T13:14:15</start_time>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>rhev</origin>
    <stateless>false</stateless>
    <placement_policy>
        <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
    </memory_policy>
    <custom_properties>
        <custom_property value="124" name="sndbuf"/>
    </custom_properties>
    <guest_info>
        <ip address="192.168.0.25"/>
    </guest_info>
    <timezone>Europe/London</timezone>
</vm>

When creating a new virtual machine, the name, template and cluster elements are required. The template and cluster are identified with id or name. See Section 8.3.2, “ Creating a Resource ” for more information.

Example 14.2. Creating a virtual machine with 512 MB and boots from the virtual hard disk

POST /rhevm-api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
      <boot dev="hd"/>
    </os>
</vm>

The name, description, type, memory, cpu topology, os and stateless properties are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.

Example 14.3. Updating a virtual machine to contain 1 GB of memory

PUT /rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <memory>1073741824</memory>
</vm>

14.1. Disks Sub-Collection

The disks sub-collection represents all virtual hard disk devices on a virtual machine. A disks representation contains the following properties:

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	Properties
`size`	integer	Size of the disk in bytes
`type`	enumerated	The type (function) of the disk device. A list of enumerated values is available in `capabilities`. See Section 7.1.12, “Disk Types”
`status`	One of `ILLEGAL`, `INVALID`, `LOCKED` or `OK`	The status of the disk device
`interface`	enumerated	The type of interface driver used to connect to the disk device. A list of enumerated values is available in `capabilities`. See Section 7.1.14, “Disk Interfaces”
`format`	enumerated	The underlying storage format. A list of enumerated values is available in `capabilities`. See Section 7.1.13, “Disk Formats”. Copy On Write (COW) allows snapshots, with a small performance overhead. Raw does not allow snapshots, but offers improved performance.
`sparse`	boolean: true or false	`true` if the physical storage for the disk should not be preallocated
`bootable`	boolean: true or false	`true` if this disk is to be marked as bootable
`wipe_after_delete`	boolean: true or false	`true` if the underlying physical storage for the disk should be zeroed when the disk is deleted
`propagate_errors`	boolean: true or false	`true` if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS
`storage_domain`	GUID	The ID of the associated storage domain, only used when adding the first disk to a virtual machine that was not itself created from a template	^[a]
^[a] Only required when the first disk is being added to a virtual machine that was not itself created from a template.

When adding a new disk, the size property is required. Also the storage_domain ID is needed in the case of the first disk being added to a virtual machine that was not itself created from a template.

Example 14.4. An XML representation of a disk device

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <size>10737418240</size>
    <type>system</type>
    <status>OK</status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
      href="/rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
</disk>

14.2. Network Interfaces Sub-Collection

The nics sub-collection represents all network interface devices on a virtual machine. A nics representation contains the following properties:

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	The name of the guest network device, e.g. `eth0`
`network id`	GUID	A reference to the network which the interface should be connected
`type`	enumerated	The type of driver used for the nic. A list of enumerated values is available in `capabilities`. See Section 7.1.11, “NIC Types”
`mac address`	string	The MAC address of the interface

When adding a new network interface, the name and network id properties are required.

Example 14.5. An XML representation of a network interface

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <name>nic1</name>
    <type>virtio</type>
    <mac address="00:1a:4a:16:84:07"/>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/rhevm-api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</nic>

14.3. CD-ROMs Sub-Collection

The cdroms sub-collection represents the CD-ROM device on a virtual machine. A cdroms representation contains the following properties:

Element	Type	Description	Properties
`file id`	string/filename	A reference to an ISO image. See Section 12.2, “ Files Sub-Collection ”

When adding a new CD-ROM, the file id property is required.

Note

Note that a virtual machine may currently only have a single CD-ROM and it is not possible to modify the CD-ROM properties using PUT.

Example 14.6. An XML representation of a CD-ROM device

<cdrom id="00000000-0000-0000-0000-000000000000"
  href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
  00000000-0000-0000-0000-000000000000">
    <file id="en_winxp_pro_with_sp2.iso"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/rhevm-api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>

14.4. Snapshots Sub-Collection

A virtual machine may have any number of snapshots of its disk state and these are represented and managed through a collection which behaves similarly to other collections, as described by Chapter 8, Common Features.

Virtual machine snapshots are represented by a snapshot element containing the following snapshot-specific properties:

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
`vm`	complex	The ID and URI of the virtual machine to which this snapshot pertains
`date`	`xsd:dateTime` format: `YYYY-MM-DDThh:mm:ss`	The date and time at which this snapshot was created.
`link rel="prev"`	complex	A link to the previous snapshot of this virtual machine

When adding a new snapshot, only the description property may be specified.

Note

Note that it is not possible to modify snapshot properties using PUT.

Example 14.7. An XML representation of a virtual machine snapshot

<snapshot id="f5288fd5-5178-4b7d-b87c-c01a40e40168"
  href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
  f5288fd5-5178-4b7d-b87c-c01a40e40168">
    <description>foobar</description>
    <actions>
        <link rel="restore"
        href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
        f5288fd5-5178-4b7d-b87c-c01a40e40168/restore"/>
    </actions>
    <link rel="prev"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
      ce411b3e-e4e0-4482-8b2f-d1ed998b9130"/>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <date>2010-08-16T14:24:29</date>
</snapshot>

An API user restores to a virtual machine snapshot using the rel="restore" action link in the snapshot representation.

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/f5288fd5-5178-4b7d-b87c-c01a40e40168/restore HTTP/1.1
Content-type: application/xml

14.5. Users Sub-Collection

A desktop virtual machine may have a set of users attached to it, represented via the users sub-collection. As per the usual idiom, POSTing to this collection attaches a user to the virtual machine, whereas DELETEing from it has the effect of detaching that user.

Note

Users referenced in this way must already exist in the Red Hat Enterprise Virtualization Manager user database, and may be identified either via their ID or by user prinicpal name (see Chapter 18, Users). In the example below, the latter approach is taken.

Example 14.8. Attaching a user to a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/users HTTP/1.1
Content-type: application/xml
Accept: application/xml

<user>
    <user_name>rhevmadmin@domain.example.com</user_name>
</user>

14.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, import, move and ticket.

14.6.1. Start Action

The start action launches a virtual machine.

Example 14.9. Action to start a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Content-type: application/xml

<action/>

The start action allows a vm element to be provided as a parameter. If a vm element is provided, boot-specific properties of the VM will be overridden at start time, using the values from the provided element. The properties will only be overriden for this boot of the virtual machine, and will not be persisted for the next boot.

Example 14.10. Action to start a virtual machine with overridden parameters

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Content-type: application/xml

<action>
    <pause>true</pause>
    <vm>
        <host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>
        <stateless>true</stateless>
        <display>
            <type>spice</type>
        </display>
        <os>
            <boot dev="cdrom"/>
        </os>
        <cdroms>
            <cdrom>
                <file id="foo.iso"/>
            </cdrom>
        </cdroms>
        <floppies>
            <floppy>
                <file id="bar.vfd"/>
            </floppy>
        </floppies>
    </vm>
</action>

14.6.2. Stop Action

The stop action forces a virtual machine to power-off.

Example 14.11. Action to stop a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1
Content-type: application/xml

<action/>

14.6.3. Shutdown Action

The shutdown action sends a shutdown request to a virtual machine.

Example 14.12. Action to send a shutdown request to a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1
Content-type: application/xml

<action/>

14.6.4. Suspend Action

The suspend action saves the virtual machine state to disk and stops it. The virtual machine state is restored with the start action.

Example 14.13. Action to save virtual machine state and suspend the machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1
Content-type: application/xml

<action/>

14.6.5. Detach Action

The detach action detaches a virtual machine from a pool.

Example 14.14. Action to detach a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1
Content-type: application/xml

<action/>

14.6.6. Migrate 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 14.15. Action to migrate a virtual machine to another host

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Content-type: application/xml

<action>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>

14.6.7. Export 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. By default, the export action will not overwrite any existing virtual machine of the same name in the destination domain. An API user changes this behaviour by setting the overwrite parameter to true. Finally, if snapshots of the virtual machine should not be included in the exported virtual machine, the discard_snapshots parameter may be set to true.

Example 14.16. Action to export a virtual machine to an export storage domain

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Content-type: application/xml

<action>
    <storage_domain>
        <name>export1</name>
    </storage_domain>
    <overwrite>true<overwrite/>
    <discard_snapshots>true<discard_snapshots/>
</action>

14.6.8. Import Action

The import action imports a virtual machine from an Export storage domain. The destination cluster and storage domain must be specified via cluster and storage_domain references.

Note

The import action is only available on virtual machines listed under an export storage domain. See Section 9.1.3, “ Export Storage Domains ”.

Example 14.17. Action to import a virtual machine from an export storage domain

POST /rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>

14.6.9. Move Action

The move action moves virtual machine disks to a different storage domain. The destination storage domain is specified via a storage_domain reference to either a name or an id.

Example 14.18. Action to move virtual machine disks to a different storage domain

POST /rhevm-api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move HTTP/1.1
Content-type: application/xml

<action>
    <storage_domain>
        <name>images2</name>
    </storage_domain>
</action>

14.6.10. Ticket Action

The ticket action generates a time-sensitive authentication token for accessing a virtual machine's display. The client-provided action may optionally include 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 completion response will specify the actual ticket value and expiry used.

Example 14.19. Action to generate authentication token for a virtual machine

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
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="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
  94e07552-14ba-4c27-8ce6-2cc75190d3ef">
    <status>COMPLETE</status>
    <ticket>
        <value>5c7CSzK8Sw41</value>
        <expiry>120</expiry>
    </ticket>
    <link rel="parent"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <link rel="replay"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>

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>

15.2. Import Action

The import action imports a template from an Export storage domain. The destination cluster and storage domain must be specified via cluster and storage_domain references.

Note

The import action is only available on templates listed under an export storage domain. See Section 9.1.3, “ Export Storage Domains ”.

Example 15.3. Action to import a template from an export storage domain

POST /rhevm-api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>

Chapter 16. Virtual Machine Pools

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

The following table shows specific elements contained in a virtual machine pool 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 pool. The `name` is unique across all pool resources.
`description`	string	A free-form user-supplied human readable description of the pool
`size`	integer	The number of virtual machines in the pool
`cluster`	complex	A reference to the cluster resource which virtual machines in this pool run on
`template`	complex	A reference to the template resource which virtual machines in this pool are based on

Example 16.1. An XML representation of a virtual machine pool

<vmpool id="00000000-0000-0000-0000-000000000000"
  href="/rhevm-api/vmpools/00000000-0000-0000-0000-000000000000">
    <name>VMPool1</name>
    <description>Virtual Machine Pool 1</description>
    <size>2</size>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
</vmpool>

Chapter 17. Roles

17.1. Permits Sub-Collection

The rel="roles" link obtained from the entry point URI (see Chapter 4, Entry Point) provides access to a static set of system roles. Each individual role elements contain the following:

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
`id`	GUID	Globally unique identifier for this role
`name`	string	The role name (may be used as a more convenient identifier in any role-specific operations)
`description`	string	A free-text description of the role
`user`	complex	A reference to the associated user (only present in the context of the role represented being assigned to an individual user)

Example 17.1. An XML representation of the roles collection

GET /rhevm-api/roles HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<roles>
    <role id="00000000-0000-0000-0000-000000000001"
      href="/rhevm-api/roles/00000000-0000-0000-0000-000000000001">
        <name>SuperUser</name>
        <description>Roles management administrator</description>
    </role>
    <role id="00000000-0000-0000-0001-000000000001"
      href="/rhevm-api/roles/00000000-0000-0000-0001-000000000001">
        <name>RHEVMUser</name>
        <description>RHEVM user</description>
    </role>
    <role id="00000000-0000-0000-0001-000000000002"
      href="/rhevm-api/roles/00000000-0000-0000-0001-000000000002">
        <name>RHEVMPowerUser</name>
        <description>RHEVM power user</description>
    </role>
    <role id="00000000-0000-0000-0001-000000000003"
      href="/rhevm-api/roles/00000000-0000-0000-0001-000000000003">
        <name>RHEVMVDIUser</name>
        <description>RHEVM VDI user</description>
    </role>
</roles>

Note

Because the global roles form a static set in Red Hat Enterprise Virtualization Manager 2.2, the usual collection idioms are not followed in this case, i.e. a new role cannot be created via POST, nor can a role be destroyed via DELETE on the collection.

17.1. Permits Sub-Collection

Each role contains a set of allowable actions, or permits, which are defined in capabilities. For more information on permits, see Section 7.2, “Permits”.

A role's permits are listed as a sub-collection:

GET /rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<permits>
    <permit id="1"
      href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>CREATE_VM</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
    <permit id="4"
      href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/4">
        <name>VM_BASIC_OPERATIONS</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
</permits>

A permit is assigned to a role when POSTed to the permits sub-collection. Use either an id= attribute or a name element to specify the permit to assign. For example:

POST /rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml

<permit id="1"/>

HTTP/1.1 201 Created
Content-Type: application/xml

<permits>
    <permit id="1"
      href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>CREATE_VM</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/rhevm-api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
</permits>

Chapter 18. Users

Users are exposed in a top-level collection and are referenced with the rel="users" link. Individual user elements contain the following:

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
`id`	GUID	Globally unique identifier for this user
`user_name`	string	The user principal name (may be used as a more convenient identifier when adding a new user)
`name`	string	A free-text name for the user
`description`	string	A free-text description of the user
`domain`	string	The containing Active Directory domain
`groups`	complex	A list of Active Directory groups for this user

Example 18.1. An XML representation of a user resource

GET /rhevm-api/users HTTP/1.1
Accept: application/xml

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
    <name>RHEV-M Admin</name>
    <actions/>
    <link rel="roles"
      href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
    <link rel="tags"
      href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
    <domain>domain.example.com</domain>
    <logged_in>false</logged_in>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <groups>
        <group>Group Policy Creator Owners@domain.example.com/Users</group>
        <group>Domain Admins@domain.example.com/Users</group>
        <group>Enterprise Admins@domain.example.com/Users</group>
        <group>Schema Admins@domain.example.com/Users</group>
        <group>Administrators@domain.example.com/Builtin</group>
    </groups>
</user>

The users collection is POSTed to add an existing Active Directory user to the Red Hat Enterprise Virtualization Manager database. The client-provided new user representation must include an embedded roles list with at least one initial role to assign to the user. For example, the following request assigns two initial roles to the user joe@domain.example.com:

POST /rhevm-api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<user>
    <user_name>joe@domain.example.com</user_name>
    <roles>
        <role>
            <name>RHEVMPowerUser</name>
        </role>
        <role id="00000000-0000-0000-0001-000000000003"/>
    </roles>
</user>

The new user is identified either by Red Hat Enterprise Virtualization Manager user ID or via the Active Directory user principal name (UPN). The user ID format reported from the Active Directory domain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as in LDIF. ^[7] , the ID has the opposite byte order and is base-64 encoded). Hence it is usually more convenient to refer to the new user by UPN.

Note

The user exists in the Active Directory domain before it is added to the Red Hat Enterprise Virtualization Manager database. An API user had the option to query this domain through the domains collection prior to creation of the user.

Roles are identified either by name or ID. The example above shows both approaches.

Further roles are attached or detached with POST or DELETE requests to the roles sub-collection of an individual user. The example below illustrates how the RHEVMVDIUser role may be added to the role assignments for a particular user.

Note

The embedded user roles list of the user element is only used for the initial creation. All interactions post-creation with the user's role assignments go through the roles sub-collection.

POST /rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<role>
    <name>RHEVMVDIUser</name>
</role>

Note

Users are not updated with the PUT verb. The only changes allowed post-creation are in the user's role assignments.

Users may be removed from the Red Hat Enterprise Virtualization Manager database via DELETE on the top level users collection. The Active Directory domain will remain unchanged after such a deletion.

^[7] The LDAP Data Interchange Format is described in RFC 2849.

Chapter 19. Domains

19.1. Domain Users Sub-Collection
19.2. Domain Groups Sub-Collection

The API provides the ability to access user and group information from the organization's Active Directory Service using the domains collection. Domain information is referenced with the rel="domains" link.

Each domain contains the following elements:

Element	Type	Description
`name`	string	The domain name
`link rel="users"`	string	A link to the sub-collection for users associated with this domain
`link rel="groups"`	string	A link to the sub-collection for groups associated with this domain

The links to users and groups sub-collections also accept search queries. See Section 8.2.3, “ Search Queries ” for more information.

Example 19.1. An XML representation of a domain resource

<domain id="77696e32-6b38-7268-6576-2e656e676c61"
  href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61">
    <name>domain.example.com</name>
    <link rel="users"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/users"/>
    <link rel="groups"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups"/>
    <link rel="users/search"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      users?search={query}"/>
    <link rel="groups/search"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      groups?search={query}"/>
</domain>

Note

The domains collection and its sub-collections are read-only.

19.1. Domain Users Sub-Collection

The users sub-collection contains all users in Active Directory. This information is used to add new users to the Red Hat Enterprise Virtualization environment as per Chapter 18, Users.

A domain user resource contains these main properties:

Element	Type	Description
`id`	GUID	Globally unique identifier for this user
`name`	string	The name of the user
`user_name`	string	The username from Active Directory
`domain id`	GUID	The containing Active Directory domain
`groups`	complex	A list of Active Directory groups for this user

For example:

<users>
    <user id="225f15cd-e891-434d-8262-a66808fcb9b1"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/
      d3b4e7be-5f57-4dac-b937-21e1771a501f">
        <name>RHEV-M Admin</name>
        <user_name>rhevmadmin@domain.example.com</user_name>
        <domain id="77696e32-6b38-7268-6576-2e656e676c61"
          href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
        <groups>
            <group>
                <name>domain.example.com/Users/Enterprise Admins</name>
            </group>
            <group>
                <name>domain.example.com/Users/Domain Admins</name>
            </group>
            ...
        </groups>
    </user>
    ...
</users>

19.2. Domain Groups Sub-Collection

The groups sub-collection contains all groups in Active Directory. A domain group resource contains these main properties:

Element	Type	Description
`id`	GUID	Globally unique identifier for this group
`name`	string	The name of the group
`domain id`	GUID	The containing Active Directory domain

<groups>
    <group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
      href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups/
      85bf8d97-273c-4a5c-b801-b17d58330dab">
        <name>example.com/Users/Enterprise Admins</name>
        <domain id="77696e32-6b38-7268-6576-2e656e676c61"
          href="/rhevm-api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
    </group>
    ...
</groups>

Chapter 20. Tags

20.1. Associating Tags With a Host, User or VM
20.2. Parent Tags

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

The tag specific elements which may be contained in the tag description are as follows:

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
`host`	complex	A reference to the host which the tag is attached. See Chapter 13, Hosts
`user`	complex	A reference to the user which the tag is attached. See Chapter 18, Users
`vm`	complex	A reference to the VM which the tag is attached. See Chapter 14, Virtual Machines

Example 20.1. An XML representation of a tag resource

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/rhevm-api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
</tag>

When creating a new tag the name property is required. The name and description elements may be updated post-creation.

20.1. Associating Tags With a Host, User or VM

The collection referenced by link rel="tags" from a host, user or vms represents the set of tags associated with the entity.

The tag representations are as described in Chapter 20, Tags, except they also contain a host id, user id or vm id reference to the entity in question.

Each tags collection may be manipulated as described in Chapter 8, Common Features. Associating a tag with an entity is achieved by POSTing a tag reference (identifying the tag either by its id or name) to the collection. Removing an association is achieved by DELETEing the appropriate element in the collection.

POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <name>Finance</name>
</tag>

HTTP/1.1 201 Created
Location: http://{host}/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
  f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

DELETE /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1

HTTP/1.1 204 No Content

To query the set of entities associated with a given tag, the collection/search URI template for the appropriate collection should be used to search for entities matching tag=MyTag.

GET /rhevm-api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<vms>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>

20.2. Parent Tags

A tag can contain a parent element, which creates a hierarchical link to a parent tag. The tags hierarchy is represented as a flat collection that decends from the root tag.

The `root` tag

The root tag is a special pseudo-tag assumed as the default tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag.

This tag hierarchy is expressed in the following way:

<tags>
    <tag id="-1" href="/rhevm-api/tags/-1">
        <name>root</name>
        <description>root</description>
        <parent>
            <tag id="-1" href="/rhevm-api/tags/-1"/>
        </parent>
    </tag>
    <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
      href="/rhevm-api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
        <name>Finance</name>
        <description>Resources for the Finance department</description>
        <parent>
            <tag id="-1" href="/rhevm-api/tags/-1"/>
        </parent>
    </tag>
    <tag id="ty38wobf-23n5-18we-v18j-5u8t348cs7rt"
      href="/rhevm-api/tags/ty38wobf-23n5-18we-v18j-5u8t348cs7rt">
        <name>Billing</name>
        <description>Billing Resources</description>
        <parent>
            <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
              href="/rhevm-api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
        </parent>
    </tag>
</tags>

POSTing a new tag with a parent element creates a link to a parent tag, using either the id= attribute in the tag element:

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5et"/>
    </parent>
</tag>

Or using the name element:

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag>
            <name>Finance</name>
        </tag>
    </parent>
</tag>

A tag can change its parent using a PUT request:

PUT /rhevm-api/tags/ty38wobf-23n5-18we-v18j-5u8t348cs7rt HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
    </parent>
</tag>

Chapter 21. Events

The rel="events" link obtained from the entry point URI accesses the events collection and lists system events from Red Hat Enterprise Virtualisation Manager.

Element	Description
`id=`	An opaque identifier for the event entry
`description`	A description of the system event
`code`	The integer event code. See Appendix A, Event Codes for a full list of event codes with descriptions.
`severity`	The level of severity for the event. One of `NORMAL`, `WARNING`, `ERROR` or `ALERT`.
`time`	The timestamp indicating when the event happened
`user id=`	The identification code for the user who triggered the event

Example 21.1. An XML representation of the the events collection

<events>
    <event id="537" href="/rhevm-api/events/537">
        <description>User vdcadmin logged in.</description>
        <code>30</code>
        <severity>NORMAL</severity>
        <time>2011-01-12T10:48:27.827+02:00</time>
        <user id="9b9002d1-ec33-4083-8a7b-31f6b8931648"
          href="/rhevm-api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
    </event>
    ...
</events>

Note

The events collection is read-only.

Chapter 22. Statistics

The rel="statistics" link obtained from the entry point URI accesses the statistics collection and lists system statistics from Red Hat Enterprise Virtualisation Manager.

Element	Description
`name`	The unique identifier for the statistic entry
`description`	A plain text description of the statistic
`unit`	The unit or rate to measure the statistical values
`type`	The type of statistic measures. Either `GAUGE` or `COUNTER`.
`values type=`	The data type for the statistical values that follow. Either `INTEGER` or `DECIMAL`.
`value`	A data set that contains `datum`
`datum`	An individual piece of data from a `value`

Example 22.1. An XML representation of the the statistics collection

<statistics>
    <statistic>
        <name>bytes.current.rx</name>
        <description>Receive rate</description>
        <unit>BITS_PER_SECOND</unit>
        <type>GUAGE</type>
        <values type="DECIMAL">
            <value>
                <datum>131072.0<datum>
            </value>
        </values>
    </statistic>
    <statistic>
        <name>errors.total.rx</name>
        <description>Receive error rate</description>
        <unit>NONE</unit>
        <type>COUNTER</type>
        <values type="INTEGER">
            <value>
                <datum>1.0<datum>
            </value>
        </values>
    </statistic>
    ...
</statistics>

Note

The statistics collection is read-only.

Event Codes

This table lists all event codes for Chapter 21, Events.

Code	Description
0	UNASSIGNED
1	VDC_START
2	VDC_STOP
12	HOST_FAILURE
13	HOST_DETECTED
14	HOST_RECOVER
15	HOST_MAINTENANCE
16	HOST_ACTIVATE
17	HOST_MAINTENANCE_FAILED
18	HOST_ACTIVATE_FAILED
19	HOST_RECOVER_FAILED
20	USER_HOST_START
21	USER_HOST_STOP
22	IRS_FAILURE
26	IRS_DISK_SPACE_LOW
30	USER_VDC_LOGIN
31	USER_VDC_LOGOUT
32	USER_RUN_VM
33	USER_STOP_VM
34	USER_ADD_VM
35	USER_UPDATE_VM
36	USER_REMOVE_VM
37	USER_ADD_VM_STARTED
38	USER_CHANGE_DISK_VM
39	USER_PAUSE_VM
40	USER_RESUME_VM
41	USER_HOST_RESTART
42	USER_ADD_HOST
43	USER_UPDATE_HOST
44	USER_REMOVE_HOST
45	USER_CREATE_SNAPSHOT
46	USER_TRY_BACK_TO_SNAPSHOT
47	USER_RESTORE_FROM_SNAPSHOT
48	USER_ADD_VM_TEMPLATE
49	USER_UPDATE_VM_TEMPLATE
50	USER_REMOVE_VM_TEMPLATE
51	USER_ADD_VM_TEMPLATE_FINISHED_SUCCESS
52	USER_ADD_VM_TEMPLATE_FINISHED_FAILURE
53	USER_ADD_VM_FINISHED_SUCCESS
54	USER_FAILED_RUN_VM
55	USER_FAILED_PAUSE_VM
56	USER_FAILED_STOP_VM
57	USER_FAILED_ADD_VM
58	USER_FAILED_UPDATE_VM
59	USER_FAILED_REMOVE_VM
60	USER_ADD_VM_FINISHED_FAILURE
61	VM_DOWN
62	VM_MIGRATION_START
63	VM_MIGRATION_DONE
64	VM_MIGRATION_ABORT
65	VM_MIGRATION_FAILED
66	VM_FAILURE
68	USER_CREATE_SNAPSHOT_FINISHED_SUCCESS
69	USER_CREATE_SNAPSHOT_FINISHED_FAILURE
70	USER_RUN_VM_AS_STATELESS_FINISHED_FAILURE
71	USER_TRY_BACK_TO_SNAPSHOT_FINISH_SUCCESS
72	USER_CHANGE_FLOPPY_VM
73	USER_INITIATED_SHUTDOWN_VM
74	USER_FAILED_SHUTDOWN_VM
75	USER_FAILED_CHANGE_FLOPPY_VM
76	USER_STOPPED_VM_INSTEAD_OF_SHUTDOWN
77	USER_FAILED_STOPPING_VM_INSTEAD_OF_SHUTDOWN
78	USER_ADD_DISK_TO_VM
79	USER_FAILED_ADD_DISK_TO_VM
80	USER_REMOVE_DISK_FROM_VM
81	USER_FAILED_REMOVE_DISK_FROM_VM
82	USER_MOVED_VM
83	USER_FAILED_MOVE_VM
84	USER_MOVED_TEMPLATE
85	USER_FAILED_MOVE_TEMPLATE
86	USER_COPIED_TEMPLATE
87	USER_FAILED_COPY_TEMPLATE
88	USER_UPDATE_VM_DISK
89	USER_FAILED_UPDATE_VM_DISK
90	USER_HOST_SHUTDOWN
91	USER_MOVED_VM_FINISHED_SUCCESS
92	USER_MOVED_VM_FINISHED_FAILURE
93	USER_MOVED_TEMPLATE_FINISHED_SUCCESS
94	USER_MOVED_TEMPLATE_FINISHED_FAILURE
95	USER_COPIED_TEMPLATE_FINISHED_SUCCESS
96	USER_COPIED_TEMPLATE_FINISHED_FAILURE
97	USER_ADD_DISK_TO_VM_FINISHED_SUCCESS
98	USER_ADD_DISK_TO_VM_FINISHED_FAILURE
99	USER_TRY_BACK_TO_SNAPSHOT_FINISH_FAILURE
100	USER_RESTORE_FROM_SNAPSHOT_FINISH_SUCCESS
101	USER_RESTORE_FROM_SNAPSHOT_FINISH_FAILURE
102	USER_FAILED_CHANGE_DISK_VM
103	USER_FAILED_RESUME_VM
104	USER_FAILED_ADD_HOST
105	USER_FAILED_UPDATE_HOST
106	USER_FAILED_REMOVE_HOST
107	USER_FAILED_HOST_RESTART
108	USER_FAILED_ADD_VM_TEMPLATE
109	USER_FAILED_UPDATE_VM_TEMPLATE
110	USER_FAILED_REMOVE_VM_TEMPLATE
111	USER_STOP_SUSPENDED_VM
112	USER_STOP_SUSPENDED_VM_FAILED
113	USER_REMOVE_VM_FINISHED
114	USER_VDC_LOGIN_FAILED
115	USER_FAILED_TRY_BACK_TO_SNAPSHOT
116	USER_FAILED_RESTORE_FROM_SNAPSHOT
117	USER_FAILED_CREATE_SNAPSHOT
118	USER_FAILED_HOST_START
119	VM_DOWN_ERROR
120	VM_MIGRATION_FAILED_FROM_TO
121	SYSTEM_HOST_RESTART
122	SYSTEM_FAILED_HOST_RESTART
123	HOST_SLOW_STORAGE_RESPONSE_TIME
124	VM_IMPORT
125	VM_IMPORT_FAILED
126	VM_NOT_RESPONDING
127	HOST_RUN_IN_NO_KVM_MODE
128	VM_MIGRATION_TRYING_RERUN
129	VM_CLEARED
130	USER_FAILED_HOST_SHUTDOWN
131	USER_EXPORT_VM
132	USER_EXPORT_VM_FAILED
133	USER_EXPORT_TEMPLATE
134	USER_EXPORT_TEMPLATE_FAILED
135	TEMPLATE_IMPORT
136	TEMPLATE_IMPORT_FAILED
137	USER_FAILED_HOST_STOP
138	VM_PAUSED_ENOSPC
139	VM_PAUSED_ERROR
140	VM_MIGRATION_FAILED_DURING_MOVE_TO_MAINTANANCE
141	HOST_VERSION_NOT_SUPPORTED_FOR_CLUSTER
142	VM_SET_TO_UNKNOWN_STATUS
143	VM_WAS_SET_DOWN_DUE_TO_HOST_REBOOT_OR_MANUAL_FENCE
144	VM_IMPORT_INFO
145	VM_BLK_VIRTIO_NO_CACHE
149	USER_ADD
150	USER_INITIATED_RUN_VM
151	USER_INITIATED_RUN_VM_FAILED
152	USER_RUN_VM_ON_NON_DEFAULT_HOST
153	USER_STARTED_VM
182	USER_FAILED_ATTACH_USER_TO_VM
201	IRS_DISK_SPACE_LOW_ERROR
204	IRS_HOSTED_ON_HOST
250	USER_UPDATE_VM_CLUSTER_DEFAULT_HOST_CLEARED
251	USER_REMOVE_VM_TEMPLATE_FINISHED
300	USER_ADD_VM_POOL
301	USER_ADD_VM_POOL_FAILED
302	USER_ADD_VM_POOL_WITH_VMS
303	USER_ADD_VM_POOL_WITH_VMS_FAILED
304	USER_REMOVE_VM_POOL
305	USER_REMOVE_VM_POOL_FAILED
306	USER_ADD_VM_TO_POOL
307	USER_ADD_VM_TO_POOL_FAILED
308	USER_REMOVE_VM_FROM_POOL
309	USER_REMOVE_VM_FROM_POOL_FAILED
310	USER_ATTACH_USER_TO_POOL
311	USER_ATTACH_USER_TO_POOL_FAILED
312	USER_DETACH_USER_FROM_POOL
313	USER_DETACH_USER_FROM_POOL_FAILED
314	USER_UPDATE_VM_POOL
315	USER_UPDATE_VM_POOL_FAILED
316	USER_ATTACH_USER_TO_VM_FROM_POOL
317	USER_ATTACH_USER_TO_VM_FROM_POOL_FAILED
318	USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_SUCCESS
319	USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_FAILURE
320	USER_ADD_VM_POOL_WITH_VMS_ADD_HOST_FAILED
325	USER_REMOVE_ADUSER
326	USER_FAILED_REMOVE_ADUSER
327	USER_FAILED_ADD_ADUSER
328	USER_ATTACH_USER_TO_TIME_LEASED_POOL
329	USER_ATTACH_USER_TO_TIME_LEASED_POOL_FAILED
330	USER_DETACH_USER_FROM_TIME_LEASED_POOL
331	USER_DETACH_USER_FROM_TIME_LEASED_POOL_FAILED
332	USER_ATTACH_AD_GROUP_TO_TIME_LEASED_POOL
333	USER_ATTACH_AD_GROUP_TO_TIME_LEASED_POOL_FAILED
334	USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL
335	USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_FAILED
336	USER_UPDATE_USER_TO_TIME_LEASED_POOL
337	USER_UPDATE_USER_TO_TIME_LEASED_POOL_FAILED
338	USER_UPDATE_AD_GROUP_TO_TIME_LEASED_POOL
339	USER_UPDATE_AD_GROUP_TO_TIME_LEASED_POOL_FAILED
342	USER_MERGE_SNAPSHOT
343	USER_FAILED_MERGE_SNAPSHOT
344	USER_UPDATE_VM_POOL_WITH_VMS
345	USER_UPDATE_VM_POOL_WITH_VMS_FAILED
346	USER_PASSWORD_CHANGED
347	USER_PASSWORD_CHANGE_FAILED
348	USER_CLEAR_UNKNOWN_VMS
349	USER_FAILED_CLEAR_UNKNOWN_VMS
350	USER_ADD_BOOKMARK
351	USER_ADD_BOOKMARK_FAILED
352	USER_UPDATE_BOOKMARK
353	USER_UPDATE_BOOKMARK_FAILED
354	USER_REMOVE_BOOKMARK
355	USER_REMOVE_BOOKMARK_FAILED
356	USER_MERGE_SNAPSHOT_FINISHED_SUCCESS
357	USER_MERGE_SNAPSHOT_FINISHED_FAILURE
360	USER_DETACH_USER_FROM_VM
361	USER_FAILED_DETACH_USER_FROM_VM
400	USER_ATTACH_VM_TO_AD_GROUP
401	USER_ATTACH_VM_TO_AD_GROUP_FAILED
402	USER_DETACH_VM_TO_AD_GROUP
403	USER_DETACH_VM_TO_AD_GROUP_FAILED
404	USER_ATTACH_VM_POOL_TO_AD_GROUP
405	USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED
406	USER_DETACH_VM_POOL_TO_AD_GROUP
407	USER_DETACH_VM_POOL_TO_AD_GROUP_FAILED
408	USER_REMOVE_AD_GROUP
409	USER_REMOVE_AD_GROUP_FAILED
430	USER_UPDATE_TAG
431	USER_UPDATE_TAG_FAILED
432	USER_ADD_TAG
433	USER_ADD_TAG_FAILED
434	USER_REMOVE_TAG
435	USER_REMOVE_TAG_FAILED
436	USER_ATTACH_TAG_TO_USER
437	USER_ATTACH_TAG_TO_USER_FAILED
438	USER_ATTACH_TAG_TO_USER_GROUP
439	USER_ATTACH_TAG_TO_USER_GROUP_FAILED
440	USER_ATTACH_TAG_TO_VM
441	USER_ATTACH_TAG_TO_VM_FAILED
442	USER_ATTACH_TAG_TO_HOST
443	USER_ATTACH_TAG_TO_HOST_FAILED
444	USER_DETACH_HOST_FROM_TAG
445	USER_DETACH_HOST_FROM_TAG_FAILED
446	USER_DETACH_VM_FROM_TAG
447	USER_DETACH_VM_FROM_TAG_FAILED
448	USER_DETACH_USER_FROM_TAG
449	USER_DETACH_USER_FROM_TAG_FAILED
450	USER_DETACH_USER_GROUP_FROM_TAG
451	USER_DETACH_USER_GROUP_FROM_TAG_FAILED
452	USER_ATTACH_TAG_TO_USER_EXISTS
453	USER_ATTACH_TAG_TO_USER_GROUP_EXISTS
454	USER_ATTACH_TAG_TO_VM_EXISTS
455	USER_ATTACH_TAG_TO_HOST_EXISTS
456	USER_LOGGED_IN_VM
457	USER_LOGGED_OUT_VM
458	USER_LOCKED_VM
459	USER_UNLOCKED_VM
460	USER_DETACH_USER_FROM_TIME_LEASED_POOL_INTERNAL
461	USER_DETACH_USER_FROM_TIME_LEASED_POOL_FAILED_INTERNAL
462	USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_INTERNAL
463	USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_FAILED_INTERNAL
467	UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE
468	UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE_FAILED
470	USER_ATTACH_VM_POOL_TO_AD_GROUP_INTERNAL
471	USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED_INTERNAL
472	USER_ATTACH_USER_TO_POOL_INTERNAL
473	USER_ATTACH_USER_TO_POOL_FAILED_INTERNAL
494	HOST_MANUAL_FENCE_STATUS
495	HOST_MANUAL_FENCE_STATUS_FAILED
496	HOST_FENCE_STATUS
497	HOST_FENCE_STATUS_FAILED
498	HOST_APPROVE
499	HOST_APPROVE_FAILED
500	HOST_FAILED_TO_RUN_VMS
501	USER_SUSPEND_VM
502	USER_FAILED_SUSPEND_VM
503	USER_SUSPEND_VM_OK
504	HOST_INSTALL
505	HOST_INSTALL_FAILED
506	HOST_INITIATED_RUN_VM
507	HOST_INITIATED_RUN_VM_FAILED
509	HOST_INSTALL_IN_PROGRESS
510	HOST_INSTALL_IN_PROGRESS_WARNING
511	HOST_INSTALL_IN_PROGRESS_ERROR
512	USER_SUSPEND_VM_FINISH_SUCCESS
513	HOST_RECOVER_FAILED_VMS_UNKNOWN
514	HOST_INITIALIZING
515	HOST_CPU_LOWER_THAN_CLUSTER
516	HOST_CPU_RETRIEVE_FAILED
517	HOST_SET_NONOPERATIONAL
518	HOST_SET_NONOPERATIONAL_FAILED
519	HOST_SET_NONOPERATIONAL_NETWORK
520	USER_ATTACH_USER_TO_VM
521	USER_SUSPEND_VM_FINISH_FAILURE
522	HOST_SET_NONOPERATIONAL_DOMAIN
523	HOST_SET_NONOPERATIONAL_DOMAIN_FAILED
524	AUTO_SUSPEND_VM
524	HOST_DOMAIN_DELAY_INTERVAL
525	AUTO_SUSPEND_VM_FINISH_SUCCESS
526	AUTO_SUSPEND_VM_FINISH_FAILURE
527	AUTO_FAILED_SUSPEND_VM
528	USER_EJECT_VM_DISK
529	USER_EJECT_VM_FLOPPY
530	HOST_MANUAL_FENCE_FAILED_CALL_FENCE_SPM
531	HOST_LOW_MEM
555	USER_MOVE_TAG
556	USER_MOVE_TAG_FAILED
600	USER_HOST_MAINTENANCE
601	CPU_FLAGS_NX_IS_MISSING
602	USER_HOST_MAINTENANCE_MIGRATION_FAILED
603	HOST_SET_NONOPERATIONAL_IFACE_DOWN
800	IMAGES_SYNCRONIZER_DESKTOP_NOT_EXIST_IN_VDC
801	IMAGES_SYNCRONIZER_TEMPLATE_NOT_EXIST_IMAGE_EXIST
802	IMAGES_SYNCRONIZER_SNAPSHOT_NOT_EXIST_IN_VDC
803	IMAGES_SYNCRONIZER_SNAPSHOTS_NOT_ATTACHED_TO_VM_IN_VDC
804	IMAGES_SYNCRONIZER_TEMPLATE_NOT_EXIST_IN_VDC
805	IMAGES_SYNCRONIZER_DESKTOP_NOT_EXIST_IN_IRS
806	IMAGES_SYNCRONIZER_SNAPSHOT_NOT_EXIST_IN_IRS
807	IMAGES_SYNCRONIZER_DESKTOP_WITHOUT_TEMPLATE_VDC
808	IMAGES_SYNCRONIZER_IMAGE_TEMPLATE_NOT_EXIST
809	USER_ADD_HOST_GROUP
810	USER_ADD_HOST_GROUP_FAILED
811	USER_UPDATE_HOST_GROUP
812	USER_UPDATE_HOST_GROUP_FAILED
813	USER_REMOVE_HOST_GROUP
814	USER_REMOVE_HOST_GROUP_FAILED
815	USER_VDC_LOGOUT_FAILED
816	MAC_POOL_EMPTY
817	CERTIFICATE_FILE_NOT_FOUND
818	RUN_VM_FAILED
819	HOST_REGISTER_ERROR_UPDATING_HOST
820	HOST_REGISTER_ERROR_UPDATING_HOST_ALL_TAKEN
821	HOST_REGISTER_HOST_IS_ACTIVE
822	HOST_REGISTER_ERROR_UPDATING_NAME
823	HOST_REGISTER_ERROR_UPDATING_NAMES_ALL_TAKEN
824	HOST_REGISTER_NAME_IS_ACTIVE
825	HOST_REGISTER_AUTO_APPROVE_PATTERN
826	HOST_REGISTER_FAILED
827	HOST_REGISTER_EXISTING_HOST_UPDATE_FAILED
828	HOST_REGISTER_SUCCEEDED
829	VM_MIGRATION_ON_CONNECT_CHECK_FAILED
830	VM_MIGRATION_ON_CONNECT_CHECK_SUCCEEDED
831	USER_DEDICATE_VM_TO_POWERCLIENT
832	USER_DEDICATE_VM_TO_POWERCLIENT_FAILED
833	MAC_ADDRESS_IS_IN_USE
835	SYSTEM_UPDATE_HOST_GROUP
836	SYSTEM_UPDATE_HOST_GROUP_FAILED
850	USER_ADD_PERMISSION
851	USER_ADD_PERMISSION_FAILED
852	USER_REMOVE_PERMISSION
853	USER_REMOVE_PERMISSION_FAILED
854	USER_ADD_ROLE
855	USER_ADD_ROLE_FAILED
856	USER_UPDATE_ROLE
857	USER_UPDATE_ROLE_FAILED
858	USER_REMOVE_ROLE
859	USER_REMOVE_ROLE_FAILED
860	USER_ATTACHED_ACTION_GROUP_TO_ROLE
861	USER_ATTACHED_ACTION_GROUP_TO_ROLE_FAILED
862	USER_DETACHED_ACTION_GROUP_FROM_ROLE
863	USER_DETACHED_ACTION_GROUP_FROM_ROLE_FAILED
864	USER_ADD_ROLE_WITH_ACTION_GROUP
865	USER_ADD_ROLE_WITH_ACTION_GROUP_FAILED
900	AD_COMPUTER_ACCOUNT_SUCCEEDED
901	AD_COMPUTER_ACCOUNT_FAILED
920	NETWORK_ATTACH_NETWORK_TO_HOST
921	NETWORK_ATTACH_NETWORK_TO_HOST_FAILED
922	NETWORK_DETACH_NETWORK_FROM_HOST
923	NETWORK_DETACH_NETWORK_FROM_HOST_FAILED
924	NETWORK_ADD_BOND
925	NETWORK_ADD_BOND_FAILED
926	NETWORK_REMOVE_BOND
927	NETWORK_REMOVE_BOND_FAILED
928	NETWORK_HOST_NETWORK_MATCH_CLUSTER
929	NETWORK_HOST_NETWORK_NOT_MATCH_CLUSTER
930	NETWORK_REMOVE_VM_INTERFACE
931	NETWORK_REMOVE_VM_INTERFACE_FAILED
932	NETWORK_ADD_VM_INTERFACE
933	NETWORK_ADD_VM_INTERFACE_FAILED
934	NETWORK_UPDATE_VM_INTERFACE
935	NETWORK_UPDATE_VM_INTERFACE_FAILED
936	NETWORK_ADD_TEMPLATE_INTERFACE
937	NETWORK_ADD_TEMPLATE_INTERFACE_FAILED
938	NETWORK_REMOVE_TEMPLATE_INTERFACE
939	NETWORK_REMOVE_TEMPLATE_INTERFACE_FAILED
940	NETWORK_UPDATE_TEMPLATE_INTERFACE
941	NETWORK_UPDATE_TEMPLATE_INTERFACE_FAILED
942	NETWORK_ADD_NETWORK
943	NETWORK_ADD_NETWORK_FAILED
944	NETWORK_REMOVE_NETWORK
945	NETWORK_REMOVE_NETWORK_FAILED
946	NETWORK_ATTACH_NETWORK_TO_HOST_GROUP
947	NETWORK_ATTACH_NETWORK_TO_HOST_GROUP_FAILED
948	NETWORK_DETACH_NETWORK_TO_HOST_GROUP
949	NETWORK_DETACH_NETWORK_TO_HOST_GROUP_FAILED
950	USER_ADD_STORAGE_POOL
951	USER_ADD_STORAGE_POOL_FAILED
952	USER_UPDATE_STORAGE_POOL
953	USER_UPDATE_STORAGE_POOL_FAILED
954	USER_REMOVE_STORAGE_POOL
955	USER_REMOVE_STORAGE_POOL_FAILED
956	USER_ADD_STORAGE_DOMAIN
957	USER_ADD_STORAGE_DOMAIN_FAILED
958	USER_UPDATE_STORAGE_DOMAIN
959	USER_UPDATE_STORAGE_DOMAIN_FAILED
960	USER_REMOVE_STORAGE_DOMAIN
961	USER_REMOVE_STORAGE_DOMAIN_FAILED
962	USER_ATTACH_STORAGE_DOMAIN_TO_POOL
963	USER_ATTACH_STORAGE_DOMAIN_TO_POOL_FAILED
964	USER_DETACH_STORAGE_DOMAIN_FROM_POOL
965	USER_DETACH_STORAGE_DOMAIN_FROM_POOL_FAILED
966	USER_ACTIVATED_STORAGE_DOMAIN
967	USER_ACTIVATE_STORAGE_DOMAIN_FAILED
968	USER_DEACTIVATED_STORAGE_DOMAIN
969	USER_DEACTIVATE_STORAGE_DOMAIN_FAILED
970	SYSTEM_DEACTIVATED_STORAGE_DOMAIN
971	SYSTEM_DEACTIVATE_STORAGE_DOMAIN_FAILED
972	USER_EXTENDED_STORAGE_DOMAIN
973	USER_EXTENDED_STORAGE_DOMAIN_FAILED
974	USER_REMOVE_VG
975	USER_REMOVE_VG_FAILED
976	USER_ACTIVATE_STORAGE_POOL
977	USER_ACTIVATE_STORAGE_POOL_FAILED
978	SYSTEM_FAILED_CHANGE_STORAGE_POOL_STATUS
979	SYSTEM_CHANGE_STORAGE_POOL_STATUS_NO_HOST_FOR_SPM
980	SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC
981	USER_FORCE_REMOVE_STORAGE_DOMAIN
982	USER_FORCE_REMOVE_STORAGE_DOMAIN_FAILED
983	RECONSTRUCT_MASTER_FAILED_NO_MASTER
984	RECONSTRUCT_MASTER_DONE
985	RECONSTRUCT_MASTER_FAILED
986	SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_SEARCHING_NEW_SPM
987	SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_WITH_ERROR
988	USER_CONNECT_HOSTS_TO_LUN_FAILED
989	SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_FROM_NON_OPERATIONAL
990	SYSTEM_MASTER_DOMAIN_NOT_IN_SYNC
991	RECOVERY_STORAGE_POOL
992	RECOVERY_STORAGE_POOL_FAILED
993	SYSTEM_CHANGE_STORAGE_POOL_STATUS_RESET_IRS
994	CONNECT_STORAGE_SERVERS_FAILED
995	CONNECT_STORAGE_POOL_FAILED
996	STORAGE_DOMAIN_ERROR
1100	NETWORK_UPDATE_DISPLAY_TO_HOST_GROUP
1101	NETWORK_UPDATE_DISPLAY_TO_HOST_GROUP_FAILED
1102	NETWORK_UPDATE_NETWORK_TO_HOST_INTERFACE
1103	NETWORK_UPDATE_NETWORK_TO_HOST_INTERFACE_FAILED
1104	NETWORK_COMMINT_NETWORK_CHANGES
1105	NETWORK_COMMINT_NETWORK_CHANGES_FAILED
1106	NETWORK_HOST_USING_WRONG_CLUSER_VLAN
1107	NETWORK_HOST_MISSING_CLUSER_VLAN
1150	IMPORTEXPORT_EXPORT_VM
1151	IMPORTEXPORT_EXPORT_VM_FAILED
1152	IMPORTEXPORT_IMPORT_VM
1153	IMPORTEXPORT_IMPORT_VM_FAILED
1154	IMPORTEXPORT_REMOVE_TEMPLATE
1155	IMPORTEXPORT_REMOVE_TEMPLATE_FAILED
1156	IMPORTEXPORT_EXPORT_TEMPLATE
1157	IMPORTEXPORT_EXPORT_TEMPLATE_FAILED
1158	IMPORTEXPORT_IMPORT_TEMPLATE
1159	IMPORTEXPORT_IMPORT_TEMPLATE_FAILED
1160	IMPORTEXPORT_REMOVE_VM
1161	IMPORTEXPORT_REMOVE_VM_FAILED
1162	IMPORTEXPORT_STARTING_EXPORT_VM
1163	IMPORTEXPORT_STARTING_IMPORT_TEMPLATE
1164	IMPORTEXPORT_STARTING_EXPORT_TEMPLATE
1165	IMPORTEXPORT_STARTING_IMPORT_VM
1166	IMPORTEXPORT_STARTING_REMOVE_TEMPLATE
1167	IMPORTEXPORT_STARTING_REMOVE_VM
1168	IMPORTEXPORT_FAILED_TO_IMPORT_VM
1169	IMPORTEXPORT_FAILED_TO_IMPORT_TEMPLATE
9000	HOST_ALERT_FENCING_IS_NOT_CONFIGURED
9001	HOST_ALERT_FENCING_TEST_FAILED
9002	HOST_ALERT_FENCING_OPERATION_FAILED
9003	HOST_ALERT_FENCING_OPERATION_SKIPPED
9004	HOST_ALERT_FENCING_NO_PROXY_HOST
9500	TASK_STOPPING_ASYNC_TASK
9501	TASK_CLEARING_ASYNC_TASK

Timezones

The API maps Windows Standard Format timezone names to tz database format when specifying a timezone for a virtual machine or VM template. This means the API only accepts certain tz database codes, which the following table lists:

tz database Format	Windows Standard Format
Africa/Cairo	Egypt Standard Time
Africa/Casablanca	Morocco Standard Time
Africa/Johannesburg	South Africa Standard Time
Africa/Lagos	W. Central Africa Standard Time
Africa/Nairobi	E. Africa Standard Time
Africa/Reykjavik	Greenwich Standard Time
Africa/Windhoek	Namibia Standard Time
America/Anchorage	Alaskan Standard Time
America/Bogota	SA Pacific Standard Time
America/Buenos_Aires	Argentina Standard Time
America/Caracas	Venezuela Standard Time
America/Chicago	Central Standard Time
America/Chihuahua	Mexico Standard Time
America/Chihuahua	Mountain Standard Time
America/Denver	Mountain Standard Time
America/Godthab	Greenland Standard Time
America/Guatemala	Central America Standard Time
America/Halifax	Atlantic Standard Time
America/La_Paz	SA Western Standard Time
America/Los_Angeles	Pacific Standard Time
America/Manaus	Central Brazilian Standard Time
America/Mexico_City	Central Standard Time
America/Mexico_City	Mexico Standard Time
America/Montevideo	Montevideo Standard Time
America/New_York	Eastern Standard Time
America/Phoenix	US Mountain Standard Time
America/Regina	Canada Central Standard Time
America/Santiago	Pacific SA Standard Time
America/Sao_Paulo	E. South America Standard Time
America/St_Johns	Newfoundland Standard Time
America/Tijuana	Pacific Standard Time
Asia/Amman	Jordan Standard Time
Asia/Baghdad	Arabic Standard Time
Asia/Baku	Azerbaijan Standard Time
Asia/Bangkok	SE Asia Standard Time
Asia/Beirut	Middle East Standard Time
Asia/Calcutta	India Standard Time
Asia/Colombo	Sri Lanka Standard Time
Asia/Dhaka	Central Asia Standard Time
Asia/Dubai	Arabian Standard Time
Asia/Irkutsk	North Asia East Standard Time
Asia/Jerusalem	Israel Standard Time
Asia/Kabul	Afghanistan Standard Time
Asia/Karachi	Pakistan Standard Time
Asia/Katmandu	Nepal Standard Time
Asia/Krasnoyarsk	North Asia Standard Time
Asia/Novosibirsk	N. Central Asia Standard Time
Asia/Rangoon	Myanmar Standard Time
Asia/Riyadh	Arab Standard Time
Asia/Seoul	Korea Standard Time
Asia/Shanghai	China Standard Time
Asia/Singapore	Singapore Standard Time
Asia/Taipei	Taipei Standard Time
Asia/Tashkent	West Asia Standard Time
Asia/Tehran	Iran Standard Time
Asia/Tokyo	Tokyo Standard Time
Asia/Vladivostok	Vladivostok Standard Time
Asia/Yakutsk	Yakutsk Standard Time
Asia/Yekaterinburg	Ekaterinburg Standard Time
Asia/Yerevan	Armenian Standard Time
Asia/Yerevan	Caucasus Standard Time
Atlantic/Azores	Azores Standard Time
Atlantic/Cape_Verde	Cape Verde Standard Time
Atlantic/South_Georgia	Mid-Atlantic Standard Time
Australia/Adelaide	Cen. Australia Standard Time
Australia/Brisbane	E. Australia Standard Time
Australia/Darwin	AUS Central Standard Time
Australia/Hobart	Tasmania Standard Time
Australia/Perth	W. Australia Standard Time
Australia/Sydney	AUS Eastern Standard Time
Etc/GMT-3	Georgian Standard Time
Etc/GMT+12	Dateline Standard Time
Etc/GMT+3	SA Eastern Standard Time
Etc/GMT+5	US Eastern Standard Time
Europe/Berlin	W. Europe Standard Time
Europe/Budapest	Central Europe Standard Time
Europe/Istanbul	GTB Standard Time
Europe/Kiev	FLE Standard Time
Europe/London	GMT Standard Time
Europe/Minsk	E. Europe Standard Time
Europe/Moscow	Russian Standard Time
Europe/Paris	Romance Standard Time
Europe/Warsaw	Central European Standard Time
Indian/Mauritius	Mauritius Standard Time
Pacific/Apia	Samoa Standard Time
Pacific/Auckland	New Zealand Standard Time
Pacific/Fiji	Fiji Standard Time
Pacific/Guadalcanal	Central Pacific Standard Time
Pacific/Honolulu	Hawaiian Standard Time
Pacific/Port_Moresby	West Pacific Standard Time
Pacific/Tongatapu	Tonga Standard Time

Revision History

Revision History

Revision 0-0

Thu Jun 17 2010

Mark McLoughlin

Initial creation