Red Hat Enterprise Virtualization 3.1

Developer Guide

Using the Red Hat Enterprise Virtualization Application Programming Interfaces

Edition 1

Red Hat Documentation Team

Red Hat Engineering Services and Operations

Daniel Macpherson

Red Hat Engineering Content Services

Stephen Gordon

Red Hat Engineering Content Services

Legal Notice

Copyright © 2012 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
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.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract

This document describes Red Hat Enterprise Virtualization's developer APIs.
Preface
1. About This Guide
2. Audience
3. Document Conventions
4. Getting Help and Giving Feedback
5. Backwards Compatibility Statement
6. Red Hat Enterprise Virtualization API Support Statement
I. Introduction
1. Introduction
1.1. Representational State Transfer
1.2. Prerequisites
2. Authentication and Security
2.1. TLS/SSL Certification
2.2. HTTP Authentication
2.3. Authentication Sessions
3. REST API Beginner Example
3.1. Example: Access API Entry Point
3.2. Example: List Data Center Collection
3.3. Example: List Host Cluster Collection
3.4. Example: List Logical Networks Collection
3.5. Example: List Host Collection
3.6. Example: Approve Host
3.7. Example: Create NFS Data Storage
3.8. Example: Create NFS ISO Storage
3.9. Example: Attach Storage Domains to Data Center
3.10. Example: Activate Storage Domains
3.11. Example: Create Virtual Machine
3.12. Example: Create Virtual Machine NIC
3.13. Example: Create Virtual Machine Storage Disk
3.14. Example: Attach ISO Image to Virtual Machine
3.15. Example: Start Virtual Machine
3.16. Example: Check System Events
3.17. Example Completion
4. Python Beginner Example
4.1. Python Quick Start Introduction
4.2. Example: Accessing the API Entry Point using Python
4.3. Example: Listing the Data Center Collection using Python
4.4. Example: Listing the Cluster Collection using Python
4.5. Example: Listing the Logical Networks Collection using Python
4.6. Example: Listing the Host Collection using Python
4.7. Example: Approving a Host using Python
4.8. Example: Creating NFS Data Storage using Python
4.9. Example: Creating NFS ISO Storage using Python
4.10. Example: Attaching Storage Domains to a Data Center using Python
4.11. Example: Activating Storage Domains using Python
4.12. Example: Creating a Virtual Machine using Python
4.13. Example: Creating a Virtual Machine NIC using Python
4.14. Example: Creating a Virtual Machine Storage Disk using Python
4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
4.16. Example: Starting a Virtual Machine using Python
4.17. Example: Checking System Events using Python
II. REST Application Programming Interface
5. Entry Point
5.1. Product Information
5.2. Link elements
5.3. Special object elements
5.4. Summary element
5.5. RESTful Service Description Language (RSDL)
6. Compatibility Level Versions
7. Capabilities
7.1. Version-Dependent Capabilities
7.2. Current Version
7.3. Features
7.4. CPUs
7.5. Power Managers
7.6. Fence Types
7.7. Storage Types
7.8. Storage Domain Types
7.9. Virtual Machine Types
7.10. Boot Devices
7.11. Display Types
7.12. NIC Interface Types
7.13. OS Types
7.14. Disk Formats
7.15. Disk Interfaces
7.16. Virtual Machine Affinities
7.17. Custom Properties
7.18. Boot Protocols
7.19. Error Handling
7.20. Storage Formats
7.21. Virtual Machine Device Types
7.22. Gluster Volume Types
7.23. Gluster Transport Types
7.24. Guster Acces Protocols
7.25. Resource Status States
7.26. Permits
7.27. Scheduling Policies
8. Common Features
8.1. Representations
8.2. Collections
8.3. Resources
9. Data Centers
9.1. Storage Domains Sub-Collection
9.2. Quotas Sub-Collection
9.3. Force Remove Action
10. Host Clusters
10.1. Networks Sub-Collection
10.2. Red Hat Storage Volumes Sub-Collection
11. Networks
12. Storage Domains
12.1. Storage types
12.2. Export Storage Domains
12.3. Files Sub-Collection
12.4. Import Existing Storage Domain
12.5. Delete Storage Domain
13. Hosts
13.1. Power Management
13.2. Memory Management
13.3. Network Interface Sub-Collection
13.4. Storage Sub-Collection
13.5. Statistics Sub-Collection
13.6. Actions
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. Statistics Sub-Collection
14.6. Actions
15. Floating Disks
15.1. Floating Disk Statistics
16. Templates
16.1. Export Action
17. Virtual Machine Pools
18. Domains
18.1. Domain Users Sub-Collection
18.2. Domain Groups Sub-Collection
19. Roles
19.1. Permits Sub-Collection
20. Groups
21. Users
22. Tags
22.1. Associating Tags With a Host, User or VM
22.2. Parent Tags
23. Events
23.1. Searching Events
23.2. Paginating Events
III. Python Sofware Development Kit
24. Software Development Kit Overview
24.1. Introduction to the Red Hat Enterprise Virtualization Software Development Kit
24.2. Software Development Kit Prerequisites
24.3. Installing the Software Development Kit
25. Using the Software Development Kit
25.1. Connecting to the API using Python
25.2. Resources and Collections
25.3. Retrieving Resources from a Collection
25.4. Retrieving a Specific Resource from a Collection
25.5. Retrieving a List of Resources from a Collection
25.6. Adding a Resource to a Collection
25.7. Updating a Resource in a Collection
25.8. Removing a Resource from a Collection
25.9. Handling Errors
26. Python Reference Documentation
A. API Usage with cURL
B. Importing Certificates
B.1. Network Security Services (NSS) Database
B.2. Java Keystores
C. Enumerated Value Translation
D. Event Codes
E. Timezones
F. Revision History

Preface

The Red Hat Enterprise Virtualization platform is a richly featured virtualization platform that provides fully integrated management across virtual machines with multiple hosts. It is based on KVM (Kernel-based Virtual Machine), the leading open source virtualization platform, and provides superior technical capabilities. The platform offers scalability in the management of a large number of physical hosts and virtual machines.

1. About This Guide

This guide explains how to use Red Hat Enterprise Virtualization Manager's Representational State Transfer (REST) API. This document covers the fundamentals of the REST architectural concepts in the context of a virtualization environment and provides examples of the API in operation.
In addition Red Hat Enterprise Virtualization also provides a Python Software Development Kit (SDK) . The SDK provides Python libraries for interacting with the REST API. The installation and use of the Python SDK is documetned in this guide.

2. Audience

The target audience for this guide includes developers and system administrators who aim to integrate their Red Hat Enterprise Virtualization environment with third-party applications and scripts.

3. 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 include the Liberation Fonts set by default.

3.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 keys 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 key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys 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 SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select 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 ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… 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 EditPaste 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.

3.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:
static int kvm_vm_ioctl_deassign_device(struct kvm *kvm,
                 struct kvm_assigned_pci_dev *assigned_dev)
{
         int r = 0;
         struct kvm_assigned_dev_kernel *match;

         mutex_lock(&kvm->lock);

         match = kvm_find_assigned_dev(&kvm->arch.assigned_dev_head,
                                       assigned_dev->assigned_dev_id);
         if (!match) {
                 printk(KERN_INFO "%s: device hasn't been assigned before, "
                   "so cannot be deassigned\n", __func__);
                 r = -EINVAL;
                 goto out;
         }

         kvm_deassign_device(kvm, match);

         kvm_free_assigned_device(kvm, match);

out:
         mutex_unlock(&kvm->lock);
         return r;
}

3.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.

4. Getting Help and Giving Feedback

4.1. Do You Need Help?

If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
  • search or browse through a knowledgebase of technical support articles about Red Hat products.
  • submit a support case to Red Hat Global Support Services (GSS).
  • access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

4.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 report in Bugzilla: http://bugzilla.redhat.com/ against the product Red Hat Enterprise Virtualization Manager.
When submitting a bug report, be sure to mention the manual's identifier: Guides-Developer
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

5. Backwards Compatibility Statement

Red Hat will make commercially reasonable efforts to ensure that applications developed for a certain version of Red Hat Enterprise Virtualization (RHEV) will work unmodified with future versions of RHEV within the same major release. Compatibility between different major releases is not guaranteed.

6. Red Hat Enterprise Virtualization API Support Statement

Red Hat Enterprise Virtualization exposes a number of interfaces for interacting with the components of the virtualization environment. These interfaces are in addition to the user interfaces provided by the Red Hat Enterprise Virtualization Manager Administration, User, and Reports Portals. Many of these interfaces are fully supported. Some however are supported only for read access or only when your use of them has been explicitly requested by Red Hat Support.

Supported Interfaces for Read and Write Access

Direct interaction with these interfaces is supported and encouraged for both read and write access:
Representational State Transfer (REST) API
The REST API exposed by the Red Hat Enterprise Virtualization Manager is a fully supported interface for interacting with Red Hat Enterprise Virtualization Manager.
Software Development Kit (SDK)
The SDK provided by the rhevm-sdk package is a fully supported interface for interacting with Red Hat Enterprise Virtualization Manager.
Command Line Shell
The command line shell provided by the rhevm-cli package is a fully supported interface for interacting with the Red Hat Enterprise Virtualization Manager.
VDSM Hooks
The creation and use of VDSM hooks to trigger modification of virtual machines based on custom properties specified in the Administration Portal is supported on Red Hat Enterprise Linux virtualization hosts. The use of VDSM Hooks on virtualization hosts running Red Hat Enterprise Virtualization Hypervisor is not currently supported.

Supported Interfaces for Read Access

Direct interaction with these interfaces is supported and encouraged only for read access. Use of these interfaces for write access is not supported unless explicitly requested by Red Hat Support:
Red Hat Enterprise Virtualization Manager History Database
Read access to the Red Hat Enterprise Virtualization Manager history database using the database views specified in the Administration Guide is supported. Write access is not supported.
Libvirt on Virtualization Hosts
Read access to libvirt using the virsh -r command is a supported method of interacting with virtualization hosts. Write access is not supported.

Unsupported Interfaces

Direct interaction with these interfaces is not supported unless your use of them is explicitly requested by Red Hat Support:
The vdsClient Command
Use of the vdsClient command to interact with virtualization hosts is not supported unless explicitly requested by Red Hat Support.
Red Hat Enterprise Virtualization Hypervisor Console
Console access to Red Hat Enterprise Virtualization Hypervisor outside of the provided text user interface for configuration is not supported unless explicitly requested by Red Hat Support.
Red Hat Enterprise Virtualization Manager Database
Direct access to and manipulation of the Red Hat Enterprise Virtualization Manager database is not supported unless explicitly requested by Red Hat Support.

Important

Red Hat Support will not debug user created scripts or hooks except where it can be demonstrated that there is an issue with the interface being used rather than the user created script itself. For more general information about Red Hat support policies see https://access.redhat.com/support/offerings/production/soc.html.

Part I. Introduction

Table of Contents

1. Introduction
1.1. Representational State Transfer
1.2. Prerequisites
2. Authentication and Security
2.1. TLS/SSL Certification
2.2. HTTP Authentication
2.3. Authentication Sessions
3. REST API Beginner Example
3.1. Example: Access API Entry Point
3.2. Example: List Data Center Collection
3.3. Example: List Host Cluster Collection
3.4. Example: List Logical Networks Collection
3.5. Example: List Host Collection
3.6. Example: Approve Host
3.7. Example: Create NFS Data Storage
3.8. Example: Create NFS ISO Storage
3.9. Example: Attach Storage Domains to Data Center
3.10. Example: Activate Storage Domains
3.11. Example: Create Virtual Machine
3.12. Example: Create Virtual Machine NIC
3.13. Example: Create Virtual Machine Storage Disk
3.14. Example: Attach ISO Image to Virtual Machine
3.15. Example: Start Virtual Machine
3.16. Example: Check System Events
3.17. Example Completion
4. Python Beginner Example
4.1. Python Quick Start Introduction
4.2. Example: Accessing the API Entry Point using Python
4.3. Example: Listing the Data Center Collection using Python
4.4. Example: Listing the Cluster Collection using Python
4.5. Example: Listing the Logical Networks Collection using Python
4.6. Example: Listing the Host Collection using Python
4.7. Example: Approving a Host using Python
4.8. Example: Creating NFS Data Storage using Python
4.9. Example: Creating NFS ISO Storage using Python
4.10. Example: Attaching Storage Domains to a Data Center using Python
4.11. Example: Activating Storage Domains using Python
4.12. Example: Creating a Virtual Machine using Python
4.13. Example: Creating a Virtual Machine NIC using Python
4.14. Example: Creating a Virtual Machine Storage Disk using Python
4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
4.16. Example: Starting a Virtual Machine using Python
4.17. Example: Checking System Events using Python

Chapter 1. Introduction

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 external applications that access the API via the standard Hypertext Transfer Protocol (HTTP).
The benefits of the REST API are:
  • Broad client support - Any programming language, framework, or system with support for HTTP protocol can use the API;
  • Self descriptive - Client applications require minimal knowledge of the virtualization infrastructure as many details are discovered at runtime;
  • Resource-based model - The resource-based REST model provides a natural way to manage a virtualization platform.
This provides developers and administrators with the ability to:
  • Integrate with enterprise IT systems.
  • Integrate with third-party virtualization software.
  • Perform automated maintenance or error checking tasks.
  • Automate repetitive tasks in a Red Hat Enterprise Virtualization environment with scripts.
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 either directly or using the provided Python libraries.

1.1. Representational State Transfer

Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTP methods, such as GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independent of any other request and contains all necessary information to complete the request.

1.2. Prerequisites

This guide requires the following:
  • A networked installation of Red Hat Enterprise Virtualization Manager, which includes the REST API;
  • A client or programming library that initiates and receives HTTP requests from the REST API. For example:
    • Red Hat Enterprise Virtualization 3.1 provides a Python software development kit (SDK) that interacts with the REST API. This guide includes a Python Beginner Example to help developers get started with using the SDK.
    • This guide includes basic instructions on use with cURL in Appendix A, API Usage with cURL.
  • Knowledge of Hypertext Transfer Protocol (HTTP), which is the protocol used for REST API interactions. The Internet Engineering Task Force provides a Request for Comments (RFC) explaining the Hypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt; and,
  • Knowledge of Extensible Markup Language (XML), which the API uses to construct resource representations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml/.
Additionally, to use the Python SDK you will need to download and install the rhevm-sdk package. This package is available to systems subscribed to a Red Hat Enterprise Virtualization entitlement pool if using certificate-based Red Hat Network, or the rhel-x86_64-server-6-rhevm-3.1 channel if using Red Hat Network classic. See the Red Hat Enterprise Virtualization Installation Guide for more information on subscribing your system(s) to download software from these locations.

Chapter 2. Authentication and Security

This chapter provides information on authorization through Red Hat Enterprise Virtualization Manager's security.

2.1. TLS/SSL Certification

The API requires Hypertext Transfer Protocol Secure (HTTPS) [1] for secure transport-level encryption of requests. This involves a process of attaining a certificate from your Red Hat Enterprise Virtualization Manager server and importing it into your client's certificate store.

Important

Attain your certificate from the Red Hat Enterprise Virtualization Manager server using a secure network connection.

Procedure 2.1. Attain a certificate

This process helps a user attain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to the client machine. A user achieves this using one of three methods:
  1. Method 1 - Use a command line tool to download the certificate from the server. Examples of command line tools include cURL and Wget; both are available for multiple platforms.
    1. If using cURL:
      curl -o rhevm.cer http://[rhevm-server]/ca.crt
    2. If using Wget:
      wget -O rhevm.cer http://[rhevm-server]/ca.crt
  2. Method 2 - Use a web browser to navigate to the certificate located at:
    http://[rhevm-server]/ca.crt
    Depending on the chosen browser, the certificate either downloads or imports into the browser's keystore.
    1. If the browser downloads the certificate: save the file as rhevm.cer.
      If the browser imports the certificate: export it from the browser's certification options and save it as rhevm.cer.
  3. Method 3 - Access your Red Hat Enterprise Virtualization Manager server either physically or through a secure shell (SSH) client, export the certificate from the server's keystore and copy it to your client machine.
    1. Access your Red Hat Enterprise Virtualization Manager server as the root user.
    2. Export a certificate from the server's keystore using the Java keytool management utility:
      keytool -exportcert -keystore /etc/pki/rhevm/.keystore -alias rhevm -storepass mypass -file rhevm.cer
      This creates a certificate file called rhevm.cer.
    3. Copy the certificate to the client machine using the scp command:
      scp rhevm.cer [username]@[client-machine]:[directory]
Each of the three methods results in a certificate file named rhevm.cer on your client machine. An API user imports this file into the client's certificate store.

Procedure 2.2. Import a certificate to your client

  • A certificate import for your client relies on how the client itself stores and interprets certificates. This guide contains some examples on importing certificates in Appendix B, Importing Certificates. For other clients, please refer to your client documentation for more information on importing a certificate.

2.2. HTTP Authentication

Any user with a Red Hat Enterprise Virtualization account has access to the REST API. An API user submits a mandatory Red Hat Enterprise Virtualization Manager username and password with all requests to the API. Each request uses HTTP Basic Authentication [2] to encode these credentials. If a request does not include an appropriate Authorization header, the API sends a 401 Authorization Required as a result:

Example 2.1. Access to the REST API without appropriate credentials

HEAD [base] HTTP/1.1
Host: [host]

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. An API user encodes an appropriate Red Hat Enterprise Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.
The following table shows the process for encoding credentials in base64.

Table 2.1. Encoding credentials for API access

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

An API user provides the base64 encoded credentials as shown:

Example 2.2. Access to the REST API with appropriate credentials

HEAD [base] HTTP/1.1
Host: [host]
Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK
...

Important

Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. REST API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests. See Section 2.1, “TLS/SSL Certification” for more information.

Important

Some base64 libraries break the result into multiple lines and terminate each line with a newline character. This breaks the header and causes a faulty request. The Authorization header requires the encoded credentials on a single line within the header.

2.3. Authentication Sessions

The API also provides the ability for authentication session support. An API user sends an initial request with authentication details, then sends all subsequent requests using a session cookie to authenticate. The following procedure demonstrates how to use an authenticated session.

Procedure 2.3. Requesting an authenticated session

  1. Send a request with the Authorization and Prefer: persistent-auth
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    Prefer: persistent-auth
    
    HTTP/1.1 200 OK
    ...
    
    This returns a response with the following header:
    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/api; Secure
    
    Note the JSESSIONID= value. In this example the value is JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK.
  2. Send all subsequent requests with the Prefer: persistent-auth and cookie header with the JSESSIONID= value. The Authorization is no longer needed when using an authenticated session.
    HEAD [base] HTTP/1.1
    Host: [host]
    Prefer: persistent-auth
    cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
    
    HTTP/1.1 200 OK
    ...
    
  3. When the session is no longer required, perform a request to the sever without the Prefer: persistent-auth header.
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    
    HTTP/1.1 200 OK
    ...
    

Chapter 3. REST API Beginner Example

This chapter provides an example to demonstrate the REST API's ability to setup a basic Red Hat Enterprise Virtualization environment and create a virtual machine.
In addition to the standard prerequisites (see Section 1.2, “Prerequisites”), this example requires the following:
  • 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 Enterprise Linux Server 6 for our installation ISO example; and
  • Red Hat Enterprise Virtualization's rhevm-iso-uploader tool to upload your chosen operating system ISO file.
This example uses cURL to demonstrate REST requests with a client application. Find out more about cURL use with the REST API in Appendix A, API Usage with cURL. Note that any application capable of HTTP requests can substitute for cURL.

Important

For simplicity, the HTTP request headers in this example omit the Host: and Authorization: fields. However, these fields are mandatory and require data specific to your installation of Red Hat Enterprise Virtualization Manager.

Important

All cURL examples include placeholders for authentication details (USER:PASS) and certificate location (CERT). Ensure all requests performed with cURL fulfil certification and authentication requirements. See Chapter 2, Authentication and Security and Appendix A, API Usage with cURL for more information.

Note

Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the id attribute for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.

3.1. Example: Access API Entry Point

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

Example 3.1. Access the API entry point

Request:
GET /api HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] https://[RHEVM Host]:8443/api
Result:
HTTP/1.1 200 OK
Content-Type: application/xml

<api>
    <link rel="capabilities" href="/api/capabilities"/>
    <link rel="clusters" href="/api/clusters"/>
    <link rel="clusters/search" href="/api/clusters?search={query}"/>
    <link rel="datacenters" href="/api/datacenters"/>
    <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
    <link rel="events" href="/api/events"/>
    <link rel="events/search" href="/api/events?search={query}"/>
    <link rel="hosts" href="/api/hosts"/>
    <link rel="hosts/search" href="/api/hosts?search={query}"/>
    <link rel="networks" href="/api/networks"/>
    <link rel="roles" href="/api/roles"/>
    <link rel="storagedomains" href="/api/storagedomains"/>
    <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
    <link rel="tags" href="/api/tags"/>
    <link rel="templates" href="/api/templates"/>
    <link rel="templates/search" href="/api/templates?search={query}"/>
    <link rel="users" href="/api/users"/>
    <link rel="groups" href="/api/groups"/>
    <link rel="domains" href="/api/domains"/>
    <link rel="vmpools" href="/api/vmpools"/>
    <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
    <link rel="vms" href="/api/vms"/>
    <link rel="vms/search" href="/api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="0" major="3"/>
    </product_info>
    <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.
The entry point also contains other data such as product_info, special_objects and summary. This data is covered in chapters outside this example.

3.2. Example: List Data Center Collection

Red Hat Enterprise 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 3.2. List data center collection

Request:
GET /api/datacenters HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:8443/api/datacenters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml

<data_centers>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"
          href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
          storagedomains"/>
        <link rel="permissions"
          href="/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>
            <state>up</state>
        </status>
    </data_center>
</data_centers>

Note the id code of your Default data center. This code identifies this data center in relation to other resources of your virtual environment.
The data center also contains a link to the storagedomains sub-collection. The data center uses this sub-collection to attach storage domains from the storagedomains main collection, which this example covers later.

3.3. Example: List Host Cluster Collection

Red Hat Enterprise Virtualization Manager creates a Default host cluster on installation. This example uses the Default cluster to group resources in your Red Hat Enterprise Virtualization environment.
The following request retrieves a representation of the cluster collection:

Example 3.3. List host clusters collection

Request:
GET /api/clusters HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:8443/api/clusters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml

<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/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 identifies 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 id and href attributes of the data_center element.
The networks sub-collection contains a list of associated network resources for this cluster. The next section examines the networks collection in more detail.

3.4. Example: List Logical Networks Collection

Red Hat Enterprise Virtualization Manager creates a default rhevm network on installation. This network acts as the management network for Red Hat Enterprise Virtualization Manager to access hypervisor hosts.
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 3.4. List logical networks collection

Request:
GET /api/networks HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:8443/api/networks
Result:
HTTP/1.1 200 OK
Content-Type: application/xml

<networks>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009">
        <name>rhevm</name>
        <description>Management Network</description>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <stp>false</stp>
        <status>
            <state>operational</state>
        </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.

3.5. Example: List Host Collection

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

Example 3.5. List hosts collection

Request:
GET /api/hosts HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:8443/api/hosts
Result:
HTTP/1.1 200 OK
Accept: application/xml

<hosts>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
        <name>hypervisor</name>
        <actions>
            <link rel="install"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
            <link rel="activate"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
            <link rel="fence"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
            <link rel="deactivate"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
            <link rel="approve"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
            <link rel="iscsilogin"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
            <link rel="iscsidiscover"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
            <link rel="commitnetconfig"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
              commitnetconfig"/>
        </actions>
        <link rel="storage"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
        <link rel="nics"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
        <link rel="tags"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
        <link rel="permissions"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
        <link rel="statistics"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
        <address>10.64.14.110</address>
        <status>
            <state>non_operational</state>
        </status>
        <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
          href="/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 identifies 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.

3.6. Example: Approve Host

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

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

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

<action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>" \
    https://[RHEVM Host]:8443/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve

The POST request requires a body for the message entities to initiate an action. Since the action does not require additional parameters, the body contains an empty action element.
Use the approve action only for Red Hat Enterprise Virtualization Hypervisor hosts. Red Hat Enterprise Linux hosts require a different process to connect to the virtualization environment.
This approves and activates the host for use in your virtual environment. The status for hypervisor changes from non_operational to up.

3.7. Example: Create NFS Data Storage

An NFS data storage domain is an exported NFS share attached to a data center and provides storage for virtualized guest images. Creation of a new storage domain requires a POST request, with the storage domain representation included, sent to the URL of the storage domain collection.

Example 3.7. Create an NFS data storage domain

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<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>" \
    https://[RHEVM Host]:8443/api/storagedomains
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.
Result:
HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
  href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
    <name>data1</name>
    <link rel="permissions"
      href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
      permissions"/>
    <link rel="files"
      href="/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="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>

3.8. Example: Create NFS ISO Storage

An NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domain requires a POST request, with the storage domain representation included, sent to the URL of the storage domain collection.

Example 3.8. Create an NFS ISO storage domain

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<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>" \
    https://[RHEVM Host]:8443/api/storagedomains
The API creates a NFS iso storage domain called iso1 with an export path of 192.168.0.10:/iso1 and gets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource.
Result:
HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
  href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
    <name>iso1</name>
    <link rel="permissions"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      permissions"/>
    <link rel="files"
      href="/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="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">        
</storage_domain>

3.9. Example: Attach Storage Domains to Data Center

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

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

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>data1</name></storage_domain>" \
    https://[RHEVM Host]:8443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

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

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>iso1</name></storage_domain>" \
    https://[RHEVM Host]:8443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

These POST requests place our two new storage_domain resources in the storagedomains sub-collection of the Default data center. This means the storagedomain sub-collection contains attached storage domains of the data center.

3.10. Example: Activate Storage Domains

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

Example 3.11. Activate data1 storage domain

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

<action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>" \
    https://[RHEVM Host]:8443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate

Example 3.12. Activate iso1 storage domain

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

<action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>"
    https://[RHEVM Host]:8443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate

This activates both storage domains for use with the data center.

3.11. Example: 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 3.13. Create a virtual machine

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<vm><name>vm1</name><cluster><name>default</name> \
    </cluster><template><name>Blank</name></template> \
    <memory>536870912</memory><os><boot dev='hd'/></os></vm>" \
    https://[RHEVM Host]:8443/api/vms
Result:
HTTP/1.1 200 OK
Accept: application/xml    

<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
  href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
    <name>vm1</name>
    <actions>
        <link rel="shutdown"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
        <link rel="start"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
        <link rel="stop"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
        <link rel="suspend"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
        <link rel="detach"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
        <link rel="export"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
        <link rel="move"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
        <link rel="ticket"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
        <link rel="migrate"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
    </actions>
    <link rel="disks"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
    <link rel="nics"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
    <link rel="cdroms"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
    <link rel="snapshots"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
    <link rel="tags"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
    <link rel="permissions"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
    <link rel="statistics"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
    <type>desktop</type>
    <status>
        <state>down</state>
    </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="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/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>rhev</origin>
    <stateless>false</stateless>
    <placement_policy>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
    </memory_policy>
</vm>

3.12. Example: Create Virtual Machine NIC

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

Example 3.14. Create a virtual machine NIC

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

<nic>
  <interface>virtio</interface>
  <name>nic1</name>
  <network>
    <name>rhevm</name>
  </network>
</nic>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<nic><name>nic1</name><network><name>rhevm</name></network></nic>" \
    https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics

3.13. Example: Create Virtual Machine Storage Disk

The following example creates an 8 GB Copy-On-Write storage disk for the example virtual machine.

Example 3.15. Create a virtual machine storage disk

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

<disk>
    <storage_domains>
        <storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"/>  
    </storage_domains>    
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<disk><storage_domains> \
    <storage_domain id='9ca7cb40-9a2a-4513-acef-dc254af57aac'/> \
    </storage_domains><size>8589934592</size><type>system</type> \
    <interface>virtio</interface><format>cow</format> \
    <bootable>true</bootable></disk>" \
    https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks

The storage_domain element tells the API to store the disk on the data1 storage domain.

3.14. Example: 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 3.16. View the files sub-collection in an ISO storage domain

Request:
GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] \
    https://[RHEVM Host]:8443/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files
The API returns the following representation of the files sub-collection:
<files>
    <file id="rhel-server-6.0-x86_64-dvd.iso"
      href="/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="/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 3.17. Attach an ISO image to the virtual machine

Request:
POST /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>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>" \
    https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms

3.15. Example: 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 3.18. Start the virtual machine

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

<action>
  <vm>
    <os>
      <boot dev="cdrom"/>
    </os>
  </vm>
</action>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action><vm><os><boot dev='cdrom'/></os></vm></action>" \
    https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start

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.

3.16. Example: 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 3.19. List the events collection

Request:
GET /api/events HTTP/1.1
Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:8443/api/events
Result:
<events>
    ...
    <event id="103" href="/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="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="102" href="/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="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
        <vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
    </event>
    <event id="101" href="/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="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    ...
</events>
The following events occur:
  • 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.

3.17. Example Completion

This example demonstrates how the API creates a virtual machine within a basic virtualization environment. The remainder of this guide provides specific details on the complete REST API featureset, including virtualization tasks of a higher complexity.

Chapter 4. Python Beginner Example

4.1. Python Quick Start Introduction

This chapter provides a series of examples demonstrating the steps to create a virtual machine within a basic Red Hat Enterprise Virtualization environment, using the Python SDK.
These examples use the ovirtsdk Python library provided by the rhevm-sdk package. This package is available to systems subscribed to a Red Hat Enterprise Virtualization entitlement pool if using certificate-based Red Hat Network, or the rhel-x86_64-server-6-rhevm-3.1 channel if using Red Hat Network classic. See the Red Hat Enterprise Virtualization Installation Guide for more information on subscribing your system(s) to download software from these locations.
You will also need:
  • A networked installation of Red Hat Enterprise Virtualization Manager.
  • A networked and configured Red Hat Enterprise Virtualization Hypervisor.
  • An ISO image file containing an operating system for installation on a virtual machine.
  • A working understanding of both the logical and physical objects that make up a Red Hat Enterprise Virtualization environment.
  • A working understanding of the Python programming language.

Important

All Python examples include placeholders for authentication details (USER for user name, and PASS for password). Ensure all requests performed with Python fulfil the authentication requirements of your environment.

Note

Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the id attribute for each resource. Identifier codes in these examples might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.

Note

These Python examples contain only basic exception and error handling logic. For more information on the exception handling specific to the SDK refer to the pydoc for the ovirtsdk.infrastructure.errors module.

4.2. Example: Accessing the API Entry Point using Python

The ovirtsdk Python library provides the API class, which acts as the entry point for the API.

Example 4.1. Accessing the API entry point using Python

This python example connects to an instance of the REST API provided by the Red Hat Enterprise Virtualization Manager at rhevm.demo.redhat.com. To connect the example creates an instance of the API class If connection was successful a message is printed. Finally the disconnect() method of the API class is called to close the connection.
The parameters provided to the constructor for the API class in this example are:
  • The url of the Manager to connect to.
  • The username of the user to authenticate as.
  • The password of the user to authenticate as.
  • The ca_file which is the path to a certificate. The certificate is expected to be a copy of the one for the Manager's Certificate Authority. It can be obtained from https://HOST/ca.crt.
The constructor for the API class supports other parameters. Only mandatory parameters are specified in this example.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="https://HOST",
               username="USER",
               password="PASS",
               ca_file="ca.crt")

    print "Connected to %s successfully!" % api.get_product_info().name

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the connection attempt was successful, the example outputs the text:
Connected to Red Hat Enterprise Virtualization Manager successfully!

4.3. Example: Listing the Data Center Collection using Python

The API class provides access to a data centers collection, named datacenters. This collection contains all data centers in the environment.

Example 4.2. Listing the Data Center Collection using Python

This Python example lists the data centers in the datacenters collection. It also outputs some basic information about each data center in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="https://HOST",
               username="USER",
               password="PASS",
               ca_file="ca.crt")

    dc_list = api.datacenters.list()

    for dc in dc_list:
        print "%s (%s)" % (dc.get_name(), dc.get_id())

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
In an environment where only the Default data center exists, and it is not activated, the example outputs:
Default (d8b74b20-c6e1-11e1-87a3-00163e77e2ed)

4.4. Example: Listing the Cluster Collection using Python

The API class provides a clusters collection, named clusters. This collection contains all clusters in the environment.

Example 4.3. Listing the clusters collection using Python

This Python example lists the clusters in the clusters collection. It also outputs some basic information about each cluster in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="https://HOST", 
               username="USER", 
               password="PASS",
               ca_file="ca.crt")
      
    c_list = api.clusters.list()       
    
    for c in c_list:
        print "%s (%s)" % (c.get_name(), c.get_id())

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
In an environment where only the Default cluster exists, the example outputs:
Default (99408929-82cf-4dc7-a532-9d998063fa95)

4.5. Example: Listing the Logical Networks Collection using Python

The API class provides access to a logical networks collection, named networks. This collection contains all logical networks in the environment.

Example 4.4. Listing the logical networks collection using Python

This Python example lists the logical networks in the networks collection. It also outputs some basic information about each network in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST", 
              username="USER", 
              password="PASS",
              ca_file="ca.crt")

    n_list = api.logicalnetworks.list()

    for n in n_list:
        print "%s (%s)" % (n.get_name(), n.get_id())
    
    api.disconnect()
    
except Exception as ex:
    print "Unexpected error: %s" % ex
In an environment where only the default management network exists, the example outputs:
rhevm (00000000-0000-0000-0000-000000000009)

4.6. Example: Listing the Host Collection using Python

The API class provides access to a hosts collection, named hosts. This collection contains all hosts in the environment.

Example 4.5. Listing the host collection using Python

This Python example lists the hosts in the hosts collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="HOST", 
              username="USER", 
              password="PASS",
              ca_file="ca.crt")

    h_list = api.hosts.list()

    for h in h_list:
        print "%s (%s)" % (h.get_name(), h.get_id())

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex

In an environment where only one host, named Atlantic, has been attached the example outputs:
Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)

4.7. Example: Approving a Host using Python

Red Hat Enterprise Virtualization Hypervisor hosts are added to the Red Hat Enterprise Virtualization Manager during their configuration. Once you have added a Hypervisor it requires approval in the Manager before it can actually be used in the environment.

Example 4.6. Approving a host using Python

This Python example calls the approve method for a host named Atlantic.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="HOST",
              username="USER",
              password="PASS",
              ca_file="ca.crt")

    h = api.hosts.get(name="Atlantic")

    if(h.approve()):
        print "Host '%s' approved (Status: %s)." % (h.get_name(), h.get_status().get_state())
    else:
        print "Approval of '%s' failed." % h.get_name()

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the approve request is successful then the script will output:
Host 'Atlantic' approved (Status: Up).
Note that the status reflects that the host has been approved and is now considered to be up.

4.8. Example: Creating NFS Data Storage using Python

When a Red Hat Enterprise Virtualization environment is first being created it is necessary to define at least a data storage domain, and an ISO storage domain. The data storage domain will be used to store virtual machine disk images while the ISO storage domain will be used to store installation media for guest operating systems.
The API class provides access to a storage domains collection, named storagedomains. This collection contains all the storage domains in the environment. The storagedomains collection can also be used to add and remove storage domains.

Note

The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.

Example 4.7. Creating NFS data storage using Python

This Python example adds an NFS data domain to the storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
  1. Identify the data center to which the storage must be attached, using the get method of the datacenters collection.
    dc = api.datacenters.get(name="Default")
  2. Identify the host that must be used to attach the storage, using the get method of the hosts collection.
    h = api.hosts.get(name="Atlantic")
  3. Define the Storage parameters for the NFS storage domain. In this example the NFS location 192.0.43.10/storage/data is being used.
    s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
  4. Request creation of the storage domain, using the add method of the storagedomains collection. In addition to the Storage parameters it is necessary to pass:
    • A name for the storage domain.
    • The data center object that was retrieved from the datacenters collection.
    • The host object that was retrieved from the hosts collection.
    • The type of storage domain being added (data, iso, or export).
    • The storage format to use (v1, v2, or v3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="HOST", 
               username="USER", 
               password="PASS",
               ca_file="ca.crt")

    dc = api.datacenters.get(name="Default")
    h = api.hosts.get(name="Atlantic")

    s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
    sd_params = params.StorageDomain(name="data1", data_center=dc, host=h, type_="data", storage_format="v3", storage=s)

    try:
        sd = api.storagedomains.add(sd_params)
        print "Storage Domain '%s' added (%s)." % (sd.get_name())
    except Exception as ex:
        print "Adding storage domain failed: %s" % ex

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the add method call is successful then the script will output:
Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).

4.9. Example: Creating NFS ISO Storage using Python

To create a virtual machine you must be able to provide installation media for the guest operating system. In a Red Hat Enterprise Virtualization Environment you store the installation media on an ISO storage domain.

Note

The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.

Example 4.8. Creating NFS ISO storage using Python

This Python example adds an NFS ISO domain to the storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
  1. Identify the data center to which the storage must be attached, using the get method of the datacenters collection.
    dc = api.datacenters.get( name="Default" )
  2. Identify the host that must be used to attach the storage, using the get method of the hosts collection.
    h = api.hosts.get(name="Atlantic")
  3. Define the Storage parameters for the NFS storage domain. In this example the NFS location 192.0.43.10/storage/iso is being used.
    s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
  4. Request creation of the storage domain, using the add method of the storagedomains collection. In addition to the Storage parameters it is necessary to pass:
    • A name for the storage domain.
    • The data center object that was retrieved from the datacenters collection.
    • The host object that was retrieved from the hosts collection.
    • The type of storage domain being added (data, iso, or export).
    • The storage format to use (v1, v2, or v3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="HOST", 
               username="USER", 
               password="PASS",
               ca_file="ca.crt")

    dc = api.datacenters.get(name="Default")
    h = api.hosts.get(name="Atlantic")

    s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
    sd_params = params.StorageDomain(name="iso1", data_center=dc, host=h, type_="iso", storage_format="v3", storage=s)

    try:
        sd = api.storagedomains.add(sd_params)
        print "Storage Domain '%s' added (%s)." % (sd.get_name())
    except Exception as ex:
        print "Adding storage domain failed: %s" % ex

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the add method call is successful then the script will output:
Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).

4.10. Example: Attaching Storage Domains to a Data Center using Python

Once you have added storage domains to Red Hat Enterprise Virtualization you must attach them to a data center and activate them before they will be ready for use.

Example 4.9. Attaching storage domains to a data center using Python

This Python example attaches a data storage domain named data1, and an ISO storage domain named iso1 to the default data center. The attach action is facilitated by the add method of the data center's storagedomains collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="HOST", 
               username="USER", 
               password="PASS",
               ca_file="ca.crt")

    dc = api.datacenters.get(name="Default")

    sd_data = api.storagedomains.get(name="data1")
    sd_iso = api.storagedomains.get(name="iso1")

    try:
        dc_sd = dc.storagedomains.add(sd_data)
        print "Attached data storage domain '%s' to data center '%s' (Status: %s)." % 
		      (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state())
    except Exception as ex:
        print "Attaching data storage domain to data center failed: %s." % ex

    try:
        dc_sd = dc.storagedomains.add(sd_iso)
        print "Attached ISO storage domain '%s' to data center '%s' (Status: %s)." % 
		      (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state())
    except Exception as ex:
        print "Attaching ISO storage domain to data center failed: %s." % ex

    api.disconnect()
    
except Exception as ex:
    print "Unexpected error: %s" % ex
If the calls to the add methods are successful then the script will output:
Attached data storage domain 'data1' to data center 'Default' (Status: maintenance).
Attached ISO storage domain 'iso1' to data center 'Default' (Status: maintenance).
Note that the status reflects that the storage domains still need to be activated.

4.11. Example: Activating Storage Domains using Python

Once you have added storage domains to Red Hat Enterprise Virtualization and attached them to a data center you must activate them before they will be ready for use.

Example 4.10. Activating storage domains using Python

This Python example activates a data storage domain named data1, and an ISO storage domain named iso1. Both storage domains are attached to the Default data center. The activate action is facilitated by the activate method of the storage domain.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST", 
              username="USER", 
              password="PASS",
              ca_file="ca.crt")

    dc = api.datacenters.get(name="Default")

    sd_data = dc.storagedomains.get(name="data1")
    sd_iso = dc.storagedomains.get(name="iso1")

    try:
        sd_data.activate()
        print "Activated data storage domain '%s' in data center '%s' (Status: %s)." % 
		      (sd_data.get_name(), dc.get_name, sd_data.get_status().get_state())
    except Exception as ex:
        print "Activating data storage domain in data center failed: %s." % ex

    try:
        sd_iso.activate()
        print "Activated ISO storage domain '%s' in data center '%s' (Status: %s)." % 
		      (sd_iso.get_name(), dc.get_name, sd_iso.get_status().get_state())
    except Exception as ex:
        print "Activating ISO storage domain in data center failed: %s." % ex

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the activate requests are successful then the script will output:
Activated data storage domain 'data1' in data center 'Default' (Status: active).
Activated ISO storage domain 'iso1' in data center 'Default' (Status: active).
Note that the status reflects that the storage domains have been activated.

4.12. Example: Creating a Virtual Machine using Python

Virtual machine creation is performed in several steps. The first step, covered here, is to create the virtual machine object itself.

Example 4.11. Creating a virtual machine using Python

This Python example creates a virtual machine named vm1. The virtual machine in this example:
  • Must have 512 MB of memory, expressed in bytes.
    vm_memory = 512 * 1024 * 1024
  • Must be attached to the Default cluster, and therefore the Default data center.
    vm_cluster = api.clusters.get(name="Default")
  • Must be based on the default Blank template.
    vm_template = api.templates.get(name="Blank")
  • Must boot from the virtual hard disk drive.
    vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])
These options are combined into a virtual machine parameter object, before using the add method of the vms collection to create the virtual machine itself.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST",
              username="USER",
              password="PASS",
              ca_file="ca.crt")

    vm_name = "vm1"
    vm_memory = 512 * 1024 * 1024
    vm_cluster = api.clusters.get(name="Default")
    vm_template = api.templates.get(name="Blank")
    vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])

    vm_params = params.VM(name=vm_name,
                         memory=vm_memory,
                         cluster=vm_cluster,
                         template=vm_template)
                         os=vm_os)

    try:
        api.vms.add(vm=vm_params)
        print "Virtual machine '%s' added." % vm_name
    except Exception as ex:
        print "Adding virtual machine '%s' failed: %s" % (vm_name, ex)

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Virtual machine 'vm1' added.

4.13. Example: Creating a Virtual Machine NIC using Python

To ensure a newly created virtual machine has network access you must create and attach a virtual NIC.

Example 4.12. Creating a virtual machine NIC using Python

This Python example creates an NIC named nic1 and attaches it to the virtual machine named vm1. The NIC in this example:
  • Must be a virtio network device.
    nic_interface = "virtio"
  • Must be linked to the rhevm management network.
    nic_network = api.networks.get(name="rhevm")
These options are combined into an NIC parameter object, before using the add method of the virtual machine's nics collection to create the NIC.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="HOST",
               username="USER", 
               password="PASS",
               ca_file="ca.crt")

    vm = api.vms.get(name="vm1")

    nic_name = "nic1"
    nic_interface = "virtio"
    nic_network = api.networks.get(name="rhevm")

    nic_params = params.NIC(name=nic_name, interface=nic_interface, network=nic_network)

    try:
        nic = vm.nics.add(nic_params)
        print "Network interface '%s' added to '%s'." % (nic.get_name(), vm.get_name())
    except Exception as ex:
        print "Adding network interface to '%s' failed: %s" % (vm.get_name(), ex)

    api.disconnect()
              
except Exception as ex:
    print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Network interface 'nic1' added to 'vm1'.

4.14. Example: Creating a Virtual Machine Storage Disk using Python

To ensure a newly created virtual machine has access to persistent storage you must create and attach a disk.

Example 4.13. Creating a virtual machine storage disk using Python

This Python example creates an 8 GB virtio disk drive and attaches it to the virtual machine named vm1. The disk in this example:
  • must be stored on the storage domain named data1,
    disk_storage_domain = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")])
  • must be 8 GB in size,
    disk_size = 8*1024*1024
  • must be a system type disk (as opposed to data),
    disk_type = "system"
  • must be virtio storage device,
    disk_interface = "virtio"
  • must be stored in cow format, and
    disk_format = "cow"
  • must be marked as a usable boot device.
    disk_bootable = True
These options are combined into a disk parameter object, before using the add method of the virtual machine's disks collection to create the disk itself.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="https://HOST",
               username="USER",
               password="PASS",
               ca_file="ca.crt")

    vm = api.vms.get(name="vm1")


    sd = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")])
    disk_size = 8*1024*1024
    disk_type = "system"
    disk_interface = "virtio"
    disk_format = "cow"
    disk_bootable = True

    disk_params = params.Disk(storage_domains=sd,
                              size=disk_size,
                              type_=disk_type,
                              interface=disk_interface,
                              format=disk_format,
                              bootable=disk_bootable)

    try:
        d = vm.disks.add(disk_params)
        print "Disk '%s' added to '%s'." % (d.get_name(), vm.get_name())
    except Exception as ex:
        print "Adding disk to '%s' failed: %s" % (vm.get_name(), ex)

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Disk 'vm1_Disk1' added to 'vm1'.

4.15. Example: Attaching an ISO Image to a Virtual Machine using Python

To begin installing a guest operating system on a newly created virtual machine you must attach an ISO file containing the operating system installation media.

Example 4.14. Identifying ISO images

ISO images are found in the files collection attached to the ISO storage domain. This example lists the contents of the files collection on an ISO storage domain.
from ovirtsdk.api import API 
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST",
              username="USER",
              password="PASS",
              ca_file="ca.crt")

    sd = api.storagedomains.get(name="iso1")
    iso = sd.files.list()

    for i in iso:
        print "%s" % i.get_name()
		
except Exception as ex:
    print "Unexpected error: %s"
If successful the script will output an entry like this for each file found in the files collection:
RHEL6.3-Server-x86_64-DVD1.iso
Note that because files on the ISO domain must be uniquely named the id and name attributes of the file are shared.

Example 4.15. Attaching an ISO image to a virtual machine using Python

This Python example attaches the RHEL6.3-Server-x86_64-DVD1.iso ISO image file to the vm1 virtual machine. Once identified the image file is attached using the add method of the virtual machine's cdroms collection.
from ovirtsdk.api import API 
from ovirtsdk.xml import params

try:
    api = API(url="HOST",
              username="USER",
              password="PASS")

    sd = api.storagedomains.get(name="iso1")

    cd_iso = sd.files.get(name="RHEL6.3-Server-x86_64-DVD1.iso")
    cd_vm = api.vms.get(name="vm1")
    cd_params = params.CdRom(vm=cd_vm, file=cd_iso)

    try:
        cd_vm.cdroms.add(cd_request)
        print "Attached CD to '%s'." % cd_vm.get_name()
    except Exception as ex:
        print "Failed to attach CD to '%s': %s" % (cd_vm.get_name(), ex)

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Attached CD to 'vm1'.

4.16. Example: Starting a Virtual Machine using Python

Starting a virtual machine

Example 4.16. Starting a virtual machine using Python

This example starts the virtual machine using the start method.
from ovirtsdk.api import API 
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST",
              username="USER",
              password="PASS",
              ca_file="ca.crt")

    vm = api.vms.get(name="vm1")

    try:
        vm.start()
        print "Started '%s'." % vm.get_name()
    except Exception ex:
        print "Unable to start '%s': %s" % (vm.get_name(), ex)

    api.disconnect()

except Exception as ex:
    print "Unexpected error: %s" % ex
If the start request is successful then the script will output:
Started 'vm1'.
Note that the status reflects that the virtual machine has been started and is now up.

4.17. Example: Checking System Events using Python

Red Hat Enterprise Virtualization Manager records and logs many system events. These event logs are accessible through the user interface, the system log files, and using the API. The ovirtsdk library exposes events using the events collection.

Example 4.17. Checking System Events using Python

In this example the events collection is listed. Note that:
  • The query parameter of the list method is used to ensure that all available pages of results are returned. By default the list method will only return the first page of results which defaults to a maximum of 100 records in length.
  • The resultant list is reversed to ensure that events are included in the output in the order that they occurred.
from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API (url="https://HOST", 
               username="USER", 
               password="PASS",
               ca_file="ca.crt")

    event_list = []
    event_page_index = 1
    event_page_current = api.events.list(query="page %s" % event_page_index)

    while(len(event_page_current) != 0):
        event_list = event_list + event_page_current
        event_page_index = event_page_index + 1
		try:
            event_page_current = api.events.list(query="page %s" % event_page_index)
	    except Exception as ex:
		    print "Error retrieving page %s of list: %s" % (event_page_index, ex)

    event_list.reverse()

    for event in event_list:
        print "%s %s CODE %s - %s" % (event.get_time(),
                                      event.get_severity().upper(),
                                      event.get_code(),
                                      event.get_description())

except Exception as ex:
    print "Unexpected error: %s" % ex
Output from this script will look like this - albeit with different events depending on the state of the environment:
2012-09-25T18:40:10.065-04:00 NORMAL CODE 30 - User admin@internal logged in.
2012-09-25T18:40:10.368-04:00 NORMAL CODE 153 - VM vm1 was started by admin@internal (Host: Atlantic).
2012-09-25T18:40:10.470-04:00 NORMAL CODE 30 - User admin@internal logged in.

Part II. REST Application Programming Interface

Table of Contents

5. Entry Point
5.1. Product Information
5.2. Link elements
5.3. Special object elements
5.4. Summary element
5.5. RESTful Service Description Language (RSDL)
6. Compatibility Level Versions
7. Capabilities
7.1. Version-Dependent Capabilities
7.2. Current Version
7.3. Features
7.4. CPUs
7.5. Power Managers
7.6. Fence Types
7.7. Storage Types
7.8. Storage Domain Types
7.9. Virtual Machine Types
7.10. Boot Devices
7.11. Display Types
7.12. NIC Interface Types
7.13. OS Types
7.14. Disk Formats
7.15. Disk Interfaces
7.16. Virtual Machine Affinities
7.17. Custom Properties
7.18. Boot Protocols
7.19. Error Handling
7.20. Storage Formats
7.21. Virtual Machine Device Types
7.22. Gluster Volume Types
7.23. Gluster Transport Types
7.24. Guster Acces Protocols
7.25. Resource Status States
7.26. Permits
7.27. Scheduling Policies
8. Common Features
8.1. Representations
8.2. Collections
8.3. Resources
9. Data Centers
9.1. Storage Domains Sub-Collection
9.2. Quotas Sub-Collection
9.3. Force Remove Action
10. Host Clusters
10.1. Networks Sub-Collection
10.2. Red Hat Storage Volumes Sub-Collection
11. Networks
12. Storage Domains
12.1. Storage types
12.2. Export Storage Domains
12.3. Files Sub-Collection
12.4. Import Existing Storage Domain
12.5. Delete Storage Domain
13. Hosts
13.1. Power Management
13.2. Memory Management
13.3. Network Interface Sub-Collection
13.4. Storage Sub-Collection
13.5. Statistics Sub-Collection
13.6. Actions
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. Statistics Sub-Collection
14.6. Actions
15. Floating Disks
15.1. Floating Disk Statistics
16. Templates
16.1. Export Action
17. Virtual Machine Pools
18. Domains
18.1. Domain Users Sub-Collection
18.2. Domain Groups Sub-Collection
19. Roles
19.1. Permits Sub-Collection
20. Groups
21. Users
22. Tags
22.1. Associating Tags With a Host, User or VM
22.2. Parent Tags
23. Events
23.1. Searching Events
23.2. Paginating Events

Chapter 5. Entry Point

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

Example 5.1. Accessing the API Entry Point

If the host is www.example.com and the base is /api, the entry point appears with the following request:
GET /api HTTP/1.1
Accept: application/xml
Host: www.example.com
Authorization: [base64 encoded credentials]

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

<api>
    <link rel="hosts" href="/api/hosts"/>
    <link rel="vms" href="/api/vms"/>
    ...
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="1" major="3"/>
    </product_info>    
    <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: and Authorization: request headers and assume the base is the default /api path. This base path differs depending on your implementation.

5.1. Product Information

The entry point contains a product_info element to help an API user determine the legitimacy of the Red Hat Enterprise Virtualization environment. This includes the name of the product, the vendor and the version.

Example 5.2. Verify a genuine Red Hat Enterprise Virtualization environment

The follow elements identify a genuine Red Hat Enterprise Virtualization 3.1 environment:
<api>
    ...
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="1" major="3"/>
    </product_info>
    ...
</api>

5.2. Link elements

Access to the Entry Point provides link elements and URIs for all of the resource collections the API exposes. Each collection uses a relation type to identify the URI a client needs.

Table 5.1. Available Relationship Types

Relationship Description
capabilities 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.
disks Virtual machine disks.
templates Templates.
vmpools Virtual machine pools.
domains Identity service domains.
groups Imported identity service groups.
roles Roles.
users Users.
tags Tags.
events Events.

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

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


Note

All URIs shown in example responses are illustrative. The format of all URIs returned by the server is opaque. Clients navigate to specific resources through the entry point URI and use the relationship types to access the URIs.
The server chooses to include absolute URIs or absolute paths [3] in the link element's href attribute, so clients are required to handle either form.
The link elements also contain a set of search URIs for certain collections. These URIs use URI templates [4] to integrate search queries. 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 access them with a URI template library.
Each search query URI template is identified with a relation type using the convention "collection/search".

Table 5.2. Relationships associated with search query URIs

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.
disks/search Query disks.
templates/search Query templates.
vmpools/search Query virtual machine pools.
events/search Query events.
users/search Query users.

5.3. Special object elements

Special object elements define relationships to special fixed resources within the virtualization environment.

Table 5.3. Special Objects

Relationship Description
templates/blank The default blank virtual machine template for your virtualization environment. This template exists in every cluster as opposed to a standard template, which only exists in a single cluster.
tags/root The root tag that acts as a base for tag hierarchy in your virtualization environment.

5.4. Summary element

The summary element shows a high level summary of the system's statistics.

Table 5.4. Summary 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.

5.5. RESTful Service Description Language (RSDL)

RESTful Service Description Language (RSDL) provides a description of the structure and elements in the the REST API in one whole XML specification. Invoke the RSDL using the following request.
GET /api?rsdl HTTP/1.1
Accept: application/xml
This produces an XML document in the following format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
    <description>...</description>
    <version major="3" minor="1" build="0" revision="0"/>
    <schema href="/api?schema" rel="schema">
        <name>...</name>
        <description>...</description>
    </schema>
    <links>
        <link href="/api/capabilities" rel="get">
            ...
        </link>
        ...
    </links>
</rsdl>

Table 5.5. RSDL Structure Elements

Element Description
description A plain text description of the RSDL document.
version The API version, including major release, minor release, build and revision.
schema A link to the XML schema (XSD) file.
links Defines each link in the API.

Each link element contains the following a structure:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
    ...
    <links>
        <link href="/api/..." rel="...">
            <request>
                <http_method>...</http_method>
                <headers>
                    <header>
                        <name>...</name>
                        <value>...</value>
                    </header>
                    ...
                </headers>
                <body>
                    <type>...</type>
                    <parameters_set>
                        <parameter required="..." type="...">
                            <name>...</name>
                        </parameter>
                        ...
                    </parameters_set>
                </body>
            </request>
            <response>
                <type>...</type>
            </response>
        </link>
        ...
    </links>
</rsdl>

Table 5.6. RSDL Link Structure Elements

Element Description
link A URI for API requests. Includes a URI attribute (href) and a relationship type attribute (rel).
request Defines the request properties required for the link.
http_method The method type to access this link. Includes the standard HTTP methods for REST API access: GET, POST, PUT and DELETE.
headers Defines the headers for the HTTP request. Contains a series of header elements, which each contain a header name and value to define the header.
body Defines the body for the HTTP request. Contains a resource type and a parameter_set, which contains a sets of parameter elements with attributes to define whether they are required for a request and the data type. The parameter element also includes a name element to define the Red Hat Enterprise Virtualization Manager property to modify and also a further parameter_set subset if type is set to collection.
response Defines the output for the HTTP request. Contains a type element to define the resource structure to output.

Use the RSDL in your applications as a method to map all links and parameter requirements for controlling a Red Hat Enterprise Virtualization environment.


[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 6. Compatibility Level Versions

Each host connected to Red Hat Enterprise Virtualization Manager contains a version of VDSM. VDSM is the agent within the virtualization infrastructure that runs on a hypervisor or host and provides local management for virtual machines, networks and storage. Red Hat Enterprise Virtualization Manager controls hypervisors and hosts using current or older versions of VDSM.
The Manager migrates virtual machines 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.
The API represents this concept as a compatibility level for each host, corresponding to the version of VDSM installed. A version element contains major and minor attributes, which describe the compatibility level.
When an administrator upgrades all hosts within a cluster to a certain level, the version level appears under a supported_versions element. This indicates the cluster's version is now updatable to that level. Once the administrator updates all clusters within a data center to a given level, the data center is updatable to that level.

Example 6.1. Upgrading compatibility levels

The API reports the following compatibility levels for Red Hat Enterprise Virtualization Manager 3.0 instance:
<host ...>
    ...
    <version major="3" minor="0"/>
    ...
</host>

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

<data_center ...>
    ...
    <version major="3" minor="0"/>
    <supported_versions/>
    ...
</data_center>
All hosts within a cluster are updated to VDSM 3.1 and the API reports:
<host ...>
    ...
    <version major="3" minor="1"/>
    ...
</host>

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

<data_center ...>
    ...
    <version major="3" minor="0"/>
    <supported_versions/>
    ...
</data_center>
The cluster is now updatable to 3.1. When the cluster is updated, the API reports:
<cluster ...>
    ...
    <version major="3" minor="1"/>
    <supported_versions/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="0"/>
    <supported_versions>
        <version major="3" minor="1"/>
    </supported_versions>
    ...
</data_center>
The API user updates the data center to 3.1. Once upgraded, the API exposes features available in Red Hat Enterprise Virtualization 3.1 for this data center.

Chapter 7. Capabilities

The capabilities collection provides information about the supported capabilities of a Red Hat Enterprise Virtualization Manager version. 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 5, Entry Point).

7.1. Version-Dependent Capabilities

The capabilities element contains any number of version elements that describe capabilities dependent on a compatibility 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.1 and 3.0 respectively:
<capabilities>
    <version major="3" minor="1">
        ...
    </version>
    <version major="3" minor="0">
        ...
    </version>
    ...
</capabilities>
Each version contains a series of capabilities dependent on the version specified.

7.2. 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="1">
        ...
        <current>true</current>
        ...
    </version>
</capabilities>

7.3. Features

Each version contains a list of compatible features.

Table 7.1. Feature Types

Feature Element Type Description
transparent_hugepages Boolean: true or false Defines the availability of Transparent Hugepages for hosts.

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

7.4. 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 is migratable to any host within the cluster.
Red Hat Enterprise Virtualization has a set of supported CPU types to choose from when configuring a cluster.

Table 7.2. CPU 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.

<capabilities>
    <version major="3" minor="1">
        ...
        <cpus>
            <cpu id="Intel Conroe Family">
                <level>3</level>
            </cpu>
            <cpu id="Intel Penryn Family">
                <level>4</level>
            </cpu>
            ...
        </cpus>
        ...
    </version>
</capabilities>

7.5. Power Managers

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

Table 7.3. Power Management 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="1">
        ...
        <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.6. Fence Types

The fence_types element defines fence_type options to fence a host and reduce power usage.
<capabilities>
    <version major="3" minor="1">
        ...
        <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.7. Storage Types

The storage_types element defines the available physical storage_type options.
<capabilities>
    <version major="3" minor="1">
        ...
        <storage_types>
            <storage_type>iscsi</storage_type>
            <storage_type>fcp</storage_type>
            <storage_type>nfs</storage_type>
            <storage_type>localfs</storage_type>
            <storage_type>posixfs</storage_type>
        </storage_types>
        ...
    </version>
</capabilities>

7.8. Storage Domain Types

The storage_domain_types element shows the available storage_domain_type options in a virtualization environment.
<capabilities>
    <version major="3" minor="1">
        ...
        <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.9. 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="1">
        ...
        <vm_types>
            <vm_type>desktop</vm_type>
            <vm_type>server</vm_type>
        </vm_types>
        ...
    </version>
</capabilities>

7.10. Boot Devices

Each virtual machine boots from a selected device. The boot_devices element lists such boot_device options.
<capabilities>
    <version major="3" minor="1">
        ...
        <boot_devices>
            <boot_device>cdrom</boot_device>
            <boot_device>hd</boot_device>
            <boot_device>network</boot_device>
        </boot_devices>
        ...
    </version>
</capabilities>

7.11. 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="1">
        ...
        <display_types>
            <display_type>vnc</display_type>
            <display_type>spice</display_type>
        </display_types>
        ...
    </version>
</capabilities>

7.12. NIC Interface Types

A virtual machine requires a network interface to connect to a network. The nic_interfaces element defines the supported NIC types available. Each nic_interface 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="1">
        ...
        <nic_interfaces>
            <nic_interface>e1000</nic_interface>
            <nic_interface>virtio</nic_interface>
            <nic_interface>rtl8139</nic_interface>
            <nic_interface>rtl8139_virtio</nic_interface>
        </nic_interfaces>
        ...
    </version>
</capabilities>

7.13. OS Types

Each virtual machine contains an os_type value to define the virtual machine operating system. The default is unassigned.
<capabilities>
    <version major="3" minor="1">
        ...
        <os_types>
            <os_type>unassigned</os_type>
            <os_type>windows_xp</os_type>
            <os_type>windows_2003</os_type>
            <os_type>windows_2008</os_type>
            <os_type>other_linux</os_type>
            <os_type>other</os_type>
            <os_type>rhel_5</os_type>
            <os_type>rhel_4</os_type>
            <os_type>rhel_3</os_type>
            <os_type>windows_2003x64</os_type>
            <os_type>windows_7</os_type>
            <os_type>windows_7x64</os_type>
            <os_type>rhel_5x64</os_type>
            <os_type>rhel_4x64</os_type>
            <os_type>rhel_3x64</os_type>
            <os_type>windows_2008x64</os_type>
            <os_type>windows_2008r2x64</os_type>
            <os_type>rhel_6</os_type>
            <os_type>rhel_6x64</os_type>
        <os_types>
        ...
    </version>
</capabilities>

7.14. 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="1">
        ...
        <disk_formats>
            <disk_format>cow</disk_format>
            <disk_format>raw</disk_format>
        </disk_formats>
        ...
    </version>
</capabilities>

7.15. Disk Interfaces

The disk_interfaces element lists disk_interface options for emulated protocols to interface with virtual disks.
<capabilities>
    <version major="3" minor="1">
        ...
        <disk_interfaces>
            <disk_interface>ide</disk_interface>
            <disk_interface>virtio</disk_interface>
        </disk_interfaces>
        ...
    </version>
</capabilities>

7.16. 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="1">
        ...
        <vm_affinities>
            <affinity>migratable</affinity>
            <affinity>user_migratable</affinity>
            <affinity>pinned</affinity>
        </vm_affinities>
        ...
    </version>
</capabilities>

7.17. 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="1">
        ...
        <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.18. Boot Protocols

The boot_protocol element lists each possible IP assignment boot_protocol for hosts when booting.
<capabilities>
    <version major="3" minor="1">
        ...
        <boot_protocols>
            <boot_protocol>dhcp</boot_protocol>
            <boot_protocol>static</boot_protocol>
            <boot_protocol>none</boot_protocol>
        </boot_protocols>
        ...
    </version>
</capabilities>

7.19. 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="1">
        ...
        <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.20. Storage Formats

The storage_formats element lists the available format versions for storage meta-data.
<capabilities>
    <version major="3" minor="1">
        ...
        <storage_formats>
            <format>v1</format>
            <format>v2</format>
            <format>v3</format>
        </storage_formats>
        ...
    </version>
</capabilities>

7.21. Virtual Machine Device Types

The vm_device_types element lists the available devices on the virtual machine.
<capabilities>
    <version major="3" minor="1">
        ...
        <vm_device_types>
            <vm_device_types>floppy</vm_device_types>
            <vm_device_types>cdrom</vm_device_types>
        </vm_device_types>
        ...
    </version>
</capabilities>

7.22. Gluster Volume Types

The gluster_volume_types element lists the available type of Gluster volumes.
<capabilities>
    <version major="3" minor="1">
        ...
        <gluster_volume_types>
            <gluster_volume_type>DISTRIBUTE</gluster_volume_types>
            <gluster_volume_types>REPLICATE</gluster_volume_types>
            ...
        </gluster_volume_types>
        ...
    </version>
</capabilities>

7.23. Gluster Transport Types

The transport_types element lists the available transport types for Gluster volumes.
<capabilities>
    <version major="3" minor="1">
        ...
        <transport_types>
            <transport_type>TCP</transport_type>
            <transport_type>RDMA</transport_type>
        </transport_types>
        ...
    </version>
</capabilities>

7.24. Guster Acces Protocols

The access_protocols element lists the available access protocols for Gluster volumes.
<capabilities>
    <version major="3" minor="1">
        ...
        <access_protocols>
            <access_protocol>GLUSTER</access_protocol>
            <access_protocol>NFS</access_protocol>
            <access_protocol>CIFS</access_protocol>
        </access_protocols>
        ...
    </version>
</capabilities>

7.25. Resource Status States

Each version contains a set of states for resource statuses. These resource status elements include creation_states, power_management_states, host_states, host_non_operational_details, network_states, storage_domain_states, template_states, vm_states, vm_pause_details, disk_states, host_nic_states, data_center_states, gluster_volume_states and brick_states.

7.26. Permits

Permits are allowable actions a user assigns to a role. Each permit contains a set of properties.

Table 7.4. Permit properties

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.27. 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>

Chapter 8. Common Features

This chapter examines features common to resources and collections.

Note

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. Include these elements in a client-provided representation on update only if their values are not altered by the API user. If altered, the API reports an error.
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="/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="/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprise Linux 6 Virtual Machine</description>
    ...
</vm>
All resource representations contain a set of common attributes

Table 8.2. Common attributes to resource representations

Attribute Type Description Properties
id GUID Each resource in the virtualization infrastructure contains an id, which acts as a globally unique identifier (GUID). The GUID is the primary method of resource identification.
href string The canonical location of the resource as an absolute path.

All resource representations contain a set of common elements.

Table 8.3. Common elements to resource representations

Element Type Description Properties
name string A user-supplied human readable name for the resource. The name is unique across all resources of its type.
description string A free-form user-supplied human readable description of the resource.

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 /api/collection HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
    <resource id="resource_id" href="/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
    ...
</collection>
Use an optional max URL parameter to limit the list of results.
GET /api/collection;max=1 HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/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

The API extends collection representations to include sub-collections when the Accept header includes the detail parameter.
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
This includes multiple sub-collection requests using either separated detail parameters:
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
Or one detail parameter that separates the sub-collection with the + operator:
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
The API supports extended sub-collections for the following main collections.

Table 8.4. Collections that use extended sub-collections

Collection Extended Sub-Collection Support
hosts statistics
vms statistics, nics, disks

Example 8.1. A request for extended statistics, nics and disks sub-collections in the vms collection

GET /api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks

8.2.3.  Searching Collections with Queries

A GET request on a "collection/search" link results in a search query of that collection. The API only returns resources within the collection that satisfy the search query constraints.
GET /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="/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>

8.2.3.1. Query Syntax

The API uses the URI templates to perform a search query with a GET request:
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
The query template value refers to the search query the API directs to the collection. This query uses the same format as Red Hat Enterprise Virtualization Query Language:
(criteria) [sortby (element) asc|desc]
The sortby clause is optional and only needed when ordering results.

Table 8.5. Example search queries

Collection Criteria Result
hosts vms.status=up Displays a list of all hosts running virtual machines that are up.
vms domain=qa.company.com Displays a list of all virtual machines running on the specified domain.
vms users.name=mary Displays a list of all virtual machines belonging to users with the username mary.
events severity>normal sortby time Displays the list of all events with severity higher than normal and sorted by the time element values.
events severity>normal sortby time desc Displays the list of all events with severity higher than normal and sorted by the time element values in descending order.

The API requires the query template to be URL-encoded to translate reserved characters, such as operators and spaces.

Example 8.2. URL-encoded search query

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

Important

Some queries for enumerated values require translation to values used in Red Hat Enterprise Virtualization Query Language. For more information, see Appendix C, Enumerated Value Translation.

8.2.3.2. Case Sensitivity

All search queries are case sensitive by default. The URL syntax provides a Boolean option to toggle case sensitivity.

Example 8.3. Case insensitive search query

GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml

8.2.3.3. Wildcards

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

Example 8.4. Wildcard search query for name=vm*

GET /api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
This query would result in all virtual machines with names beginning with vm, such as vm1, vm2, vma or vm-webserver.

Example 8.5. Wildcard search query for name=v*1

GET /api/vms?search=name%3Dv*1 HTTP/1.1
Accept: 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.2.3.4. Pagination

Some Red Hat Enterprise Virtualization environments contain large collections of resources. However, the API only displays a default number of resources for one search query to a collection. To display more than the default, the API separates collections into pages via a search query containing the page command.

Example 8.6. Paginating resources

This example paginates resources in a collection. The URL-encoded request is:
GET /api/collection?search=page%201 HTTP/1.1
Accept: application/xml
Increase the page value to view the next page of results.
GET /api/collection?search=page%202 HTTP/1.1
Accept: application/xml
Use the page command also in conjunction with other commands in a search query. For example:
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
This query displays the second page in a collection listing ordered by a chosen element.

8.2.4.  Creating a Resource in a Collection

The API creates a new resource with a POST request to the collection URI containing a representation of the new resource.
A POST request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
Each resource type has its own specific required properties. The client supplies these properties as XML elements when creating a new resource. Refer to the individual resource type documentation for more details. If a required property is absent, the creation fails with a fault representation indicating the missing elements.
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

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

<resource id="resource_id" href="/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.2.4.1.  Asynchronous Requests

The API performs asynchronous POST requests unless the user overrides them with an Expect: 201-created header.
For example, certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resource 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 /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

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

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
A GET request to the creation_status link provides a creation status update:
GET /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="/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
Overriding the asynchronous resource creation requires an Expect: 201-created header:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

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

8.3.  Resources

This section examines common features for resources.

8.3.1.  Retrieving a Resource

The API retrieves the state of a resource with a GET request on a URI obtained from a collection listing.
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

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

<resource id="resource_id" href="/api/collection/resource_id">
    ...
</resource>

8.3.2.  Updating a Resource

The API modifies resource properties with a PUT request containing an updated description from a previous GET request for the resource URI. Details on modifiable properties are found in the individual resource type documentation.
A PUT request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
PUT /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="/api/collection/resource_id">
    <name>New-Resource-Name</name>
    ...
</resource>
This does not include immutable resource properties that an API user has attempted to modify. If an attempt is made to modify a strictly immutable resource property, the API reports a 409 Conflict error with a fault representation in the response body.
Properties omitted from the representation are ignored and not changed.
Asynchronous Requests
PUT requests also feature the ability to asynchronously update resources. This means a client can send an update request without waiting for the request to complete. Perform an asynchronous update request with the async URL parameter and an Expect: 202-Accepted header.
PUT /api/collection/resource_id;async HTTP/1.1
Accept: application/xml
Expect: 202-Accepted

8.3.3.  Deleting a Resource

The API deletes a resource with a DELETE request sent to its URI.
DELETE /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 204 No Content
Some cases require optional body content in the DELETE request to specify additional properties. A DELETE request with optional body content requires a Content-Type: application/xml header to inform the API of the XML representation in the body content. If a DELETE request contains no body content, omit the Content-Type: application/xml header.
Asynchronous Requests
DELETE requests also feature the ability to asynchronously delete resources. This means a client can send a delete request without waiting for the request to complete. Perform an asynchronous delete request with the async URL parameter and an Expect: 202-Accepted header.
DELETE /api/collection/resource_id;async HTTP/1.1
Accept: application/xml
Expect: 202-Accepted

8.3.4.  Sub-Collection Relationships

A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or 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.
Sub-collections are used to model the following relationships types:
  • N:M mappings, where one parent resource can contain several child resources and vice versa. For example, a virtual machine can contain several disks and some disks are shared among multiple virtual machines.
  • 1:N mappings, where mapped resources are dependent on a parent resource. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and snapshots.
  • 1:N mappings, where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a cluster and a network.
The API defines a relationship between a resource and a sub-collection using the link rel= attribute:
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

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

<resource id="resource_id" href="/api/collection/resource_id">
    ...
    <link rel="subcollection"
      href="/api/collection/resource_id/subcollection"/>
    ...
</resource>
The API user now queries the sub-collection.
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml

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

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        ...
    </subresource>
    ...
</subcollection>

8.3.5.  XML Element Relationships

XML element links act as an alternative to sub-collections to express relationships between resources. XML element links are simply elements with a "href" attribute that points to the linked element.
XML element links are used to model simple 1:N mappings between resources without a dependency and without data associated with the relationship. For example, the relationship between a host and a cluster.
Examples of such relationships include:
  • Backlinks from a resource in a sub-collection to a parent resource; or
  • Links between resources with an arbitrary relationship.

Example 8.7. Backlinking from a sub-collection resource to a resource using an XML element

GET /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="/api/collection/resource_id/subcollection/subresource_id">
        <resource id="resource_id" href="/api/collection/resource_id"/>
        ...
    </subresource>
</subcollection>

8.3.6.  Actions

Most resources include a list of action links to provide functions not achieved through the standard HTTP methods.
<resource>
    ...
    <actions>
        <link rel="start" href="/api/collection/resource_id/start"/>
        <link rel="stop" href="/api/collection/resource_id/stop"/>
        ...
    </actions>
    ...
</resource>
The API invokes an action with a POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and task-specific parameters.

Table 8.6. Common action parameters

Element Description
async true if the server responds 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.
An action also requires a Content-Type: application/xml header since the POST request requires an XML representation in the body content.
When the action is initiated asynchronously, the immediate 202 Accepted response provides a link to monitor the status of the task:
POST /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="/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.

Table 8.7. Action statuses

Status Description
pending Task has not yet started.
in_progress Task is in operation.
complete Task completed successfully.
failed Task 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 /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="/api/collection/resource_id/action/action_id">
    <status>
        <state>pending</state>
    </status>
    <link rel="parent" /api/collection/resource_id"/>
    <link rel="replay" href="/api/collection/resource_id/action"/>
<action>
An action representation also includes some links that are identified by the rel attribute:

Table 8.8. Action relationships

Type Description
parent A link back to the resource of this action.
replay A link back to the original action URI. POSTing to this URI causes the action to be re-initiated.

8.3.7.  Permissions

Each resource contains a permissions sub-collection. Each permission contains a user, an assigned role and the specified resource. For example:
GET /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="/api/collection/resource_id/permissions/permission_id">
        <role id="role_id" href="/api/roles/role_id"/>
        <user id="user_id" href="/api/users/user_id"/>
        <resource id="resource_id" href="/api/collection/resource_id"/>
    </permission>
    ...
</permissions>
A resource acquires a new permission when an API user sends a POST request with a permission representation and a Content-Type: application/xml header to the resource's permissions sub-collection. Each new permission requires a role and a user:
POST /api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
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="/api/resources/resource_id/permissions/permission_id">
    <role id="role_id" href="/api/roles/role_id"/>
    <user id="user_id" href="/api/users/user_id"/>
    <resource id="resource_id" href="/api/collection/resource_id"/>
</permission>

8.3.8.  Handling Errors

Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a fault representation in the response entity body. The fault contains a reason and detail strings. Clients must accommodate failed requests via extracting the fault or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.
PUT /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

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 5, Entry Point).
The following table shows specific elements contained in a data center resource representation.

Note

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

Table 9.1. Data center elements

Element Type Description Properties
link rel="storagedomains" relationship A link to the sub-collection for storage domains attached to this data center.
link rel="permissions" relationship A link to the sub-collection for data center permissions. See Section 8.3.7, “ Permissions ”.
link rel="quotas" relationship A link to the sub-collection for quotas associated with this data center.
storage_type enumerated Describes the storage type in this datacenter. A list of enumerated values is available in capabilities. See Section 7.7, “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.20, “Storage Formats”.
version major= minor= 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: uninitialized, up, maintenance, not_operational, problematic and contend. These states are listed in data_center_states under capabilities (See Section 7.25, “Resource Status States”).

Example 9.1. An XML representation of a data center

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

Creation of a new data center requires the name, storage_type and version elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 9.2. Creating a data center

POST /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_center>

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

Example 9.3. Updating a data center

PUT /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_center>

Removal of a data center requires a DELETE request.

Example 9.4. Removing a data center

DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1

HTTP/1.1 204 No Content

9.1. Storage Domains Sub-Collection

Each data center contains a sub-collection for attached storages domain. An API user interacts with this sub-collection using the standard REST methods as per Chapter 8, Common Features.
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. States for the status element are listed in storage_domain_states under capabilities (See Section 7.25, “Resource Status States”)

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

9.1.1. Attaching and Detaching a Storage Domain

A data center is only ready for use when at least one storage domain is attached, which an API user POSTs to the data center's storage domains sub-collection.
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.5. Attach a storage domain to a data center

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Accept: application/xml
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="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
  fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>images0</name>
    <type>data</type>
    <status>
        <state>inactive</state>
    </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="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <actions>
        <link rel="activate"
          href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
        <link rel="deactivate"
          href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
    </actions>
</storage_domain>

Detach a storage domain from a data center with a DELETE request. Include an optional async element for this request to be asynchronous.

Example 9.6. Detach a storage domain from a data center

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

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

9.1.2. Actions

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

9.1.2.1.  Activate Action

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

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

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

<action/>

9.1.2.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.8. Action to deactivate a storage domain on a datacenter

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

<action/>

9.2. Quotas Sub-Collection

Important

The information in this section is provided as a technical preview only.
The quotas sub-collection lists restrictions that Red Hat Enterprise Virtualization Manager implements on resources. An API user views this sub-collection and its resources using the GET method as per Chapter 8, Common Features.

Example 9.9. An XML representation of a quota

<quota href="/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c
  /quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe" 
  id="e13ff85a-b2ba-4f7b-8010-e0d057c03dfe">
    <name>MyQuota</name>
    <description>A quota for my Red Hat Enterprise
      Virtualization environment</description>
    <data_center href= "/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c" 
    id="56087282-d7a6-11e1-af44-001a4a400e0c"/>
</quota>

Creation of a new quota requires the name and description elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 9.10. Creating a quota

POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1
Accept: application/xml
Content-type: application/xml

<quota>
    <name>VMQuota</name>
    <description>My new quota for virtual machines</description>
</quota>

Removal of a quota requires a DELETE request.

Example 9.11. Removing a quota

DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe HTTP/1.1

HTTP/1.1 204 No Content

9.3. Force Remove Action

An API user forces the removal of a data center when encountering unresolvable problems with storage domains, such as the loss of connection to a master storage domain or a lack of available hosts when deleting storage domains. The API includes a force action to help with these situations.
This action removes database entries associated with a chosen data center before the API removes the data center from the Red Hat Enterprise Virtualization environment. This means the API removes the data center regardless of associated storage domains.
This action requires a DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.

Example 9.12. Force remove action on a data center

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

<action>
  <force>true</force>
</action>

This action:
  • Deletes all database information for data storage domains associated the data center;
  • Deletes all database information for resources, such as virtual machines and templates, on data storage domains associated the data center;
  • Detaches iso and export storage domains from the data center; and
  • Deletes the database information for the data center.
This action overrides the requirement for a data center to be empty before deletion.

Important

This action only removes the database entries for resources associated with the data center. The data storage domains associated with the data center require manual format before reuse. Metadata for iso and export domains require manual cleaning prior to use on another data center.

Chapter 10. Host Clusters

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 5, Entry Point).
The following table shows specific elements contained in a host cluster resource representation.

Note

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

Table 10.1. Host cluster elements

Element Type Description Properties
link rel="glustervolumes" relationship A link to the sub-collection for Red Hat Storage volumes associated with this cluster.
link rel="networks" relationship A link to the sub-collection for networks associated with this cluster.
link rel="permissions" relationship A link to the sub-collection for cluster permissions. See Section 8.3.7, “ Permissions ”.
cpu id= complex A server CPU reference that defines the CPU type all hosts must support in the cluster. See Section 7.4, “CPUs”.
data_center id= GUID 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 Table 10.2, “Memory policy elements”.
scheduling_policy complex Defines the load-balancing or power sharing modes for hosts in the cluster. See Table 10.3, “Scheduling policy elements”.
version major= minor= 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.19, “Error Handling”.
virt_service Boolean Defines whether to expose virtualization services for this cluster.
gluster_service Boolean Defines whether to expose Red Hat Storage services for this cluster.

The memory_policy element contains the following elements:

Table 10.2. Memory policy elements

Element Type Description Properties
overcommit percent= 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 Section 7.3, “Features”) to ensure your version supports transparent hugepages.

The scheduling_policy element contains the following elements:

Table 10.3. Scheduling policy 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.27, “Scheduling Policies”.
thresholds low= high= duration= 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

<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
  href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
    <name>Default</name>
    <description>The default server cluster</description>
    <link rel="glustervolumes"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes"/>
    <link rel="networks"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
    <link rel="permissions"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
    <cpu id="Intel Penryn Family"/>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/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"<usage> major="3"/>
    </supported_versions>
    <error_handling>
        <on_error>migrate</on_error>
    </error_handling>
    <virt_service>true</virt_service>
    <gluster_service>false</gluster_service>
</cluster>

Creation of a new cluster requires the name, cpu id= and datacenter elements. Identify the datacenter with either the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 10.2. Creating a host cluster

POST /api/clusters 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, cpu id= and error_handling elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

Example 10.3. Updating a host cluster

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

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

Removal of a cluster requires a DELETE request.

Example 10.4. Removing a cluster

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1

HTTP/1.1 204 No Content

10.1.  Networks Sub-Collection

Networks associated with a cluster are represented with the networks sub-collection. Every host within a cluster connects to these associated networks.
The representation of a cluster's network sub-collection is the same as a standard network resource (see Chapter 11, Networks) except for the following additional elements:

Table 10.4. Additional network elements

Element Type Description Properties
cluster id= relationship A reference to the cluster of which this network is a member.
required Boolean Defines required or optional network status.
display Boolean Defines the display network status. Used for backward compatibility.
usages complex Defines a set of usage elements for the network. Users can define networks as VM and DISPLAY networks at this level.

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.5. Associating a network resource with a cluster

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

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <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="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>rhevm</name>
    <status>
        <state>operational</state>
    </status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <required>true</required>
    <usages>
        <usage>VM</usage>
    </usages>
</network>

Update the resource with a PUT request.

Example 10.6. Setting the display network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
    <usages>
        <usage>VM</usage>
        <usage>DISPLAY</usage>
    </usages>
</network>

The required or optional network status is set using a PUT request to specify the Boolean value (true or false) of the required element.

Example 10.7. Setting optional network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
</network>

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

Example 10.8. Removing a network association from a cluster

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

HTTP/1.1 204 No Content

10.2.  Red Hat Storage Volumes Sub-Collection

Important

The information in this section is provided as a technical preview only.
Red Hat Enterprise Virtualization provides a means for creating and managing Red Hat Storage volumes. Red Hat Storage volumes are associated with host clusters and are represented with the glustervolumes sub-collection.

Important

Red Hat Storage 2.0 is required for controlling volumes via Red Hat Enterprise Virtualization.
The representation of a Red Hat Storage volume resource in the glustervolumes sub-collection is defined using the following elements:

Table 10.5. Gluster volume elements

Element Type Description Properties
volume_type enumerated Defines the volume type. See the capabilities collection for a list of volume types.
bricks relationship The sub-collection for the Red Hat Storage bricks. When creating a new volume, the request requires a set of brick elements to create and manage in this cluster. Requires the server_id of the Red Hat Storage server and a brick_dir element for the brick directory
transport_types complex Defines a set of volume transport_type elements. See the capabilities collection for a list of available transport types.
replica_count integer Defines the file replication count for a replicated volume.
stripe_count integer Defines the stripe count for a triped volume
options complex A set of additional Red Hat Storage option elements. Each option includes an option name and a value.

Example 10.9. An XML representation of a Red Hat Storage volume

<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
  href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
  /glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
    <name>GlusterVolume1</name>
    <link rel="bricks"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
      /glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <transport_types>
        <transport_type>TCP</transport_type>
    </transport_types>
    <replica_count>2</replica_count>
    <stripe_count>1</stripe_count>
    <options>
        <option>
            <name>cluster.min-free-disk</name>
            <value>536870912</value>
        </option>
    </options>   
</gluster_volume>

An API user manipulates the glustervolumes sub-collection as described in Chapter 8, Common Features. Create a Red Hat Storage volume via a POST request with the required name, volume_type and bricks to the sub-collection.

Example 10.10. Creating a Red Hat Storage volume

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

<gluster_volume>
    <name>GlusterVolume1</name>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <bricks>
        <brick>
            <server_id>server1</server_id>
            <brick_dir>/exp1</brick_dir>
        </brick>
    <bricks>
</gluster_volume>

Remove a Red Hat Storage volume with a DELETE request.

Example 10.11. Removing a Gluster volume

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1

HTTP/1.1 204 No Content

Important

Resources in the glustervolumes sub-collection cannot be updated.

10.2.1.  Bricks Sub-Collection

The glustervolumes sub-collection contains its own bricks sub-collection to define individual bricks in a Red Hat Storage volume. The representation of a volume's bricks sub-collection is defined using the following elements:

Table 10.6. Brick elements

Element Type Description Properties
server_id string A reference to the Red Hat Storage server.
brick_dir string Defines a brick directory on the Red Hat Storage server.
replica_count integer Defines the file replication count for the brick in the volume.
stripe_count integer Defines the stripe count for the brick in the volume

An API user manipulates the glustervolumes sub-collection as described in Chapter 8, Common Features. Create new bricks via a POST request with the required server_id and brick_dir to the sub-collection.

Example 10.12. Adding a brick

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<brick>
    <server_id>server1</server_id>
    <brick_dir>/exp1</brick_dir>
</brick>

Remove a brick with a DELETE request.

Example 10.13. Removing a brick

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1

HTTP/1.1 204 No Content

Important

Resources in the bricks sub-collection cannot be updated.

10.2.2.  Start Action

The start action makes a Gluster volume available for use.

Example 10.14. Starting a Volume

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>

Use an optional force Boolean element to force the action for a running volume. This is useful for starting disabled brick processes in a running volume.

10.2.3.  Stop Action

The stop action deactivates a Gluster volume.

Example 10.15. Stopping a Volume

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>

Use an optional force Boolean element to brute force the stop action.

10.2.4.  Set Option Action

The setoption action sets a Gluster volume option.

Example 10.16. Set an option

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
    <option>
        <name>cluster.min-free-disk</name>
        <value>536870912</value>
    </option>
<action>

10.2.5.  Reset Option Action

The resetoption action resets a Gluster volume option.

Example 10.17. Reset an option

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
        <option>
            <name>cluster.min-free-disk</name>
        </option>
<action>

10.2.6.  Reset All Options Action

The resetalloptions action resets all Gluster volume options.

Example 10.18. Reset all options

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>

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 5, Entry Point).
The following table shows specific elements contained in a network resource representation.

Note

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

Table 11.1. Network elements

Element Type Description Properties
data_center id= GUID A reference to the data center of which this cluster is a member. See Chapter 9, Data Centers.
vlan id= integer A VLAN tag.
mtu interger Sets the maximum transmission unit for the logical network. If omitted, the logical network uses the default value.
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. These states are listed in network_states under capabilities (See Section 7.25, “Resource Status States”).
usages complex Defines a set of usage elements for the network. Users can define networks as VM networks at this level.

Example 11.1. An XML representation of a network resource

<network id="00000000-0000-0000-0000-000000000009"
  href="/api/networks/00000000-0000-0000-0000-000000000009">
    <name>rhevm</name>
    <description>Management Network</description>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
    <mtu>1500</mtu>
    <stp>false</stp>
    <status>
        <state>operational</status>
    </status>
    <usages>
        <usage>VM</usage>
    </usages>
</network>

Creation of a new network requires the name and datacenter elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 11.2. Creating a network resource

POST /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.2, “ Updating a Resource ” for more information.

Example 11.3. Updating a network resource

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

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

Removal of a network requires a DELETE request.

Example 11.4. Removing a network

DELETE /api/networks/e6575a87-377c-4f67-9c1b-7b94eff76b17 HTTP/1.1

HTTP/1.1 204 No Content

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

Chapter 12. Storage Domains

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 5, Entry Point).
The following table shows specific elements contained in a storage domain resource representation.

Note

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

Table 12.1. Storage domain elements

Element Type Description Properties
link rel="permissions" relationship A link to the sub-collection for storage domain permissions. See Section 8.3.7, “ Permissions ”.
link rel="files" relationship A link to the files sub-collection for this storage domains.
link rel="vms" relationship A link to the vms sub-collection for a storage domain with type set to export.
link rel="templates" relationship A link to the templates sub-collection for a storage domain with type set to export.
type enumerated The storage domain type. A list of enumerated values are available in capabilities. See Section 7.8, “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.20, “Storage Formats”.
storage_domain_state enumerated Defines if the storage domain is currently attached to a data center. A list of enumerated values are available in capabilities.

Example 12.1.  An XML representation of a storage domain

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/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_state>unattached</storage_domain_state>
</storage_domain>

Creation of a new storage domain requires the name, type, host and storage elements. Identify the host element with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 12.2.  Creating a storage domain

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>

Only the name element is updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

Example 12.3.  Updating a storage domain

PUT /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data2</name>
    ...
</storage_domain>

Removal of a storage domain requires a DELETE request.

Example 12.4. Removing a storage domain

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1

HTTP/1.1 204 No Content

The API user attaches the storage domain to a data center after creation. See Section 9.1.1, “Attaching and Detaching a Storage Domain” for instructions.

Important

The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

12.1.  Storage types

The storage element contains a type element, which is an enumerated value found under the capabilities collection. See Section 7.7, “Storage Types”.
The storage element also contains additional elements specific to each storage type. The next few sections examine these additional storage type elements.

12.1.1.  NFS

The following table contains nfs specific elements in a storage description.

Table 12.2. NFS specific elements

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.  PosixFS

The following table contains posixfs specific elements in a storage description.

Table 12.3. PosixFS specific elements

Element Type Description Properties
address string The host name or IP address of the PosixFS server.
path string The path of PosixFS mountable directory on the server.
vfs_type string The Linux-supported file system type of the PosixFS share.
mount_options string The options for mounting the PosixFS share.

12.1.3.  iSCSI and FCP

The following table contains iscsi and fcp specific elements in a storage description.

Table 12.4. iSCSI and FCP specific elements

Element Type Description Properties
logical_unit id= complex The id of the logical unit. A storage domain also accepts multiple iSCSI or FCP logical units.
override_luns Boolean Defines whether to replace all logical unit settings with new settings. Set to true to override.

The logical_unit contains a set of sub-elements.

Table 12.5. Logical unit elements

Element Type Description Properties
address string The address of the server containing the storage device.
port integer The port number of the server.
target string The target IQN for the storage device.
username string A CHAP user name for logging into a target.
password string A CHAP password for logging into a target.
serial string The serial ID for the target.
vendor_id string The vendor name for the target.
product_id string The product code for the target.
lun_mapping integer The Logical Unit Number device mapping for the target.

In the case of iSCSI, if a logical_unit description also contains details of the iSCSI target with the LUN in question, the target performs an automatic login when the storage domain is created.

12.1.4.  LocalFS

The localfs specific elements in a storage description are:

Table 12.6. Localfs specific elements

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

A localfs storage domain requires a data center with storage_type set to localfs (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.  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.

Example 12.5. Listing the virtual machines sub-collection of an export storage domain

GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml

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

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

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.
The import action imports a virtual machine or a template from an export storage domain. The destination cluster and storage domain is specified with cluster and storage_domain references.
Include an optional name element to give the virtual machine or template a specific name.

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

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

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

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

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

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

Include an optional clone Boolean element to import the virtual machine as a new entity.

Example 12.8. Action to import a virtual machine as a new entity

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

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
    <clone>true</clone>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
</action>

Include an optional disks element to choose which disks to import using individual disk id elements.

Example 12.9. Selecting disks for an import action

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

<action>
    <cluster>
        <name>Default</name>
    </cluster>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
    <disks>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/>
    </disks>
</action>

Delete a virtual machine or template from an export storage domain with a DELETE request.

Example 12.10. Delete virtual machine from an export storage domain

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml

HTTP/1.1 204 No Content

12.3.  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.11. Listing the files sub-collection of an ISO storage domain

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

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

<files>
    <file id="en_winxp_pro_with_sp2.iso"
      href="/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="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
    <file id="boot.vfd"
      href="/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="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>

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

12.4.  Import Existing Storage Domain

The 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 the name is not specified.

Example 12.12. Importing an existing export storage domain

POST /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
Content-Type: application/xml

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

12.5.  Delete Storage Domain

A storage_domain reference is passed in the body of a DELETE request for a storage domain. The storage_domain reference is in the following form:
<storage_domain>
    <host id="..."/>
</storage_domain>
OR
<storage_domain>
    <host>
        <name>...</name>
    </host>
</storage_domain>
Format Storage Domain
An API user provides a optional format element to specify whether or not to format the storage domain after deletion.

Example 12.13. Formatting a storage domain after deletion

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

If no format element is passed, the storage domain remains unformatted.
Logical Removal of Storage Domain
The API also provides a function for the logical removal of the storage domain. This retains the storage domain's data for import. Use the destroy element to logically remove the storage domain and retain the data.

Example 12.14. Logical removal of a storage domain

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

Chapter 13. Hosts

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 5, Entry Point).
The following table shows specific elements contained in a host resource representation.

Note

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

Table 13.1. Host elements

Element Type Description Properties
link rel="storage" relationship A link to the storage sub-collection for host storage.
link rel="nics" relationship A link to the nics sub-collection for host network interfaces.
link rel="tags" relationship A link to the tags sub-collection for host tags.
link rel="permissions" relationship A link to the permissions sub-collection for host permissions. See Section 8.3.7, “ Permissions ”.
link rel="statistics" relationship A link to the statistics 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.
certificate complex A reference to the host certificate details, including organization and subject.
status See below The host status.
cluster id= GUID A reference to the cluster that includes this host.
port integer The listen port of the VDSM daemon running on this host.
storage_manager complex Defines an appropriate host to use as the storage pool manager (SPM). Requires a host priority attribute and a Boolean value (true or true).
power_management complex Configuration options for host power management. See Section 13.1, “Power Management”.
ksm Boolean: true or false true if Kernel SamePage Merging (KSM) is enabled.
transparent_hugepages Boolean: true or false true if Transparent Hugepages is enabled.
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=, topology sockets= and speed. The topology cores= aggregates the total cores while the topology sockets= aggregates the total physical CPUs. The total cores available to virtual machines equals the number of sockets multiplied by the cores per socket.
memory integer The total amount of host memory in bytes.
summary complex Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of active, migrating and total VMs.
version major= minor= 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.

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, connecting, reboot, unassigned and up. These states are listed in host_states under capabilities (See Section 7.25, “Resource Status States”).

Example 13.1. An XML representation of a host

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    <actions>
        <link rel="install"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/install"/>
        <link rel="activate"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/activate"/>
        <link rel="fence"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/fence"/>
        <link rel="deactivate"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/deactivate"/>
        <link rel="approve"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/approve"/>
        <link rel="iscsilogin"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsilogin"/>
        <link rel="iscsidiscover"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsidiscover"/>
        <link rel="commitnetconfig"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/commitnetconfig"/>
    </actions>
    <link rel="storage"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage"/>
    <link rel="nics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics"/>
    <link rel="tags"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/tags"/>
    <link rel="permissions"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/permissions"/>
    <link rel="statistics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/statistics"/>
    <type>rhev-h</type>
    <address>host1.example.com</address>
    <status>
        <state>up</state>
    </status>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <port>54321</port>
    <storage_manager priority="2">true</storage_manager>
    <power_management>
        <enabled>false</enabled>
        <options/>
    </power_management>
    <ksm>
        <enabled>true</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" sockets="1"/>
        <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>

Creation of a new host requires the name, address and root_password elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 13.2. Creating a host

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

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

New host creation applies only to the addition of Red Hat Enterprise Linux hosts. Red Hat Enterprise Virtualization Manager detects hypervisor hosts automatically and requires approval for their use.
The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.
The name, name, cluster, power_management, transparent_hugepages and ksm elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

Example 13.3. Updating a host

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

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

Removal of a host requires a DELETE request.

Example 13.4. Removing a host

DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1

HTTP/1.1 204 No Content

13.1. Power Management

The power_management element provides users with the ability to set a power management configuration, which is required for host fencing. Certain sub-elements are required when configuring power_management.

Table 13.2. Power management options

Element Type Description Properties
type= fencing device code A list of valid fencing device codes are available in the capabilities collection. See Section 7.5, “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.5, “Power Managers”).
A new host includes an optional power_management configuration when POSTing to the host resource. The power_management configuration is updatable using a PUT request.

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

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/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 configuration settings for a host's memory management.
Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density. KSM uses the ksm element.

Example 13.6. Setting KSM memory management

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

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <ksm>true</ksm>
</host>

Transparent Hugepage support expands the size of memory pages beyond the standard 4kB limit. This reduces memory consumption and increases host performance. Transparent Hugepage support uses the transparent_hugepages element.

Example 13.7. Setting Transparent Hugepage memory management

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

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <transparent_hugepages>true</transparent_hugepages>
</host>

Availability of Transparent Hugepage support is found in the capabilities collection. See Section 7.3, “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 elements:

Note

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

Table 13.3. Elements for a host's network interfaces

Element Type Description Properties
name string The name of the host network interface, e.g. eth0 [a]
link rel="statistics" relationship A link to the statistics sub-collection for a host's network interface statistics.
link rel="master" relationship A reference to the master bonded interface, if this is a slave interface.
host id= GUID A reference to the host.
network id= GUID A reference to the network, if any, that the interface is attached. [b]
mac address= string The MAC address of the interface.
ip address= netmask= gateway= mtu= complex The IP level configuration of the interface.
mtu complex The maximum transmission unit for the interface.
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.18, “Boot Protocols”.
speed integer The network interface speed in bits per second.
status enumerated The link status for the network interface. These states are listed in host_nic_states under capabilities (See Section 7.25, “Resource Status States”).
vlan id integer The VLAN which this interface represents.
bonding complex A list of options and slave NICs for bonded interfaces. [c]
bridged Boolean Defines the bridged network status. Set to true for a bridged network and true for a bridgeless network.
[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.8. An XML representation of a network interface on a host

<host_nic id="e8f02fdf-3d7b-4135-86e1-1bf185570cd8"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
  e8f02fdf-3d7b-4135-86e1-1bf185570cd8">
    <name>bond0</name>
    <link rel="statistics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
      e8f02fdf-3d7b-4135-86e1-1bf185570cd8/statistics"/>      
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <network id="e657d631-657d-42bb-a536-73501a085d85"
      href="/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"/>
    <mtu>1500</mtu>
    <boot_protocol>dhcp</boot_protocol>
    <speed>1000000000</speed>
    <status>
        <state>up</state>
    </status>
    <bonding>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonding>
    <actions>
        <link rel="attach"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach"/>
        <link rel="detach"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach"/>
    </actions>
    <bridged>true</bridged>
</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 elements using a PUT request.
When adding a new network interface, the name and network elements are required. Identify the network element with the id attribute or name element.
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <name>MyNIC</name>
    <network id="e657d631-657d-42bb-a536-73501a085d85">
        <name>MyNetwork</name>
    </network>
</host_nic>
An API user modifies a network interface with a PUT request.
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <ip address="192.168.0.129" netmask="255.255.255.0" gateway="192.168.0.1"/>
</host_nic>
An API user removes a network interface with a DELETE request.
DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1

HTTP/1.1 204 No Content

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

13.3.1. Bonded Interfaces

A bonded interface is represented as a host_nic resource containing a bonding element.

Table 13.4. Bonded interface 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 id= 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 creating a new host_nic (POST) or updating a host_nic (PUT). Use either the id or name elements identify the slave host_nic elements.

Example 13.9. Creating a bonded interface

POST /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"/>
    <bonding>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonding>
</host_nic>

Important

bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.
Use a DELETE request to a bonded interface URI to delete it.

Important

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

13.3.2. Network Interface Statistics

Each host's network interface exposes a statistics sub-collection for a host's network interface statistics. Each statistic contains the following elements:

Table 13.5. Elements for a host's network interface statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
host_nic id= relationship A relationship to the containing host_nic resource.

The following table lists the statistic types for network interfaces on hosts.

Table 13.6. Host NIC statistic types

Name
Description
data.current.rx
The rate in bytes per second of data received.
data.current.tx
The rate in bytes per second of data transmitted.
errors.total.rx
Total errors from receiving data.
errors.total.tx
Total errors from transmitting data.

Example 13.10. An XML representation of a host's network interface statistics sub-collection

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
      c34728e8-4338-4540-ac9b-86b8582e602e/statistics/
      ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <host_nic id="c34728e8-4338-4540-ac9b-86b8582e602e"
          href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
          c34728e8-4338-4540-ac9b-86b8582e602e"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

13.3.3. Attach Action

A host network interface is attached to a network, indicating the given network is accessible over the interface. Either the id or name elements identify the network.

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

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

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

Important

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

13.3.4. Detach Action

Detach an interface from a network. Either the id or name elements identify the network.

Example 13.12. Action to detach a host network interface from a network

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

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

Important

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

13.3.5. Multiple Network Setup Action

A host's nics collection contains an action to perform setup of multiple network interfaces. Perform a POST request on the setupnetworks action.

Example 13.13. Action to setup multiple host network interfaces

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

<action>
    <host_nics>
        <host_nic id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
            <name>em1</name>
            <network id="00000000-0000-0000-0000-000000000009"/>
            <boot_protocol>dhcp</boot_protocol>
        </host_nic<
        <host_nic id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
            <name>em2</name>
            <network id="00000000-0000-0000-0000-000000000010"/>
            <ip address="10.35.1.247" netmask="255.255.254.0"
              gateway="10.35.1.254"/>
            <boot_protocol>static</boot_protocol>
        </host_nic>
        <checkConnectivity>true</checkConnectivity>
        <connectivityTimeout>60</connectivityTimeout>
        <force>false</false>
    </host_nics>
</action>

This action updates all specified network interface resources with standard NIC elements. The request includes additional elements specified in the following table.

Table 13.7. Additional elements for multiple host network interface setup

Element Type Description Properties
checkConnectivity Boolean Set to true to verify connectivity between the host and the Red Hat Enterprise Virtualization Manager. If the connectivity is lost, Red Hat Enterprise Virtualization Manager reverts the settings.
connectivityTimeout integer Defines the timeout for loss of connectivity.
force Boolean Set to true to force changes even if connectivity is lost.

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 is used to create storage domains, as described in Chapter 12, Storage Domains.
Each storage representation in the sub-collection represents a SCSI LUN.

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

<host_storage>
    <storage id="82fb123b-321e-40a1-9889-95dcd2654463"
      href="/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>
</host_storage>

Note

The host_storage collection is read-only.

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

13.5. Statistics Sub-Collection

Each host resource exposes a statistics sub-collection for host-specific statistics. Each statistic contains the following elements:

Table 13.8. Elements for host statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
host id= relationship A relationship to the containing host resource.

The following table lists the statistic types for hosts.

Table 13.9. Host statistic types

Name
Description
memory.total
Total memory in bytes on the host.
memory.used
Memory in bytes used on the host.
memory.free
Memory in bytes free on the host.
memory.buffers
I/O buffers in bytes.
memory.cached
OS caches in bytes.
swap.total
Total swap memory in bytes on the host.
swap.free
Swap memory in bytes free on the host.
swap.used
Swap memory in bytes used on the host.
swap.cached
Swap memory in bytes also cached in host's memory.
ksm.cpu.current
Percentage of CPU usage for Kernel SamePage Merging.
cpu.current.user
Percentage of CPU usage for users.
cpu.current.system
Percentage of CPU usage for system.
cpu.current.idle
Percentage of idle CPU usage.
cpu.load.avg.5m
CPU load average per five minutes.

Example 13.15. An XML representation of the host's statistics sub-collection

<statistics>
    <statistic id="4ae97794-f56d-3f05-a9e7-8798887cd1ac"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/
      statistics/4ae97794-f56d-3f05-a9e7-8798887cd1ac">
        <name>memory.total</name>
        <description>Total memory</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="INTEGER">
            <value>
                <datum>3983540224<datum>
            </value>
        </values>
        <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    </statistic>
    ...
</statistics>

Note

A host's statistics sub-collection is read-only.

13.6. 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.6.1.  Install Action

Install VDSM and related software on the host. The host type defines additional parameters for the action.
  • Red Hat Enterprise Linux host - This host type requires a root_password element that refers to the password for the host's root user.
  • Red Hat Enterprise Virtualization Hypervisor host - This host type requires an image element that refers to an ISO file stored on the Red Hat Enterprise Virtualization Manager server.

Example 13.16. Action to install VDSM to a Red Hat Enterprise Linux host

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

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

Example 13.17. Action to install VDSM to a Red Hat Enterprise Virtualization Hypervisor host

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

<action>
    <image>/usr/share/rhev-hypervisor/rhev-hypervisor.iso</image>
</action>

13.6.2.  Activate Action

Activate the host for use, such as running virtual machines.

Example 13.18. Action to activate a host

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

<action/>

13.6.3. Fence Action

An API user controls a host's power management device with the fence action. See Section 13.1, “Power Management” for details on configuring a fencing device for a host.
The capabilities lists available fence_type options. See Section 7.6, “Fence Types” for details on accessing this list.

Example 13.19. Action to fence a host

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

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

13.6.4.  Deactivate Action

Deactivate the host to perform maintenance tasks.

Example 13.20. Action to deactivate a host

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

<action/>

13.6.5.  Approve Action

Approve a pre-installed Red Hat Enterprise Virtualization Hypervisor host for usage in the virtualization environment. This action also accepts an optional cluster element to define the target cluster for this host.

Example 13.21. Action to approve a host

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

<action>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
<action>

13.6.6.  iSCSI Login Action

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

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

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1
Accept: application/xml
Content-Type: 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.6.7.  iSCSI Discover Action

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

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

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1
Accept: application/xml
Content-Type: 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="/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.6.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 and deletion of a bonded interface.

Example 13.24. Action to commit network configuration

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

<action/>

Important

Networking configuration is only committed after the Manager has established that host connectivity is not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and automatically reverts to the previous networking configuration.

Chapter 14. Virtual Machines

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 5, Entry Point).
The following table shows specific elements contained in a virtual machine resource representation.

Note

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

Table 14.1. Virtual machine elements

Element Type Description Properties
link rel="disks" relationship A link to the disks sub-collection for virtual machine resources.
link rel="nics" relationship A link to the nics sub-collection for virtual machine resources.
link rel="cdroms" relationship A link to the cdroms sub-collection for virtual machine resources.
link rel="snapshots" relationship A link to the snapshots sub-collection for virtual machine resources.
link rel="tags" relationship A link to the tags sub-collection for virtual machine resources.
link rel="permissions" relationship A link to the permissions sub-collection for virtual machine permissions. See Section 8.3.7, “ Permissions ”.
link rel="statistics" relationship 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.9, “Virtual Machine Types”.
status See below The virtual machine status.
memory integer The amount of memory allocated to the guest in bytes.
cpu complex
Defines CPU details for the virtual machine. The topology sub-element sets number of logical sockets available to the guest and the number of cores per socket. The total cores available to the virtual machine equals the number of sockets multiplied by the cores per socket.
The cputune sub-element maps virtual CPUs to physical host CPUs using a series of vcpupin elements. Each vcpupin elements contains a virtual CPU attribute (vcpu) and an attribute to define which physical to use (cpuset). Set the cpuset to either a single CPU (cpuset="0"), multiple CPUs (cpuset="0,2"), a CPU range (cpuset="0-3") or a CPU range with exclusion (cpuset="0-3,^2").
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.10, “Boot Devices”.
os kernel string A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os initrd string A path to an initrd image to be used with the previously specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os cmdline string A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
high_availability complex Set enabled to true if the virtual machine should be automatically restarted if the virtual machine or its 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. The allow_reconnect Boolean value specifies if a client can reconnet to the machine via display.
cluster id= GUID A reference to the virtual machine's host cluster. See Chapter 10, Host Clusters.
template id= GUID A reference to the template on which this virtual machine is based.
domain id= GUID A reference to the virtual machine's domain.
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.
origin One of rhev, ovirt, 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 contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot.
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). Leave the host element empty to set no preferred host.
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.
quota id= GUID Sets a quota for the virtual machine.
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.17, “Custom Properties”.
usb complex Defines the USB policy for a virtual machine. Requires an enabled element set to a Boolean value and a type element set to either native or legacy.
guest_info complex A reference to the guest client information. Includes an ip element with an address= attribute.
vmpool complex A reference to the virtual machine pool. This element only appears for virtual machines part of a pool.
timezone tz database format: Area/Location The the Sysprep timezone setting for a Windows virtual machine. Only certain timezones are allowed as specified in Appendix E, Timezones.
domain complex The the Sysprep domain setting for a Windows virtual machine. Requires a name from the domains collection. See Chapter 18, Domains for more information about domains.
payloads complex Defines a set of payload elements to deliver content to a virtual machine upon boot. Each payload requires a type attribute, either cdrom or floppy, and a file element that specifies the name and location using the name attribute. Within the file element is a content element, which defines the content to deliver to the file.

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. These states are listed in vm_states under capabilities (See Section 7.25, “Resource Status States”).

Example 14.1. An XML representation of a virtual machine

<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
  href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
    <name>vm1</name>
    <description>Virtual Machine 1</description>
    <actions>
        <link rel="start"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/start"/>
        <link rel="stop"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/stop"/>
        <link rel="shutdown"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/shutdown"/>
        <link rel="suspend"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/suspend"/>
        <link rel="detach"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/detach"/>
        <link rel="migrate"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/migrate"/>
        <link rel="export"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/export"/>
        <link rel="import"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        <link rel="move"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move"/>
        <link rel="ticket"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/ticket"/>
    </actions>
    <link rel="disks"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks"/>
    <link rel="nics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics"/>
    <link rel="cdroms"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/cdroms"/>
    <link rel="snapshots"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/snapshots"/>
    <link rel="users"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/users"/>
    <link rel="tags"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/tags"/>
    <link rel="permissions"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/permissions"/>
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/statistics"/>
    <type>desktop</type>
    <status>
        <state>up</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="2" sockets="2"/>
        <cputune>
            <vcpupin vcpu="0" cpuset="1-4,^2"/>
            <vcpupin vcpu="1" cpuset="0,1"/>
            <vcpupin vcpu="2" cpuset="2,3"/>
            <vcpupin vcpu="3" cpuset="0,4"/>
        </cputune>
    </cpu>
    <os type="RHEL5">
        <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="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/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>
    <usb>
        <enabled>true</enabled>
    </usb>
    <custom_properties>
        <custom_property value="124" name="sndbuf"/>
    </custom_properties>
    <guest_info>
        <ip address="192.168.0.25"/>
    </guest_info>
    <payloads>
        <payload type='cdrom'>
            <file name='/etc/hosts'>
                <content>
                  127.0.0.1 localhost myvm.example.com
                </content>
             </file>
         </payload>
     </payloads>
</vm>

Creation of a new virtual machine requires the name, template and cluster elements. Identify the template and cluster elements with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

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

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

Note

Memory in the previous example is converted to bytes using the following formula:
512MB * 10242 = 536870912 bytes
The name, description, cluster, type, memory, cpu, os, high_availability, display, timezone, domain, stateless, placement_policy, memory_policy, usb, payloads, origin and custom_properties elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

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

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

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

Note

Memory in the previous example is converted to bytes using the following formula:
1024MB * 10242 = 1073741824 bytes
Removal of a virtual machine requires a DELETE request.

Example 14.4. Removing a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1

HTTP/1.1 204 No Content

14.1. Disks Sub-Collection

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

Note

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

Table 14.2. Elements for virtual machine disks

Element Type Description Properties
link rel="statistics" relationship A link to the statistics sub-collection for a virtual machine's disk statistics.
storage_domains Complex The storage domains associated with this disk. Each storage_domain element contains an id attribute with the associated storage domain's GUID. Update this element with POST to perform live migration of a disk from one data storage domain to another. [a]
size integer Size of the disk in bytes.
provisioned_size integer The provisioned size of the disk in bytes.
actual_size integer Actual size of the disk in bytes.
status One of illegal, invalid, locked or ok The status of the disk device. These states are listed in disk_states under capabilities (See Section 7.25, “Resource Status States”).
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.15, “Disk Interfaces”.
format enumerated The underlying storage format. A list of enumerated values is available in capabilities. See Section 7.14, “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.
shareable Boolean: true or false true to share the disk with multiple virtual machines.
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.
vm id= GUID The ID of the containing virtual machine.
quota id= GUID Sets a quota for the disk.
lunStorage complex A reference to a direct LUN mapping for storage usage. Requires a storage element that contains iSCSI or FCP device details. See Section 12.1.3, “ iSCSI and FCP ” for more information.
active Boolean Defines if the disk is connected to the virtual machine.
[a] This element is only required if the disk is being added to a virtual machine and not created from a virtual machine template.

Example 14.5. An XML representation of a disk device

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>  
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>10737418240</size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>   
    <lunStorage>
        <storage>
            <logical_unit id="lun1">
                ...
            </logical_unit>
        <storage>
    </lunStorage>
</disk>

When adding a new disk, the size element is required. Also the API requires the storage_domains element when the disk is added to a virtual machine and not itself created from a template.

Example 14.6. Creating a new a disk device on a virtual machine

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

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>

The name, description, storage_domains, interface, bootable, shareable, wipe_after_delete and propagate_errors elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

Example 14.7. Updating a virtual machine disk

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <bootable>false</bootable>
    <shareable>false</shareable>
</disk>

Removal of a virtual machine disk requires a DELETE request.

Example 14.8. Removing a virtual machine disk

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1

HTTP/1.1 204 No Content

14.1.1. Disk Cloning

Clone a disk from a template with the clone element. Set the clone element to true within the disks sub-collection when creating a virtual machine. This clones a disk from the base template and attaches it to the virtual machine.

Example 14.9. Cloning a disk from a template

The following example clones a disk from a template during the creation of a virtual machine.
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
        
<vm>
    <name>cloned_vm</name>
    <template id="64d4aa08-58c6-4de2-abc4-89f19003b886"/>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
    <disks>
        <clone>true</clone>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b">
            <format>COW</format>
        </disk>
        <disk id="42aef10d-3dd5-4704-aa73-56a023c1464c">
            <format>COW</format>
        </disk>
    </disks>
</vm>

Important

Search queries for virtual machine disks based upon disk name require the alias search parameter instead of name.

14.1.2. Disk Statistics

Each virtual machine's disk exposes a statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:

Table 14.3. Elements for virtual machine disk statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
disk id= relationship A relationship to the containing disk resource.

The following table lists the statistic types for virtual machine disks.

Table 14.4. Virtual machine disk statistic types

Name
Description
data.current.read
The data transfer rate in bytes per second when reading from the disk.
data.current.write
The data transfer rate in bytes per second when writing to the disk.

Example 14.10. An XML representation of a virtual machine's statistics sub-collection

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/disks/
      f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

14.1.3. Floating Disk Attach and Detach

Attach any floating disks from the main rel="disks" collection using a POST request on the virtual machine's disks sub-collection. Include the id of the disk to attach.

Example 14.11. Attach a floating disk

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

<disk>
  <id="d135f1c5-b5e1-4238-9381-b3277f5a3742"/>
</disk>

Detach any disk from a virtual machine's disks sub-collection using a DELETE request on the disk resource but ensure to include a detach Boolean element so the disk is not destroyed.

Example 14.12. Detach a disk from a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  d135f1c5-b5e1-4238-9381-b3277f5a3742HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <detach>true</detach>
</action>

14.1.4. Disk Activate and Deactivate Actions

Each virtual machine's disk provides a set of activate and deactivate actions to add and remove disks from a virtual machine.

Example 14.13. Action to activate a virtual machine disk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Example 14.14. Action to deactivate a virtual machine disk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Use these actions to hotplug disks to virtual machines and activate newly attached floating disks.

Important

The hotplugging feature only supports VirtIO disks and virtual machine operating systems that support hotplugging operations. Example operating systems include:
  • Red Hat Enterprise Linux 6;
  • Red Hat Enterprise Linux 5;
  • Windows Server 2008; and,
  • Windows Server 2003.

14.2. Network Interfaces Sub-Collection

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

Note

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

Table 14.5. Elements for virtual machine network interfaces

Element Type Description Properties
link rel="statistics" relationship A link to the statistics sub-collection for a virtual machine's network interface statistics.
network id= GUID A reference to the network which the interface should be connected.
interface enumerated The type of driver used for the nic. A list of enumerated values is available in capabilities. See Section 7.12, “NIC Interface Types”.
mac address= string The MAC address of the interface.
port_mirroring complex Defines whether the NIC receives mirrored traffic. Define a networks element with a series of network id= references.
active Boolean Defines if the NIC is connected to the virtual machine.

Example 14.15. An XML representation of a network interface

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
      7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>   
    <name>nic1</name>
    <interface>virtio</interface>
    <mac address="00:1a:4a:16:84:07"/>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    <port_mirroring>
        <networks>
            <network id="56087282-d7a6-11e1-af44-001a4a400e0c"
              href="/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
        </networks>
    </port_mirroring>
</nic>

When adding a new network interface, the name and network elements are required. Identify the network element with the id attribute or name element.

Example 14.16. Creating a virtual machine NIC

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic1</name>
    <network id="00000000-0000-0000-0000-000000000009"/>
</nic>

An API user modifies a network interface with a PUT request.

Example 14.17. Updating a virtual machine NIC

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic2</name>
    <network id="00000000-0000-0000-0000-000000000010"/>
    <type>e1000</type>
</nic>

An API user removes a network interface with a DELETE request.

Example 14.18. Deleting a virtual machine NIC

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1

HTTP/1.1 204 No Content

14.2.1. Network Interface Statistics

Each virtual machine's network interface exposes a statistics sub-collection for network interface statistics. Each statistic contains the following elements:

Table 14.6. Elements for a virtual machine's network interface statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
nic id= relationship A relationship to the containing nic resource.

The following table lists the statistic types for network interfaces on virtual machines.

Table 14.7. Virtual machine NIC statistic types

Name
Description
data.current.rx
The rate in bytes per second of data received.
data.current.tx
The rate in bytes per second of data transmitted.
errors.total.rx
Total errors from receiving data.
errors.total.tx
Total errors from transmitting data.

Example 14.19. An XML representation of a virtual machine's NIC statistics sub-collection

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
      6cd08e76-57c0-41ba-a728-7eba46ae1e36/statistics/
      ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

14.2.2. Network Interface Activate and Deactivate Actions

Each virtual machine's network interface provides a set of activate and deactivate actions to add and remove NICs from a virtual machine.

Example 14.20. Action to activate a virtual machine NIC

POST /api/vms/b1c03f94-9cad-4344-8a89-6a7064a73bb3/nics/a4226079-5ce7-4927-bd78-814049ef1ffe/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Example 14.21. Action to deactivate a virtual machine NIC

POST /api/vms/b1c03f94-9cad-4344-8a89-6a7064a73bb3/nics/a4226079-5ce7-4927-bd78-814049ef1ffe/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Use these actions to hotplug and hotunplug NICs to virtual machines.

Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:
  • Red Hat Enterprise Linux 6;
  • Red Hat Enterprise Linux 5;
  • Windows Server 2008; and,
  • Windows Server 2003.

14.3. CD-ROMs Sub-Collection

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

Table 14.8. Elements for virtual machine CD-ROMs

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

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

<cdrom id="00000000-0000-0000-0000-000000000000"
  href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
  00000000-0000-0000-0000-000000000000">
    <file id="rhel-server-6.0-x86_64-dvd.iso"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>

Send a POST request with a file id element to add a new CD-ROM resource.

Example 14.23. Changing a CD-ROM file

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>

The API changes the CD-ROM using a PUT request:

Example 14.24. Changing a CD-ROM file

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>

The API changes the CD-ROM for the current session only using a PUT request with an additional current URI argument:

Example 14.25. Changing a CD-ROM file during a current session

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000?current HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>

Note

A virtual machine only contains a single CD-ROM device.

14.4. Snapshots Sub-Collection

A virtual machine saves and restores disk state as a number of snapshots. These are represented and managed through a rel="snapshot" sub-collection that behaves similar to other collections, as described in Chapter 8, Common Features.
Each virtual machine snapshot is represented with an individual snapshot element that contains the following sub-elements:

Note

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

Table 14.9. Elements for virtual machine snapshots

Element Type Description Properties
vm id= GUID 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" relationship A link to the previous snapshot of this virtual machine.

When adding a new snapshot, only the description element is specified.

Note

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

Example 14.26. An XML representation of a virtual machine snapshot

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

An API user restores a virtual machine snapshot using the rel="restore" action link in the snapshot representation.
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/f5288fd5-5178-4b7d-b87c-c01a40e40168/restore HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Note

The REST API also provides live snapshot capability, which allows users to take snapshots while a virtual machine is running.

14.4.1. Clone a Virtual Machine from a Snapshot

API provides a function to create virtual machines from a snapshot of a previous machine. API users create a new virtual machine while retaining the original virtual machine with all snapshots intact.
Creation of a virtual machines from a snapshot requires an additional snapshots element to a standard representation of a virtual machine, which a user sends in a POST request to the vms collection.
The snapshots element contains a snapshot id= element to define the specific snapshot to use as a basis for the virtual machine. The snapshots element also requires a Boolean clone element, which signifies to the API to clone the new virtual machine from the specified snapshot.

Example 14.27. Clone Virtual Machine from Snapshot

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

<vm>
  ...
  <snapshots>
    <clone<true</clone>
    <snapshot id="id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/>
  </snapshots>
  ...
</vm>

14.5. Statistics Sub-Collection

Each virtual machine resource exposes a statistics sub-collection for virtual machine-specific statistics. Each statistic contains the following elements:

Table 14.10. Elements for virtual machine statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
vm id= relationship A relationship to the containing vm resource.

The following table lists the statistic types for virtual machines.

Table 14.11. Virtual machine statistic types

Name
Description
memory.installed
Total memory in bytes allocated for the virtual machine's use.
memory.used
Current memory in bytes used by the virtual machine.
cpu.current.guest
Percentage of CPU used by the guest.
cpu.current.hypervisor
Percentage of CPU overhead on the hypervisor.
cpu.current.total
Total percentage of the current CPU in use.

Example 14.28. An XML representation of a virtual machine's statistics sub-collection

<statistics>
    <statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/
      statistics/ef802239-b74a-329f-9955-be8fea6b50a4">
        <name>memory.installed</name>
        <description>Total memory configured</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="DECIMAL">
            <value>
                <datum>1073741824<datum>
            </value>
        </values>
        <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
          href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    </statistic>
    ...
</statistics>

Note

A virtual machine's statistics sub-collection is read-only.

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, cancelmigration, export, move and ticket.
Information on the action for importing virtual machines is found in Section 12.2, “ Export Storage Domains ”.

14.6.1.  Start Action

The start action launches a virtual machine.

Example 14.29. Action to start a virtual machine

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

<action/>

The start action allows a vm element to be provided as a parameter. If a vm element is provided, the virtual machine uses the values from the provided element and overrides system settings at start time. These settings persist until a user stops the virtual machine. Examples of these elements include os, domain, placement_policy, cdroms, stateless and display type.

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

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

<action>
    <pause>true</pause>
    <vm>
        <stateless>true</stateless>
        <display>
            <type>spice</type>
        </display>
        <os>
            <boot dev="cdrom"/>
        </os>
        <cdroms>
            <cdrom>
                <file id="windows-xp.iso"/>
            </cdrom>
        </cdroms>
        <domain>
            <name>domain.example.com</name>
            <user>
                <user_name>domain_user</user_name>
                <password>domain_password</password>
            </user>
        </domain>
        <placement_policy>
            <host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>       
        </placement_policy>
    </vm>
</action>

Note

Only virtual machines running Windows operating systems use the domain element when overriding parameters on boot with the start action. The domain element determines the domain that the Windows virtual machine joins. If the domain does not exist in the domains collection (see Chapter 18, Domains), this element requires additional user authentication details, including a user_name and password. If the domain exists in the domains collection, the action requires no additional user authentication details.

14.6.2.  Stop Action

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

Example 14.31. Action to stop a virtual machine

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

<action/>

14.6.3.  Shutdown Action

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

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

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

<action/>

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.33. Action to save virtual machine state and suspend the machine

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

<action/>

14.6.5.  Detach Action

The detach action detaches a virtual machine from a pool.

Example 14.34. Action to detach a virtual machine

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

<action/>

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

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

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

14.6.7.  Cancel Migration Action

The cancel migration action stops any migration of a virtual machine to another physical host.

Example 14.36. Action to cancel migration of a virtual machine to another host

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

<action/>

14.6.8.  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.
The export action reports a failed action if a virtual machine of the same name exists in the destination domain. Set the exclusive parameter to true to change this behaviour and overwrite any existing virtual machine.
If snapshots of the virtual machine are not included with the exported virtual machine, set the discard_snapshots parameter to true.

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

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

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

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.38. Action to move virtual machine disks to a different storage domain

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move HTTP/1.1
Accept: application/xml
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 optionally includes a ticket representation containing a value (if the token string needs to take on a particular form) and/or an expiry time in minutes. In any case, the response specifies the actual ticket value and expiry used.

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

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

<action>
    <ticket>
        <expiry>120</expiry>
    </ticket>
</action>

200 OK
Content-Type: application/xml

<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
  href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
  94e07552-14ba-4c27-8ce6-2cc75190d3ef">
    <status>
        <state>complete</state>
    </status>
    <ticket>
        <value>5c7CSzK8Sw41</value>
        <expiry>120</expiry>
    </ticket>
    <link rel="parent"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <link rel="replay"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>

14.6.11.  Force Remove Action

An API user forces the removal of a faulty virtual machine with the force action. This action requires a DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.

Example 14.40. Force remove action on a virtual machine

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

<action>
    <force>true</force>
</action>

Chapter 15. Floating Disks

The disks collection provides information about all disks in a Red Hat Enterprise Virtualization environment. A user attaches and dettaches disks from any virtual machine and floats them between virtual machines. An API user accesses this information through the rel="disks" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a disks resource representation.

Note

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

Table 15.1. Elements for floating disks

Element Type Description Properties
link rel="statistics" relationship A link to the statistics sub-collection for a virtual machine's disk statistics.
image_id GUID A reference to the virtual machine image stored on the defined storage domain.
storage_domains Complex The storage domains associated with this disk. Each storage_domain element contains an id attribute with the associated storage domain's GUID. Update this element with POST to perform live migration of a disk from one data storage domain to another.
size integer Size of the disk in bytes.
provisioned_size integer The provisioned size of the disk in bytes.
actual_size integer Actual size of the disk in bytes.
status One of illegal, invalid, locked or ok The status of the disk device. These states are listed in disk_states under capabilities (See Section 7.25, “Resource Status States”).
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.15, “Disk Interfaces”.
format enumerated The underlying storage format. A list of enumerated values is available in capabilities. See Section 7.14, “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.
shareable Boolean: true or false true to share the disk with multiple virtual machines.
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.
quota id= GUID Sets a quota for the disk.
lunStorage complex A reference to a direct LUN mapping for storage usage. Requires a storage element that contains iSCSI or FCP device details. See Section 12.1.3, “ iSCSI and FCP ” for more information.
active Boolean Defines if the disk is connected to the virtual machine.

Example 15.1. An XML representation of a disk device

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>  
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>10737418240</size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <lunStorage>
        <storage>
            <logical_unit id="lun1">
                ...
            </logical_unit>
        <storage>
    </lunStorage>
</disk>

When creating a new floating disk, the API requires the size and storage_domains elements.

Example 15.2. Creating a new a floating disk device

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

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
</disk>

Important

Search queries for disks based upon name require the alias search parameter instead of name.

15.1. Floating Disk Statistics

Each floating disk exposes a statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:

Table 15.2. Elements for virtual machine disk statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
disk id= relationship A relationship to the containing disk resource.

The following table lists the statistic types for floating disks.

Table 15.3. Disk statistic types

Name
Description
data.current.read
The data transfer rate in bytes per second when reading from the disk.
data.current.write
The data transfer rate in bytes per second when writing to the disk.

Example 15.3. An XML representation of a virtual machine's statistics sub-collection

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

Chapter 16. Templates

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 5, Entry Point).
The following table shows specific elements contained in a virtual machine template resource representation.

Note

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

Table 16.1. Virtual machine template elements

Element Type Description Properties
link rel="disks" relationship A link to the disks sub-collection for virtual machine template resources.
link rel="nics" relationship A link to the nics sub-collection for virtual machine template resources.
link rel="cdroms" relationship A link to the cdroms sub-collection for virtual machine template resources.
link rel="permissions" relationship A link to the permissions sub-collection for virtual machine template permissions. See Section 8.3.7, “ Permissions ”.
type enumerated The type of virtual machine the template provides. A list of enumerated values are available in capabilities. See Section 7.9, “Virtual Machine Types”.
status One of illegal, locked or ok The template status. These states are listed in template_states under capabilities (See Section 7.25, “Resource Status States”).
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.10, “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= GUID A reference to the template's host cluster. See Chapter 10, Host Clusters.
vm id= GUID A reference to the VM on which this template is based. See Chapter 14, Virtual Machines.
domain id= GUID A reference to the template's domain.
creation_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this template was created.
origin One of rhev, ovirt, 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. The allow_reconnect Boolean value specifies if a client can reconnet to the machine via display.
stateless Boolean: true or false A stateless template contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot.
usb complex Defines the USB policy for a virtual machine template. Requires an enabled element set to a Boolean value and a type element set to either native or legacy.
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). Leave the host element empty to set no preferred host.
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.17, “Custom Properties”.
timezone tz database format: Area/Location The the Sysprep timezone setting for a Windows virtual machine template. Only certain timezones are allowed as specified in Appendix E, Timezones.
domain complex The the Sysprep domain setting for a Windows virtual machine template. Requires a name from the domains collection. See Chapter 18, Domains for more information about domains.

Example 16.1. An XML representation of a virtual machine template

<template id="00000000-0000-0000-0000-000000000000"
  href="/api/templates/00000000-0000-0000-0000-000000000000">
    <name>Blank</name>
    <description>Blank template</description>
    <actions>
        <link rel="export"
          href="/api/templates/00000000-0000-0000-0000-000000000000/export"/>
    </actions>
    <link rel="disks"
      href="/api/templates/00000000-0000-0000-0000-000000000000/disks"/>
    <link rel="nics"
      href="/api/templates/00000000-0000-0000-0000-000000000000/nics"/>
    <link rel="cdroms"
      href="/api/templates/00000000-0000-0000-0000-000000000000/cdroms"/>
    <link rel="permissions"
      href="/api/templates/00000000-0000-0000-0000-000000000000/permissions"/>
    <type>server</type>
    <status>
        <state>ok</state>
    </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="/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>
    <usb>
        <enabled>true</enabled>
    </usb>
</template>

Creation of a new template requires the name and vm elements. Identify the vm with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 16.2. Creating a template from a virtual machine

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

<template>
    <name>template1</name>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"/>
</template>

The name, description, type, memory, cpu topology, os, high_availability, display, stateless, usb and timezone elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.

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

PUT /api/templates/a03dca95-98cb-430d-89dc-b11482543748 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <memory>1073741824</memory>
</template>

Removal of a virtual machine template requires a DELETE request.

Example 16.4. Removing a virtual machine template

DELETE /api/templates/a03dca95-98cb-430d-89dc-b11482543748 HTTP/1.1

HTTP/1.1 204 No Content

Templates contain a number of device sub-collections that follow the same XML representation structure as devices in the vms collection:

Note

Users delete a template disk from a specific storage domain using the following body in the DELETE request:
DELETE /api/templates/a03dca95-98cb-430d-89dc-b11482543748/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

16.1.  Export Action

The templates collection contains an export action. Information on the action for importing templates is found in Section 12.2, “ Export Storage Domains ”.
The export action exports a template to an Export storage domain. A destination storage domain is specified with a storage_domain reference.
The export action reports a failed action if a virtual machine template of the same name exists in the destination domain. Set the exclusive parameter to true to change this behaviour and overwrite any existing virtual machine template.

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

POST /api/templates/a03dca95-98cb-430d-89dc-b11482543748/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

Chapter 17. 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 5, Entry Point).
The following table shows specific elements contained in a virtual machine pool resource representation.

Note

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

Table 17.1. Virtual machine pool elements

Element Type Description Properties
size integer The number of virtual machines in the pool.
cluster id= GUID A reference to the cluster resource which virtual machines in this pool run.
template id= GUID A reference to the template resource which virtual machines in this pool are based.

Example 17.1. An XML representation of a virtual machine pool

<vmpool id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"
  href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e">
    <name>VMPool1</name>
    <description>Virtual Machine Pool 1</description>
    <size>2</size>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/api/templates/00000000-0000-0000-0000-000000000000"/>
</vmpool>

A new pool requires the name, cluster and template elements. Identify the cluster and template with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 17.2. Creating a virtual machine pool

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

<vmpool>
    <name>VM Pool A</name>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/api/templates/00000000-0000-0000-0000-000000000000"/>
</vmpool>

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

Example 17.3. Updating a virtual machine pool

PUT /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vmpool>
    <name>VM Pool B</name>
    <description>Virtual Machine Pool B</description>
    <size>3</size>
</vmpool>

Removal of a virtual machine pool requires a DELETE request.

Example 17.4. Removing a virtual machine

DELETE /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1

HTTP/1.1 204 No Content

Important

The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.

Chapter 18. Domains

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

Table 18.1. Domain elements

Element Type Description
name string The domain name.
link rel="users" relationship A link to the sub-collection for users associated with this domain.
link rel="groups" relationship 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, “ Searching Collections with Queries ” for more information.

Example 18.1. An XML representation of a domain resource

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

Note

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

18.1. Domain Users Sub-Collection

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

Table 18.2. Domain user elements

Element Type Description
name string The name of the user.
last_name string The surname of the user.
user_name string The username from directory service.
domain id GUID The containing directory service domain.
groups complex A list of directory service groups for this user.

Example 18.2. An XML representation of a user in the users sub-collection

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/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="/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>

18.2. Domain Groups Sub-Collection

The groups sub-collection contains all groups in the directory service. A domain group resource contains a set of elements.

Table 18.3. Domain group elements

Element Type Description
name string The name of the group.
domain id GUID The containing directory service domain.

Example 18.3. An XML representation of a group in the groups sub-collection

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/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="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
</group>

Chapter 19. Roles

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

Note

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

Table 19.1. Role elements

Element Type Description Properties
link="permits" relationship A link to the permits sub-collection for role permits.
mutable Boolean: true or false Defines the ability to update or delete the role. Roles with mutable set to false are roles built into the Red Hat Enterprise Virtualization environment.
administrative Boolean: true or false Defines the role as administrative-only.

Example 19.1. An XML representation of the roles collection

<roles>
    <role id="00000000-0000-0000-0000-000000000001"
      href="/api/roles/00000000-0000-0000-0000-000000000001">
        <name>SuperUser</name>
        <description>Roles management administrator</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0000-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>true</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000001"
      href="/api/roles/00000000-0000-0000-0001-000000000001">
        <name>RHEVMUser</name>
        <description>RHEVM user</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0001-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000002"
       href="/api/roles/00000000-0000-0000-0001-000000000002">
        <name>RHEVMPowerUser</name>
        <description>RHEVM power user</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0001-000000000002/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
</roles>

Creation of a role requires values for name, administrative and a list of initial permits. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.

Example 19.2. Creating a role

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

<role>
    <name>Finance Role</name>
    <administrative>true</administrative>
    <permits>
        <permit id="1"/>
    </permits>
</role>

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

Example 19.3. Updating a role

PUT /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<role>
    <name>Engineering Role</name>
    <description>Standard users in the Engineering Role</description>
    <administrative>false</administrative>
</role>

Removal of a role requires a DELETE request.

Example 19.4. Removing a role

DELETE /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1

HTTP/1.1 204 No Content

19.1. Permits Sub-Collection

Each role contains a set of allowable actions, or permits, which the API lists in capabilities. For more information on access to permits, see Section 7.26, “Permits”.
A role's permits are listed as a sub-collection:

Example 19.5. Listing a role's permits

GET /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="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>create_vm</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
    ...
</permits>

Assign a permit to a role with a POST request to the permits sub-collection. Use either an id attribute or a name element to specify the permit to assign.

Example 19.6. Assign a permit to a role

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

<permit id="1"/>

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

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

Remove a permit from a role with a DELETE request to the permit resource.

Example 19.7. Remove a permit from a role

DELETE /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1

HTTP/1.1 204 No Content

Chapter 20. Groups

The groups collection contains imported groups from directory services. A group resource contains a set of elements.

Table 20.1. Imported group elements

Element Type Description
link rel="tags" relationship A link to the tags sub-collection for tags attached to this group.
link rel="permissions" relationship A link to the permissions sub-collection for permissions attached to this group.
link rel="roles" relationship A link to the roles sub-collection for roles attached to this group.

Example 20.1. An XML representation of a group resource

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab">
    <name>Everyone</name>
    <link rel="tags"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/tags"/>
    <link rel="permissions"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/permissions"/>
    <link rel="roles"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/roles"/>
</group>

The API adds existing directory service groups to the Red Hat Enterprise Virtualization Manager database with a POST request to the groups collection.

Example 20.2. Adding a group from directory service

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

<group>
    <name>www.example.com/accounts/groups/mygroup</name>
</group>

Chapter 21. Users

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

Note

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

Table 21.1. User elements

Element Type Description Properties
user_name string The user principal name (UPN). The UPN is used as a more convenient identifier when adding a new user.
link rel="tags" relationship A link to the tags sub-collection for user resources.
link rel="roles" relationship A link to the roles sub-collection for user resources.
name string A free-text name for the user.
domain string The containing directory service domain.
groups complex A list of directory service groups for this user.

Example 21.1. An XML representation of a user resource

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

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
    <name>RHEV-M Admin</name>
    <actions/>
    <link rel="roles"
      href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
    <link rel="tags"
      href="/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 API adds an existing directory service user to the Red Hat Enterprise Virtualization Manager database with a POST request to the users collection. The client-provided new user representation includes 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:

Example 21.2. Adding a user from directory service and assigning two roles

POST /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 directory service user principal name (UPN). The user ID format reported from the directory service domain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as in LDIF [5] , 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 directory service domain before it is added to the Red Hat Enterprise Virtualization Manager database. An API user has 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 API adds the RHEVMVDIUser role 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.

Example 21.3. Adding roles to a user

POST /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.
The API removes users from the Red Hat Enterprise Virtualization Manager database with a DELETE request on the users collection. The directory service domain remains unchanged after such a deletion.


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

Chapter 22. 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 5, Entry Point).
The following table shows specific elements contained in a tag resource representation.

Note

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

Table 22.1. Tag elements

Element Type Description Properties
host GUID A reference to the host which the tag is attached. See Chapter 13, Hosts.
user GUID A reference to the user which the tag is attached. See Chapter 21, Users.
vm GUID A reference to the VM which the tag is attached. See Chapter 14, Virtual Machines.
parent complex A reference to the VM which the tag is attached.

Example 22.1. An XML representation of a tag resource

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

Creation of a new tag requires the name element. The name, description and parent elements are updatable post-creation.

22.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 22, Tags, except they also contain a host id, user id or vm id reference to the entity in question.
Each tags collection is 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.

Example 22.2. Associating a tag with a virtual machine

POST /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
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/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="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

Removing an association is achieved with a DELETE request to the appropriate element in the collection.

Example 22.3. Removing a tag from a virtual machine

DELETE /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.

Example 22.4. Querying a collection for tagged resources

GET /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="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>

22.2. Parent Tags

An API user assigns a parent element to a tag to create a hierarchical link to a parent tag. The tags are presented as a flat collection, which descends from the root tag, with tag representations containing a link element to a parent tag

Note

The root tag is a special pseudo-tag assumed as the default parent 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:

Example 22.5. Tag Hierarchy

<tags>
    <tag id="-1" href="/api/tags/-1">
        <name>root</name>
        <description>root</description>
        <parent>
            <tag id="-1" href="/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
      href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
        <name>Finance</name>
        <description>Resources for the Finance department</description>
        <parent>
            <tag id="-1" href="/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="ac18dabf-23e5-12be-a383-a38b165ca7bd"
      href="/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd">
        <name>Billing</name>
        <description>Billing Resources</description>
        <parent>
            <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
              href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
        </parent>
    </tag>
</tags>
In this XML representation, the tags follow this hierarchy:
root              (id: -1)
  - Finance       (id: f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e)
      - Billing   (id: ac18dabf-23e5-12be-a383-a38b165ca7bd)

POSTing a new tag with a parent element creates an association with a parent tag, using either the id attribute or the name element to reference the parent tag

Example 22.6. Setting an association with a parent tag with the id attribute

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

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

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

Example 22.7. Setting an association with a parent tag with the name element

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

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

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

A tag changes a parent using a PUT request:

Example 22.8. Changing the parent tag

PUT /api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

Chapter 23. Events

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

Table 23.1. Event elements

Element Type Description
description string A description of the system event
code integer The integer event code. See Appendix D, Event Codes for a full list of event codes with descriptions.
severity One of normal, warning, error or alert The level of severity for the event.
time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The timestamp indicating when the event happened.
user id GUID The identification code for the user who triggered the event.

Example 23.1. An XML representation of the events collection

<events>
    <event id="537" href="/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="/api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
    </event>
    ...
</events>

In addition to user, an event representation also contains a set of XML element relationships to resources relevant to the event.

Example 23.2. An XML representation of a virtual machine creation event

<event id="635" href="/api/events/635">
    <description>VM bar was created by rhevadmin.</description>
    <code>34</code>
    <severity>normal</severity>
    <time>2011-07-11T16:32:03.172+02:00</time>
    <user id="4621b611-43eb-4d2b-ae5f-1180850268c4"
      href="/api/users/4621b611-43eb-4d2b-ae5f-1180850268c4"/>
    <vm id="9b22d423-e16b-4dd8-9c06-c8e9358fbc66"
      href="/api/vms/9b22d423-e16b-4dd8-9c06-c8e9358fbc66"/>
    <storage_domain id="a8a0e93d-c570-45ab-9cd6-3c68ab31221f"
      href="/api/storagedomains/a8a0e93d-c570-45ab-9cd6-3c68ab31221f"/>
</event>
This example representation provides XML element relationships to a virtual machine resource and a storage domain resource.

Note

The events collection is read-only.

23.1. Searching Events

The events collection provides search queries similar to other resource collections (See Section 8.2.3, “ Searching Collections with Queries ”). An additional feature when searching the events collection is the ability to search from a certain event. This queries all of events since a specified event.
Querying from an event requires an additional from parameter added before the search query. This from argument references an event id code.

Example 23.3. Searching from an event

GET /api/events;from=1012?search=type%3D30 HTTP/1.1
Accept: application/xml
This displays all events with type set to 30 since id="1012"
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="1018" href="/api/events/1018">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:22.485+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1016" href="/api/events/1016">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:07.236+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1014" href="/api/events/1014">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:02:16.009+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
</events>

Important

The from argument previously used the following format:
/api/events?search=type%3D30&from=1012
This format is now depreciated.

23.2. Paginating Events

A virtualization environment generates a large amount of events after a period of time. However, the API only displays a default number of events for one search query. To display more than the default, the API separates results into pages with the page command in a search query.
The following search query tells the API to paginate results using a page value in combination with the sortby clause:
sortby time asc page 1
The sortby clause defines the base element to order of the results and whether the results are ascending or descending. For search queries of events, set the base element to time and the order to ascending (asc) so the API displays all events from the creation of your virtualization environment.
The page condition defines the page number. One page equals the default number of events to list. Pagination begins at page 1. To view more pages, increase the page value:
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4

Example 23.4. Paginating events

This example paginates event resources. The URL-encoded request is:
GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1
Accept: application/xml
Increase the page value to view the next page of results.
GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1
Accept: application/xml
Use an additional from argument to set the starting id.
GET /api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1
Accept: application/xml

Part III. Python Sofware Development Kit

Chapter 24. Software Development Kit Overview

24.1. Introduction to the Red Hat Enterprise Virtualization Software Development Kit

The software development kit provides programming language specific libraries for interacting with the REST API provided by Red Hat Enterprise Virtualization Manager. These libraries include classes to represent resources made available by the API and methods for interacting with them. This allows you to concentrate on writing code specific to what they you are trying to achieve rather than on hand crafting appropriately formatted HTTP requests and manually orchestrating their delivery.
The software development kit includes collections and methods mapping directly to all aspects of the REST API. As a result this software development kit documentation focuses on providing examples written in the supported programming language. For a complete reference of all collections, resources, actions, and attributes supported refer to the REST API material.

24.2. Software Development Kit Prerequisites

To install the software development kit you must have:
  • A system with Red Hat Enterprise Linux 6.3, or later, installed. Both the Server and Workstation variants are supported.
  • A subscription to Red Hat Hat Enterprise Virtualization entitlements.
When you install the rhevm-sdk package the Python 2.6 interpreter will be installed if it does not already exist on the system.

Important

To run scripts which make use of the libraries provided by the software development kit the rhevm-sdk must be installed. As a result the prerequisites listed here must be met both on the systems being used to develop scripts using the software development kit and on those systems on which the scripts are intended to run.

24.3. Installing the Software Development Kit

Summary
The software development kit is provided by the rhevm-sdk. The package includes all of the Python bindings for the Red Hat Enterprise Virtualization Manager Application Programming Interface (API). To begin using the software development kit you must install the rhevm-sdk package on the system that you wish to use for your script development. The instructions that appear here are intended for use on a system running Red Hat Enterprise Linux 6.3 or later.

Procedure 24.1. Installing the Python SDK

  1. Ensure that your system has the required entitlements:
    • When using certificate-based Red Hat Network you must subscribe to the Red Hat Enterprise Virtualization entitlement to install the rhevm-sdk package.
    • When using Red Hat Network classic you must ensure subscribe to the Red Hat Enterprise Virtualization Manager (v.3.1 x86_64) channel to install the rhevm-sdk package. This software channel is also referred to as rhel-x86_64-server-6-rhevm-3.1.
  2. Ensure that you are logged in as the root user.
  3. Install the rhevm-sdk package using the yum command.
    # yum install rhevm-sdk
Result
The rhevm-sdk package is now installed. The ovirtsdk Python library is now available for use on the local system.

Chapter 25. Using the Software Development Kit

25.1. Connecting to the API using Python

To connect to the REST API using Python you must create an instance of the API class from the ovirtsdk.api module. To be able to do this it is necessary to first import the class at the start of the script:
from ovirtsdk.api import API
The constuctor of the API class takes a number of arguments. Supported arguments are:
url
Specifies the URL of the Manager to connect to, including the /api path. This parameter is mandatory.
username
Specifies the user name to connect using, in User Principle Name (UPN) format. This parameter is mandatory.
password
Specifies the password for the user name provided by the username parameter. This parameter is mandatory.
key_file
Specifies a PEM formatted key file containing the private key associated with the certificate specified by cert_file. This parameter is optional.
cert_file
Specifies a PEM formatted client certificate to be used for establishing the identity of the client on the server. This parameter is optional.
ca_file
Specifies the certificate file of the certificate authority for the server. This parameter is mandatory unless the insecure parameter is set to True.
port
Specifies the port to connect using, where it has not been provided as component of the url parameter. This parameter is optional.
timeout
Specifies the amount of time in seconds that is allowed to pass before a request is to be considered as having timed out. This parameter is optional.
persistent_auth
Specifies whether persistent authentication is enabled for this connection. Valid values are True and False. This parameter is optional.
insecure
Specifies whether or not the connection needs to be secured. Valid values are True and False. If the insecure parameter is set to False - which is the default - then the ca_file, key_file, and cert_file must be supplied to secure the connection.
filter
Specifies whether or not user permission based filter is on or off. Valid values are True and False. If the filter parameter is set to False - which is the default - then the authentication credentials provided must be those of an administrative user. If the filter parameter is set to True then any user can be used and the Manager will filter the actions available to the user based on their permissions.
debug
Specifies whether debug mode is enabled for this connection. Valid values are True and False. This parameter is optional.
This example script creates an instance of the API class, checks that the connection is working using the test() method, and disconnects using the disconnect() method.
from ovirtsdk.api import API    
    
api_instance = API ( url="https://rhevm31.demo.redhat.com", 
                     username="admin@internal", 
                     password="Redhat123" 
                     ca_file="/etc/pki/ovirt-engine/ca.pem")

print "Connected successfully!"

api_instance.disconnect()
For a full list of methods supported by the API class refer to the PyDoc output for the ovirtsdk.api package.

25.2. Resources and Collections

The RESTful nature of the API is evident throughout the Python bindings for both philosophical and practical reasons. All RESTful APIs have two key concepts that you need to be aware of:
Collections
A collection is a set of resources of the same type. The API provides both top level collections and sub-collections. An example of a top level collection is the hosts collection which contains all virtualization hosts in the environment. An example of a sub-collection is the host.nics collection which contains resources for all network interface cards attached to a host resource.
The interface for interacting with collections provides methods for adding resources (add), getting resources (get), and listing resources (list).
Resources
A resource in a RESTful API is an object with a fixed interface that also contains a set of attributes that are relevant to the specific type of resource being represented. The interface for interacting with resources provides methods for updating (update ) and deleting (delete) resources. Additionally some resources support actions specific to the resource type. An example is the approve method of Host resources.

25.3. Retrieving Resources from a Collection

Resources are retrieved from a collection using the get and list methods.
get
Retrieves a single resource from the collection. The item to retrieve is determined based on the name provided as an argument. The get method takes these arguments:
  • name - The name of the resource to retrieve from the collection.
list
Retrieves any number of resources from the collection. The items to retrieve are determined based on the criteria provided. The list method takes these arguments:
  • **kwargs - A dictionary of additional arguments allowing keyword based filtering.
  • query - A query written in the same format as that used for searches executed using the Red Hat Enterprise Virtualization user interfaces.
  • max - The maximum number of resources to retrieve.
  • case_sensitive - Whether or not search terms are to be treated as case sensitive (True or False, the default is True).

25.4. Retrieving a Specific Resource from a Collection

In these examples a specific resource is retrieved from a collection using the get method.

Example 25.1. Retrieving a Specific Resource by Name

Retrieving the Default data center from the datacenters collection using the name parameter of the get method:
dc = api.datacenters.get("Default")
This syntax is equivalent:
dc = api.datacenters.get(name="Default")

25.5. Retrieving a List of Resources from a Collection

In these examples a list of resources is retrieved from a collection using the list method.

Example 25.2. Retrieving a List of all Resources in a Collection

Retrieving a list of all resources in the datacenters collection. The query parameter of the list method allows the use of engine based queries. In this way the SDK supports the use of queries in the same format as those executed in the Administration and User Portals. The query parameter is also the mechanism for providing pagination arguments while iterating through the collection.
dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
In this example the list of resources contained in the datacenters collection is ultimately stored in the locally defined dc_list list variable.

Warning

The list method of a collection is restricted to returning only as many elements as allowed by the SearchResultsLimit Red Hat Enterprise Virtualization Manager configuration key.
To ensure that all records in a the list are returned it is recommended that you paginate through the results as illustrated in this example.
Alternatively you may choose to set the max parameter of the list method to the maximum number of records that you wish to retrieve.

Example 25.3. Retrieving a List of Resources in a Collection Matching a Keyword Based Filter

Retrieving a list of all resources in the datacenters collection that have a storage type of nfs. In this example both the query parameter and **kwargs parameter are supplied. The query is used for pagination in the same way as illustrated in the previous example. The **kwargs parameter is used to filter based on the storage type of the data center.
dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
In this example the list of resources contained in the datacenters collection with a storage type of nfs is ultimately stored in the locally defined dc_list list variable.

25.6. Adding a Resource to a Collection

The add method of a collection adds a resource. The resource to be added is created based on the parameters provided. Parameters are provided to the add method using an instance of an object from the ovirtsdk.xml.params module. Which specific class from the module needs to be used varies based on the type of resource being created.

Example 25.4. Adding a Resource to a Collection

In this example a virtual machine resource is created.
vm_params = params.VM(name="DemoVM",
                      cluster=api.clusters.get("Default"),
                      template=api.templates.get("Blank"),
                      memory=536870912)
vm = api.vms.add(vm_params)

While the virtual machine created by this example is not yet ready to run it illustrates the process for creating any Red Hat Enterprise Virtualization resource:
  • Create an instance of the parameter object for the type of resource being created.
  • Identify the collection to which the resource will be added.
  • Call the add method of the collection passing the parameter object as a parameter.
Some parameter objects also have complex parameters of their own.

Example 25.5. Complex Parameters

In this example an NFS data center running in full version 3.1 compatibility mode is being created. To do this it is necessary to first construct a ovirtsdk.xml.params.Version object. Then this is used as a parameter when creating an instance of a ovirtsdk.xml.params.DataCenter object containing parameters of the data center to be created. The resource is then created using the add method of the datacenters collection.
v_params = params.Version(major=3, minor=1)
dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params)
dc = api.datacenters.add(dc_params)

25.7. Updating a Resource in a Collection

To update a resource you must retrieve it from the collection it resides in, modify the desired parameters, and then call the update method for the resource to save the changes. Parameter modification is performed by using the set_* methods of the retrieved resource.

Example 25.6. Updating a Resource

In this example the data center named DemoDataCenter has its description updated.
dc = api.datacenters.get("DemoDataCenter")
dc.set_description("This data center description provided using the Python SDK")
dc.update()

25.8. Removing a Resource from a Collection

To remove a resource you must retrieve it from the collection that contains it and call the delete method of the resource.

Example 25.7. Removing a Resource from a Collection

Deleting a virtual machine named DemoVM from the vms collection:
vm = api.vms.get("DemoVM")
vm.delete()

25.9. Handling Errors

Where errors are encountered the Software Development Kit uses exceptions to highlight them. The Software Development Kit defines exception types in addition to those defined by the Python interpreter itself. These exceptions are located in the ovirtsdk.infrastructure.errors module:
  • ConnectionError
  • DisconnectedError
  • ImmutableError
  • NoCertificatesError
  • RequestError
  • UnsecuredConnectionAttemptError
These exceptions can be caught and handled like any other Python exception:

Example 25.8. Catching a ConnectionError Exception

from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://HOST",
              user="USER,
              pass="PASS,
              ca_file="/etc/pki/ovirt-engine/ca.pem")
except ConnectionError err:
    print "Connection failed: %s" % err

Chapter 26. Python Reference Documentation

Documentation generated using pydoc is available for these modules provided by the rhevm-sdk package:
If instead you wish to view the pydoc generated documentation on your local machine provide the name of the module you are interested in as an argument to the pydoc command:
$ pydoc MODULE

API Usage with cURL

This appendix provides instructions on adapting REST requests for use with cURL. cURL is a command line tool for transfering data across various protocols, including HTTP, and supports multiple platforms such as Linux, Windows, Mac OS and Solaris. Most Linux distributions include cURL as a package.
Installing cURL
A Red Hat Enterprise Linux user installs cURL with the following terminal command:
yum install curl
For other platforms, seek installation instructions on the cURL website (http://curl.haxx.se/).
Using cURL
cURL uses a command line interface to send requests to a HTTP server. Integrating a request requires the following command syntax:
Usage: curl [options] uri
The uri refers to target HTTP address to send the request. This is a location on your Red Hat Enterprise Virtualization Manager host within the API entry point path (/api).

cURL options

-X COMMAND, --request COMMAND
The request command to use. In the context of the REST API, use GET, POST, PUT or DELETE.
Example: -X GET
-H LINE, --header LINE
HTTP header to include with the request. Use multiple header options if more than one header is required.
Example: -H "Accept: application/xml" -H "Content-Type: application/xml"
-u USERNAME:PASSWORD, --user USERNAME:PASSWORD
The username and password of the Red Hat Enterprise Virtualization user. This attribute acts as a convenient replacement for the Authorization: header.
Example: -u admin@internal:p@55w0rd!
--cacert CERTIFICATE
The location of the certificate file for SSL communication to the REST API. The certificate file is saved locally on the client machine. Use the -k attribute to bypass SSL. See Chapter 2, Authentication and Security for more information on obtaining a certificate.
Example: --cacert ~/Certificates/rhevm.cer
-d BODY, --data BODY
The body to send for requests. Use with POST, PUT and DELETE requests. Ensure to specify the Content-Type: application/xml header if a body exists in the request.
Example: -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>"
Examples
The following examples show how to adapt REST requests to cURL command syntax:

Example A.1. GET request

The following GET request lists the virtual machines in the vms collection. Note that a GET request does not contain a body.
GET /api/vms HTTP/1.1
Accept: application/xml
Adapt the method (GET), header (Accept: application/xml) and URI (https://[RHEVM-Host]:8443/api/vms) into the following cURL command:
$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:8443/api/vms
An XML representation of the vms collection displays.

Example A.2. POST request

The following POST request creates a virtual machine in the vms collection. Note that a POST request requires a body.
POST /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>
Adapt the method (POST), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms) and request body into the following cURL command:
$ curl -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os></vm>" https://[RHEVM-Host]:8443/api/vms
The REST API creates a new virtual machine and displays an XML representation of the resource.

Example A.3. PUT request

The following PUT request updates the memory of a virtual machine resource. Note that a PUT request requires a body.
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <memory>1073741824</memory>
</vm>
Adapt the method (PUT), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><memory>1073741824</memory></vm>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API updates the virtual machine with a new memory configuration.

Example A.4. DELETE request

The following DELETE request removes a virtual machine resource.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Adapt the method (DELETE) and URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) into the following cURL command:
$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API removes the virtual machine. Note the Accept: application/xml request header is optional due to the empty result of DELETE requests.

Example A.5. DELETE request with body

The following DELETE request force removes a virtual machine resource as indicated with the optional body.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <force>true</force>
</action>
Adapt the method (DELETE), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<action><force>true</force></action>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API force removes the virtual machine.

cURL Library (libcurl)
In addition the the standard command line tools, cURL also features libcurl, a library for programming language integration. For more information on supported programming languages and integration methods, see the libcurl website (http://curl.haxx.se/libcurl/).

Importing Certificates

The following appendix provides examples for importing certificates for clients.

B.1. Network Security Services (NSS) Database

Network Security Services (NSS) is an set of open-source cryptography libraries that support SSL. Several Linux tools, such as cURL, use NSS to verify trusted SSL communication. This process helps a user import the rhevm.cer certificate from Section 2.1, “TLS/SSL Certification” into the local NSS Database.
For an individual user, import the rhevm.cer certificate using the following command:
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "Red Hat Enterprise Virtualization Manager" -i rhevm.cer
For all users on a system, import the rhevm.cer certificate as root using the following command:
# certutil -d sql:/etc/pki/nssdb -A -t TC -n "Red Hat Enterprise Virtualization Manager" -i rhevm.cer

B.2. Java Keystores

This appendix demonstrates how to import the X.509 certificate exported from the Red Hat Enterprise Virtualization server (See Section 2.1, “TLS/SSL Certification” for information on certificate exports) into a new Java keystore file.

Procedure B.1. Import a certificate into a new Java keystore

This process helps a user import the rhevm.cer certificate from Section 2.1, “TLS/SSL Certification” into a Java keystore. This procedure requires the keytool management utility from the Java Development Kit (JDK) available for Linux and Windows systems.
  1. Access your client machine and locate the rhevm.cer certificate.
  2. Import the rhevm.cer certificate using the Java keytool management utility.
    keytool -importcert -v -trustcacerts -keystore restapi.jks -noprompt -alias rhevm -file rhevm.cer
    The keytool utility creates a new keystore file named restapi.jks.
  3. keytool asks for the keystore password. Enter a password and keytool asks to verify it.
  4. keytool adds the rhevm.cer certificate to the restapi.jks keystore. Use keytool -list command to view the certificate's entry in the keystore:
    keytool -list -keystore restapi.jks -storepass [password]

Important

Some versions of keytool parse the certificate incorrectly. If keytool does not recognise the certificate, convert it to a different X.509 format with the openssl tool:
openssl x509 -in rhevm.cer -out rhevm.new -outform [pem|der]
This creates a file called rhevm.new to use in place of rhevm.cer.

Enumerated Value Translation

The API uses Red Hat Enterprise Virtualization Query Language to perform search queries. For more information on the Queyr Language, read the full specification in Appendix F.1. Search of the Red Hat Enterprise Virtualization Administration Guide 3.1.
Please note that certain enumerated values in the API require a different search query when using the Query Language. The following table provides a translation for these key enumerated values.

Table C.1. Enumerated value translations

Resource Type
API Enumerable Type
API Enumerable Value
Query Language Property
Query Language Value
Data Centers
data_center_states not_operational status notoperational
Network
network_states non_operational status nonoperational
Hosts
host_states non_responsive status nonresponsive
install_failed installfailed
preparing_for_maintenance preparingformaintenance
non_operational nonoperational
pending_approval pendingapproval
Virtual Machines
vm_states powering_up status poweringup
powered_down powereddown
migrating migratingfrom
migrating migratingto
not_responding notresponding
wait_for_launch waitforlaunch
reboot_in_progress rebootinprogress
saving_state savingstate
restoring_state restoringstate
image_locked imagelocked
powering_down poweringdown
os_types windows_xp os windowsxp
windows_2003 windows2003
windows_2008 windows2008
other_linux otherlinux
rhel_5 rhel5
rhel_4 rhel4
rhel_3 rhel3
windows_7 windows7
windows_7x64 windows7x64
rhel_5x64 rhel5x64
rhel_4x64 rhel4x64
rhel_3x64 rhel3x64
windows_2008x64 windows2008x64
windows_2008r2 windows2008r2x64
rhel_6 rhel6
rhel_6x64 rhel6x64

Event Codes

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

Table D.1. Event codes

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:

Table E.1. Accepted tz database codes

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 1-81.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 1-81Fri 27 Sep 2013Zac Dover
BZ#1007864 - s/Red Had/Red Hat/g
Revision 1-79Wed 15 Nov 2012Stephen Gordon
Further update for change of channel name.
Revision 1-78Wed 14 Nov 2012Dan Macpherson
Change of channel name for RHN.
Revision 1-77Mon 12 Nov 2012Dan Macpherson
Added Important admonition to SSL section.
Changed vm_payloads/vm_payload elements to payloads/payload.
Revision 1-76Wed 7 Nov 2012Stephen Gordon
BZ#859477 - Corrected minor typographical error in "Retrieving a List of Resources in a Collection Matching a Keyword".
BZ#859477 - Corrected minor typographical error in "Updating a Resource in a Collection".
Revision 1-75Mon 5 Nov 2012Stephen Gordon
BZ#859473 - Corrected minor typographical error in "Software Development Kit Prerequisites".
BZ#859476 - Corrected minor typographical error in "Connecting to the API using Python".
Revision 1-74Fri 30 Oct 2012Stephen Gordon
BZ#855975 - Corrected minor typographical error in Installing the Python SDK (Topic 11463).
Revision 1-73Fri 26 Oct 2012Stephen Gordon
Removed incorrectly added Remote Client Server Mode topic.
Revision 1-72Tue 24 Oct 2012Dan Macpherson
Removed JSON Support
Minor change to Auth example URLs
Revision 1-71Thu Oct 18 2012Stephen Gordon
Added API support statement.
Revision 1-70Wed Oct 17 2012Stephen Gordon
Added SDK exceptions documentation and updated all examples for consistency.
Revision 1-69Tue 16 Oct 2012Dan Macpherson
Added NSSDB import information
Revision 1-68Mon 15 Oct 2012Dan Macpherson
Minor revision
Revision 1-67Fri 12 Oct 2012Dan Macpherson
Documentation refresh
Revision 1-66Fri 12 Oct 2012Dan Macpherson
Correction of minor typo
Revision 1-65Fri 12 Oct 2012Dan Macpherson
Final implementation of feedback from technical review and QE
Revision 1-64Thu 11 Oct 2012Dan Macpherson
Correction to relationship mapping descriptions.
Revision 1-63Thu 11 Oct 2012Dan Macpherson
Minor typo fix.
Revision 1-61.1Wed 4 Oct 2012Stephen Gordon
Minor revision - rebuilt to get correct table of contents layout.
Revision 1-61Wed 3 Oct 2012Dan Macpherson
Minor revision - missing element items.
Revision 1-60Tue 2 Oct 2012Dan Macpherson
Added appendix and table for enumerated value translation.
Revision 1-59Mon 24 Sept 2012Stephen Gordon
Updated "25.3. Retrieving a Resource from a Collection" to provide better examples of keyword based filtering.
Revision 1-58Fri 21 Sept 2012Stephen Gordon
Updated PyDoc output for ovirtsdk package to include links to off.
Revision 1-57Thu 20 Sept 2012Stephen Gordon
Further expanded Python SDK content - adding topics 11626, 11627, 11628, and 11629. The updated topics relate to:
- Adding a Resource to a Collection
- Retrieving a Resource from a Collection
- Removing a Resource from a Collection
- Updating a Resource in a Collection
Revision 1-56Wed 19 Sept 2012Stephen Gordon
Further expanded Python SDK content - adding topics 9288, 9290, 11463, 9289, and 11607.
Revision 1-55Wed 19 Sept 2012Stephen Gordon
Added PyDoc generated documentation. Some further work required to avoid 404s at lower levels of the SDK.
Revision 1-54Tue 18 Sept 2012Daniel Macpherson
Minor typo fix
Revision 1-53Tue 18 Sept 2012Daniel Macpherson
Minor typo fixes
Added note regarding session support
BZ#858028 - REST API Guide incorrectly describes Export action
Revision 1-52Tue 5 Sept 2012Daniel Macpherson
Minor typo fixes
Revision 1-51Thu 29 Aug 2012Daniel Macpherson
Added appendix on JSON Support
Revision 1-50Thu 29 Aug 2012Daniel Macpherson
Renamed to Developer Guide
Addition of SDK content
Implementations of numerous fixes for 3.1 release:
BZ#830893 - Quotas - Ability to limit amount of resources a user can use.
BZ#847369 - Ovirt Rest API - 'from' in search is treated as parameter
BZ#791285 - Improve SEO for Guide
BZ#830864 - Create VM from snapshot
BZ#830856 - Document live snapshot capability
BZ#852263 - Typos found during translation of Beta 1
BZ#848762 - Typo in part 12.3 of the API guide
BZ#807575 - Insufficient information about adding network via REST API
BZ#818747 - CPU assignment feature [taskset]
BZ#830832 - Add support for editing multiple networks
BZ#830829 - bridgeless networks for non-VM networks
BZ#830816 - it is possible to hot plug/unplug NIC from VM during VM powering up
BZ#830836 - optional networks
BZ#830835 - port mirroring network
BZ#818738 - support non admin users in api
BZ#818742 - add support for RHEVM case-insensitive search
BZ#818744 - Add status field to api/storagedomains
BZ#818731 - Document async DELETE
BZ#833521 - Document mechanism(s) to delete and modify objects via API
BZ#827523 - Explicitly state units used for memory element of virtual machine
BZ#830489 - Document how to detach a data domain from the DC
BZ#830876 - Allow to cancel ongoing migration
BZ#830842 - Enable Sharing virtual disk between guests
BZ#830872 - Allow VM to have disks from multiple storage domains
BZ#830874 - floating disks - Decouple virtual disks with virtual machines.
BZ#830861 - Storage Live Migration of VMs disks from one data store to another
BZ#818749 - allow to pass userdata to the VM (via API only)
BZ#830823 - Allow to set MTU at logical network level (aka jumbo frames)
BZ#830890 - allow to set preferred SPM (spm priority)
BZ#830888 - add support for posix based shared file systems
BZ#830879 - hot plug/unplug disk
BZ#830875 - Raw Device Mapping functionality for RHEV
BZ#837476 - typo "an root..."
BZ#838903 - Document api RSDL (RESTful service description language)
Revision 1-49Mon Apr 2 2012Daniel Macpherson
BZ#806619 - Expanded description on CPU topology for virtual machines.
Revision 1-48Tues Mar 13 2012Daniel Macpherson
BZ#657227 - Corrections to UUIDs
Revision 1-47Wed Feb 17 2012Daniel Macpherson
BZ#771664 - Removed description from user element
BZ#657227 - Corrections to UUIDs
Revision 1-45Wed Feb 15 2012Daniel Macpherson
BZ#786410 - Add sockets attribute to host CPU.
BZ#740402 - Correction to typo.
BZ#767973 - Add destroy domain option to documentation.
BZ#765830 - Incorrect property for element in table.
Revision 1-44Tue Feb 07 2012Zac Dover
BZ#787935 - corrected a sentence at the behest of jskeoch
Revision 1-39Thu Dec 1 2011Daniel Macpherson
BZ#759326 - Removed inaccurate instruction in force delete vm
BZ#757123 - Change to vm start action example for host's placement_policy.
BZ#754574 - Correction to XML examples.
BZ#754351 - Corrections to cURL and XML examples.
Revision 1-38Thu Nov 24 2011Stephen Gordon
BZ#756789 - Corrections to arguments in cURL examples.
Revision 1-37Fri Nov 11 2011Daniel Macpherson
BZ#750323, BZ#750325 - Corrections to typos in examples.
Revision 1-36Mon Oct 31 2011Daniel Macpherson
Minor corrections.
Revision 1-35Thu Oct 27 2011Daniel Macpherson
Added admonitions for sections excluded from Backwards Compatibility Statement.
Revised cURL Usage appendix to ensure markup is similar to other RHEV documentation.
Revision 1-34Thu Oct 27 2011Daniel Macpherson
Added Backwards Compatibility Statement to Preface.
Revision 1-33Wed Oct 26 2011Daniel Macpherson
Added three examples to cURL integration appendix.
Revision 1-32Tue Oct 25 2011Daniel Macpherson
Proofread examples.
Added cURL integration Appendix.
Modified Storage Domains Sub-Collection section in Data Center chapter to make Attaching Storage Domain instructions prominent in TOC.
Revision 1-31Thu Oct 19 2011Daniel Macpherson
Minor changes for localization purposes.
Revision 1-30Wed Oct 12 2011Daniel Macpherson
BZ#739993 - Added Pagination section under Search Queries in the Common Features chapter.
BZ#743592 - Added sentence on setting no preferred host in placement_policy for Virtual Machines.
Minor changes for localization purposes.
Revision 1-29Tue Oct 4 2011Daniel Macpherson
Minor fixes to typos in examples.
Revision 1-28Tue Oct 4 2011Daniel Macpherson
BZ#742863 - Capabilities chapter: Changed CPU types in example.
BZ#742775 - Coverted enumerated values to lowercase.
Revision 1-27Fri Sept 30 2011Daniel Macpherson
BZ#740523 - Added section on cloning disks from a virtual machine template.
Minor changes for localization purposes.
Revision 1-26Wed Sept 28 2011Daniel Macpherson
BZ#739993 - Added section for paginating events.
Revision 1-25Fri Sept 22 2011Daniel Macpherson
BZ#738478 - Removal of element in the Example chapter
BZ#739897 - Added host element to storage domain creation
BZ#740471 - Amended section on querying collections to include sortby instructions
BZ#740401, BZ#740402 - Completed docs Quality Engineering Review
Revision 1-23Fri Sept 19 2011Daniel Macpherson
BZ#737860 - Minor change to VM origin in VM creation example.
Revision 1-22Fri Sept 9 2011Daniel Macpherson
BZ#734463 - Updated element tables in VM disks, VM NICs and Host NICs sub-collections to include statistics link.
BZ#734634 - Fixed storage_domains element in example and VM disks section.
Revision 1-21Thu Sept 8 2011Daniel Macpherson
BZ#734436 - Added elements for product_info in Entry Point chapter.
BZ#695635 - Added minor addition to DELETE methods without Content-Type header.
BZ#719501 - Added sysprep (domain and timezone) documentation for virtual machines and templates.
BZ#734634 - Fixed missing storage domain in disk creation example.
BZ#734463 - Added/improved statistics documentation for Hosts, Host NICs, VMs, VM disks and VM NICs.
Revision 1-18Thu Aug 24 2011Daniel Macpherson
BZ#695635 - Added new section on force remove action for data centers.
BZ#680858 - Added new section on force remove action for virtual machines.
BZ#702895 - Provided additional information on changing virtual machine CD-ROM images.
BZ#730565 - Added new section for TLS/SSL certification and an Appendix for importing a certificate to a Java keystore.
BZ#729898 - Added references to Content-type: xml/application header for requests that require a body. Reviewed headers in all examples.
BZ#720593 - Included documentation on event search queries using the "from" URI parameter.
BZ#719570 - Updated Network Interface sub-collection in Virtual Machines chapter to specify references to network are made with either "id" or "name" when creating or modifying a new resource. Updated Network Interface sub-collection in Templates chapter to remove read-only status and specify same rules as Network Interface sub-collection in Virtual Machines chapter.
Revision 1-17Thu Aug 04 2011Daniel Macpherson
Final QE Revisions
Revision 1-16Thu Aug 04 2011Daniel Macpherson
Minor change to entry point image
Revision 1-15Thu Aug 04 2011Daniel Macpherson
Minor fixes to content
Revision 1-14Thu Aug 04 2011Daniel Macpherson
Revised Guide as per Quality Engineering feedback (BZ#723767, BZ#723773, BZ#723776, BZ#723769, BZ#723768, BZ#723770, BZ#723774, BZ#723775, BZ#723777, BZ#723771)
Revision 1-12Tue Jul 19 2011Daniel Macpherson
Revised Guide as per Tech Review
Revision 1-11Thu Jul 7 2011Daniel Macpherson
Updated Preface to include Documentation Suite
Revision 1-10Thu Jul 7 2011Daniel Macpherson
Minor edits to content
Revision 1-9Thu Jul 7 2011Daniel Macpherson
Minor edits to content
Revised Entry Point Image to include new collections
Revision 1-8Wed Jul 6 2011Daniel Macpherson
Finalization of draft content
Revision 1-6Thu Jun 30 2011Daniel Macpherson
Revised structure for version 3.0
Revision 1-5Mon Jun 20 2011Daniel Macpherson
Added new elements and document structure for version 3.0
Revision 1-4Thu Jun 16 2011Daniel Macpherson
Draft revision of document
Inclusion of Example chapter