Red Hat Enterprise Virtualization 3.2 Developer Guide

Andrew Burden Steve Gordon Dan Macpherson

Red Hat Enterprise Virtualization3.2Developer Guide

Using the Red Hat Enterprise Virtualization Application ProgrammingInterfacesEdition 1

Red Hat Enterprise Virtualization 3.2 Developer Guide

Using the Red Hat Enterprise Virtualization Application ProgrammingInterfacesEdition 1

Andrew [email protected]

Steve [email protected]

Dan [email protected]

Legal Notice

Copyright © 2013 Red Hat, Inc..

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 UnportedLicense. If you distribute this document, or a modified version of it, you must provide attribution to RedHat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must beremoved.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section4d 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 Statesand/or other countries.

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

Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to orendorsed by the official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack Logo are either registered trademarks/service marks ortrademarks/service marks of the OpenStack Foundation, in the United States and other countries andare used with the OpenStack Foundation's permission. We are not affiliated with, endorsed orsponsored 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 API and SDK.

http://creativecommons.org/licenses/by-sa/3.0/

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of Contents

Preface1. Document Conventions

1.1. Typographic Conventions1.2. Pull-quote Conventions1.3. Notes and Warnings

2. Getting Help and Giving Feedback2.1. Do You Need Help?2.2. We Need Feedback!

Part I. Introduction

Chapter 1. Introduction1.1. Introduction to the Red Hat Enterprise Virtualization REST API1.2. Representational State Transfer1.3. Red Hat Enterprise Virtualization REST API Prerequisites

Chapter 2. Authentication and Security2.1. TLS/SSL Certification2.2. HTTP Authentication2.3. Authentication Sessions

Chapter 3. REST API Quick Start Example3.1. REST API Quick Start Introduction3.2. Example: Access API Entry Point3.3. Example: List Data Center Collection3.4. Example: List Host Cluster Collection3.5. Example: List Logical Networks Collection3.6. Example: List Host Collection3.7. Example: Approve Host3.8. Example: Create NFS Data Storage3.9. Example: Create NFS ISO Storage3.10. Example: Attach Storage Domains to Data Center3.11. Example: Activate Storage Domains3.12. Example: Create Virtual Machine3.13. Example: Create Virtual Machine NIC3.14. Example: Create Virtual Machine Storage Disk3.15. Example: Attach ISO Image to Virtual Machine3.16. Example: Start Virtual Machine3.17. Example: Check System Events

Chapter 4 . Python Quick Start Example4.1. Python Quick Start Introduction4.2. Example: Accessing the API Entry Point using Python4.3. Example: Listing the Data Center Collection using Python4.4. Example: Listing the Cluster Collection using Python4.5. Example: Listing the Logical Networks Collection using Python4.6. Example: Listing the Host Collection using Python4.7. Example: Approving a Host using Python4.8. Example: Creating NFS Data Storage using Python4.9. Example: Creating NFS ISO Storage using Python4.10. Example: Attaching Storage Domains to a Data Center using Python4.11. Example: Activating Storage Domains using Python4.12. Example: Creating a Virtual Machine using Python

1010101112121213

14

15151515

17171819

212121242527283132343637384141424344

4 7474848495051525355575859

Table of Contents

1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.13. Example: Creating a Virtual Machine NIC using Python4.14. Example: Creating a Virtual Machine Storage Disk using Python4.15. Example: Attaching an ISO Image to a Virtual Machine using Python4.16. Example: Starting a Virtual Machine using Python4.17. Example: Checking System Events using Python

Part II. REST Application Programming Interface

Chapter 5. Entry Point5.1. Accessing the API Entry Point5.2. Product Information5.3. Link Elements5.4. Special Object Elements5.5. Summary Element5.6. RESTful Service Description Language (RSDL)

Chapter 6. Compatibility Level Versions6.1. Compatibility Level Versions6.2. Upgrading Compatibility Levels

Chapter 7. Capabilit ies7.1. Capabilities7.2. Version-Dependent Capabilities7.3. Current Version7.4. Features7.5. CPUs7.6. Power Managers7.7. Fence Types7.8. Storage Types7.9. Storage Domain Types7.10. Virtual Machine Types7.11. Boot Devices7.12. Display Types7.13. NIC Interface Types7.14. OS Types7.15. Disk Formats7.16. Disk Interfaces7.17. Virtual Machine Affinities7.18. Custom Properties7.19. Boot Protocols7.20. Error Handling7.21. Storage Formats7.22. Virtual Machine Device Types7.23. Gluster Volume Types7.24. Gluster Transport Types7.25. Guster Access Protocols7.26. Resource Status States7.27. Permits7.28. Scheduling Policies

Chapter 8. Common Features8.1. Element Property Icons8.2. Representations

8.2.1. Representations8.2.2. Common Attributes to Resource Representations8.2.3. Common Elements to Resource Representations

8.3. Collections

6163656768

70

71717272747475

787878

8181818181828383848485858586868787878888888989899090909191

92929292929393


2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8.3.1. Collections8.3.2. Listing All Resources in a Collection8.3.3. Listing Extended Resource Sub-Collections8.3.4. Searching Collections with Queries8.3.5. Maximum Results Parameter8.3.6. Case Sensitivity8.3.7. Query Syntax8.3.8. Wildcards8.3.9. Pagination8.3.10. Creating a Resource in a Collection8.3.11. Asynchronous Requests

8.4. Resources8.4.1. Resources8.4.2. Retrieving a Resource8.4.3. Updating a Resource8.4.4. Deleting a Resource8.4.5. Sub-Collection Relationships8.4.6. XML Element Relationships8.4.7. Actions8.4.8. Permissions8.4.9. Handling Errors

Chapter 9. Data Centers9.1. Data Center Elements9.2. XML Representation of a Data Center9.3. Methods

9.3.1. Creating a New Data Center9.3.2. Updating a Data Center9.3.3. Removing a Data Center

9.4. Sub-Collections9.4.1. Storage Domains Sub-Collection

9.4.1.1. Storage Domains Sub-Collection9.4.1.2. Attaching and Detaching a Storage Domain9.4.1.3. Actions

9.4.1.3.1. Activate Storage Domain Action9.4.1.3.2. Deactivate Storage Domain Action

9.4.2. Quotas Sub-Collection9.5. Actions

9.5.1. Force Remove Data Center Action

Chapter 10. Host Clusters10.1. Host Cluster Elements10.2. Memory Policy Elements10.3. Scheduling Policy Elements10.4. XML Representation of a Host Cluster10.5. Methods

10.5.1. Creating a Host Cluster10.5.2. Updating a Host Cluster10.5.3. Removing a Host Cluster

10.6. Sub-Collections10.6.1. Networks Sub-Collection10.6.2. Storage Volumes Sub-Collection

10.6.2.1. Red Hat Storage Volumes Sub-Collection10.6.2.2. Bricks Sub-Collection10.6.2.3. Actions

10.6.2.3.1. Start Action

939394949595959697979899999999

100100101101103104

106106106107107107108108108108108110110110110111111

113113114114115116116117117117117119119122123123

Table of Contents

3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.6.2.3.2. Stop Action10.6.2.3.3. Set Option Action10.6.2.3.4. Reset Option Action10.6.2.3.5. Reset All Options Action

Chapter 11. Networks11.1. Network Elements11.2. XML Representation of a Network Resource11.3. Methods

11.3.1. Creating a Network Resource11.3.2. Updating a Network Resource11.3.3. Removing a Network Resource

Chapter 12. Storage Domains12.1. Storage Domain Elements12.2. XML Representation of a Storage Domain12.3. Methods

12.3.1. Creating a Storage Domain12.3.2. Updating a Storage Domain12.3.3. Removing a Storage Domain

12.4. Storage Types12.4.1. Storage Types12.4.2. NFS Storage12.4.3. PosixFS Storage12.4.4. iSCSI and FCP Storage12.4.5. LocalFS Storage

12.5. Export Storage Domains12.5.1. Export Storage Domains

12.6. Sub-Collections12.6.1. Files Sub-Collection

12.7. Actions12.7.1. Importing an Existing Storage Domain12.7.2. Deleting a Storage Domain

Chapter 13. Hosts13.1. Host Elements13.2. XML Representation of a Host13.3. Power Management Elements13.4. Memory Management Elements13.5. Methods

13.5.1. Creating a Host13.5.2. Updating a Host13.5.3. Removing a Host

13.6. Sub-Collections13.6.1. Host Network Interface Sub-Collection

13.6.1.1. Host Network Interface Sub-Collection13.6.1.2. Bonded Interfaces13.6.1.3. Network Interface Statistics13.6.1.4. Actions

13.6.1.4.1. Attach Network to Host Action13.6.1.4.2. Detach Network from Host Action13.6.1.4.3. Multiple Network Setup Action

13.6.2. Storage Sub-Collection13.6.3. Host Statistics Sub-Collection

13.7. Actions13.7.1. Install VDSM Action

123123124124

125125125126126126127

128128130130130131131131131131132132133133133136136137137138

14 0140142145146147147148148148148148151152154154154155156156158158


4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13.7.2. Activate Host Action13.7.3. Fence Host Action13.7.4. Deactivate Host Action13.7.5. Approve Host Action13.7.6. Host iSCSI Login Action13.7.7. Host iSCSI Discover Action13.7.8. Commit Host Network Configuration Action

Chapter 14 . Virtual Machines14.1. Virtual Machine Elements14.2. XML Representation of a Virtual Machine14.3. Methods

14.3.1. Creating a Virtual Machine14.3.2. Updating a Virtual Machine14.3.3. Removing a Virtual Machine14.3.4. Removing a Virtual Machine but not the Virtual Disk

14.4. Sub-Collections14.4.1. Disks Sub-Collection

14.4.1.1. Disks Sub-Collection14.4.1.2. Disk Cloning14.4.1.3. Disk Statistics Sub-Collection14.4.1.4. Floating Disk Attach and Detach Actions14.4.1.5. Disk Activate and Deactivate Actions

14.4.2. Network Interfaces Sub-Collection14.4.2.1. Network Interfaces Sub-Collection14.4.2.2. Network Interface Statistics Sub-Collection

14.4.3. CD-ROMs Sub-Collection14.4.4. Snapshots Sub-Collection

14.4.4.1. Snapshots Sub-Collection14.4.4.2. Clone a Virtual Machine from a Snapshot

14.4.5. Statistics Sub-Collection14.5. Actions

14.5.1. Start Virtual Machine Action14.5.2. Stop Virtual Machine Action14.5.3. Shutdown Virtual Machine Action14.5.4. Suspend Virtual Machine Action14.5.5. Detach Virtual Machine from Pool Action14.5.6. Migrate Virtual Machine Action14.5.7. Cancel Virtual Machine Migration Action14.5.8. Export Virtual Machine Action14.5.9. Virtual Machine T icket Action14.5.10. Force Remove Virtual Machine Action

Chapter 15. Floating Disks15.1. Floating Disk Elements15.2. XML Representation of a Floating Disk15.3. Methods

15.3.1. Creating a Floating Disk15.4. Sub-Collections

15.4.1. Statistics Sub-Collection

Chapter 16. Templates16.1. Virtual Machine Template Elements16.2. XML Representation of a Virtual Machine Template16.3. Methods

16.3.1. Creating a New Template

159159159160160160161

162162166169169170171171171171171174175176177178178180181183183184185186186187188188188189189189190191

192192194194194195195

197197200200201

Table of Contents

5

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16.3.2. Updating a Template16.3.3. Removing a Template

16.4. Actions16.4.1. Export Template Action

Chapter 17. Virtual Machine Pools17.1. Virtual Machine Pool Elements17.2. XML Representation of a Virtual Machine Pool17.3. Methods

17.3.1. Creating a New Virtual Machine Pool17.3.2. Updating a Virtual Machine Pool17.3.3. Removing a Virtual Machine Pool

Chapter 18. Domains18.1. Domain Elements18.2. XML Representation of a Domain Resource18.3. Sub-Collections

18.3.1. Domain Users Sub-Collection18.3.2. Domain Groups Sub-Collection

Chapter 19. Groups19.1. Imported Group Elements19.2. XML Representation of a Group Resource19.3. Adding a Group from a Directory Service

Chapter 20. Roles20.1. Role Elements20.2. XML Representation of the Roles Collection20.3. Methods

20.3.1. Creating a Role20.3.2. Updating a Role20.3.3. Removing a Role

20.4. Roles Permits Sub-Collection20.4.1. Roles Permits Sub-Collection20.4.2. Assign a Permit to a Role20.4.3. Remove a Permit from a Role

Chapter 21. Users21.1. User Elements21.2. XML representation of a User Resource21.3. Methods

21.3.1. Adding a User21.3.2. Adding Roles to a User

Chapter 22. Tags22.1. Tag Elements22.2. XML Representation of a Tag Resource22.3. Associating Tags

22.3.1. Associating Tags With a Host, User or VM22.3.2. Removing a Tag22.3.3. Querying a Collection for Tagged Resources

22.4. Parent Tags22.4.1. Parent Tags22.4.2. Setting a Parent Tag22.4.3. Changing a Parent Tag

Chapter 23. Events

201201201201

203203203203203204204

205205205205205206

208208208208

210210210211211212212212212213213

215215215216216217

218218218218218219219220220221222

224


6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23.1. Event Elements23.2. XML Representation of the Events Collection23.3. XML Representation of a Virtual Machine Creation Event23.4. Searching Events23.5. Paginating Events

Part III. Python Sofware Development Kit

Chapter 24 . Software Development Kit Overview24.1. Introduction to the Red Hat Enterprise Virtualization Software Development Kit24.2. Software Development Kit Prerequisites24.3. Installing the Software Development Kit

Chapter 25. Using the Software Development Kit25.1. Connecting to the API using Python25.2. Resources and Collections25.3. Retrieving Resources from a Collection25.4. Retrieving a Specific Resource from a Collection25.5. Retrieving a List of Resources from a Collection25.6. Adding a Resource to a Collection25.7. Updating a Resource in a Collection25.8. Removing a Resource from a Collection25.9. Handling Errors

Chapter 26. Python Reference Documentation26.1. Python Reference Documentation

SDK ExamplesA.1. Common StatementsA.2. Common Functions and WrappersA.3. Python SDK Example: HostsA.4. Python SDK Example: Virtual MachinesA.5. Python SDK Example: TemplatesA.6. Python SDK Example: Virtual Machine PoolsA.7. Python SDK Example: StorageA.8. Python SDK Example: GroupsA.9. Python SDK Example: PermissionsA.10. Python SDK Example: Users

API Usage with cURLB.1. API Usage with cURLB.2. Installing cURLB.3. Using cURLB.4. Examples

B.4.1. GET Request with cURLB.4.2. POST Request with cURLB.4.3. PUT Request with cURLB.4.4. DELETE Request with cURLB.4.5. DELETE Request Including Body with cURL

CertificatesC.1. Creating SSL/TLS CertificatesC.2. Creating an SSL CertificateC.3. Configuring HTTPS CommunicationC.4. Network Security Services (NSS) DatabaseC.5. Java Keystores

224224224225226

228

229229229229

231231232233233234235236236236

238238

239239240246250257259261267270275

279279279279280280280281282282

284284285286287287

Table of Contents

7

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Enumerated Value TranslationD.1. Enumerated Value Translation

Event CodesE.1. Event Codes

TimezonesF.1. T imezones

Revision History

289289

292292

304304

308


8

Table of Contents

9

Preface

1. Document ConventionsThis manual uses several conventions to highlight certain words and phrases and draw attention tospecific pieces of information.

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

1.1. Typographic ConventionsFour typographic conventions are used to call attention to specific words and phrases. Theseconventions, 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 highlightkeys and key combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current workingdirectory, enter the cat my_next_bestselling_novel command at the shell promptand 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 alldistinguishable thanks to context.

Key combinations can be distinguished from an individual key by the plus sign that connects each part ofa 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 valuesmentioned 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 fordirectories. Each class has its own associated set of permissions.

Proportional Bold

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

Choose System → Preferences → Mouse from the main menu bar to launch MousePreferences. In the Buttons tab, select the Left-handed mouse check box and clickClose to switch the primary mouse button from the left to the right (making the mousesuitable for use in the left hand).

To insert a special character into a gedit file, choose Applications → Accessories →


10

https://fedorahosted.org/liberation-fonts/

Character Map from the main menu bar. Next, choose Search → Find… from theCharacter Map menu bar, type the name of the character in the Search field and clickNext. The character you sought will be highlighted in the Character Table. Double-clickthis highlighted character to place it in the Text to copy field and then click the Copybutton. Now switch back to your document and choose Edit → Paste from the gedit menubar.

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

Mono-spaced Bold Italic or Proportional Bold Italic

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

To connect to a remote machine using ssh, type ssh [email protected] at a shellprompt. If the remote machine is example.com and your username on that machine isjohn, type ssh [email protected] .

The mount -o remount file-system command remounts the named file system. Forexample, 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. Itwill return a result as follows: package-version-release.

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

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

Publican is a DocBook publishing system.

1.2. Pull-quote ConventionsTerminal 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 svnbooks_tests Desktop1 downloads images notes scripts svgs

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

Preface

11

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;}

1.3. Notes and WarningsFinally, 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 shouldhave 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 thecurrent session, or services that need restarting before an update will apply. Ignoring a boxlabeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

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

2. Getting Help and Giving Feedback

2.1. Do You Need Help?If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer


12

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

2.2. We Need Feedback!If you find a typographical error in this manual, or if you have thought of a way to make this manualbetter, 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 whendescribing it. If you have found an error, please include the section number and some of the surroundingtext so we can find it easily.

Preface

13

http://access.redhat.com

https://www.redhat.com/mailman/listinfo

http://bugzilla.redhat.com/

Part I. Introduction


14

Chapter 1. Introduction

1.1. Introduction to the Red Hat Enterprise Virtualization REST APIRed Hat Enterprise Virtualization Manager provides a Representational State Transfer (REST) API.The API provides software developers and system administrators with control over their Red HatEnterprise Virtualization environment outside of the standard web interface. The REST API is useful fordevelopers and administrators who aim to integrate the functionality of a Red Hat EnterpriseVirtualization environment with custom scripts or external applications that access the API via thestandard Hypertext Transfer Protocol (HTTP).

The benefits of the REST API are:

Broad client support - Any programming language, framework, or system with support for HTTPprotocol can use the API;

Self descriptive - Client applications require minimal knowledge of the virtualization infrastructure asmany details are discovered at runtime;

Resource-based model - The resource-based REST model provides a natural way to manage avirtualization 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. Itaims to provide developers and administrators with instructions and examples to help harness thefunctionality of their Red Hat Enterprise Virtualization environment through the REST API either directlyor using the provided Python libraries.

Report a bug

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

Report a bug

1.3. Red Hat Enterprise Virtualization REST API PrerequisitesThis 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

Chapter 1. Introduction

15

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8595-342847+%5BSpecified%5D&cf_build_id=8595-342847+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Introduction+to+the+Red+Hat+Enterprise+Virtualization+REST+API%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8594-301722+%5BSpecified%5D&cf_build_id=8594-301722+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Representational+State+Transfer%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

example:

Red Hat Enterprise Virtualization 3.1 and higher provides a Python software development kit(SDK) that interacts with the REST API. This guide includes a Python Beginner Example to helpdevelopers get started with using the SDK.

This guide includes basic instructions on use with cURL.

Knowledge of Hypertext Transfer Protocol (HTTP), which is the protocol used for REST APIinteractions. 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 resourcerepresentations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml/.

Note

Each version of Red Hat Enterprise Virtualization has a unique SDK associated with it. Pleaseensure that you are using the correct SDK for your current environment. For example, if you areusing Red Hat enterprise Virtualization 3.2, you should be using the SDK developed for 3.2.

Additionally, to use the Python SDK you will need to download and install the rhevm-sdk package. Thispackage is available to systems subscribed to a Red Hat Enterprise Virtualizationentitlement pool if using certificate-based Red Hat Network, or the Red Hat Enterprise Virtualization Manager channel if using Red Hat Network classic. See the Red Hat EnterpriseVirtualization Installation Guide for more information on subscribing your system(s) to downloadsoftware from these locations.

Note

Refer to the Red Hat Enterprise Virtualization Manager Release Notes for specific channel namescurrent to your system.

Report a bug


16

http://www.ietf.org/rfc/rfc2616.txt

http://www.w3.org/TR/xml/

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7929-493176+%5BSpecified%5D&cf_build_id=7929-493176+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Red+Hat+Enterprise+Virtualization+REST+API+Prerequisites%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 2. Authentication and Security

2.1. TLS/SSL CertificationThe Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure(HTTPS) for secure interaction with client software, such as the Manager's SDK and CLI components.This involves a process of attaining a certificate from your Red Hat Enterprise Virtualization Managerserver and importing it into your client's certificate store.

Important

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

Procedure 2.1. Attain a certificate

This process helps a user attain a certificate from the Red Hat Enterprise Virtualization Manager andtransfer 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 ofcommand line tools include cURL and Wget ; both are available for multiple platforms.

a. If using cURL:

curl -o rhevm.cer http://[rhevm-server]/ca.crt

b. 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'skeystore.

a. 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 optionsand save it as rhevm.cer.

3. Method 3 - Access your Red Hat Enterprise Virtualization Manager server either physically orthrough a secure shell (SSH) client, export the certificate from the server's keystore and copy it toyour client machine.

a. Access your Red Hat Enterprise Virtualization Manager server as the root user.

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

c. Copy the certificate to the client machine using the scp command:

[1]


17

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 APIuser 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. Thisguide contains some examples on importing certificates. For clients not using Network SecurityServices (NSS) or Java KeyStore (JKS), please refer to your client documentation for moreinformation on importing a certificate.

Report a bug

2.2. HTTP AuthenticationAny user with a Red Hat Enterprise Virtualization account has access to the REST API. An API usersubmits a mandatory Red Hat Enterprise Virtualization Manager username and password with allrequests to the API. Each request uses HTTP Basic Authentication to encode these credentials. If arequest 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.1Host: [host]

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. An API user encodes anappropriate Red Hat Enterprise Virtualization Manager domain and user in the supplied credentials withthe 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 [email protected]:123456

base64 encodedcredentials

cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

An API user provides the base64 encoded credentials as shown:

[2]


18

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7555-435339+%5BSpecified%5D&cf_build_id=7555-435339+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+TLS%2FSSL+Certification%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 2.2. Access to the REST API with appropriate credentials

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

HTTP/1.1 200 OK...

Important

Basic authentication involves potentially sensitive information, such as passwords, sent as plaintext. REST API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-levelencryption of plain-text requests.

Important

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

Report a bug

2.3. Authentication SessionsThe API also provides the ability for authentication session support. An API user sends an initial requestwith 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.1Host: [host]Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2Prefer: 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 withthe JSESSIONID= value. The Authorization is no longer needed when using an


19

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8596-365095+%5BSpecified%5D&cf_build_id=8596-365095+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+HTTP+Authentication%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

authenticated session.

HEAD [base] HTTP/1.1Host: [host]Prefer: persistent-authcookie: 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.1Host: [host]Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK...

Report a bug

[1] HTTPS is d escrib ed in RFC 28 18 HTTP Over TLS.

[2] Basic Authenticatio n is d escrib ed in RFC 26 17 HTTP Authenticatio n: Basic and Dig est Access Authenticatio n.


20

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12747-365966+%5BSpecified%5D&cf_build_id=12747-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Authentication+Sessions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

http://tools.ietf.org/html/rfc2818


Chapter 3. REST API Quick Start Example

3.1. REST API Quick Start IntroductionThis chapter provides an example to demonstrate the REST API's ability to setup a basic Red HatEnterprise Virtualization environment and create a virtual machine.

In addition to the standard 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 RedHat Enterprise Linux Server 6 for our installation ISO example; and

Red Hat Enterprise Virtualization's rhevm-iso-uploader tool to upload your chosen operatingsystem ISO file.

This example uses cURL to demonstrate REST requests with a client application. Note that anyapplication 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 RedHat Enterprise Virtualization Manager.

Important

All cURL examples include placeholders for authentication details (USER:PASS) and certificatelocation (CERT ). Ensure all requests performed with cURL fulfil certification and authenticationrequirements.

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 theidentifier codes in your Red Hat Enterprise Virtualization environment.

Report a bug

3.2. Example: Access API Entry PointThe following request retrieves a representation of the main entry point of the API.


21

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8597-342869+%5BSpecified%5D&cf_build_id=8597-342869+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+REST+API+Quick+Start+Introduction%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.1. Access the API entry point

Request:

GET /api HTTP/1.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] https://[RHEVM Host]:443/api

Result:


22

HTTP/1.1 200 OKContent-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>


23

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

Report a bug

3.3. Example: List Data Center CollectionRed Hat Enterprise Virtualization Manager creates a Default data center on installation. This exampleuses the Default data center as the basis for our virtual environment.

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


24

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7640-367053+%5BSpecified%5D&cf_build_id=7640-367053+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Access+API+Entry+Point%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.2. List data center collection

Request:

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

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/datacenters

Result:


<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 otherresources of your virtual environment.

The data center also contains a link to the storagedomains sub-collection. The data center uses thissub-collection to attach storage domains from the storagedomains main collection, which thisexample covers later.

Report a bug

3.4. Example: List Host Cluster CollectionRed Hat Enterprise Virtualization Manager creates a Default host cluster on installation. This exampleuses the Default cluster to group resources in your Red Hat Enterprise Virtualization environment.


25

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7641-367054+%5BSpecified%5D&cf_build_id=7641-367054+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+List+Data+Center+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The following request retrieves a representation of the cluster collection:

Example 3.3. List host clusters collection

Request:

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

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/clusters

Result:


<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 otherresources of your virtual environment.

The Default cluster is associated with the Default data center through a relationship using the idand href attributes of the data_center element.

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


26

Report a bug

3.5. Example: List Logical Networks CollectionRed Hat Enterprise Virtualization Manager creates a default rhevm network on installation. This networkacts as the management network for Red Hat Enterprise Virtualization Manager to access hypervisorhosts.

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.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/networks

Result:


<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 datacenter's id code.

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

Report a bug


27

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7642-367056+%5BSpecified%5D&cf_build_id=7642-367056+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+List+Host+Cluster+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7643-367058+%5BSpecified%5D&cf_build_id=7643-367058+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+List+Logical+Networks+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

3.6. Example: List Host CollectionThis example uses a Red Hat Enterprise Virtualization Hypervisor host. Red Hat EnterpriseVirtualization Manager automatically registers any configured Red Hat Enterprise VirtualizationHypervisor. This example retrieves a representation of the hosts collection and shows a Red HatEnterprise Virtualization Hypervisor host named hypervisor registered with the virtualizationenvironment.


28

Example 3.5. List hosts collection

Request:

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

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/hosts

Result:


29

HTTP/1.1 200 OKAccept: 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>


30

<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 ofyour virtual environment.

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

Report a bug

3.7. Example: Approve HostThe 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.1Accept: application/xmlContent-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]:443/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 doesnot require additional parameters, the body contains an empty action element.

Use the approve action only for Red Hat Enterprise Virtualization Hypervisor hosts. Red Hat EnterpriseLinux 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 hypervisorchanges from non_operational to up.


31

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7644-367060+%5BSpecified%5D&cf_build_id=7644-367060+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+List+Host+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

3.8. Example: Create NFS Data StorageAn NFS data storage domain is an exported NFS share attached to a data center and provides storagefor virtualized guest images. Creation of a new storage domain requires a POST request, with thestorage domain representation included, sent to the URL of the storage domain collection.


32

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7645-367062+%5BSpecified%5D&cf_build_id=7645-367062+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Approve+Host%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.7. Create an NFS data storage domain

Request:

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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]:443/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:


33


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

Report a bug

3.9. Example: Create NFS ISO StorageAn NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage forDVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domain requires aPOST request, with the storage domain representation included, sent to the URL of the storage domaincollection.


34

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7646-367064+%5BSpecified%5D&cf_build_id=7646-367064+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Create+NFS+Data+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.8. Create an NFS ISO storage domain

Request:

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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]:443/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. TheAPI also returns the following representation of the newly created storage domain resource.

Result:


35


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

Report a bug

3.10. Example: Attach Storage Domains to Data CenterThe 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.1Accept: application/xmlContent-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]:443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains


36

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7647-367065+%5BSpecified%5D&cf_build_id=7647-367065+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Create+NFS+ISO+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Request:

POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1Accept: application/xmlContent-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]:443/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 containsattached storage domains of the data center.

Report a bug

3.11. Example: Activate Storage DomainsThis example activates the data1 and iso1 storage domains for the Red Hat Enterprise VirtualizationManager's use.


37

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7648-367067+%5BSpecified%5D&cf_build_id=7648-367067+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Attach+Storage+Domains+to+Data+Center%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-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]:443/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.1Accept: application/xmlContent-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]:443/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.

Report a bug

3.12. Example: Create Virtual MachineThe following example creates a virtual machine called vm1 on the Default cluster using thevirtualization 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.


38

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7649-367070+%5BSpecified%5D&cf_build_id=7649-367070+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Activate+Storage+Domains%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.13. Create a virtual machine

Request:

POST /api/vms HTTP/1.1Accept: application/xmlContent-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]:443/api/vms

Result:


39


<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"


40

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>

Report a bug

3.13. Example: Create Virtual Machine NICThe 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.1Accept: application/xmlContent-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]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics

Report a bug

3.14. Example: Create Virtual Machine Storage DiskThe following example creates an 8 GB Copy-On-Write storage disk for the example virtual machine.


41

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7650-367072+%5BSpecified%5D&cf_build_id=7650-367072+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Create+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7651-367074+%5BSpecified%5D&cf_build_id=7651-367074+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Create+Virtual+Machine+NIC%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.15. Create a virtual machine storage disk

Request:

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1Accept: application/xmlContent-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]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks

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

Report a bug

3.15. Example: Attach ISO Image to Virtual MachineThe boot media for our example virtual machine requires an CD-ROM or DVD ISO image for an operatingsystem 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 HatEnterprise Virtualization Platform provides an uploader tool that ensures that the ISO images areuploaded 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 viewthe file resource:


42

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7652-367076+%5BSpecified%5D&cf_build_id=7652-367076+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Create+Virtual+Machine+Storage+Disk%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] \ https://[RHEVM Host]:443/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.1Accept: application/xmlContent-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]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms

Report a bug

3.16. Example: Start Virtual Machine


43

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7653-367077+%5BSpecified%5D&cf_build_id=7653-367077+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Attach+ISO+Image+to+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The virtual environment is complete and the virtual machine contains all necessary components tofunction. 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.1Accept: application/xmlContent-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]:443/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. Thisenables the virtual machine to install Red Hat Enterprise Server 6 from the attached ISO image. The bootdevice reverts back to disk for all future boots.

Report a bug

3.17. Example: Check System EventsThe start action for the vm1 creates several entries in the events collection. This example lists theevents collection and identifies events specific to the API starting a virtual machine.


44

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7654-367080+%5BSpecified%5D&cf_build_id=7654-367080+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Start+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 3.19. List the events collection

Request:

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

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/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.

Report a bug


45

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7655-367082+%5BSpecified%5D&cf_build_id=7655-367082+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Check+System+Events%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer


46

Chapter 4. Python Quick Start Example

4.1. Python Quick Start IntroductionThis chapter provides a series of examples demonstrating the steps to create a virtual machine within abasic Red Hat Enterprise Virtualization environment, using the Python SDK.

These examples use the ovirtsdk Python library provided by the rhevm-sdk package. This package isavailable to systems subscribed to a Red Hat Enterprise Virtualization entitlement pool ifusing certificate-based Red Hat Network, or the Red Hat Enterprise Virtualization Managerchannel if using Red Hat Network classic. See the Red Hat Enterprise Virtualization Installation Guide formore information on subscribing your system(s) to download software from these locations.

Note

Refer to the Red Hat Enterprise Virtualization Manager Release Notes for specific channel namescurrent to your system.

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 EnterpriseVirtualization 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 authenticationrequirements 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 theidentifier codes in your Red Hat Enterprise Virtualization environment.

Note

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


47

Report a bug

4.2. Example: Accessing the API Entry Point using PythonThe 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 EnterpriseVirtualization Manager at rhevm.demo.redhat.com . To connect the example creates an instanceof 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 onefor 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 arespecified in this example.

from ovirtsdk.api import APIfrom 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!

Report a bug

4.3. Example: Listing the Data Center Collection using PythonThe API class provides access to a data centers collection, named datacenters. This collectioncontains all data centers in the environment.


48

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9228-432681+%5BSpecified%5D&cf_build_id=9228-432681+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+Quick+Start+Introduction%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9227-365121+%5BSpecified%5D&cf_build_id=9227-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Accessing+the+API+Entry+Point+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .2. Listing the Data Center Collection using Python

This Python example lists the data centers in the datacenters collection. It also outputs somebasic information about each data center in the collection.



dc_list = api.datacenters.list()

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

api.disconnect()


In an environment where only the Default data center exists, and it is not activated, the exampleoutputs:

Default (d8b74b20-c6e1-11e1-87a3-00163e77e2ed)

Report a bug

4.4. Example: Listing the Cluster Collection using PythonThe API class provides a clusters collection, named clusters. This collection contains all clusters inthe environment.


49

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9219-365121+%5BSpecified%5D&cf_build_id=9219-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Listing+the+Data+Center+Collection+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .3. Listing the clusters collection using Python

This Python example lists the clusters in the clusters collection. It also outputs some basicinformation about each cluster in the collection.


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()


In an environment where only the Default cluster exists, the example outputs:

Default (99408929-82cf-4dc7-a532-9d998063fa95)

Report a bug

4.5. Example: Listing the Logical Networks Collection usingPythonThe API class provides access to a logical networks collection, named networks. This collectioncontains all logical networks in the environment.


50

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9213-365121+%5BSpecified%5D&cf_build_id=9213-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Listing+the+Cluster+Collection+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 basicinformation about each network in the collection.


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)

Report a bug

4.6. Example: Listing the Host Collection using PythonThe API class provides access to a hosts collection, named hosts. This collection contains all hosts inthe environment.


51

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9218-365121+%5BSpecified%5D&cf_build_id=9218-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Listing+the+Logical+Networks+Collection+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .5. Listing the host collection using Python

This Python example lists the hosts in the hosts collection.


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()


In an environment where only one host, named Atlantic, has been attached the example outputs:

Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)

Report a bug

4.7. Example: Approving a Host using PythonRed Hat Enterprise Virtualization Hypervisor hosts are added to the Red Hat Enterprise VirtualizationManager during their configuration. Once you have added a Hypervisor it requires approval in theManager before it can actually be used in the environment.


52

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9226-365121+%5BSpecified%5D&cf_build_id=9226-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Listing+the+Host+Collection+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .6. Approving a host using Python

This Python example calls the approve method for a host named Atlantic.


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()


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.

Report a bug

4.8. Example: Creating NFS Data Storage using PythonWhen a Red Hat Enterprise Virtualization environment is first being created it is necessary to define atleast a data storage domain, and an ISO storage domain. The data storage domain will be used to storevirtual machine disk images while the ISO storage domain will be used to store installation media forguest operating systems.

The API class provides access to a storage domains collection, named storagedomains. Thiscollection contains all the storage domains in the environment. The storagedomains collection canalso be used to add and remove storage domains.

Note

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


53

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9222-365121+%5BSpecified%5D&cf_build_id=9222-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Approving+a+Host+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .7. Creating NFS data storage using Python

This Python example adds an NFS data domain to the storagedomains collection. Adding an NFSstorage 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 hostscollection.


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 storagedomainscollection. 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:


54


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()


If the add method call is successful then the script will output:

Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).

Report a bug

4.9. Example: Creating NFS ISO Storage using PythonTo create a virtual machine you must be able to provide installation media for the guest operatingsystem. In a Red Hat Enterprise Virtualization Environment you store the installation media on an ISOstorage domain.

Note

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


55

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9215-365121+%5BSpecified%5D&cf_build_id=9215-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Creating+NFS+Data+Storage+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .8. Creating NFS ISO storage using Python

This Python example adds an NFS ISO domain to the storagedomains collection. Adding an NFSstorage 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 hostscollection.


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 storagedomainscollection. 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:


56



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()


If the add method call is successful then the script will output:

Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).

Report a bug

4.10. Example: Attaching Storage Domains to a Data Center usingPythonOnce you have added storage domains to Red Hat Enterprise Virtualization you must attach them to adata center and activate them before they will be ready for use.


57

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9221-365121+%5BSpecified%5D&cf_build_id=9221-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Creating+NFS+ISO+Storage+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 domainnamed iso1 to the default data center. The attach action is facilitated by the add method of thedata center's storagedomains collection.




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.

Report a bug

4.11. Example: Activating Storage Domains using PythonOnce you have added storage domains to Red Hat Enterprise Virtualization and attached them to a datacenter you must activate them before they will be ready for use.


58

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9225-365121+%5BSpecified%5D&cf_build_id=9225-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Attaching+Storage+Domains+to+a+Data+Center+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .10. Activating storage domains using Python

This Python example activates a data storage domain named data1, and an ISO storage domainnamed iso1. Both storage domains are attached to the Default data center. The activate action isfacilitated by the activate method of the storage domain.




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()


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.

Report a bug

4.12. Example: Creating a Virtual Machine using PythonVirtual machine creation is performed in several steps. The first step, covered here, is to create thevirtual machine object itself.


59

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9224-365121+%5BSpecified%5D&cf_build_id=9224-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Activating+Storage+Domains+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 ofthe vms collection to create the virtual machine itself.



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()


If the add request is successful then the script will output:


60

Virtual machine 'vm1' added.

Report a bug

4.13. Example: Creating a Virtual Machine NIC using PythonTo ensure a newly created virtual machine has network access you must create and attach a virtual NIC.


61

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9212-365121+%5BSpecified%5D&cf_build_id=9212-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Creating+a+Virtual+Machine+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 virtualmachine's nics collection to create the NIC.



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


Network interface 'nic1' added to 'vm1'.

Report a bug


62

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9217-365121+%5BSpecified%5D&cf_build_id=9217-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Creating+a+Virtual+Machine+NIC+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

4.14. Example: Creating a Virtual Machine Storage Disk usingPythonTo ensure a newly created virtual machine has access to persistent storage you must create and attacha disk.


63

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 namedvm1. 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 virtualmachine's disks collection to create the disk itself.


64




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()



Disk 'vm1_Disk1' added to 'vm1'.

Report a bug

4.15. Example: Attaching an ISO Image to a Virtual Machine usingPythonTo begin installing a guest operating system on a newly created virtual machine you must attach an ISOfile containing the operating system installation media.


65

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9214-365121+%5BSpecified%5D&cf_build_id=9214-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Creating+a+Virtual+Machine+Storage+Disk+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 4 .14 . Identifying ISO images

ISO images are found in the files collection attached to the ISO storage domain. This example liststhe contents of the files collection on an ISO storage domain.

from ovirtsdk.api import API from ovirtsdk.xml import params


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 thefile are shared.


66

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 vm1virtual machine. Once identified the image file is attached using the add method of the virtualmachine's cdroms collection.


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(file=cd_iso)

try: cd_vm.cdroms.add(cd_params) 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()



Attached CD to 'vm1'.

Note

This procedure is for attaching an ISO image to virtual machines with a status of Down. To attachan ISO to a virtual machine with an Up status, amend the second try statement to the following:

try: cdrom=cd_vm.cdroms.get(id="00000000-0000-0000-0000-000000000000") cdrom.set_file(cd_iso) cdrom.update(current=True) print "Attached CD to '%s'." % cd_vm.get_name()except: print "Failed to attach CD to '%s': %s" % (cd_vm.get_name(), ex)

Report a bug

4.16. Example: Starting a Virtual Machine using Python


67

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9220-383039+%5BSpecified%5D&cf_build_id=9220-383039+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Attaching+an+ISO+Image+to+a+Virtual+Machine+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Starting a virtual machine

Example 4 .16. Starting a virtual machine using Python

This example starts the virtual machine using the start method.




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

api.disconnect()


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.

Report a bug

4.17. Example: Checking System Events using PythonRed Hat Enterprise Virtualization Manager records and logs many system events. These event logs areaccessible through the user interface, the system log files, and using the API. The ovirtsdk libraryexposes events using the events collection.


68

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9223-365121+%5BSpecified%5D&cf_build_id=9223-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Starting+a+Virtual+Machine+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 resultsare returned. By default the list method will only return the first page of results which defaults toa maximum of 100 records in length.

The resultant list is reversed to ensure that events are included in the output in the order that theyoccurred.



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())


Output from this script will look like this - albeit with different events depending on the state of theenvironment:

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.

Report a bug


69

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9216-365121+%5BSpecified%5D&cf_build_id=9216-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Example%3A+Checking+System+Events+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Part II. REST Application Programming Interface


70

Chapter 5. Entry Point

5.1. Accessing the API Entry PointA user begins interacting with the API through a GET request on the entry point URI consisting of a hostand 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 followingrequest:

GET /api HTTP/1.1Accept: application/xmlHost: www.example.comAuthorization: [base64 encoded credentials]


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


71

Note

For simplicity, all other examples omit the Host: and Authorization: request headers andassume the base is the default /api path. This base path differs depending on yourimplementation.

Report a bug

5.2. Product InformationThe entry point contains a product_info element to help an API user determine the legitimacy of theRed Hat Enterprise Virtualization environment. This includes the name of the product, the vendor andthe version.

Example 5.2. Verify a genuine Red Hat Enterprise Virtualization environment

The follow elements identify a genuine Red Hat Enterprise Virtualization 3.2 environment:

<api> ... <product_info> <name>Red Hat Enterprise Virtualization</name> <vendor>Red Hat</vendor> <version revision="0" build="0" minor="2" major="3"/> </product_info> ...</api>

Report a bug

5.3. Link ElementsAccess to the Entry Point provides link elements and URIs for all of the resource collections the APIexposes. Each collection uses a relation type to identify the URI a client needs.


72

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7715-348263+%5BSpecified%5D&cf_build_id=7715-348263+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Accessing+the+API+Entry+Point%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7930-384900+%5BSpecified%5D&cf_build_id=7930-384900+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Product+Information%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.

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

Note

All URIs shown in example responses are illustrative. The format of all URIs returned by theserver is opaque. Clients navigate to specific resources through the entry point URI and use therelationship types to access the URIs.The server chooses to include absolute URIs or absolute paths in the link element's hrefattribute, so clients are required to handle either form.

[3]


73

The link elements also contain a set of search URIs for certain collections. These URIs use URI

templates to integrate search queries. The purpose of the URI template is to accept a searchexpression using the natural HTTP pattern of a query parameter. The client does not require priorknowledge of the URI structure. Thus clients should treat these templates as being opaque and accessthem 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


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.

Report a bug

5.4. Special Object ElementsSpecial object elements define relationships to special fixed resources within the virtualizationenvironment.

Table 5.3. Special Objects


templates/blank The default blank virtual machine template for your virtualizationenvironment. This template exists in every cluster as opposed to astandard template, which only exists in a single cluster.

tags/root The root tag that acts as a base for tag hierarchy in your virtualizationenvironment.

Report a bug

5.5. Summary ElementThe summary element shows a high level summary of the system's statistics.

[4]


74

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7931-366699+%5BSpecified%5D&cf_build_id=7931-366699+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Link+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7932-348275+%5BSpecified%5D&cf_build_id=7932-348275+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Special+Object+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

5.6. RESTful Service Description Language (RSDL)RESTful Service Description Language (RSDL) provides a description of the structure and elements inthe the REST API in one whole XML specification. Invoke the RSDL using the following request.

GET /api?rsdl HTTP/1.1Accept: 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:


75

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7933-348278+%5BSpecified%5D&cf_build_id=7933-348278+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Summary+Element%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

<?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 arelationship type attribute (rel).

request Defines the request properties required for the link.

http_method The method type to access this link. Includes the standard HTTPmethods 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 todefine the header.

body Defines the body for the HTTP request. Contains a resource type anda parameter_set, which contains a sets of parameter elementswith attributes to define whether they are required for a request andthe data type. The parameter element also includes a nameelement to define the Red Hat Enterprise Virtualization Managerproperty to modify and also a further parameter_set subset if typeis set to collection.

response Defines the output for the HTTP request. Contains a type element todefine the resource structure to output.

Use the RSDL in your applications as a method to map all links and parameter requirements for


76

controlling a Red Hat Enterprise Virtualization environment.

Report a bug

[3] The RFC d escrib ing Unifo rm Reso urce Lo cato r Generic Syntax p ro vid es a Co llected ABNF fo r URI that exp lains the d ifferenceb etween these fo rms.

[4] The Internet-Draft d escrib ing the fo rmat o f a URI Temp late is availab le at http ://to o ls.ietf.o rg /html/d raft-g reg o rio -uritemp late-0 3.


77

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12755-365966+%5BSpecified%5D&cf_build_id=12755-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+RESTful+Service+Description+Language+%28RSDL%29%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

http://tools.ietf.org/html/rfc3986#appendix-A

http://tools.ietf.org/html/draft-gregorio-uritemplate-03

Chapter 6. Compatibility Level Versions

6.1. Compatibility Level VersionsEach host connected to Red Hat Enterprise Virtualization Manager contains a version of VDSM. VDSM isthe agent within the virtualization infrastructure that runs on a hypervisor or host and provides localmanagement for virtual machines, networks and storage. Red Hat Enterprise Virtualization Managercontrols 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 Managerexcludes certain features from a current version of VDSM until all hosts within a cluster have the sameVDSM version, or more recent, installed.

The API represents this concept as a compatibility level for each host, corresponding to theversion of VDSM installed. A version element contains major and minor attributes, which describethe compatibility level.

When an administrator upgrades all hosts within a cluster to a certain level, the version level appearsunder a supported_versions element. This indicates the cluster's version is now updatable to thatlevel. Once the administrator updates all clusters within a data center to a given level, the data center isupdatable to that level.

Report a bug

6.2. Upgrading Compatibility Levels


78

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8598-348319+%5BSpecified%5D&cf_build_id=8598-348319+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Compatibility+Level+Versions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 6.1. Upgrading compatibility levels

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

<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:

Chapter 6. Compatibility Level Versions

79

<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 inRed Hat Enterprise Virtualization 3.1 for this data center.

Report a bug


80

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7656-348323+%5BSpecified%5D&cf_build_id=7656-348323+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Upgrading+Compatibility+Levels%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 7. Capabilities

7.1. CapabilitiesThe capabilities collection provides information about the supported capabilities of a Red HatEnterprise Virtualization Manager version. These capabilities include active features and availableenumerated values for specific properties. An API user accesses this information through the rel="capabilities" link obtained from the entry point URI.

Report a bug

7.2. Version-Dependent CapabilitiesThe capabilities element contains any number of version elements that describe capabilitiesdependent on a compatibility level.

The version element includes attributes for major and minor version numbers. This indicates thecurrent version level.

The following representation shows capabilities specific to Red Hat Enterprise VirtualizationManager 3.2 and 3.1 respectively:

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

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

Report a bug

7.3. Current VersionThe current element signifies if the version specified is the most recent supported compatibilitylevel. The value is either a Boolean true or false.

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

Report a bug

7.4. Features


81

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8599-348333+%5BSpecified%5D&cf_build_id=8599-348333+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Capabilities%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7955-384913+%5BSpecified%5D&cf_build_id=7955-384913+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Version-Dependent+Capabilities%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7934-384915+%5BSpecified%5D&cf_build_id=7934-384915+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Current+Version%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Each version contains a list of compatible features.

Table 7.1. Feature Types

Feature Element Type Description

transparent_hugepages Boolean: trueor false

Defines the availability of TransparentHugepages for hosts.

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

Report a bug

7.5. CPUsEach cluster is configured with a minimal CPU type that all hosts in that cluster must support. Guestsrunning on hosts within the cluster all run on this CPU type, ensuring that every guest is migratable toany host within the cluster.

Red Hat Enterprise Virtualization has a set of supported CPU types to choose from when configuring acluster.

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

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

Report a bug


82

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7935-384919+%5BSpecified%5D&cf_build_id=7935-384919+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Features%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7936-348350+%5BSpecified%5D&cf_build_id=7936-348350+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+CPUs%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

7.6. Power ManagersRed Hat Enterprise Virtualization platform provides a list of supported power_managers for hostfencing 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. Optionsinclude 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>

Report a bug

7.7. Fence TypesThe fence_types element defines fence_type options to fence a host and reduce power usage.


83

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7937-348354+%5BSpecified%5D&cf_build_id=7937-348354+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Power+Managers%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

7.8. Storage TypesThe 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>

Report a bug

7.9. Storage Domain TypesThe storage_domain_types element shows the available storage_domain_type options in avirtualization 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>

Report a bug


84

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7938-348358+%5BSpecified%5D&cf_build_id=7938-348358+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Fence+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7939-348361+%5BSpecified%5D&cf_build_id=7939-348361+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7940-348364+%5BSpecified%5D&cf_build_id=7940-348364+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Domain+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

7.10. Virtual Machine TypesThe vm_types element defines each virtual machine type (vm_type) available for creation in a virtualenvironment.

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

Report a bug

7.11. Boot DevicesEach 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>

Report a bug

7.12. Display TypesAccess to a virtual machine through Red Hat Enterprise Virtualization Manager requires a displayprotocol. 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>

Report a bug


85

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7941-348367+%5BSpecified%5D&cf_build_id=7941-348367+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7942-348374+%5BSpecified%5D&cf_build_id=7942-348374+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Boot+Devices%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7943-348384+%5BSpecified%5D&cf_build_id=7943-348384+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Display+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

7.13. NIC Interface TypesA virtual machine requires a network interface to connect to a network. The nic_interfaces elementdefines the supported NIC types available. Each nic_interface depends on the drivers available fordifferent types of virtual machines. VirtIO drivers are available for Red Hat Enterprise Linux 4.8 andabove, and for Windows virtual machines. Windows supports rtl8139 without the need for drivers. OtherLinux 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>

Report a bug

7.14. OS TypesEach virtual machine contains an os_type value to define the virtual machine operating system. Thedefault 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>windows_8x64</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>


86

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7944-348386+%5BSpecified%5D&cf_build_id=7944-348386+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+NIC+Interface+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

7.15. Disk FormatsAn 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>

Report a bug

7.16. Disk InterfacesThe disk_interfaces element lists disk_interface options for emulated protocols to interfacewith virtual disks.

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

Report a bug

7.17. Virtual Machine AffinitiesVirtual machines migrate between hosts in a cluster. The vm_affinities element defines eachavailable 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>


87

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7946-377511+%5BSpecified%5D&cf_build_id=7946-377511+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+OS+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7947-348407+%5BSpecified%5D&cf_build_id=7947-348407+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disk+Formats%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7948-348411+%5BSpecified%5D&cf_build_id=7948-348411+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disk+Interfaces%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

7.18. Custom PropertiesThe custom_properties element lists a set of environment variables for a virtual environment. Thevirtual 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) todefine 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>

Report a bug

7.19. Boot ProtocolsThe boot_protocol element lists each possible IP assignment boot_protocol for hosts whenbooting.

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

Report a bug

7.20. Error HandlingA 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.


88

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7949-348412+%5BSpecified%5D&cf_build_id=7949-348412+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Affinities%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7950-348416+%5BSpecified%5D&cf_build_id=7950-348416+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Custom+Properties%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7951-348420+%5BSpecified%5D&cf_build_id=7951-348420+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Boot+Protocols%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

7.21. Storage FormatsThe 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>

Report a bug

7.22. Virtual Machine Device TypesThe 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>

Report a bug

7.23. Gluster Volume TypesThe gluster_volume_types element lists the available type of Gluster volumes.


89

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7952-348421+%5BSpecified%5D&cf_build_id=7952-348421+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Error+Handling%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7953-348425+%5BSpecified%5D&cf_build_id=7953-348425+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Formats%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13026-366543+%5BSpecified%5D&cf_build_id=13026-366543+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Device+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

7.24. Gluster Transport TypesThe 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>

Report a bug

7.25. Guster Access ProtocolsThe 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>

Report a bug

7.26. Resource Status StatesEach 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,


90

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13027-366543+%5BSpecified%5D&cf_build_id=13027-366543+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Gluster+Volume+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13028-366543+%5BSpecified%5D&cf_build_id=13028-366543+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Gluster+Transport+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13029-366543+%5BSpecified%5D&cf_build_id=13029-366543+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Guster+Access+Protocols%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

template_states, vm_states, vm_pause_details, disk_states, host_nic_states, data_center_states, gluster_volume_states and brick_states.

Report a bug

7.27. PermitsPermits 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: trueor false

The permit is assigned to only administrativeroles.

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

Report a bug

7.28. Scheduling PoliciesThe scheduling_policies element defines the load-balancing and power-saving modes for hosts inthe cluster.

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

Report a bug


91

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7954-348429+%5BSpecified%5D&cf_build_id=7954-348429+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Resource+Status+States%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7956-348434+%5BSpecified%5D&cf_build_id=7956-348434+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Permits%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7957-451534+%5BSpecified%5D&cf_build_id=7957-451534+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Scheduling+Policies%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 8. Common Features

8.1. Element Property Icons

Note

Throughout this guide, the elements of each resource are detailed in tables. These tables includea properties column, displaying icons depicting element properties. The meaning of these icons isshown 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-providedrepresentation of a resource on creation, but are notmandatory for an update of a resource.

Non-updateable These elements cannot have their value changed whenupdating a resource. Include these elements in a client-provided representation on update only if their values arenot altered by the API user. If altered, the API reports anerror.

Read-only These elements are read-only. Values for read-onlyelements are not created or modified.

Report a bug

8.2. Representations

8.2.1. RepresentationsThe 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>

Report a bug

8.2.2. Common Attributes to Resource Representations


92

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12756-366663+%5BSpecified%5D&cf_build_id=12756-366663+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Element+Property+Icons%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8600-348666+%5BSpecified%5D&cf_build_id=8600-348666+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Representations%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 virtualizationinfrastructure contains an id, whichacts as a globally unique identifier(GUID). The GUID is the primarymethod of resource identification.

href string The canonical location of the resourceas an absolute path.

Report a bug

8.2.3. Common Elements to Resource RepresentationsAll 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 namefor the resource. The name is uniqueacross all resources of its type.

description string A free-form user-supplied humanreadable description of the resource.

Report a bug

8.3. Collections

8.3.1. CollectionsA 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 virtualizationhosts in the environment. An example of a sub-collection is the host.nics collection which containsresources for all network interface cards attached to a host resource.

Report a bug

8.3.2. Listing All Resources in a CollectionObtain a listing of resources in a collection with a GET request on the collection URI obtained from theentry point.

Include an Accept HTTP header to define the MIME type for the response format.

GET /api/[collection] HTTP/1.1Accept: [MIME type]

Report a bug


93

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7960-348674+%5BSpecified%5D&cf_build_id=7960-348674+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Common+Attributes+to+Resource+Representations%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7961-348679+%5BSpecified%5D&cf_build_id=7961-348679+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Common+Elements+to+Resource+Representations%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8601-383278+%5BSpecified%5D&cf_build_id=8601-383278+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Collections%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7716-325581+%5BSpecified%5D&cf_build_id=7716-325581+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Listing+All+Resources+in+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

8.3.3. Listing Extended Resource Sub-CollectionsThe API extends collection representations to include sub-collections when the Accept header includesthe detail parameter.

GET /api/collection HTTP/1.1Accept: application/xml; detail=subcollection

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

GET /api/collection HTTP/1.1Accept: application/xml; detail=subcollection1; detail=subcollection2

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

GET /api/collection HTTP/1.1Accept: 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 vmscollection

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

Report a bug

8.3.4. Searching Collections with QueriesA GET request on a "collection/search" link results in a search query of that collection. The APIonly returns resources within the collection that satisfy the search query constraints.

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


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

Report a bug


94

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7717-384078+%5BSpecified%5D&cf_build_id=7717-384078+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Listing+Extended+Resource+Sub-Collections%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7721-348715+%5BSpecified%5D&cf_build_id=7721-348715+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Searching+Collections+with+Queries%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

8.3.5. Maximum Results ParameterUse an optional max URL parameter to limit the list of results.

GET /api/collection;max=1 HTTP/1.1Accept: 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>

Note

If the collection is searchable, the 'max' parameter overrides the database default of maximumreturned results.

Report a bug

8.3.6. Case SensitivityAll search queries are case sensitive by default. The URL syntax provides a Boolean option to togglecase sensitivity.

Example 8.2. Case insensit ive search query

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

Report a bug

8.3.7. Query SyntaxThe API uses the URI templates to perform a search query with a GET request:

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

The query template value refers to the search query the API directs to the collection. This queryuses 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.


95

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13030-369128+%5BSpecified%5D&cf_build_id=13030-369128+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Maximum+Results+Parameter%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12757-365966+%5BSpecified%5D&cf_build_id=12757-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Case+Sensitivity%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 8.5. Example search queries

Collection Criteria Result

hosts vms.status=up Displays a list of all hostsrunning virtual machines thatare up.

vms domain=qa.company.com Displays a list of all virtualmachines running on thespecified domain.

vms users.name=mary Displays a list of all virtualmachines belonging to userswith the username mary.

events severity>normal sortby time

Displays the list of all eventswith severity higher than normal and sorted by the time element values.

events severity>normal sortby time desc

Displays the list of all eventswith severity higher than normal and sorted by the time element values indescending order.

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

Example 8.3. URL-encoded search query

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

Report a bug

8.3.8. WildcardsSearch 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.1Accept: application/xml

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


96

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7718-348722+%5BSpecified%5D&cf_build_id=7718-348722+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Query+Syntax%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

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

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

Report a bug

8.3.9. PaginationSome 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 displaymore than the default, the API separates collections into pages via a search query containing the pagecommand.

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.1Accept: application/xml

Increase the page value to view the next page of results.

GET /api/collection?search=page%202 HTTP/1.1Accept: 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.1Accept: application/xml

This query displays the second page in a collection listing ordered by a chosen element.

Report a bug

8.3.10. Creating a Resource in a CollectionCreate a new resource with a POST request to the collection URI containing a representation of the newresource.

A POST request requires a Content-Type header. This informs the API of the representation MIMEtype in the body content as part of the request.


Each resource type has its own specific required properties. The client supplies these properties whencreating a new resource. Refer to the individual resource type documentation for more details.

If a required property is absent, the creation fails with a representation indicating the missing elements.


97

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7719-348734+%5BSpecified%5D&cf_build_id=7719-348734+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Wildcards%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7720-323510+%5BSpecified%5D&cf_build_id=7720-323510+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Pagination%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

POST /api/[collection] HTTP/1.1Accept: [MIME type]Content-Type: [MIME type]

[body]

Report a bug

8.3.11. Asynchronous RequestsThe 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 createdasynchronously. 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_statuselement and link for creation status updates. For example:

POST /api/collection HTTP/1.1Accept: application/xmlContent-Type: application/xml

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

HTTP/1.1 202 AcceptedContent-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.1Accept: 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:


98

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7723-325585+%5BSpecified%5D&cf_build_id=7723-325585+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Resource+in+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

POST /api/collection HTTP/1.1Accept: application/xmlContent-Type: application/xmlExpect: 201-created

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

Report a bug

8.4. Resources

8.4.1. ResourcesResources are data sources in a RESTful web service. Each resource type contains a set of commonparameters that the REST API abstracts to form a resource representation, usually in XML or JSON.Users can view a resource representation, then edit the parameters and send the representation backto the resource's URL within the API, which modifies the resource. Users can also delete individualresources through REST.

A RESTful web service also groups resources into collections. Users can view a representation of allresources in a collection. Users also send resource representations to a specific collection to create anew resource within that particular collection.

Report a bug

8.4.2. Retrieving a ResourceObtain the state of a resource with a GET request on a URI obtained from a collection listing.


GET /api/[collection]/[resource_id] HTTP/1.1Accept: [MIME type]

Report a bug

8.4.3. Updating a ResourceModify resource properties with a PUT request containing an updated description from a previous GETrequest for the resource URI. Details on modifiable properties are found in the individual resource typedocumentation.

A PUT request requires a Content-Type: application/xml header. This informs the API of therepresentation MIME type in the body content as part of the request.


PUT /api/collection/resource_id HTTP/1.1Accept: [MIME type]Content-Type: [MIME type]

[body]


99

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7722-348745+%5BSpecified%5D&cf_build_id=7722-348745+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Asynchronous+Requests%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8605-439490+%5BSpecified%5D&cf_build_id=8605-439490+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Resources%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7724-325582+%5BSpecified%5D&cf_build_id=7724-325582+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Retrieving+a+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

This does not include immutable resource properties that an API user has attempted to modify. If anattempt is made to modify a strictly immutable resource property, the API reports a conflict with an errormessage representation in the response body.

Properties omitted from the representation are ignored and not changed.

Report a bug

8.4.4. Deleting a ResourceDelete a resource with a DELETE request sent to its URI.


DELETE /api/[collection]/[resource_id] HTTP/1.1Accept: [MIME type]

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 header to inform the API of therepresentation MIME type in the body content. If a DELETE request contains no body content, omit the Content-Type header.

Report a bug

8.4.5. Sub-Collection RelationshipsA sub-collection relationship defines a hierarchical link between a resource and a sub-collection. Thesub-collection exists or has some meaning in the context of a parent resource. For example, a virtualmachine contains network interfaces, which means the API maps the relationship between the virtualmachine 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. Forexample, a virtual machine can contain several disks and some disks are shared among multiplevirtual machines.

1:N mappings, where mapped resources are dependent on a parent resource. Without the parentresource, the dependent resource cannot exist. For example, the link between a virtual machine andsnapshots.

1:N mappings, where mapped resources exist independently from parent resources but data is stillassociated 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.1Accept: application/xml


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


100

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7725-361388+%5BSpecified%5D&cf_build_id=7725-361388+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7726-325591+%5BSpecified%5D&cf_build_id=7726-325591+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Deleting+a+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The API user now queries the sub-collection.

GET /api/collection/resource_id/subcollection HTTP/1.1Accept: application/xml


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

Report a bug

8.4.6. XML Element RelationshipsXML 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 dependencyand without data associated with the relationship. For example, the relationship between a host and acluster.

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 XMLelement

GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1


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

Report a bug

8.4.7. ActionsMost resources include a list of action links to provide functions not achieved through the standardHTTP methods.


101

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7727-361390+%5BSpecified%5D&cf_build_id=7727-361390+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Sub-Collection+Relationships%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7728-361391+%5BSpecified%5D&cf_build_id=7728-361391+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Element+Relationships%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

<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 anaction representation contains a href link to be polled for completion.

grace_period a grace period in milliseconds, which must expire before the action isinitiated.

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

An action also requires a Content-Type: application/xml header since the POST requestrequires an XML representation in the body content.

When the action is initiated asynchronously, the immediate 202 Accepted response provides a link tomonitor the status of the task:

POST /api/collection/resource_id/action HTTP/1.1Content-Type: application/xmlAccept: application/xml

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

HTTP/1.1 202 AcceptedContent-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.


102

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.1Accept: 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 theaction to be re-initiated.

Report a bug

8.4.8. PermissionsEach resource contains a permissions sub-collection. Each permission contains a user, anassigned role and the specified resource. For example:


103

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8602-361395+%5BSpecified%5D&cf_build_id=8602-361395+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Actions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

GET /api/collection/resource_id/permissions HTTP/1.1Accept: 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 permissionrepresentation and a Content-Type: application/xml header to the resource's permissionssub-collection. Each new permission requires a role and a user:

POST /api/collection/resource_id/permissions HTTP/1.1Content-Type: application/xmlAccept: application/xml

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

HTTP/1.1 201 CreatedContent-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>

Report a bug

8.4.9. Handling ErrorsSome errors require further explanation beyond a standard HTTP status code. For example, the APIreports an unsuccessful resource state update or action with a fault representation in the responseentity body. The fault contains a reason and detail strings. Clients must accommodate failedrequests via extracting the fault or the expected resource representation depending on the responsestatus code. Such cases are clearly indicated in the individual resource documentation.


104

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8603-361397+%5BSpecified%5D&cf_build_id=8603-361397+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Permissions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

PUT /api/collection/resource_id HTTP/1.1Accept: application/xmlContent-Type: application/xml

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

HTTP/1.1 409 ConflictContent-Type: application/xml

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

Report a bug


105

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8604-361398+%5BSpecified%5D&cf_build_id=8604-361398+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Handling+Errors%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 9. Data Centers

9.1. Data Center ElementsThe datacenters collection provides information about the data centers in a Red Hat EnterpriseVirtualization environment. An API user accesses this information through the rel="datacenters"link obtained from the entry point URI.

The following table shows specific elements contained in a data center resource representation.

Table 9.1. Data center elements


link rel="storagedomains"

relationship A link to the sub-collection forstorage domains attached to thisdata center.

link rel="permissions"

relationship A link to the sub-collection for datacenter permissions.

link rel="quotas" relationship A link to the sub-collection for quotasassociated with this data center.

storage_type enumerated Describes the storage type in thisdatacenter. A list of enumeratedvalues is available in capabilities.

storage_format enumerated Describes the storage formatversion for the data center. A list ofenumerated values are available in capabilities.

version major= minor= complex The compatibility level of the datacenter.

supported_versions complex A list of possible version levels forthe data center.

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_statesunder capabilities.

Report a bug

9.2. XML Representation of a Data Center


106

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7965-366665+%5BSpecified%5D&cf_build_id=7965-366665+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Data+Center+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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>

Report a bug

9.3. Methods

9.3.1. Creating a New Data CenterCreation of a new data center requires the name, storage_type and version elements.

Example 9.2. Creating a data center

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

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

Report a bug

9.3.2. Updating a Data CenterThe name, description, storage_type, version and storage_format elements are updatablepost-creation.


107

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7966-361405+%5BSpecified%5D&cf_build_id=7966-361405+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Data+Center%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7729-361407+%5BSpecified%5D&cf_build_id=7729-361407+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+New+Data+Center%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 9.3. Updating a data center

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

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

Report a bug

9.3.3. Removing a Data CenterRemoval 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

Report a bug

9.4. Sub-Collections

9.4.1. Storage Domains Sub-Collection

9.4 .1.1. Storage Domains Sub-CollectionEach data center contains a sub-collection for attached storages domain. An API user interacts with thissub-collection using the standard REST methods.

An attached storage domain has a similar representation to a top-level storage domain, with theexception that it has a data center specific status and set of actions. States for the status element arelisted in storage_domain_states under capabilities.

Important

The API as documented in this section is experimental and subject to change. It is not covered bythe backwards compatibility statement.

Report a bug

9.4 .1.2. Attaching and Detaching a Storage DomainA 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


108

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7731-361409+%5BSpecified%5D&cf_build_id=7731-361409+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Data+Center%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7732-361411+%5BSpecified%5D&cf_build_id=7732-361411+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Data+Center%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8609-361416+%5BSpecified%5D&cf_build_id=8609-361416+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Domains+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-type: application/xml

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

HTTP/1.1 201 CreatedLocation: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819edContent-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 elementfor 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.1Accept: application/xmlContent-type: application/xml

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


109

Report a bug

9.4 .1.3. Actions

9.4 .1.3.1. Activate Storage Domain ActionAn attached storage domain requires activation on a data center before use. The activate action doesnot 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.1Accept: application/xmlContent-type: application/xml

<action/>

Report a bug

9.4 .1.3.2. Deactivate Storage Domain ActionAn attached storage domain is deactivated on a data center before removal. The deactivate action doesnot 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.1Accept: application/xmlContent-type: application/xml

<action/>

Report a bug

9.4.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 implementson resources. An API user views this sub-collection and its resources using the GET method.


110

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7733-361420+%5BSpecified%5D&cf_build_id=7733-361420+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Attaching+and+Detaching+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7734-361422+%5BSpecified%5D&cf_build_id=7734-361422+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Activate+Storage+Domain+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7735-361423+%5BSpecified%5D&cf_build_id=7735-361423+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Deactivate+Storage+Domain+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.

Example 9.10. Creating a quota

POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1Accept: application/xmlContent-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


Report a bug

9.5. Actions

9.5.1. Force Remove Data Center ActionAn API user forces the removal of a data center when encountering unresolvable problems with storagedomains, such as the loss of connection to a master storage domain or a lack of available hosts whendeleting 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 thedata center from the Red Hat Enterprise Virtualization environment. This means the API removes thedata 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:


111

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12766-366553+%5BSpecified%5D&cf_build_id=12766-366553+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Quotas+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-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 datastorage 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 datacenter.

Report a bug


112

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7736-361428+%5BSpecified%5D&cf_build_id=7736-361428+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Force+Remove+Data+Center+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 10. Host Clusters

10.1. Host Cluster ElementsThe clusters collection provides information about host clusters in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="clusters" link obtained fromthe entry point URI.

The following table shows specific elements contained in a host cluster resource representation.

Table 10.1. Host cluster elements


link rel="glustervolumes"

relationship A link to the sub-collection for RedHat Storage volumes associatedwith this cluster.

link rel="networks"

relationship A link to the sub-collection fornetworks associated with thiscluster.


relationship A link to the sub-collection for clusterpermissions.

cpu id= complex A server CPU reference that definesthe CPU type all hosts must supportin the cluster.

data_center id= GUID A reference to the data centermembership of this cluster.

memory_policy complex Defines the cluster's policy on hostmemory utilization.

scheduling_policy complex Defines the load-balancing or power-saving modes for hosts in thecluster.

version major= minor=

complex The compatibility level of the cluster.

supported_versions

complex A list of possible version levels forthe cluster.

error_handling complex/enumerated Defines virtual machine handlingwhen a host within a clusterbecomes non-operational. Requiresa single on_error elementcontaining an enumerated typeproperty listed in capabilities.

virt_service Boolean Defines whether to exposevirtualization services for thiscluster.

gluster_service Boolean Defines whether to expose Red HatStorage services for this cluster.


113

Report a bug

10.2. Memory Policy ElementsThe memory_policy element contains the following elements:

Table 10.2. Memory policy elements


overcommit percent= complex The percentage of host memoryallowed in use before no more virtualmachines can start on a host. Virtualmachines can use more than theavailable host memory due tomemory sharing under KSM.Recommended values include 100(None), 150 (Server Load) and 200(Desktop Load).

transparent_hugepages complex Define the enabled status ofTransparent Hugepages. The statusis either true or false. Check capabilities feature set toensure your version supports transparent hugepages.

Report a bug

10.3. Scheduling Policy ElementsThe scheduling_policy element contains the following elements:


114

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7967-432461+%5BSpecified%5D&cf_build_id=7967-432461+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+Cluster+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7968-366572+%5BSpecified%5D&cf_build_id=7968-366572+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Memory+Policy+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 10.3. Scheduling policy elements


policy enumerated The VM scheduling mode for hostsin the cluster. A list of enumeratedtypes are listed in capabilities.

thresholds low= high= duration=

complex Defines CPU limits for the host. The high attribute controls the highestCPU usage percentage the host canhave before being consideredoverloaded. The low attributecontrols the lowest CPU usagepercentage the host can have beforebeing considered underutilized. The duration attribute refers to thenumber of seconds the host needsto be overloaded before thescheduler starts and moves the loadto another host.

Report a bug

10.4. XML Representation of a Host Cluster


115

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7969-366573+%5BSpecified%5D&cf_build_id=7969-366573+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Scheduling+Policy+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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>

Report a bug

10.5. Methods

10.5.1. Creating a Host ClusterCreation of a new cluster requires the name, cpu id= and datacenter elements. Identify the datacenter with either the id attribute or name element.


116

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7970-361442+%5BSpecified%5D&cf_build_id=7970-361442+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Host+Cluster%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 10.2. Creating a host cluster

POST /api/clusters HTTP/1.1Accept: application/xmlContent-type: application/xml

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

Report a bug

10.5.2. Updating a Host ClusterThe name, description, cpu id= and error_handling elements are updatable post-creation.

Example 10.3. Updating a host cluster

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

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

Report a bug

10.5.3. Removing a Host ClusterRemoval of a cluster requires a DELETE request.

Example 10.4 . Removing a cluster

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


Report a bug


10.6.1. Networks Sub-CollectionNetworks associated with a cluster are represented with the networks sub-collection. Every host withina cluster connects to these associated networks.

The representation of a cluster's network sub-collection is the same as a standard network resourceexcept for the following additional elements:


117

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7737-361444+%5BSpecified%5D&cf_build_id=7737-361444+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Host+Cluster%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7738-361446+%5BSpecified%5D&cf_build_id=7738-361446+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Host+Cluster%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7739-361447+%5BSpecified%5D&cf_build_id=7739-361447+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Host+Cluster%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 10.4 . Addit ional network elements


cluster id= relationship A reference to the cluster of whichthis network is a member.

required Boolean Defines required or optional networkstatus.

display Boolean Defines the display network status.Used for backward compatibility.

usages complex Defines a set of usage elements forthe network. Users can definenetworks as VM and DISPLAYnetworks at this level.

An API user manipulates the networks sub-collection with the standard REST methods. POST ing anetwork 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.1Accept: application/xmlContent-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"> <name>rhevm</name></network>

HTTP/1.1 201 CreatedLocation: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665fContent-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.


118

Example 10.6. Sett ing the display network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1Accept: application/xmlContent-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 orfalse) of the required element.

Example 10.7. Sett ing optional network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1Accept: application/xmlContent-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


Report a bug

10.6.2. Storage Volumes Sub-Collection

10.6.2.1. 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 Storagevolumes. Red Hat Storage volumes are associated with host clusters and are represented with the


119

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8610-366637+%5BSpecified%5D&cf_build_id=8610-366637+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Networks+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 isdefined using the following elements:

Table 10.5. Gluster volume elements


volume_type enumerated Defines the volume type. See the capabilities collection for a listof volume types.

bricks relationship The sub-collection for the Red HatStorage bricks. When creating a newvolume, the request requires a set ofbrick elements to create andmanage in this cluster. Requires the server_id of the Red Hat Storageserver and a brick_dir elementfor the brick directory

transport_types complex Defines a set of volume transport_type elements. Seethe capabilities collection for alist of available transport types.

replica_count integer Defines the file replication count fora replicated volume.

stripe_count integer Defines the stripe count for a tripedvolume

options complex A set of additional Red Hat Storage option elements. Each optionincludes an option name and a value.


120

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>

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.1Accept: application/xmlContent-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 Red Hat Storage volume

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



121

Important

Resources in the glustervolumes sub-collection cannot be updated.

Report a bug

10.6.2.2. Bricks Sub-CollectionThe glustervolumes sub-collection contains its own bricks sub-collection to define individual bricksin a Red Hat Storage volume. The representation of a volume's bricks sub-collection is defined usingthe following elements:

Table 10.6. Brick elements


server_id string A reference to the Red Hat Storageserver.

brick_dir string Defines a brick directory on the RedHat Storage server.

replica_count integer Defines the file replication count forthe brick in the volume.

stripe_count integer Defines the stripe count for the brickin the volume

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.1Accept: application/xmlContent-Type: application/xml

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

Remove a brick with a DELETE request.


122

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12767-366667+%5BSpecified%5D&cf_build_id=12767-366667+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Red+Hat+Storage+Volumes+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Important

Resources in the bricks sub-collection cannot be updated.

Report a bug

10.6.2.3. Actions

10.6.2.3.1. Start ActionThe 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.1Accept: application/xmlContent-Type: application/xml

<action/>

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

Report a bug

10.6.2.3.2. Stop ActionThe 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.1Accept: application/xmlContent-Type: application/xml

<action/>

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

Report a bug

10.6.2.3.3. Set Option ActionThe setoption action sets a volume option.


123

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12768-366668+%5BSpecified%5D&cf_build_id=12768-366668+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Bricks+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12769-365966+%5BSpecified%5D&cf_build_id=12769-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Start+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12770-365966+%5BSpecified%5D&cf_build_id=12770-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Stop+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 10.16. Set an option

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

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

Report a bug

10.6.2.3.4 . Reset Option ActionThe resetoption action resets a 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.1Accept: application/xmlContent-Type: application/xml

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

Report a bug

10.6.2.3.5. Reset All Options ActionThe resetalloptions action resets all 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.1Accept: application/xmlContent-Type: application/xml

<action/>

Report a bug


124

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12771-365966+%5BSpecified%5D&cf_build_id=12771-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Set+Option+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12772-365966+%5BSpecified%5D&cf_build_id=12772-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Reset+Option+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12773-365966+%5BSpecified%5D&cf_build_id=12773-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Reset+All+Options+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 11. Networks

11.1. Network ElementsThe networks collection provides information about the logical networks in a Red Hat EnterpriseVirtualization environment. An API user accesses this information through the rel="networks" linkobtained from the entry point URI.

The following table shows specific elements contained in a network resource representation.

Table 11.1. Network elements


data_center id= GUID A reference to the data center ofwhich this cluster is a member.

vlan id= integer A VLAN tag.

mtu interger Sets the maximum transmission unitfor the logical network. If omitted, thelogical network uses the defaultvalue.

stp Boolean: true or false true if Spanning Tree Protocol isenabled on this network.

status One of operationalor non_operational

The status of the network. Thesestates are listed in network_states under capabilities.

usages complex Defines a set of usage elements forthe network. Users can definenetworks as VM networks at thislevel.

Important


Report a bug

11.2. XML Representation of a Network Resource


125

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7971-366670+%5BSpecified%5D&cf_build_id=7971-366670+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Network+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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>

Report a bug

11.3. Methods

11.3.1. Creating a Network ResourceCreation of a new network requires the name and datacenter elements.

Example 11.2. Creating a network resource

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

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

Report a bug

11.3.2. Updating a Network ResourceThe name, description, ip, vlan, stp and display elements are updatable post-creation.

Example 11.3. Updating a network resource

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

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


126

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7972-361474+%5BSpecified%5D&cf_build_id=7972-361474+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Network+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7740-361477+%5BSpecified%5D&cf_build_id=7740-361477+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Network+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

11.3.3. Removing a Network ResourceRemoval of a network requires a DELETE request.

Example 11.4 . Removing a network

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


Report a bug


127

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7741-361479+%5BSpecified%5D&cf_build_id=7741-361479+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Network+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7742-361481+%5BSpecified%5D&cf_build_id=7742-361481+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Network+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 12. Storage Domains

12.1. Storage Domain ElementsThe storagedomains collection provides information about the storage domains in a Red HatEnterprise Virtualization environment. An API user accesses this information through the rel="storagedomains" link obtained from the entry point URI.

The following table shows specific elements contained in a storage domain resource representation.


128

Table 12.1. Storage domain elements



relationship A link to the sub-collection forstorage domain permissions.

link rel="files" relationship A link to the files sub-collection forthis storage domains.

link rel="vms" relationship A link to the vms sub-collection for astorage 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 ofenumerated values are available in capabilities.

master Boolean: true or false true if this is the master storagedomain of a data center.

host complex A reference to the host on which thisstorage domain should be initialized.The only restriction on this host isthat it should have access to thephysical storage specified.

storage complex Describes the underlying storage ofthe storage domain.

available integer Space available in bytes.

used integer Space used in bytes.

committed integer Space committed in bytes.

storage_format enumerated Describes the storage formatversion for the storage domain. A listof enumerated values are availablein capabilities.

storage_domain_state

enumerated Defines if the storage domain iscurrently attached to a data center. Alist of enumerated values areavailable in capabilities.

Important

The API as documented in this chapter is experimental and subject to change. It is not covered bythe backwards compatibility statement.

Report a bug


129

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7973-366671+%5BSpecified%5D&cf_build_id=7973-366671+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Domain+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

12.2. XML Representation of a Storage DomainExample 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>

Report a bug

12.3. Methods

12.3.1. Creating a Storage DomainCreation of a new storage domain requires the name, type, host and storage elements. Identify the host element with the id attribute or name element.

Example 12.2. Creating a storage domain

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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>

The API user attaches the storage domain to a data center after creation.


130

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7974-361492+%5BSpecified%5D&cf_build_id=7974-361492+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

12.3.2. Updating a Storage DomainOnly the name element is updatable post-creation.

Example 12.3. Updating a storage domain

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

Report a bug

12.3.3. Removing a Storage DomainRemoval 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


Report a bug

12.4. Storage Types

12.4.1. Storage TypesThe storage element contains a type element, which is an enumerated value found under the capabilities collection.

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

Report a bug

12.4.2. NFS StorageThe following table contains nfs specific elements in a storage description.


131

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7743-361500+%5BSpecified%5D&cf_build_id=7743-361500+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7744-361496+%5BSpecified%5D&cf_build_id=7744-361496+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7745-361497+%5BSpecified%5D&cf_build_id=7745-361497+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8617-361504+%5BSpecified%5D&cf_build_id=8617-361504+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Types%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 12.2. NFS specific elements


address string The host name or IP address of theNFS server.

path string The path of NFS mountable directoryon the server.

Report a bug

12.4.3. PosixFS StorageThe following table contains posixfs specific elements in a storage description.

Table 12.3. PosixFS specific elements


address string The host name or IP address of thePosixFS server.

path string The path of PosixFS mountabledirectory on the server.

vfs_type string The Linux-supported file systemtype of the PosixFS share.

mount_options string The options for mounting thePosixFS share.

Report a bug

12.4.4. iSCSI and FCP StorageThe following table contains iscsi and fcp specific elements in a storage description.

Table 12.4 . iSCSI and FCP specific elements


logical_unit id= complex The id of the logical unit. A storagedomain also accepts multiple iSCSIor FCP logical units.

override_luns Boolean Defines whether to replace all logicalunit settings with new settings. Setto true to override.

The logical_unit contains a set of sub-elements.


132

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7975-366578+%5BSpecified%5D&cf_build_id=7975-366578+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+NFS+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12774-366580+%5BSpecified%5D&cf_build_id=12774-366580+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+PosixFS+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 12.5. Logical unit elements


address string The address of the servercontaining the storage device.

port integer The port number of the server.

target string The target IQN for the storagedevice.

username string A CHAP user name for logging into atarget.

password string A CHAP password for logging into atarget.

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 devicemapping for the target.

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

Report a bug

12.4.5. LocalFS StorageThe localfs specific elements in a storage description are:

Table 12.6. Localfs specific elements


path string The path of local storage domain onthe host.

A localfs storage domain requires a data center with storage_type set to localfs. This datacenter only contains a single host cluster, and the host cluster only contains a single host.

Report a bug

12.5. Export Storage Domains

12.5.1. Export Storage DomainsStorage domains with type set to export contain vms and templates sub-collections, which list theimport candidate VMs and templates stored on that particular storage domain.


133

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7976-366582+%5BSpecified%5D&cf_build_id=7976-366582+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+iSCSI+and+FCP+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7977-366583+%5BSpecified%5D&cf_build_id=7977-366583+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+LocalFS+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vmsAccept: 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. Thedestination 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.1Accept: application/xmlContent-type: application/xml

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


134

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.1Accept: application/xmlContent-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


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


135

Example 12.9. Selecting disks for an import action


<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.1Accept: application/xml


Report a bug


12.6.1. Files Sub-CollectionThe 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 virtualfloppy 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 anISO storage domain.


136

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8619-361516+%5BSpecified%5D&cf_build_id=8619-361516+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Export+Storage+Domains%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1Accept: 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 thefilename.

Report a bug

12.7. Actions

12.7.1. Importing an Existing Storage DomainThe API provides a user with the ability to remove an ISO or Export storage domain from one Red HatEnterprise Virtualization Manager instance without re-formatting the underlying storage and import it intoanother instance. Importing is achieved similarly to adding a new storage domain, except the name is notspecified.


137

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8620-361517+%5BSpecified%5D&cf_build_id=8620-361517+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Files+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 12.12. Importing an existing export storage domain

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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>


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

Report a bug

12.7.2. Deleting a Storage DomainA 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 domainafter deletion.


138

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7803-361519+%5BSpecified%5D&cf_build_id=7803-361519+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Importing+an+Existing+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 storagedomain's data for import. Use the destroy element to logically remove the storage domain and retainthe data.

Example 12.14 . Logical removal of a storage domain

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

Report a bug


139

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7804-361520+%5BSpecified%5D&cf_build_id=7804-361520+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Deleting+a+Storage+Domain%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 13. Hosts

13.1. Host ElementsThe hosts collection provides information about the hosts in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="hosts" link obtained from theentry point URI.

The following table shows specific elements contained in a host resource representation.


140

Table 13.1. Host elements


link rel="storage" relationship A link to the storage sub-collectionfor host storage.

link rel="nics" relationship A link to the nics sub-collection forhost network interfaces.

link rel="tags" relationship A link to the tags sub-collection forhost tags.


relationship A link to the permissions sub-collection for host 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 thehost.

certificate complex A reference to the host certificatedetails, including organizationand subject.

status See below The host status.

cluster id= GUID A reference to the cluster thatincludes this host.

port integer The listen port of the VDSM daemonrunning on this host.

storage_manager complex Defines an appropriate host to useas the storage pool manager (SPM).Requires a host priority attributeand a Boolean value (true or true).

power_management complex Configuration options for host powermanagement.

ksm Boolean: true orfalse

true if Kernel SamePage Merging(KSM) is enabled.

transparent_hugepages Boolean: true orfalse

true if Transparent Hugepages isenabled.

iscsi complex The SCSI initiator for the host.

cpu complex Statistics for the host CPU. Includessub-elements for the CPU's name, topology cores=, topology sockets= and speed. The topology cores= aggregates thetotal cores while the topology sockets= aggregates the totalphysical CPUs. The total coresavailable to virtual machines equals

Chapter 13. Hosts

141

the number of sockets multiplied bythe cores per socket.

memory integer The total amount of host memory inbytes.

summary complex Summary statistics of the virtualmachines on the host. Includes sub-elements for numbers of active, migrating and total VMs.

version major= minor= complex The compatibility level of the host.

root_password string The root password of this host, byconvention only included in theclient-provided host representationon creation.

libvirt_version complex The libvirt compatibility level of thehost.

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.

Report a bug

13.2. XML Representation of a Host


142

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7978-372477+%5BSpecified%5D&cf_build_id=7978-372477+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 13.1. An XML representation of a host

Chapter 13. Hosts

143

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


144

<summary> <active>2</active> <migrating>0</migrating> <total>3</total> </summary> <version major="3" minor="0"/> <libvirt_version major="0" minor="10" build="2" revision="0" full_version="libvirt-0.10.2-15.el6"/></host>

Report a bug

13.3. Power Management ElementsThe power_management element provides users with the ability to set a power managementconfiguration, which is required for host fencing. Certain sub-elements are required when configuring power_management.

Table 13.2. Power management options


type= fencing device code A list of valid fencing device codesare available in the capabilitiescollection.

enabled Boolean: true or false Indicates whether powermanagement configuration isenabled or disabled.

address string The host name or IP address of thehost.

username string A valid user name for powermanagement.

password string A valid, robust password for powermanagement.

options complex Fencing options for the selected type=.

agent complex Specifies fencing agent optionswhen multiple fences are used.Subelement concurrent is a True|False Boolean that selects concurrent|sequentialconfiguration respectively. Use the order subelement to prioritize thefencing agents. Other subelementsinclude address, username, password, and options.

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.

Chapter 13. Hosts

145

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7979-372481+%5BSpecified%5D&cf_build_id=7979-372481+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Host%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

A new host includes an optional power_management configuration when POST ing to the hostresource. The power_management configuration is updatable using a PUT request.

Example 13.2. 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> <agents> <agent type="rsa"> <address>192.168.1.111</address> <username>e.xample</username> order="primary" <password>p@55w0rd!</password> <options> <option name="443" value="true"/> <option name="secure" value "false"/> </options> <concurrent>false</concurrent> <order>1</order> </agent> <agent type="ipmi"> <address>192.168.1.112</address> <username>e.xample</username> order="primary" <password>p@55w0rd!</password> <options> <option name="443" value="true"/> <option name="secure" value "false"/> </options> <concurrent>false</concurrent> <order>2</order> </agent> </agents> </power_management> ...</host>

Report a bug

13.4. Memory Management ElementsThe API provides two configuration settings for a host's memory management.

Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pagesto a single page reference. This helps with optimization for memory density. KSM uses the ksm element.


146

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7980-481215+%5BSpecified%5D&cf_build_id=7980-481215+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Power+Management+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 13.3. Sett ing KSM memory management

PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1Accept: application/xmlContent-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 supportuses the transparent_hugepages element.

Example 13.4 . Sett ing Transparent Hugepage memory management

PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1Accept: application/xmlContent-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.

Report a bug

13.5. Methods

13.5.1. Creating a HostCreation of a new host requires the name, address and root_password elements.

Example 13.5. Creating a host

POST /api/hosts HTTP/1.1Accept: application/xmlContent-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 EnterpriseVirtualization Manager detects hypervisor hosts automatically and requires approval for their use.

Chapter 13. Hosts

147

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7800-365100+%5BSpecified%5D&cf_build_id=7800-365100+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Memory+Management+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The root_password element is only included in the client-provided initial representation and is notexposed in the representations returned from subsequent requests.

Report a bug

13.5.2. Updating a HostThe name, description, cluster, power_management, transparent_hugepages and ksmelements are updatable post-creation.

Example 13.6. Updating a host

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

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

Report a bug

13.5.3. Removing a HostRemoval of a host requires a DELETE request.

Example 13.7. Removing a host

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


Report a bug


13.6.1. Host Network Interface Sub-Collection

13.6.1.1. Host Network Interface Sub-CollectionThe nics sub-collection represents a host's physical network interfaces. Each host_nic element inthe representation acts as a network interface and contains the following elements:


148

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7746-361533+%5BSpecified%5D&cf_build_id=7746-361533+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Host%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7747-432455+%5BSpecified%5D&cf_build_id=7747-432455+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Host%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7748-361536+%5BSpecified%5D&cf_build_id=7748-361536+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Host%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 13.3. Elements for a host's network interfaces


name string The name of the host networkinterface, e.g. eth0

link rel="statistics"

relationship A link to the statistics sub-collection for a host's networkinterface statistics.

link rel="master" relationship A reference to the master bondedinterface, 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.

mac address= string The MAC address of the interface.

ip address= netmask= gateway= mtu=

complex The IP level configuration of theinterface.

mtu complex The maximum transmission unit forthe interface.

boot_protocol enumerated The protocol for IP addressassignment when the host isbooting. A list of enumerated valuesis available in capabilities.

speed integer The network interface speed in bitsper second.

status enumerated The link status for the networkinterface. These states are listed in host_nic_states under capabilities.

vlan id integer The VLAN which this interfacerepresents.

bonding complex A list of options and slave NICsfor bonded interfaces.

bridged Boolean Defines the bridged network status.Set to true for a bridged networkand true for a bridgeless network.

[a]

[b ]

[c ]

[a] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b e ad d ed .[b ] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b e ad d ed .[c] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b e ad d ed .

Chapter 13. Hosts

149

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. All other network interfaces contain updatable network, ipand 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.


150

POST /api/hosts HTTP/1.1Accept: application/xmlContent-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.1Accept: application/xmlContent-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


Important


Report a bug

13.6.1.2. Bonded InterfacesA bonded interface is represented as a host_nic resource containing a bonding element.

[a]

[b ]

[a] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b e ad d ed .[b ] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b e ad d ed .

Chapter 13. Hosts

151

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7981-366677+%5BSpecified%5D&cf_build_id=7981-366677+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+Network+Interface+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-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.

Report a bug

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


152

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9064-366679+%5BSpecified%5D&cf_build_id=9064-366679+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Bonded+Interfaces%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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


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>

Chapter 13. Hosts

153

Note

This statistics sub-collection is read-only.

Report a bug

13.6.1.4 . Actions

13.6.1.4 .1. Attach Network to Host ActionA host network interface is attached to a network, indicating the given network is accessible over theinterface. 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.1Accept: application/xmlContent-type: application/xml

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

Important

This networking configuration change must be explicitly committed.

Report a bug

13.6.1.4 .2. Detach Network from Host ActionDetach 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.1Accept: application/xmlContent-type: application/xml

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

Important

This networking configuration change must be explicitly committed.


154

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9065-361543+%5BSpecified%5D&cf_build_id=9065-361543+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Network+Interface+Statistics%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7750-361545+%5BSpecified%5D&cf_build_id=7750-361545+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Attach+Network+to+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

13.6.1.4 .3. Multiple Network Setup ActionA 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.1Accept: application/xmlContent-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 requestincludes additional elements specified in the following table.

Table 13.7. Addit ional elements for multiple host network interface setup


checkConnectivity Boolean Set to true to verify connectivitybetween the host and the Red HatEnterprise Virtualization Manager. Ifthe connectivity is lost, Red HatEnterprise Virtualization Managerreverts the settings.

connectivityTimeout

integer Defines the timeout for loss ofconnectivity.

force Boolean Set to true to force changes even ifconnectivity is lost.

Report a bug

Chapter 13. Hosts

155

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7751-432456+%5BSpecified%5D&cf_build_id=7751-432456+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Detach+Network+from+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12775-365966+%5BSpecified%5D&cf_build_id=12775-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Multiple+Network+Setup+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

13.6.2. Storage Sub-CollectionThe storage sub-collection provides a list of the iSCSI and FCP storage representations available onthe host. This storage is used to create 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


Report a bug

13.6.3. Host Statistics Sub-CollectionEach host resource exposes a statistics sub-collection for host-specific statistics. Each statisticcontains the following elements:


156

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7982-361552+%5BSpecified%5D&cf_build_id=7982-361552+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Storage+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 13.8. Elements for host statistics











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.

Chapter 13. Hosts

157

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.

Report a bug

13.7. Actions

13.7.1. Install VDSM ActionInstall VDSM and related software on the host. The host type defines additional parameters for theaction.

Red Hat Enterprise Linux host - This host type requires a root_password element that refersto the password for the host's root user.

Red Hat Enterprise Virtualization Hypervisor host - This host type requires an image elementthat 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.1Accept: application/xmlContent-type: application/xml

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


158

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7983-361553+%5BSpecified%5D&cf_build_id=7983-361553+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+Statistics+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

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

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

Report a bug

13.7.2. Activate Host ActionActivate 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.1Accept: application/xmlContent-type: application/xml

<action/>

Report a bug

13.7.3. Fence Host ActionAn API user controls a host's power management device with the fence action. The capabilitieslists available fence_type options.

Example 13.19. Action to fence a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fenceAccept: application/xmlContent-Type: application/xml

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

Report a bug

13.7.4. Deactivate Host ActionDeactivate the host to perform maintenance tasks.

Chapter 13. Hosts

159

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7752-361555+%5BSpecified%5D&cf_build_id=7752-361555+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Install+VDSM+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7753-361557+%5BSpecified%5D&cf_build_id=7753-361557+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Activate+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7755-361558+%5BSpecified%5D&cf_build_id=7755-361558+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Fence+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 13.20. Action to deactivate a host

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

<action/>

Report a bug

13.7.5. Approve Host ActionApprove a pre-installed Red Hat Enterprise Virtualization Hypervisor host for usage in the virtualizationenvironment. This action also accepts an optional cluster element to define the target cluster for thishost.

Example 13.21. Action to approve a host

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

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

Report a bug

13.7.6. Host iSCSI Login ActionThe iscsilogin action enables a host to login to an iSCSI target. Logging into a target makes thecontained LUNs available in the host_storage 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.1Accept: application/xmlContent-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>

Report a bug

13.7.7. Host iSCSI Discover Action


160

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7754-361561+%5BSpecified%5D&cf_build_id=7754-361561+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Deactivate+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7756-361563+%5BSpecified%5D&cf_build_id=7756-361563+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Approve+Host+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7757-361564+%5BSpecified%5D&cf_build_id=7757-361564+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+iSCSI+Login+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-Type: application/xml

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

Report a bug

13.7.8. Commit Host Network Configuration ActionAn API user commits the network configuration to persist a host network interface attachment ordetachment, 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.1Accept: application/xmlContent-type: application/xml

<action/>

Important

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

Report a bug

Chapter 13. Hosts

161

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7758-457002+%5BSpecified%5D&cf_build_id=7758-457002+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Host+iSCSI+Discover+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7759-361569+%5BSpecified%5D&cf_build_id=7759-361569+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Commit+Host+Network+Configuration+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 14. Virtual Machines

14.1. Virtual Machine ElementsThe vms collection provides information about virtual machines in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="vms" link obtained from the entrypoint URI.

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


162

Table 14 .1. Virtual machine elements


link rel="disks" relationship A link to the disks sub-collection forvirtual machine resources.

link rel="nics" relationship A link to the nics sub-collection forvirtual machine resources.

link rel="cdroms" relationship A link to the cdroms sub-collectionfor virtual machine resources.

link rel="snapshots" relationship A link to the snapshots sub-collection for virtual machineresources.

link rel="tags" relationship A link to the tags sub-collection forvirtual machine resources.


relationship A link to the permissions sub-collection for virtual machinepermissions.

link rel="statistics" relationship A link to the statistics sub-collection for virtual machineresources.

type enumerated The virtual machine type. A list ofenumerated values are available in capabilities.

status See below The virtual machine status.

memory integer The amount of memory allocated tothe guest in bytes.

cpu complex Defines CPU details for the virtualmachine. The topology sub-element sets number of logical sockets available to the guest andthe number of cores per socket.The total cores available to thevirtual machine equals the number ofsockets multiplied by the cores persocket.

The cputune sub-element mapsvirtual CPUs to physical host CPUsusing a series of vcpupinelements. Each vcpupin elementscontains a virtual CPU attribute(vcpu) and an attribute to definewhich physical to use (cpuset). Setthe cpuset to either a single CPU(cpuset="0"), multiple CPUs(cpuset="0,2"), a CPU range(cpuset="0-3") or a CPU rangewith exclusion (cpuset="0-3,^2").


163

The cpu_mode sub-element defineshow closely the virtual CPU relatesto the host CPU. It has three values: custom is the default if no mode isgiven, host_model copies the hostCPU as best as libvirt canunderstand, and host_passthrough passes allaspects of the host to the guest,even those that libvirt does notrecognise. However, host_passthrough will preventmigration of that virtual machine.

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. Alist of enumerated values areavailable in capabilities.

os kernel string A path to a kernel image the virtualmachine is configured to boot. Thisoption supports booting a Linuxkernel directly rather than throughthe BIOS bootloader.

os initrd string A path to an initrd image to be usedwith the previously specified kernel.This option supports booting a Linuxkernel directly rather than throughthe BIOS bootloader.

os cmdline string A kernel command line parameterstring to be used with the definedkernel. This option supports bootinga Linux kernel directly rather thanthrough the BIOS bootloader.

high_availability complex Set enabled to true if the virtualmachine should be automaticallyrestarted if the virtual machine or itshost crashes. A priority elementcontrols the order in which virtualmachines are re-started.

display complex The display type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean valuespecifies if a client can reconnect tothe machine via display.

The smartcard_enabled sub-element is a Boolean (true or false) to specify if a Smartcard


164

attached to a client is passedthrough to a virtual machine. Thedefault is false.

cluster id= GUID A reference to the virtual machine'shost cluster.

template id= GUID A reference to the template on whichthis virtual machine is based.

domain id= GUID A reference to the virtual machine'sdomain.

start_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which thisvirtual machine was started.

creation_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which thisvirtual machine was created.

origin One of rhev, ovirt, vmwareor xen

The system from which this virtualmachine originated.

stateless Boolean: true orfalse

true if the virtual machine isstateless. A stateless virtualmachine contains a snapshot of itsdisk image taken at boot and deletedat shutdown. This means statechanges do not persist after areboot.

placement_policy complex Sets the placement policy for virtualmachine migration. Requires adefault host= and an affinity(one of migratable, user_migratable or pinned).Leave the host element empty toset no preferred host.

memory_policy complex Sets the memory policy for virtualmachines. Defines the minimumamount of guaranteed memory ona host in order for the virtualmachine to run.

quota id= GUID Sets a quota for the virtual machine.

custom_properties complex A set of user-defined environmentvariable passed as parameters tocustom scripts. Each custom_property contains nameand value attributes. A list ofenumerated values are available in capabilities.

usb complex Defines the USB policy for a virtualmachine. Requires an enabled


165

element set to a Boolean value anda type element set to either native or legacy.

guest_info complex A reference to the guest clientinformation. Includes an ip elementwith an address= attribute.

vmpool complex A reference to the virtual machinepool. This element only appears forvirtual machines part of a pool.

timezone tz databaseformat: Area/Location

The the Sysprep timezone settingfor a Windows virtual machine.

domain complex The the Sysprep domain setting fora Windows virtual machine. Requiresa name from the domainscollection.

payloads complex Defines a set of payload elementsto deliver content to a virtualmachine upon boot. Each payloadrequires a type attribute, either cdrom or floppy, and a fileelement that specifies the name andlocation using the name attribute.Within the file element is a content element, which defines thecontent 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.

Report a bug


166

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7984-372728+%5BSpecified%5D&cf_build_id=7984-372728+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .1. An XML representation of a virtual machine


167

<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"/> <cpu_tune> <vcpu_pin vcpu="0" cpu_set="1-4,^2"/> <vcpu_pin vcpu="1" cpu_set="0,1"/> <vcpu_pin vcpu="2" cpu_set="2,3"/> <vcpu_pin vcpu="3" cpu_set="0,4"/> </cpu_tune> <cpu_mode>host_passthrough</cpu_mode> </cpu> <os type="RHEL5"> <boot dev="hd"/> <kernel/>


168

<initrd/> <cmdline/> </os> <highly_available> <enabled>true</enabled> <priority>20</priority> </highly_available> <display> <type>vnc</type> <port>5910</port> <monitors>1</monitors> <smartcard_enabled>true</smartcard_enabled> </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>

Report a bug

14.3. Methods

14.3.1. Creating a Virtual MachineCreation 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.


169

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7985-372730+%5BSpecified%5D&cf_build_id=7985-372730+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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


<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 * 1024 2 = 536870912 bytes

Report a bug

14.3.2. Updating a Virtual MachineThe name, description, cluster, type, memory, cpu, os, high_availability, display, timezone, domain, stateless, placement_policy, memory_policy, usb, payloads, originand custom_properties elements are updatable post-creation.

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

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

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

Note

Memory in the previous example is converted to bytes using the following formula:

1024MB * 1024 2 = 1073741824 bytes


170

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7760-361624+%5BSpecified%5D&cf_build_id=7760-361624+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

14.3.3. Removing a Virtual MachineRemoval 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


Report a bug

14.3.4. Removing a Virtual Machine but not the Virtual DiskDetach the virtual disk prior to removing the virtual machine. This preserves the virtual disk. Removal ofa virtual machine requires a DELETE request.

Example 14 .5. Removing a virtual machine

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

<action> <vm> <disks> <detach_only>true</detach_only> </disks> </vm></action>

Report a bug


14.4.1. Disks Sub-Collection

14 .4 .1.1. Disks Sub-CollectionThe disks sub-collection represents all virtual hard disk devices on a virtual machine. A diskrepresentation contains the following elements:


171

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7761-361625+%5BSpecified%5D&cf_build_id=7761-361625+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7762-361623+%5BSpecified%5D&cf_build_id=7762-361623+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Virtual+Machine%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13931-401746+%5BSpecified%5D&cf_build_id=13931-401746+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Virtual+Machine+but+not+the+Virtual+Disk%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 14 .2. Elements for virtual machine disks



relationship A link to the statistics sub-collection for a virtual machine's diskstatistics.

storage_domains Complex The storage domains associatedwith this disk. Each storage_domain elementcontains an id attribute with theassociated storage domain's GUID.Update this element with POST toperform live migration of a disk fromone data storage domain to another.

size integer Size of the disk in bytes.

provisioned_size integer The provisioned size of the disk inbytes.

actual_size integer Actual size of the disk in bytes.

status One of illegal, invalid, locked or ok

The status of the disk device. Thesestates are listed in disk_statesunder capabilities.

interface enumerated The type of interface driver used toconnect to the disk device. A list ofenumerated values is available in capabilities.

format enumerated The underlying storage format. A listof enumerated values is available in capabilities. Copy On Write(COW) allows snapshots, with asmall performance overhead. Rawdoes not allow snapshots, but offersimproved performance.

sparse Boolean: true or false true if the physical storage for thedisk should not be preallocated.

bootable Boolean: true or false true if this disk is to be marked asbootable.

shareable Boolean: true or false true to share the disk with multiplevirtual machines.

wipe_after_delete Boolean: true or false true if the underlying physicalstorage for the disk should bezeroed when the disk is deleted.

propagate_errors Boolean: true or false true if disk errors should not causevirtual machine to be paused and,instead, disk errors should bepropagated to the guest OS.

vm id= GUID The ID of the containing virtualmachine.

[a]


172

quota id= GUID Sets a quota for the disk.

lunStorage complex A reference to a direct LUN mappingfor storage usage. Requires a storage element that containsiSCSI or FCP device details.

active Boolean Defines if the disk is connected tothe virtual machine.

Example 14 .6. 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_domainselement when the disk is added to a virtual machine and not itself created from a template.

[a] This element is o nly req uired if the d isk is b eing ad d ed to a virtual machine and no t created fro m a virtual machine temp late.


173

Example 14 .7. Creating a new a disk device on a virtual machine

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1Accept: application/xmlContent-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.

Example 14 .8. Updating a virtual machine disk

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

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

Removal of a virtual machine disk requires a DELETE request.

Example 14 .9. Removing a virtual machine disk

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


Report a bug

14 .4 .1.2. Disk CloningClone a disk from a template with the clone element. Set the clone element to true within the diskssub-collection when creating a virtual machine. This clones a disk from the base template and attaches itto the virtual machine.


174

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7986-366684+%5BSpecified%5D&cf_build_id=7986-366684+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disks+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .10. 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.1Accept: application/xmlContent-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 searchparameter instead of name.

Report a bug

14 .4 .1.3. Disk Statistics Sub-CollectionEach 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











disk id= relationship A relationship to the containing disk resource.

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


175

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12779-365966+%5BSpecified%5D&cf_build_id=12779-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disk+Cloning%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Table 14 .4 . Virtual machine disk statistic types

Name Description

data.current.read The data transfer rate in bytes per second when reading from thedisk.

data.current.write The data transfer rate in bytes per second when writing to the disk.

Example 14 .11. 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


Report a bug

14 .4 .1.4 . Floating Disk Attach and Detach ActionsAttach any floating disks from the main rel="disks" collection using a POST request on the virtualmachine's disks sub-collection. Include the id of the disk to attach.

Example 14 .12. Attach a floating disk

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

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


176

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7988-361633+%5BSpecified%5D&cf_build_id=7988-361633+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disk+Statistics+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Example 14 .13. Detach a disk from a virtual machine

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

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

Report a bug

14 .4 .1.5. Disk Activate and Deactivate ActionsEach virtual machine's disk provides a set of activate and deactivate actions to add and removedisks from a virtual machine.

Example 14 .14 . Action to activate a virtual machine disk

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

<action/>

Example 14 .15. Action to deactivate a virtual machine disk

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

<action/>

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


177

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12780-366544+%5BSpecified%5D&cf_build_id=12780-366544+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Floating+Disk+Attach+and+Detach+Actions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Important

The hotplugging feature only supports Virt IO disks and virtual machine operating systems thatsupport hotplugging operations. Example operating systems include:

Red Hat Enterprise Linux 6;Red Hat Enterprise Linux 5;Windows Server 2008; and,Windows Server 2003.

Report a bug

14.4.2. Network Interfaces Sub-Collection

14 .4 .2.1. Network Interfaces Sub-CollectionThe nics sub-collection represents all network interface devices on a virtual machine. A nicrepresentation contains the following elements:

Table 14 .5. Elements for virtual machine network interfaces



relationship A link to the statistics sub-collection for a virtual machine'snetwork interface statistics.

network id= GUID A reference to the network which theinterface should be connected. Ablank network id is allowed.

interface enumerated The type of driver used for the nic. Alist of enumerated values is availablein capabilities.

mac address= string The MAC address of the interface.

port_mirroring complex Defines whether the NIC receivesmirrored traffic. Define a networkselement with a series of network id= references.

plugged Boolean Defines if the NIC is plugged in tothe virtual machine.

linked Boolean Defines if the NIC is linked to thevirtual machine.


178

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13031-366552+%5BSpecified%5D&cf_build_id=13031-366552+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Disk+Activate+and+Deactivate+Actions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .16. 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 .17. Creating a virtual machine NIC

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1Accept: application/xmlContent-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 .18. Updating a virtual machine NIC

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

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


179

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

Example 14 .19. Deleting a virtual machine NIC

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


Important

The hotplugging feature only supports virtual machine operating systems with hotpluggingoperations. Example operating systems include:

Red Hat Enterprise Linux 6;Red Hat Enterprise Linux 5;Windows Server 2008; and,Windows Server 2003.

Report a bug

14 .4 .2.2. Network Interface Statistics Sub-CollectionEach virtual machine's network interface exposes a statistics sub-collection for network interfacestatistics. Each statistic contains the following elements:

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











nic id= relationship A relationship to the containing nic resource.

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


180

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7989-374152+%5BSpecified%5D&cf_build_id=7989-374152+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Network+Interfaces+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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


Report a bug

14.4.3. CD-ROMs Sub-CollectionThe cdroms sub-collection represents the CD-ROM device on a virtual machine. A cdromrepresentation contains the following elements:

Table 14 .8. Elements for virtual machine CD-ROMs


file id= string/filename A reference to an ISO image.


181

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7991-361646+%5BSpecified%5D&cf_build_id=7991-361646+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Network+Interface+Statistics+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .21. 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 .22. Changing a CD-ROM file

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-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 .23. Changing a CD-ROM file

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


182

Note

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

Report a bug

14.4.4. Snapshots Sub-Collection

14 .4 .4 .1. Snapshots Sub-CollectionA virtual machine saves and restores disk state as a number of snapshots. These are represented andmanaged through a rel="snapshot" sub-collection that behaves similar to other collections.

Each virtual machine snapshot is represented with an individual snapshot element that contains thefollowing sub-elements:

Table 14 .9. Elements for virtual machine snapshots


vm id= GUID The ID and URI of the virtualmachine to which this snapshotpertains.

date xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which thissnapshot was created.

link rel="prev" relationship A link to the previous snapshot ofthis 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 .


183

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7992-365110+%5BSpecified%5D&cf_build_id=7992-365110+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+CD-ROMs+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .25. 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 snapshotrepresentation.

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

<action/>

Note

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

Report a bug

14 .4 .4 .2. Clone a Virtual Machine from a SnapshotAPI provides a function to create virtual machines from a snapshot of a previous machine. API userscreate 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 standardrepresentation 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 asa basis for the virtual machine.


184

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7993-366653+%5BSpecified%5D&cf_build_id=7993-366653+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Snapshots+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .26. Clone Virtual Machine from Snapshot


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

Report a bug

14.4.5. Statistics Sub-CollectionEach virtual machine resource exposes a statistics sub-collection for virtual machine-specificstatistics. Each statistic contains the following elements:

Table 14 .10. Elements for virtual machine statistics











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.


185

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12782-376368+%5BSpecified%5D&cf_build_id=12782-376368+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Clone+a+Virtual+Machine+from+a+Snapshot%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

14.5. Actions

14.5.1. Start Virtual Machine ActionThe start action launches a virtual machine.

Example 14 .28. Action to start a virtual machine

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

<action/>

The start action allows a vm element to be provided as a parameter. If a vm element is provided, thevirtual 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.


186

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7994-365114+%5BSpecified%5D&cf_build_id=7994-365114+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Statistics+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .29. Action to start a virtual machine with overridden parameters

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1Accept: application/xmlContent-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 whenoverriding parameters on boot with the start action. The domain element determines thedomain that the Windows virtual machine joins. If the domain does not exist in the domainscollection, this element requires additional user authentication details, including a user_nameand password. If the domain exists in the domains collection, the action requires no additional user authentication details.

Report a bug

14.5.2. Stop Virtual Machine ActionThe stop action forces a virtual machine to power-off.


187

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7763-361658+%5BSpecified%5D&cf_build_id=7763-361658+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Start+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .30. Action to stop a virtual machine

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

<action/>

Report a bug

14.5.3. Shutdown Virtual Machine ActionThe shutdown action sends a shutdown request to a virtual machine.

Example 14 .31. Action to send a shutdown request to a virtual machine

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

<action/>

Report a bug

14.5.4. Suspend Virtual Machine ActionThe suspend action saves the virtual machine state to disk and stops it. The virtual machine state isrestored with the start action.

Example 14 .32. Action to save virtual machine state and suspend the machine

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

<action/>

Report a bug

14.5.5. Detach Virtual Machine from Pool ActionThe detach action detaches a virtual machine from a pool.

Example 14 .33. Action to detach a virtual machine

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

<action/>

Report a bug


188

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7764-361659+%5BSpecified%5D&cf_build_id=7764-361659+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Stop+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7765-361661+%5BSpecified%5D&cf_build_id=7765-361661+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Shutdown+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7766-361663+%5BSpecified%5D&cf_build_id=7766-361663+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Suspend+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7767-361665+%5BSpecified%5D&cf_build_id=7767-361665+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Detach+Virtual+Machine+from+Pool+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

14.5.6. Migrate Virtual Machine ActionThe migrate action migrates a virtual machine to another physical host. The destination host element isan optional element as Red Hat Enterprise Virtualization Manager automatically selects a default host formigration. If an API user requires a specific host, the user can specify the host with either an id or name parameter.

Example 14 .34 . Action to migrate a virtual machine to another host

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

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

Report a bug

14.5.7. Cancel Virtual Machine Migration ActionThe cancel migration action stops any migration of a virtual machine to another physical host.

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

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

<action/>

Report a bug

14.5.8. Export Virtual Machine ActionThe export action exports a virtual machine to an export storage domain. A destination storage domainmust 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 destinationdomain. Set the exclusive parameter to true to change this behaviour and overwrite any existingvirtual machine.

If snapshots of the virtual machine are not included with the exported virtual machine, set the discard_snapshots parameter to true.


189

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7768-361667+%5BSpecified%5D&cf_build_id=7768-361667+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Migrate+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12783-365966+%5BSpecified%5D&cf_build_id=12783-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Cancel+Virtual+Machine+Migration+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 14 .36. Action to export a virtual machine to an export storage domain

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

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

Report a bug

14.5.9. Virtual Machine Ticket ActionThe ticket action generates a time-sensitive authentication token for accessing a virtual machine'sdisplay. The client-provided action optionally includes a ticket representation containing a value (ifthe token string needs to take on a particular form) and/or an expiry time in minutes. In any case, theresponse specifies the actual ticket value and expiry used.

Example 14 .37. Action to generate authentication token for a virtual machine

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

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

200 OKContent-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>

Report a bug


190

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7769-361673+%5BSpecified%5D&cf_build_id=7769-361673+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Export+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7771-361676+%5BSpecified%5D&cf_build_id=7771-361676+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Ticket+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

14.5.10. Force Remove Virtual Machine ActionAn 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 setto true. The request also requires an additional Content-type: application/xml header toprocess the XML representation in the body.

Example 14 .38. Force remove action on a virtual machine

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


Report a bug


191

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7772-361677+%5BSpecified%5D&cf_build_id=7772-361677+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Force+Remove+Virtual+Machine+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 15. Floating Disks

15.1. Floating Disk ElementsThe disks collection provides information about all disks in a Red Hat Enterprise Virtualizationenvironment. A user attaches and dettaches disks from any virtual machine and floats them betweenvirtual machines. An API user accesses this information through the rel="disks" link obtained fromthe entry point URI.

The following table shows specific elements contained in a disks resource representation.


192

Table 15.1. Elements for floating disks



relationship A link to the statistics sub-collection for a virtual machine's diskstatistics.

image_id GUID A reference to the virtual machineimage stored on the defined storagedomain.

storage_domains Complex The storage domains associatedwith this disk. Each storage_domain elementcontains an id attribute with theassociated storage domain's GUID.Update this element with POST toperform live migration of a disk fromone data storage domain to another.

size integer Size of the disk in bytes.

provisioned_size integer The provisioned size of the disk inbytes.

actual_size integer Actual size of the disk in bytes.

status One of illegal, invalid, locked or ok

The status of the disk device. Thesestates are listed in disk_statesunder capabilities.

interface enumerated The type of interface driver used toconnect to the disk device. A list ofenumerated values is available in capabilities.

format enumerated The underlying storage format. A listof enumerated values is available in capabilities. Copy On Write(COW) allows snapshots, with asmall performance overhead. Rawdoes not allow snapshots, but offersimproved performance.

sparse Boolean: true or false true if the physical storage for thedisk should not be preallocated.

bootable Boolean: true or false true if this disk is to be marked asbootable.

shareable Boolean: true or false true to share the disk with multiplevirtual machines.

wipe_after_delete Boolean: true or false true if the underlying physicalstorage for the disk should bezeroed when the disk is deleted.

propagate_errors Boolean: true or false true if disk errors should not causevirtual machine to be paused and,instead, disk errors should be


193

propagated to the guest OS.

quota id= GUID Sets a quota for the disk.

lunStorage complex A reference to a direct LUN mappingfor storage usage. Requires a storage element that containsiSCSI or FCP device details.

active Boolean Defines if the disk is connected tothe virtual machine.

Important

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

Report a bug

15.2. XML Representation of a Floating DiskExample 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>

Report a bug

15.3. Methods

15.3.1. Creating a Floating Disk


194

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12784-366689+%5BSpecified%5D&cf_build_id=12784-366689+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Floating+Disk+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12785-365966+%5BSpecified%5D&cf_build_id=12785-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Floating+Disk%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-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>

Report a bug


15.4.1. Statistics Sub-CollectionEach floating disk exposes a statistics sub-collection for disk-specific statistics. Each statisticcontains the following elements:

Table 15.2. Elements for virtual machine disk statistics











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

data.current.write The data transfer rate in bytes per second when writing to the disk.


195

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12786-365966+%5BSpecified%5D&cf_build_id=12786-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Floating+Disk%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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


Report a bug


196

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12787-365966+%5BSpecified%5D&cf_build_id=12787-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Statistics+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 16. Templates

16.1. Virtual Machine Template ElementsThe templates collection provides information about the virtual machine templates in a Red HatEnterprise Virtualization environment. An API user accesses this information through the rel="templates" link obtained from the entry point URI.

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


197

Table 16.1. Virtual machine template elements


link rel="disks" relationship A link to the disks sub-collection forvirtual machine template resources.

link rel="nics" relationship A link to the nics sub-collection forvirtual machine template resources.

link rel="cdroms" relationship A link to the cdroms sub-collectionfor virtual machine templateresources.


relationship A link to the permissions sub-collection for virtual machinetemplate permissions.

type enumerated The type of virtual machine thetemplate provides. A list ofenumerated values are available in capabilities.

status One of illegal, locked or ok

The template status. These statesare listed in template_statesunder capabilities.

memory integer The amount of memory allocated tothe guest, in bytes.

cpu complex The CPU topology (i.e. number of sockets and cores) available tothe 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 adev attribute on a boot element. Alist of enumerated values areavailable in capabilities.

os kernel string A path to a kernel image which thetemplate is configured to boot from.

os initrd string A path to an initrd image to be usedwith the kernel above.

os cmdline string A kernel command line parameterstring to be used with the kernelabove.

cluster id= GUID A reference to the template's hostcluster.

vm id= GUID A reference to the VM on which thistemplate is based.

domain id= GUID A reference to the template'sdomain.

creation_time xsd:dateTimeformat: YYYY-MM-

The date and time at which thistemplate was created.


198

MM-DDThh:mm:ss

origin One of rhev, ovirt, vmwareor xen

The system from which this templateoriginated.

high_availability complex Set enabled to true if the VMshould be automatically restarted ifthe host crashes. A priorityelement controls the order in whichVMs are re-started.

display complex The display type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean valuespecifies if a client can reconnet tothe machine via display.

stateless Boolean: true orfalse

A stateless template contains asnapshot of its disk image taken atboot and deleted at shutdown. Thismeans state changes do not persistafter a reboot.

usb complex Defines the USB policy for a virtualmachine template. Requires an enabled element set to a Booleanvalue and a type element set toeither native or legacy.

placement_policy complex Sets the placement policy for virtualmachine migration. Requires adefault host= and an affinity(one of migratable, user_migratable or pinned).Leave the host element empty toset no preferred host.

custom_properties complex A set of user-defined environmentvariable passed as parameters tocustom scripts. Each custom_property contains nameand value attributes. A list ofenumerated values are available in capabilities.

timezone tz databaseformat: Area/Location

The the Sysprep timezone settingfor a Windows virtual machinetemplate.

domain complex The the Sysprep domain setting fora Windows virtual machine template.Requires a name from the domainscollection.

Report a bug


199

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8001-366690+%5BSpecified%5D&cf_build_id=8001-366690+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Template+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

16.2. XML Representation of a Virtual Machine TemplateExample 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>

Report a bug

16.3. Methods


200

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8002-365121+%5BSpecified%5D&cf_build_id=8002-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Virtual+Machine+Template%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

16.3.1. Creating a New TemplateCreation of a new template requires the name and vm elements. Identify the vm with the id attribute or name element.

Example 16.2. Creating a template from a virtual machine

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

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

Report a bug

16.3.2. Updating a TemplateThe name, description, type, memory, cpu topology, os, high_availability, display, stateless, usb and timezone elements are updatable post-creation.

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

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

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

Report a bug

16.3.3. Removing a TemplateRemoval 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


Report a bug

16.4. Actions

16.4.1. Export Template Action


201

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7773-361710+%5BSpecified%5D&cf_build_id=7773-361710+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+New+Template%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7774-361711+%5BSpecified%5D&cf_build_id=7774-361711+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Template%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7775-361713+%5BSpecified%5D&cf_build_id=7775-361713+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Template%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The templates collection contains an export action.

The export action exports a template to an Export storage domain. A destination storage domain isspecified with a storage_domain reference.

The export action reports a failed action if a virtual machine template of the same name exists in thedestination domain. Set the exclusive parameter to true to change this behaviour and overwrite anyexisting 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.1Accept: application/xmlContent-type: application/xml

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

Report a bug


202

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7776-361716+%5BSpecified%5D&cf_build_id=7776-361716+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Export+Template+Action%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 17. Virtual Machine Pools

17.1. Virtual Machine Pool ElementsThe vmpools collection provides information about the virtual machine pools in a Red Hat EnterpriseVirtualization environment. An API user accesses this information through the rel="vmpools" linkobtained from the entry point URI.

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

Table 17.1. Virtual machine pool elements


size integer The number of virtual machines in thepool.

cluster id= GUID A reference to the cluster resourcewhich virtual machines in this pool run.

template id= GUID A reference to the template resourcewhich virtual machines in this pool arebased.

Important

The API as documented in this chapter is experimental and subject to change. It is not covered bythe backwards compatibility statement.

Report a bug

17.2. XML Representation of a Virtual Machine PoolExample 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>

Report a bug

17.3. Methods

17.3.1. Creating a New Virtual Machine Pool

Chapter 17. Virtual Machine Pools

203

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8003-366691+%5BSpecified%5D&cf_build_id=8003-366691+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Virtual+Machine+Pool+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8004-365121+%5BSpecified%5D&cf_build_id=8004-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Virtual+Machine+Pool%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

A new pool requires the name, cluster and template elements. Identify the cluster and template with the id attribute or name element.

Example 17.2. Creating a virtual machine pool

POST /api/vmpools HTTP/1.1Accept: application/xmlContent-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>

Report a bug

17.3.2. Updating a Virtual Machine PoolThe name, description and size are updatable post-creation.

Example 17.3. Updating a virtual machine pool

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

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

Report a bug

17.3.3. Removing a Virtual Machine PoolRemoval 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


Report a bug


204

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7777-361721+%5BSpecified%5D&cf_build_id=7777-361721+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+New+Virtual+Machine+Pool%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7778-361723+%5BSpecified%5D&cf_build_id=7778-361723+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Virtual+Machine+Pool%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7779-361724+%5BSpecified%5D&cf_build_id=7779-361724+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Virtual+Machine+Pool%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 18. Domains

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

Table 18.1. Domain elements


name string The domain name.

link rel="users" relationship A link to the sub-collection for usersassociated with this domain.

link rel="groups" relationship A link to the sub-collection for groupsassociated with this domain.

The links to users and groups sub-collections also accept search queries.

Note

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

Report a bug

18.2. XML Representation of a Domain ResourceExample 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>

Report a bug


18.3.1. Domain Users Sub-Collection

Chapter 18. Domains

205

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8005-365121+%5BSpecified%5D&cf_build_id=8005-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Domain+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8006-365121+%5BSpecified%5D&cf_build_id=8006-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Domain+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

The users sub-collection contains all users in the directory service. This information is used to add newusers to the Red Hat Enterprise Virtualization environment.

Table 18.2. Domain user elements


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>[email protected]</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>

Report a bug

18.3.2. Domain Groups Sub-CollectionThe groups sub-collection contains all groups in the directory service. A domain group resourcecontains a set of elements.

Table 18.3. Domain group elements


name string The name of the group.

domain id GUID The containing directory service domain.


206

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8007-365121+%5BSpecified%5D&cf_build_id=8007-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Domain+Users+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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>

Report a bug

Chapter 18. Domains

207

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8008-365121+%5BSpecified%5D&cf_build_id=8008-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Domain+Groups+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 19. Groups

19.1. Imported Group ElementsThe groups collection contains imported groups from directory services. A group resource contains aset of elements.

Table 19.1. Imported group elements


link rel="tags" relationship A link to the tags sub-collection for tags attachedto this group.

link rel="permissions" relationship A link to the permissions sub-collection forpermissions attached to this group.

link rel="roles" relationship A link to the roles sub-collection for rolesattached to this group.

Report a bug

19.2. XML Representation of a Group ResourceExample 19.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>

Report a bug

19.3. Adding a Group from a Directory ServiceThe API adds existing directory service groups to the Red Hat Enterprise Virtualization Managerdatabase with a POST request to the groups collection.

Example 19.2. Adding a group from a directory service

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

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


208

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8009-365121+%5BSpecified%5D&cf_build_id=8009-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Imported+Group+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8010-365121+%5BSpecified%5D&cf_build_id=8010-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Group+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

Chapter 19. Groups

209

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12788-365966+%5BSpecified%5D&cf_build_id=12788-365966+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Adding+a+Group+from+a+Directory+Service%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 20. Roles

20.1. Role ElementsThe rel="roles" link obtained from the entry point URI provides access to a static set of systemroles. Each individual role element contains the following:

Table 20.1. Role elements


link="permits" relationship A link to the permits sub-collectionfor role permits.

mutable Boolean: true or false Defines the ability to update ordelete the role. Roles with mutableset to false are roles built into theRed Hat Enterprise Virtualizationenvironment.

administrative Boolean: true or false Defines the role as administrative-only.

Report a bug

20.2. XML Representation of the Roles Collection


210

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8011-366694+%5BSpecified%5D&cf_build_id=8011-366694+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Role+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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

Report a bug

20.3. Methods

20.3.1. Creating a RoleCreation of a role requires values for name, administrative and a list of initial permits.

Example 20.2. Creating a role

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

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

Chapter 20. Roles

211

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8012-365121+%5BSpecified%5D&cf_build_id=8012-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+the+Roles+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

20.3.2. Updating a RoleThe name, description and administrative elements are updatable post-creation.

Example 20.3. Updating a role

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

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

Report a bug

20.3.3. Removing a RoleRemoval of a role requires a DELETE request.

Example 20.4 . Removing a role

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


Report a bug

20.4. Roles Permits Sub-Collection

20.4.1. Roles Permits Sub-CollectionEach role contains a set of allowable actions, or permits, which the API lists in capabilities. Formore information on access to permits.

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


212

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7780-361747+%5BSpecified%5D&cf_build_id=7780-361747+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+a+Role%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7781-361748+%5BSpecified%5D&cf_build_id=7781-361748+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Role%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7782-361749+%5BSpecified%5D&cf_build_id=7782-361749+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Role%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 20.5. Listing a role's permits

GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1Accept: 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>

Report a bug

20.4.2. Assign a Permit to a RoleAssign a permit to a role with a POST request to the permits sub-collection. Use either an idattribute or a name element to specify the permit to assign.

Example 20.6. Assign a permit to a role

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

<permit id="1"/>


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

Report a bug

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

Chapter 20. Roles

213

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8013-365121+%5BSpecified%5D&cf_build_id=8013-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Roles+Permits+Sub-Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7783-361752+%5BSpecified%5D&cf_build_id=7783-361752+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Assign+a+Permit+to+a+Role%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 20.7. Remove a permit from a role

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


Report a bug


214

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7784-361755+%5BSpecified%5D&cf_build_id=7784-361755+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Remove+a+Permit+from+a+Role%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 21. Users

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

Table 21.1. User elements


user_name string The user principal name (UPN). TheUPN is used as a more convenientidentifier when adding a new user.

link rel="tags" relationship A link to the tags sub-collection foruser resources.

link rel="roles" relationship A link to the roles sub-collection foruser resources.

name string A free-text name for the user.

domain string The containing directory servicedomain.

groups complex A list of directory service groups forthis user.

Report a bug

21.2. XML representation of a User Resource

Chapter 21. Users

215

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8014-366611+%5BSpecified%5D&cf_build_id=8014-366611+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+User+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 21.1. An XML representation of a user resource

GET /api/users HTTP/1.1Accept: 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>[email protected]</user_name> <groups> <group>Group Policy Creator [email protected]/Users</group> <group>Domain [email protected]/Users</group> <group>Enterprise [email protected]/Users</group> <group>Schema [email protected]/Users</group> <group>[email protected]/Builtin</group> </groups></user>

Report a bug

21.3. Methods

21.3.1. Adding a UserThe API adds an existing directory service user to the Red Hat Enterprise Virtualization Managerdatabase with a POST request to the users collection. The client-provided new user representationincludes an embedded roles list with at least one initial role to assign to the user. For example, thefollowing request assigns two initial roles to the user [email protected] :

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

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

<user> <user_name>[email protected]</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


216

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8015-365121+%5BSpecified%5D&cf_build_id=8015-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+representation+of+a+User+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

directory service user principal name (UPN). The user ID format reported from the directory servicedomain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as inLDIF , the ID has the opposite byte order and is base-64 encoded. Hence it is usually moreconvenient 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 EnterpriseVirtualization 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.

Report a bug

21.3.2. Adding Roles to a UserFurther roles are attached or detached with POST or DELETE requests to the roles sub-collection of anindividual user. The example below illustrates how the API adds the RHEVMVDIUser role to the roleassignments for a particular user.

Note

The embedded user roles list of the user element is only used for the initial creation. Allinteractions 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.1Content-Type: application/xmlAccept: application/xml

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

Report a bug

[5]

[5] The LDAP Data Interchang e Fo rmat is d escrib ed in RFC 28 49 .

Chapter 21. Users

217

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7785-361762+%5BSpecified%5D&cf_build_id=7785-361762+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Adding+a+User%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7786-361764+%5BSpecified%5D&cf_build_id=7786-361764+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Adding+Roles+to+a+User%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer


Chapter 22. Tags

22.1. Tag ElementsThe 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.

The following table shows specific elements contained in a tag resource representation.

Table 22.1. Tag elements


host GUID A reference to the host which the tagis attached.

user GUID A reference to the user which the tagis attached.

vm GUID A reference to the VM which the tagis attached.

parent complex A reference to the VM which the tagis attached.

Report a bug

22.2. XML Representation of a Tag ResourceExample 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>

Report a bug

22.3. Associating Tags

22.3.1. Associating Tags With a Host, User or VMThe collection referenced by link rel="tags" from a host, user or vms represents the set of tagsassociated with the entity.

These tag representations also contain a host id, user id or vm id reference to the entity inquestion.

Associating a tag with an entity is achieved by POST ing a tag reference (identifying the tag either by its


218

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8016-366615+%5BSpecified%5D&cf_build_id=8016-366615+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Tag+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8017-365121+%5BSpecified%5D&cf_build_id=8017-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Tag+Resource%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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.1Accept: application/xmlContent-Type: application/xml

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


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

Report a bug

22.3.2. Removing a TagRemoving 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


Report a bug

22.3.3. Querying a Collection for Tagged ResourcesTo query the set of entities associated with a given tag, the collection/search URI template for theappropriate collection should be used to search for entities matching tag=MyTag.

Chapter 22. Tags

219

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8637-365067+%5BSpecified%5D&cf_build_id=8637-365067+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Associating+Tags+With+a+Host%2C+User+or+VM%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7790-365069+%5BSpecified%5D&cf_build_id=7790-365069+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Tag%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 22.4 . Querying a collection for tagged resources

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


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

Report a bug

22.4. Parent Tags

22.4.1. Parent TagsAn API user assigns a parent element to a tag to create a hierarchical link to a parent tag. The tagsare presented as a flat collection, which descends from the root tag, with tag representationscontaining 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 isspecified. The root tag cannot be deleted nor assigned a parent tag.

This tag hierarchy is expressed in the following way:


220

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7791-365071+%5BSpecified%5D&cf_build_id=7791-365071+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Querying+a+Collection+for+Tagged+Resources%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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)

Report a bug

22.4.2. Setting a Parent TagPOST ing a new tag with a parent element creates an association with a parent tag, using either the idattribute or the name element to reference the parent tag

Chapter 22. Tags

221

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8018-365121+%5BSpecified%5D&cf_build_id=8018-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Parent+Tags%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 22.6. Sett ing an association with a parent tag with the id attribute



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

Example 22.7. Sett ing an association with a parent tag with the name element



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

Report a bug

22.4.3. Changing a Parent TagA 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.1Accept: application/xmlContent-Type: application/xml

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


222

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7792-366619+%5BSpecified%5D&cf_build_id=7792-366619+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Setting+a+Parent+Tag%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Report a bug

Chapter 22. Tags

223

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7793-366620+%5BSpecified%5D&cf_build_id=7793-366620+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Changing+a+Parent+Tag%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 23. Events

23.1. Event ElementsThe rel="events" link obtained from the entry point URI accesses the events collection and listssystem events from Red Hat Enterprise Virtualization Manager.

Table 23.1. Event elements


description string A description of the system event

code integer The integer event code.

severity One of normal, warning, erroror alert

The level of severity for the event.

time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The timestamp indicating when the eventhappened.

user id GUID The identification code for the user who triggeredthe event.

Note

The events collection is read-only.

Report a bug

23.2. XML Representation of the Events CollectionExample 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>

Report a bug

23.3. XML Representation of a Virtual Machine Creation EventIn addition to user, an event representation also contains a set of XML element relationships to


224

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8019-365121+%5BSpecified%5D&cf_build_id=8019-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Event+Elements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8020-365121+%5BSpecified%5D&cf_build_id=8020-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+the+Events+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 astorage domain resource.

Report a bug

23.4. Searching EventsThe events collection provides search queries similar to other resource collections. An additionalfeature when searching the events collection is the ability to search from a certain event. This queriesall 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.

Chapter 23. Events

225

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8021-365121+%5BSpecified%5D&cf_build_id=8021-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+XML+Representation+of+a+Virtual+Machine+Creation+Event%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 23.3. Searching from an event

GET /api/events;from=1012?search=type%3D30 HTTP/1.1Accept: application/xml

This displays all events with type set to 30 since id="1012"

HTTP/1.1 200 OKContent-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.

Report a bug

23.5. Paginating EventsA virtualization environment generates a large amount of events after a period of time. However, the APIonly displays a default number of events for one search query. To display more than the default, the APIseparates 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


226

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7787-365080+%5BSpecified%5D&cf_build_id=7787-365080+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Searching+Events%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

sortby clause:

sortby time asc page 1

The sortby clause defines the base element to order of the results and whether the results areascending or descending. For search queries of events, set the base element to time and the order toascending (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:




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.1Accept: application/xml

Increase the page value to view the next page of results.

GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1Accept: 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.1Accept: application/xml

Report a bug

Chapter 23. Events

227

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7788-365082+%5BSpecified%5D&cf_build_id=7788-365082+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Paginating+Events%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Part III. Python Sofware Development Kit


228

Chapter 24. Software Development Kit Overview

24.1. Introduction to the Red Hat Enterprise VirtualizationSoftware Development KitThe software development kit provides programming language specific libraries for interacting with theREST API provided by Red Hat Enterprise Virtualization Manager. These libraries include classes torepresent resources made available by the API and methods for interacting with them. This allows you toconcentrate on writing code specific to what you are trying to achieve rather than on handcraftingappropriately formatted HTTP requests and manually orchestrating their delivery.

The software development kit includes collections and methods mapping directly to all aspects of theREST API. As a result this software development kit documentation focuses on providing exampleswritten in the supported programming language. For a complete reference of all collections, resources,actions, and attributes supported refer to the REST API material.

Report a bug

24.2. Software Development Kit PrerequisitesTo install the software development kit you must have:

A system with Red Hat Enterprise Linux 6.3, or later, installed. Both the Server and Workstationvariants 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 alreadyexist on the system.

Important

To run scripts which make use of the libraries provided by the software development kit therhevm-sdk must be installed. As a result the prerequisites listed here must be met both on thesystems being used to develop scripts using the software development kit and on those systemson which the scripts are intended to run.

Report a bug

24.3. Installing the Software Development KitSummary

The software development kit is provided by the rhevm-sdk. The package includes all of the Pythonbindings for the Red Hat Enterprise Virtualization Manager Application Programming Interface (API). Tobegin using the software development kit you must install the rhevm-sdk package on the system thatyou wish to use for your script development. The instructions that appear here are intended for use on asystem running Red Hat Enterprise Linux 6.3 or later.

Procedure 24 .1. Installing the Python SDK

Chapter 24. Software Development Kit Overview

229

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9288-451935+%5BSpecified%5D&cf_build_id=9288-451935+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Introduction+to+the+Red+Hat+Enterprise+Virtualization+Software+Development+Kit%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9290-365121+%5BSpecified%5D&cf_build_id=9290-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Software+Development+Kit+Prerequisites%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

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 channel to install the rhevm-sdk package. Referto the Red Hat Enterprise Virtualization Manager Release Notes for specific channel namescurrent to your system.

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 thelocal system.

Report a bug


230

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11463-432682+%5BSpecified%5D&cf_build_id=11463-432682+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Installing+the+Software+Development+Kit%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 25. Using the Software Development Kit

25.1. Connecting to the API using PythonTo connect to the REST API using Python you must create an instance of the API class from theovirtsdk.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:

urlSpecifies the URL of the Manager to connect to, including the /api path. This parameter ismandatory.

usernameSpecifies the user name to connect using, in User Principle Name (UPN) format. This parameteris mandatory.

passwordSpecifies the password for the user name provided by the username parameter. Thisparameter is mandatory.

key_fileSpecifies a PEM formatted key file containing the private key associated with the certificatespecified by cert_file. This parameter is optional.

cert_fileSpecifies a PEM formatted client certificate to be used for establishing the identity of the clienton the server. This parameter is optional.

ca_fileSpecifies the certificate file of the certificate authority for the server. This parameter ismandatory unless the insecure parameter is set to True.

portSpecifies the port to connect using, where it has not been provided as component of the urlparameter. This parameter is optional.

t imeoutSpecifies the amount of time in seconds that is allowed to pass before a request is to beconsidered as having timed out. This parameter is optional.

persistent_authSpecifies whether persistent authentication is enabled for this connection. Valid values are True and False. This parameter is optional and defaults to False.


231

insecureAllows a connection via SSL without certificate authority. Valid values are True and False. Ifthe insecure parameter is set to False - which is the default - then the ca_file must besupplied to secure the connection.

This option should be used with caution, as it may allow man-in-the-middle (MITM) attackers tospoof the identity of the server.

filterSpecifies 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 authenticationcredentials 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 userbased on their permissions.

debugSpecifies whether debug mode is enabled for this connection. Valid values are True and False. This parameter is optional.

You can communicate with multiple Red Hat Enterprise Virtualization Managers by creating andmanipulating separate instances of the ovirtsdk.API Python class.

This example script creates an instance of the API class, checks that the connection is working usingthe 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.apipackage.

Report a bug

25.2. Resources and CollectionsThe RESTful nature of the API is evident throughout the Python bindings for both theoretical andpractical reasons. All RESTful APIs have two key concepts that you need to be aware of:

CollectionsA collection is a set of resources of the same type. The API provides both top-level collectionsand sub-collections. An example of a top-level collection is the hosts collection which contains


232

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9289-374820+%5BSpecified%5D&cf_build_id=9289-374820+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Connecting+to+the+API+using+Python%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

all virtualization hosts in the environment. An example of a sub-collection is the host.nicscollection 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).

ResourcesA resource in a RESTful API is an object with a fixed interface that also contains a set ofattributes that are relevant to the specific type of resource being represented. The interface forinteracting with resources provides methods for updating (update ) and deleting (delete)resources. Additionally some resources support actions specific to the resource type. Anexample is the approve method of Host resources.

Report a bug

25.3. Retrieving Resources from a CollectionResources are retrieved from a collection using the get and list methods.

getRetrieves a single resource from the collection. The item to retrieve is determined based on thename provided as an argument. The get method takes these arguments:

name - The name of the resource to retrieve from the collection.

id - The globally unique identifier (GUID) of the resource to retrieve from the collection.

listRetrieves any number of resources from the collection. The items to retrieve are determinedbased 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 theRed 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).

Report a bug

25.4. Retrieving a Specific Resource from a CollectionIn these examples a specific resource is retrieved from a collection using the get method.


233

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11607-450299+%5BSpecified%5D&cf_build_id=11607-450299+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Resources+and+Collections%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11627-369625+%5BSpecified%5D&cf_build_id=11627-369625+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Retrieving+Resources+from+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 25.1. Retrieving a Specific Resource by Name

Retrieving the Default data center from the datacenters collection using the name parameter ofthe get method:

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

This syntax is equivalent:


Report a bug

25.5. Retrieving a List of Resources from a CollectionIn 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 listmethod allows the use of engine based queries. In this way the SDK supports the use of queries inthe same format as those executed in the Administration and User Portals. The query parameter isalso the mechanism for providing pagination arguments while iterating through the collection.

dc_list = []dc_page_index = 1dc_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 inthe locally defined dc_list list variable.

Warning

The list method of a collection is restricted to returning only as many elements as allowed bythe SearchResultsLimit Red Hat Enterprise Virtualization Manager configuration key.To ensure that all records in a the list are returned it is recommended that you paginatethrough the results as illustrated in this example.Alternatively you may choose to set the max parameter of the list method to the maximumnumber of records that you wish to retrieve.


234

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11854-365121+%5BSpecified%5D&cf_build_id=11854-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Retrieving+a+Specific+Resource+from+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 25.3. Retrieving a List of Resources in a Collection Matching a Keyword BasedFilter

Retrieving a list of all resources in the datacenters collection that have a storage type of nfs. Inthis example both the query parameter and **kwargs parameter are supplied. The query is used forpagination in the same way as illustrated in the previous example. The **kwargs parameter is usedto filter based on the storage type of the data center.

dc_list = []dc_page_index = 1dc_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.

Report a bug

25.6. Adding a Resource to a CollectionThe add method of a collection adds a resource. The resource to be added is created based on theparameters provided. Parameters are provided to the add method using an instance of an object fromthe ovirtsdk.xml.params module. Which specific class from the module needs to be used varies basedon 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 forcreating 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.


235

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11853-365121+%5BSpecified%5D&cf_build_id=11853-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Retrieving+a+List+of+Resources+from+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example 25.5. Complex Parameters

In this example an NFS data center running in full version 3.2 compatibility mode is being created. Todo this it is necessary to first construct a ovirtsdk.xml.params.Version object. Then this isused as a parameter when creating an instance of a ovirtsdk.xml.params.DataCenter objectcontaining parameters of the data center to be created. The resource is then created using the addmethod of the datacenters collection.

v_params = params.Version(major=3, minor=2)dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params)dc = api.datacenters.add(dc_params)

Report a bug

25.7. Updating a Resource in a CollectionTo update a resource you must retrieve it from the collection it resides in, modify the desiredparameters, and then call the update method for the resource to save the changes. Parametermodification 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()

Report a bug

25.8. Removing a Resource from a CollectionTo remove a resource you must retrieve it from the collection that contains it and call the deletemethod 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()

Report a bug

25.9. Handling ErrorsWhere errors are encountered the Software Development Kit uses exceptions to highlight them. TheSoftware Development Kit defines exception types in addition to those defined by the Python interpreter


236

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11626-384922+%5BSpecified%5D&cf_build_id=11626-384922+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Adding+a+Resource+to+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11629-365121+%5BSpecified%5D&cf_build_id=11629-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Updating+a+Resource+in+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11628-365121+%5BSpecified%5D&cf_build_id=11628-365121+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Removing+a+Resource+from+a+Collection%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

itself. These exceptions are located in the ovirtsdk.infrastructure.errors module:

ConnectionErrorRaised when a transport layer error has occurred.

DisconnectedErrorRaised when attempting to use sdk after it was explicitly disconnected.

ImmutableErrorRaised when initiating sdk while an sdk instance already exists under the same domain.Applicable to sdk <3.2.

NoCertificatesErrorRaised when no CA is provided and --insecure is 'False'.

RequestErrorRaised at any kind of oVirt server error.

UnsecuredConnectionAttemptErrorRaised when HTTP protocol is used while server is running HTTPS.

MissingParametersErrorRaised when you are trying to use get() method without providing either id or name.

These exceptions can be caught and handled like any other Python exception:

Example 25.8. Catching a ConnectionError Exception


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

Report a bug


237

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+11972-370804+%5BSpecified%5D&cf_build_id=11972-370804+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Handling+Errors%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Chapter 26. Python Reference Documentation

26.1. Python Reference DocumentationDocumentation generated using pydoc is available for these modules provided by the rhevm-sdkpackage:

ovirtsdk.api

ovirtsdk.infrastructure.brokers

If instead you wish to view the pydoc generated documentation on your local machine provide the nameof the module you are interested in as an argument to the pydoc command:

$ pydoc MODULE

Report a bug


238

http://docs.python.org/library/pydoc.html

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13032-366718+%5BSpecified%5D&cf_build_id=13032-366718+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+Reference+Documentation%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

SDK Examples

A.1. Common StatementsCreating a Fibre Channel Storage Domain on a Data Center

Storage_Domain__name = 'SD-FC-001'Data_Center__name = 'DC-FC-001'Host__name = 'bobo-vds'Lun__ID = '3514f0c519e40063c'

sdParams = params.StorageDomain(name=Storage_Domain__name, data_center=api.datacenters.get(Data_Center__name), type_='data', storage_format='v3', host=api.hosts.get(Host__name), storage = params.Storage(type_='fcp', volume_group=params.VolumeGroup(logical_unit=[params.LogicalUnit(id=Lun__ID)])))

Creating a Storage Domain

try: if api.storagedomains.add(sdParams): print 'FC Storage Domain was created successfully'except Exception as e: print 'Failed to create FC Storage Domain:\n%s' % str(e)

Attaching a Storage Domain

try: if api.datacenters.get(name=Data_Center__name).storagedomains.add(api.storagedomains.get(name=Storage_Domain__name)): print 'FC Storage Domain was attached successfully'except Exception as e: print 'Failed to attach FC Storage Domain:\n%s' % str(e)

Activating a Storage Domain

try: if api.datacenters.get(name=Data_Center__name).storagedomains.get(Storage_Domain__name).activate(): print 'FC Storage Domain was activated successfully'except Exception as e: print 'Failed to activate FC Storage Domain:\n%s' % str(e)

Maintaining a Storage Domain

SDK Examples

239

try: if api.datacenters.get(name=Data_Center__name).storagedomains.get(Storage_Domain__name).deactivate(): print 'FC Storage Domain was maintenance successfully'except Exception as e: print 'Failed to maintenance FC Storage Domain:\n%s' % str(e)

Detach a Storage Domain from a Data Center

try: if api.datacenters.get(name=Data_Center__name).storagedomains.get(Storage_Domain__name).delete(): print 'FC Storage Domain was detached successfully'except Exception as e: print 'Failed to detach FC Storage Domain:\n%s' % str(e)

Delete an 'unattached' Storage Domain

try: if api.storagedomains.get(Storage_Domain__name).delete(params.StorageDomain(name=Storage_Domain__name,host=params.Host(name=Host__name), format=True)): print 'FC Storage Domain was removed successfully'except Exception as e: print 'Failed to remove FC Storage Domain:\n%s' % str(e)

Report a bug

A.2. Common Functions and WrappersHeader

__test__ = False

import config import states

from time import sleep import logging import ovirtsdk.api from ovirtsdk.xml import params from ovirtsdk.infrastructure import errors from ovirtsdk.infrastructure import contextmanager from functools import wraps

MB = 1024*1024 GB = 1024*MB

logging.basicConfig(filename='messages.log',level=logging.DEBUG) LOGGER = logging.getLogger(__name__) _major = int(config.OVIRT_VERSION[0]) _minor = int(config.OVIRT_VERSION[2:]) VERSION = params.Version(major=_major, minor=_minor)


240

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13568-435328+%5BSpecified%5D&cf_build_id=13568-435328+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Common+Statements%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

disconnect

def disconnect(): proxy = contextmanager.get('proxy') persistent_auth = contextmanager.get('persistent_auth') filter_header = contextmanager.get('filter')

if proxy and persistent_auth: try: proxy.request(method='GET', url='/api', headers={'Filter': filter_header}, last=True) except Exception: pass contextmanager._clear(force=True)

getApi

def _getApi(): """ Return ovirtsdk api.

Will not create another API instance when reloading this module in ipython (when common.API is already defined). Works around problem when reloading, which would otherwise cause the error `ImmutableError: [ERROR]::'proxy' is immutable.`. """ try: return API except NameError: disconnect() return ovirtsdk.api.API( url=config.OVIRT_URL, insecure=True, username=config.OVIRT_USERNAME+'@'+config.OVIRT_DOMAIN, password=config.OVIRT_PASSWORD)

API = _getApi()

waitForState

SDK Examples

241

def waitForState(obj, desiredStates, failStates=None, timeout=config.TIMEOUT, sampling=1, restoreState=None): """ Waits for oVirt object to change state using :py:func:`time.sleep`.

:param obj: the oVirt object (host, VM, ...) for which to wait :param desiredStates: the desired oVirt object states, accepts both a list of states or a single state :param failStates: fail if the object reaches one of these states :param timeout: (int) time in seconds to wait for desired state :param sampling: (int) how often to check state, in seconds :param restoreState state, tryies to maintentce->up host, when it is non_operational

:raises AssertionError: when timeout is exceeded and the object still isn't in the desired state or if failState was reached

.. seealso:: :mod:`tests.states` """ # 120 seconds is not enougn to wait for start if type(obj).__name__ == 'VM' and desiredStates == states.vm.up: timeout = 240

global res

if obj is None: return if type(desiredStates) is not list: desiredStates = [desiredStates] if type(failStates) is not list and failStates is not None: failStates = [failStates] elif failStates is None: failStates = []

assert type(obj) is not str, "Bad use of 'waitForState()'" t = 0 state = newState(obj) while state not in desiredStates and t <= timeout: sleep(sampling) t += sampling state = newState(obj) assert state not in failStates, \ "Failed to get %s into state '%s' because it reached the fail \ state '%s'" % (objectDescr(obj), desiredStates, state)

if t > timeout: LOGGER.error("%s didn't reach one of states %s in timout \ of %i sec, current state is '%s'" % (objectDescr(obj), str(desiredStates), timeout, state)) assert state in desiredStates, \ "Failed to get %s into desired state" % objectDescr(obj)

if type(obj).__name__ == 'VM': disks = obj.get_disks().list() if disks is not None: for disk in disks: waitForState(disk, states.disk.ok)

updateObject


242

Important

Storage domains have unexpected behaviour (by-design in oVirt). When you use a storagedomain that is unattached (by using àpi.storagedomains`) and then attach it, it will have nostatus when you look at it from this angle (and ùpdateObject` will return None). The state can bethen found in àpi.datacenters.get('dc').storagedomains`.

SDK Examples

243

def updateObject(obj): """ Return oVirt object with updated data.

:param obj: oVirt object (host, VM, storage, ...) :return: The object with updated data, for example status. None if object was deleted in the meantime (or attached/detached in case of storage domains). """

assert type(obj) is not str, "Bad use of 'updateObject()'" parent = None t = type(obj).__name__

if 'Host' == t: parent = API.hosts elif 'VM' == t: return getObjectByName(API.vms, obj.name) elif 'Disk' == t: return API.disks.get(id=obj.get_id()) elif 'VMSnapshot' == t: vmId = obj.get_vm().get_id() vm = API.vms.get(id=vmId) return vm.snapshots.get(id=obj.get_id()) elif 'VMDisk' == t: vmId = obj.get_vm().get_id() vm = API.vms.get(id=vmId) parent = vm.disks elif 'Template' == t: return getObjectByName(API.templates, obj.name) elif 'DataCenter' == t: parent = API.datacenters elif 'Cluster' == t: parent = API.clusters elif 'StorageDomain' == t: parent = API.storagedomains elif 'VmPool' == t: parent = API.vmpools elif 'DataCenterStorageDomain' == t: dcname = obj.parentclass.name dc = API.datacenters.get(dcname) parent = dc.storagedomains elif 'StorageDomainVM' == t: sdName = obj.parentclass.name sd = API.storagedomains.get(sdName) parent = sd.vms elif 'StorageDomainTemplate' == t: sdName = obj.parentclass.name sd = API.storagedomains.get(sdName) parent = sd.templates elif 'TemplateDisk' == t: tmpId = obj.get_template().get_id() tmp = API.templates.get(id=tmpId) parent = tmp.disks else: raise Exception("Unknown object %s, cannot update it's state" % (objectDescr(obj)))

return parent.get(id=obj.get_id())


244

newState

def (obj): """ Obtain new state of an oVirt object.

:param obj: oVirt object (host, VM, storage, ...) :return: (string) the new state of the object

.. seealso:: :func:`updateObject`, :mod:`tests.states` """ assert type(obj) is not str, "Bad use of 'newState()'" updatedObject = updateObject(obj) if updatedObject is None: LOGGER.warning("Object %s has no status" % (objectDescr(obj))) return None

if type(updatedObject).__name__ == 'VMSnapshot': return updatedObject.snapshot_status

status = updatedObject.status if status is None: LOGGER.warning("Object %s has no status" % (objectDescr(obj))) return None return status.state

objectDescr

def objectDescr(obj): """ Return oVirt object description.

:param obj: oVirt object (host, VM, storage, ...) :return: (string) `"ObjectType 'object name'"` """

typeName = type(obj).__name__ if 'StorageDomain' in typeName: typeName = 'Storage Domain'

return "%s '%s'" % (typeName, obj.name)

createDataCenter

def createDataCenter(name, storageType=config.MAIN_STORAGE_TYPE, version=VERSION): LOGGER.info("Creating data center '%s'" % name) API.datacenters.add(params.DataCenter( name=name, storage_type=storageType, version=version)) dc = API.datacenters.get(name) assert dc is not None

addNetworkToDC

SDK Examples

245

def addNetworkToDC(name, dcName): """ Add new network to DC 'dcName' with name 'name'. """ dc = API.datacenters.get(dcName) API.networks.add(params.Network(data_center=dc, name=name)) LOGGER.info("Network '%s' was added to DC '%s'." %(name, dcName))

net = API.networks.get(name=name) assert net is not None, "Network couldn't be created." return net

removeDataCenter

def removeDataCenter(name): """ Removes datacenter """ dc = API.datacenters.get(name) if dc is not None: LOGGER.info("Removing datacenter '%s'" % name) dc.delete() assert updateObject(dc) is None, "Can't remove datacenter"

createCluster

def createCluster(name, datacenterName, cpu_type=config.HOST_CPU_TYPE, version=VERSION): """ Creates cluster """ LOGGER.info("create_cluster") dc = API.datacenters.get(datacenterName) API.clusters.add(params.Cluster( name=name, cpu=params.CPU(id=cpu_type), data_center=dc, version=VERSION)) cluster = API.clusters.get(name) LOGGER.info("Creating cluster '%s'" % name) assert cluster is not None

removeCluster

def removeCluster(name): """ Removes cluster """ cluster = API.clusters.get(name) if cluster is not None: cluster.delete() LOGGER.info("Removing cluster '%s'" % name) assert updateObject(cluster) is None, "Can't remove cluster"

Report a bug

A.3. Python SDK Example: HostscreateHost


246

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13569-385484+%5BSpecified%5D&cf_build_id=13569-385484+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Common+Functions+and+Wrappers%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def createHost(clusterName, hostName, hostAddress, hostPassword): """ create host """ msg = "Installing host '%s' on '%s'" LOGGER.info(msg % (hostAddress, clusterName))

cluster = API.clusters.get(clusterName) API.hosts.add(params.Host( name=hostName, address=hostAddress, cluster=cluster, root_password=hostPassword)) host = API.hosts.get(hostName) assert host is not None

waitForState(host, states.host.up, failStates = states.host.install_failed, timeout = config.HOST_INSTALL_TIMEOUT, restoreState=states.host.non_operational)

waitForTasks

def waitForTasks(host, max_times=3, sleep_time=10): """ Max 3(default) times try to deactive host, if there are running tasks So try to wait about 30seconds, 3x10s(default) Parameters: * host - host to be deactivated * max_times - max times time try to deactive host * sleep_time - time to sleep between tryies """ while max_times > 0: try: host.deactivate() break except errors.RequestError as er: max_times -= 1 if max_times == 0: raise er sleep(sleep_time)

removeHost

SDK Examples

247

def removeHost(hostName): """ remove Host""" host = API.hosts.get(hostName) if host is not None: LOGGER.info("Deactivating host '%s'" % hostName)

# Max 3 times try to deactive host, if there are running tasks # So try to wait about 30seconds, 3x10s waitForTasks(host) waitForState(host, states.host.maintenance)

LOGGER.info("Deleting host") host.delete() assert updateObject(host) is None, "Failed to remove host" else: raise errors.RequestError("Unable to see any host") #dc = API.datacenters.get(config.MAIN_DC_NAME) ??? #waitForState(dc, 'up')

activeDeactiveHost

def activeDeactiveHost(hostName): """ Active, deactive host """ LOGGER.info("Activating/deactivating host '%s'" %hostName) host = API.hosts.get(hostName) waitForTasks(host)

LOGGER.info("Waiting for maintence") host = API.hosts.get(hostName) waitForState(host, states.host.maintenance) host.activate() LOGGER.info("Waiting for 'up' state") waitForHostUpState(host)

# Check DC state dc = API.datacenters.get(config.MAIN_DC_NAME) waitForState(dc, 'up')

checkHostStatus

def checkHostStatus(hostName): """ Check if is status up -> do UP """ host = API.hosts.get(hostName) if host is None: LOGGER.info("Host '%s' dont exists." % hostName) return if host.status.state != states.host.up: LOGGER.info("Host '%s' state is '%s'" % (hostName, host.status.state)) if host.status.state != states.host.maintenance: host.deactivate() waitForState(host, states.host.maintenance, timeout=180) LOGGER.info("Activating") host.activate() #waitForState(host, states.host.up) waitForHostUpState(host)


248

checkDataCenterStatus

def checkDataCenterStatus(dcName): """" Print dc status and attached storage domains statuses. Parameters: * dcName - name of DC to be printed """ dc = API.datacenters.get(dcName) if dc is None: LOGGER.info("DC '%s' dont exists." % dcName) return LOGGER.info("DC '%s' state is '%s'" % (dcName, dc.status.state)) for sd in dc.storagedomains.list(): LOGGER.info(" SD %s status is %s" % (sd.get_name(), str(sd.status.state)))

configureHostNetwork

def configureHostNetwork(hostName): """ Try to change network properties. Parameters: * hostName - name of host to be changed """ h = getFilterHeader() # Deactive host - need to be before configuring network loginAsAdmin() host = API.hosts.get(hostName) waitForTasks(host) waitForState(host, states.host.maintenance)

try: host = API.hosts.get(hostName) loginAsUser(filter_=h) for nic in host.nics.list(): if nic.status.state == 'up': nic.set_boot_protocol("dhcp") nic.update() break except Exception as e: raise e else: pass finally: # Activate host after test loginAsAdmin() host = API.hosts.get(hostName) host.activate() waitForHostUpState(host) dc = API.datacenters.get(config.MAIN_DC_NAME) waitForState(dc, states.host.up) loginAsUser(filter_=h)

waitForHostUpState

SDK Examples

249

maxTry = 3 def waitForHostUpState(host): """ Wait for host, when its state is up. Wait for 3x 240s. Could happend that host don't come up, so try again. Parameters: * host - host that should be wait for """ try: waitForState(host, states.host.up, timeout=240) except Exception as e: global maxTry maxTry -= 1 if maxTry == 0: maxTry = 3 raise e if host.status.state == states.host.non_operational or\ host.status.state == states.host.unassigned: host.deactivate() waitForState(host, states.host.maintenance) host.activate() waitForHostUpState(host)

Report a bug

A.4. Python SDK Example: Virtual MachinesgenerateTicket

def generateTicket(vmName): """ Starts vm and wait for up state. Generate ticket to connect to vm """ #vm = API.vms.get(vmName) vm = getObjectByName(API.vms, vmName) if vm.status.state != states.vm.up: vm.start() waitForState(vm, states.vm.up) vm.ticket() vm.stop() waitForState(vm, states.vm.down)

createVm


250

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13696-385574+%5BSpecified%5D&cf_build_id=13696-385574+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Hosts%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def createVm(vmName, memory=1*GB, createDisk=True, diskSize=512*MB, cluster=config.MAIN_CLUSTER_NAME, storage=config.MAIN_STORAGE_NAME): """ Creates VM and adds a system disk.

The defaultly created disk will be a bootable COW sparse system disk with size `diskSize` and interface virtio. If you want to add a different disk, set `createDisk` to False and add it manually. """ cluster = getObjectByName(API.clusters, cluster) template = getObjectByName(API.templates, 'Blank')

if getObjectByName(API.vms, vmName) is not None: LOGGER.warning("Vm '%s' with this name already exists" % vmName) return

API.vms.add(params.VM( name=vmName, memory=memory, cluster=cluster, template=template))

vm = getObjectByName(API.vms, vmName)

assert vm is not None, "Failed to create vm"

if createDisk: LOGGER.info('Attaching disk to VM') sd = getObjectByName(API.storagedomains, storage) param = params.StorageDomains( storage_domain=[sd]) updateObject(vm).disks.add(params.Disk( storage_domains=param, size=diskSize, #type_='system', status=None, interface='virtio', format='cow', sparse=True, bootable=True))

waitForState(vm, states.vm.down) LOGGER.info("VM '%s' was created." %(vmName))

getMainVmDisk

def getMainVmDisk(vmName): """ Return first disk of vm """ vm = getObjectByName(API.vms, vmName) disks = vm.disks.list() if len(disks) > 0: return disks[0] else: return None

waitForAllDisks

SDK Examples

251

def waitForAllDisks(vmName): """ Wait until all vm disks are ok """ vm = getObjectByName(API.vms, vmName) disks = vm.disks.list() if len(disks) > 0: for disk in disks: waitForState(disk, states.disk.ok)

stopVm_

def stopVm_(vmName): """ Stop vm and dont wait for disks """ vm = getObjectByName(API.vms, vmName) if vm.status.state != states.vm.down: try: vm.stop() except errors.RequestError as e: if 'vm is not running' in e.detail.lower(): pass else: raise waitForState(vm, states.vm.down)

stopVm

def stopVm(vmName): """ Stop vm and wait for main disk """ stopVm_(vmName) disk = getMainVmDisk(vmName) waitForState(disk, states.disk.ok)

removeAllVms

def removeAllVms(): """ Remove all vms in system """ for vm in API.vms.list(): if vm.status.state != states.vm.down: vm.stop() waitForState(vm, states.vm.down) removeVmObject(vm)

removeObject

def removeObject(obj): """ Removes object """ if obj is None: return obj.delete() waitForRemove(obj) LOGGER.info("Object '%s' removed." % (obj.get_name()))


252

removeVmObject

def removeVmObject(vm): """ Remove vm object """ removeObject(vm)

removeVm

def removeVm(vmName): """ Remove VM and wait until it really gets removed. """ vm = getObjectByName(API.vms, vmName) if vm is None: return LOGGER.info("Removing vm '%s'" %vmName) t = 0 while vm.status.state == states.vm.image_locked and t <= config.TIMEOUT: t += 1 sleep(1) updateObject(vm)

if vm.status.state != states.vm.down: vm.stop() waitForState(vm, states.vm.down)

waitForAllDisks(vmName) removeVmObject(vm)

suspendVm

SDK Examples

253

def suspendVm(vmName): """ Suspends VM and handles 'asynch running tasks' exception.

While suspending, the 'asynchronous running task' RequestError often occurs and means you have to wait a while to suspend the VM. """ vm = API.vms.get(vmName) assert vm.status.state == states.vm.up, \ "VM has to be in state 'up' before suspend" asyncException = True t = 0 while asyncException == True and t <= config.TIMEOUT: try: vm.suspend() asyncException = False except errors.RequestError as e: if 'asynchronous running tasks' in e.detail.lower(): LOGGER.info("Asynchronous running tasks in VM, \ cannot suspend, trying again") asyncException = True sleep(1) t += 1 else: raise if t > config.TIMEOUT: LOGGER.error("%s didn't start to suspend within timout \ of '%i' sec, current state is '%s'" % (objectDescr(vm), config.TIMEOUT, vm.status.state)) assert newState(vm) == states.vm.saving_state or \ newState(vm) == states.vm.suspended waitForState(vm, states.vm.suspended)

migrateVm

def migrateVm(vm, host): """ Migrate vm. Parameters: * vm - vm to be migrated * host - host where the vm should be migrated """ vm.migrate(params.Action(host=host)) waitForState(vm, states.vm.up, timeout=240) LOGGER.info("Migrated VM '%s' to host '%s'" % (vm.get_name(), host.get_name()))

moveVm


254

def moveVm(vmName, storageName): """ Move vm vmName to storage storageName Parameters: * vmName - vm to be moved * storageName - storage where the vm should be moved """ vm = getObjectByName(API.vms, vmName) sd = getObjectByName(API.storagedomains, storageName)

vm.move(params.Action(storage_domain=sd)) waitForState(vm, states.vm.down, timeout=7*60) LOGGER.info("VM '%s' was moved to sd '%s'" % (vmName, storageName))

createDiskObjectNoCheck

def createDiskObjectNoCheck(diskName, storage=config.MAIN_STORAGE_NAME): """ Create disk and return it, dont wait for ok state """ sd = getObjectByName(API.storagedomains, storage) param = params.StorageDomains(storage_domain=[sd]) disk = API.disks.add(params.Disk(alias=diskName, name=diskName, provisioned_size=10, size=10, status=None, interface='virtio', format='cow', sparse=True, bootable=False, storage_domains=param)) return disk

createDiskObject

def createDiskObject(diskName, storage=config.MAIN_STORAGE_NAME): """ Create disk and return it. Parameters: * diskName - name of disk * storage - storage, where disk should be created """ disk = createDiskObjectNoCheck(diskName, storage=storage) waitForState(disk, states.disk.ok) LOGGER.info("Disk '%s' created." % (disk.get_name())) assert disk is not None return disk

deleteDiskObject

def deleteDiskObject(disk): """ Delete disk, and wait for remove Parameters: * disk - disk to be removed """ disk.delete() LOGGER.info("Removing disk '%s'" % (disk.get_alias())) waitForRemove(disk)

SDK Examples

255

deleteDisk

def deleteDisk(diskId, alias=None): """ Delete disk. Parameters: * diskId - id of disk * alias - alias of disk, used if there is no id """ if alias is not None: disk = API.disks.get(alias=alias) else: disk = API.disks.get(id=diskId) if disk is None: LOGGER.info("Trying to delete nonexisting disk") return

deleteDiskObject(disk)

attachDiskToVm

def attachDiskToVm(disk, vmName): """ Attach disk to vm. Parameters: * disk - disk object to be attached to vm * vmName - vmName of vm to be attached to diskId """ vm = getObjectByName(API.vms, vmName) if vm is None: LOGGER.warn("Vm '%s' is None, test will fail" % vmName) if disk is None: LOGGER.warn("Disk '%s' is None, test will fail" % disk.get_name())

LOGGER.info("Attaching disk '" + disk.get_name() + "' to vm " + vmName) disk = vm.disks.add(disk) # Attach disk = vm.disks.get(id=disk.get_id()) assert disk is not None LOGGER.info("Disk '%s' state is '%s'" % (disk.get_name(), disk.status.state))

waitForState(disk, states.disk.ok) disk.delete(params.Action(detach=True)) # Detach disk = vm.disks.get(id=disk.get_id()) waitForState(disk, states.disk.ok)

editVmDiskProperties


256

def editVmDiskProperties(vmName, diskAlias=None): """ Edit vm disk properies. Parameters: * vmName - name of vm that should be changed disk """ vm = getObjectByName(API.vms, vmName) if vm is None: LOGGER.warning("Vm '%s' not exists." % (vmName)) return if diskAlias is not None: disk = vm.disks.get(alias=diskAlias) else: disk = vm.disks.list()[0] if disk is None: LOGGER.warn("Disk '%s' is None, test will fail" % disk.get_alias())

dName = disk.get_name() dId = disk.get_id() before = disk.get_interface() if before == 'virtio': after = 'ide' else: after = 'virtio'

disk.set_interface(after) disk.update() disk = vm.disks.get(id=dId) now = disk.get_interface() assert before != now, "Failed to update disk interface properties" LOGGER.info("Editting disk '" + dName + "'")

startStopVm

def startStopVm(vmName): """ Starts and stops VM """ vm = API.vms.get(vmName) vm.start() LOGGER.info("VM '%s' starting" % (vmName)) waitForState(vm, states.vm.up) vm.stop() LOGGER.info("VM '%s' stoping" % (vmName)) waitForState(vm, states.vm.down)

Report a bug

A.5. Python SDK Example: TemplatescreateTemplate

SDK Examples

257

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13697-385569+%5BSpecified%5D&cf_build_id=13697-385569+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Virtual+Machines%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def createTemplate(vmName, templateName): """ Create template from vmName """ vm = getObjectByName(API.vms, vmName) API.templates.add(params.Template(name=templateName, vm=vm)) LOGGER.info('Creating temaplate "' + templateName + '"') waitForState(vm, states.vm.down) assert getObjectByName(API.templates, templateName) is not None

removeTemplate

def removeTemplate(templateName): """ Remove template and wait until it really gets removed. Parameters: * templateName - name of template to be deleted """ template = getObjectByName(API.templates, templateName)

if template is None: LOGGER.info("Template '%s' can's be seen, or does not exist." % templateName) return

template.delete() LOGGER.info("Removing template '" + templateName + "'") waitForRemove(template)

searchByObjectName

def searchByObjectName(obj, name, id): """ Return object by its name Parameters: * obj - object, which want to search * name - name of object * id - id of object, used if name is None """ if name is None: return obj.get(id=id) # This is used because user level API don't support searching for o in obj.list(): if o.get_name() == name: return o

getObjectByName


258

def getObjectByName(obj, name, id=None): """ Return object by its name. Valid /vmpools. Parameters: * obj - object, which want to search * name - name of object * id - id of object, used if name is None """ try: return searchByObjectName(obj, name, id) except errors.RequestError as er: # This is used because user can't access to some urls # So this is workaround and should be removed after bug is OK filter_header = getFilterHeader() loginAsAdmin() o = searchByObjectName(obj, name, id) loginAsUser(filter_=filter_header) return o

Report a bug

A.6. Python SDK Example: Virtual Machine PoolscreateVmPool

def createVmPool(poolName, templateName, clusterName=config.MAIN_CLUSTER_NAME, size=1): """ Create Vm pool """ template = API.templates.get(templateName) cluster = API.clusters.get(clusterName)

API.vmpools.add(params.VmPool(name=poolName, cluster=cluster, template=template, size=size))

ff = getFilterHeader() loginAsAdmin() assert API.vmpools.get(poolName) is not None LOGGER.info('Creating vmpool "' + poolName + '"') loginAsUser(filter_=ff)

waitForRemove

def waitForRemove(obj): """ Wait config.TIMEOUT seconds until object is removed. Parameters: * obj - object for which want to wait """ t = 0 while updateObject(obj) is not None and t <= config.TIMEOUT: t += 1 sleep(1) assert updateObject(obj) is None, "Could not remove object"

detachAllVmsInPool

SDK Examples

259

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13698-385422+%5BSpecified%5D&cf_build_id=13698-385422+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Templates%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def detachAllVmsInPool(vmpoolName): """ Removes all Vms in pool and return these vms Parameters: * vmpoolName - name of pool from which vms will be detached """ vms = [] for vm in getAllVmsInPool(vmpoolName): LOGGER.info("Pool '%s' vm '%s' removing" % (vmpoolName, vm.get_name())) vm.detach() waitForState(vm, states.vm.down) vms.append(vm) return vms

removeAllVmsInPool

def removeAllVmsInPool(vmpoolName): """ Removes all Vms in pool """ for vm in getAllVmsInPool(vmpoolName): LOGGER.info("Pool '%s' vm '%s' removing" % (vmpoolName, vm.get_name())) vm.detach() waitForState(vm, states.vm.down) vm.delete() waitForRemove(vm)

getAllVmsInPool

def getAllVmsInPool(vmpoolName): """ Return list of vms in pool. Parameters: * vmpoolName - name of pool """ vms = [] for vm in API.vms.list(): pool = vm.get_vmpool() if pool is not None: pool = getObjectByName(API.vmpools, None, id=pool.get_id()) if pool.get_name() == vmpoolName: vms.append(vm)

return vms

removeVmPool

def removeVmPool(vmpool): """ Removes vm pool. Parameters: * vmpool - vmpool to be deleted """ if vmpool is None: LOGGER.warning("Trying to delete nonexisting vmpool.") return vmpool.delete() waitForRemove(vmpool) LOGGER.info("Vmpool '" + vmpool.get_name() + "' removed")


260

addVmToPool

def addVmToPool(vmpool): """ Add one new vm to vmpool """ LOGGER.info("Configuring VM pool '%s'" % (vmpool.get_name()))

sizeBefore = vmpool.get_size() newSize = int(sizeBefore) + 1 vmpool.set_size(newSize) vmpool.update()

vmpoolBasicOperations

def vmpoolBasicOperations(vmpool): """ Allocate vm from pool and then stop it Parameters: * vmpool - vmpool to test """ LOGGER.info("Trying basic operations on pool '%s'" % (vmpool.get_name()))

res = vmpool.allocatevm() vm = API.vms.get(id=res.get_vm().get_id()) waitForState(vm, states.vm.up) vm.stop() waitForState(vm, states.vm.down)

Report a bug

A.7. Python SDK Example: StoragecreateNfsStorage

SDK Examples

261

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13699-385426+%5BSpecified%5D&cf_build_id=13699-385426+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Virtual+Machine+Pools%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def createNfsStorage(storageName, storageType='data', address=config.NFS_STORAGE_ADDRESS, path=config.NFS_STORAGE_PATH, datacenter=config.MAIN_DC_NAME, host=config.MAIN_HOST_NAME): """ Creates NFS storage, but does not attach it.

Does not test if the storage already exists, so that it can be used in negative tests (the error will be produced by the sdk, not by this function.

:param storageName: (string) name of the storage domain to create :param storageType: (string) either 'data', 'export' or 'iso' :param address: (string) IP address of the storage :param path: (string) path to the storage on the server given by `address`, for example `'/mnt/nfs/mystorage'` :param datacenter: (string) name of the datacenter where it will be created :param host: (string) name of the host to use """

dc = API.datacenters.get(datacenter) sd = API.storagedomains.get(storageName)

storageParams = params.Storage(type_='nfs', address = address, path = path) sdParams = params.StorageDomain(name=storageName, data_center=dc, storage_format='v1', type_=storageType, host=API.hosts.get(host), storage = storageParams)

LOGGER.info("Creating NFS storage with name '%s' at host '%s'" % (storageName, host)) LOGGER.info("IP/Path of NFS: %s:%s" %(address, path)) storage = API.storagedomains.add(sdParams) storage = API.storagedomains.get(storage.get_name()) assert storage is not None, "Failed to create storage" return storage.get_name()

removeAllFromSD

def removeAllFromSD(sdName): """ Removes vms and temapltes from SD """ sd = API.storagedomains.get(sdName) for vm in sd.vms.list(): removeVmObject(vm) for tmp in sd.templates.list(): removeTemplate(tmp.get_name())

createIscsiStorage


262

def createIscsiStorage(storageName, storageType='data', address=config.LUN_ADDRESS, target=config.LUN_TARGET, guid=config.LUN_GUID, datacenter=config.MAIN_DC_NAME, host=config.MAIN_HOST_NAME): """ Creates iSCSI storage, but does not attach it.

Does not test if the storage already exists, so that it can be used in negative tests (the error will be produced by the sdk, not by this function.

.. seealso:: :func:`createNfsStorage` """ dc = API.datacenters.get(datacenter)

logicalUnit = params.LogicalUnit(id=guid, address=address, port=3260, target=target) storageParams = params.Storage(type_='iscsi', volume_group=params.VolumeGroup(logical_unit=[logicalUnit]))

sdParams = params.StorageDomain(name=storageName, data_center=dc, storage_format='v1', type_=storageType, host=API.hosts.get(host), storage = storageParams)

LOGGER.info("Creating iSCSI storage with name '%s'" % (storageName)) API.storagedomains.add(sdParams) storage = API.storagedomains.get(storageName) assert storage is not None, "Failed to create storage"

deactivateActivateByStateObject

def deactivateActivateByStateObject(storage, storageInDc, state, jmp, datacenter=config.MAIN_DC_NAME): if jmp or (storage.status is None and storageInDc is not None and \ storageInDc.status is not None and \ storageInDc.status.state != state): storageInDc.deactivate() waitForState(storageInDc, states.storage.maintenance, timeout=10*60) storageInDc.activate() waitForState(storageInDc, states.storage.active, timeout=10*60)

deactivateActivate

def deactivateActivate(storageName, datacenter=config.MAIN_DC_NAME): deactivateActivateByState(storageName=storageName, state=states.storage.active, jmp=False, datacenter=datacenter)

deactivateActivateByState

SDK Examples

263

def deactivateActivateByState(storageName, state, jmp, datacenter=config.MAIN_DC_NAME): dc = API.datacenters.get(datacenter) storage = API.storagedomains.get(storageName)

storageInDc = dc.storagedomains.get(storageName)

if jmp or (storage.status is None and storageInDc is not None and \ storageInDc.status is not None and \ storageInDc.status.state != state): storageInDc.deactivate() waitForState(storageInDc, states.storage.maintenance, timeout=10*60) storageInDc.activate() waitForState(storageInDc, states.storage.active, timeout=10*60)

attachActivateStorage

def attachActivateStorage(storageName, isMaster=False, datacenter=config.MAIN_DC_NAME): """ Attach and activate a storage domain.

Will not check if the storage is already active/attached, so it can be used in negative tests (the error will be from the sdk, not from here) """

LOGGER.info("Attaching storage '%s' to data center" % (storageName)) dc = API.datacenters.get(datacenter) storage = API.storagedomains.get(storageName) if dc.storagedomains.get(storageName) is not None: return

dc.storagedomains.add(storage) storage = dc.storagedomains.get(storageName) assert storage is not None, \ "Failed to attach storage to datacenter"

# the main storage gets activated on it's own, no need to call activate() if not isMaster: storage.activate() waitForState(storage, states.storage.active, timeout=10*60)

removeNonMasterStorage


264

def removeNonMasterStorage(storageName, datacenter=config.MAIN_DC_NAME, host=config.MAIN_HOST_NAME, destroy=False): """ Deactivate, detach and remove a non-master storage domain. """ dc = API.datacenters.get(name=datacenter) storage = API.storagedomains.get(storageName) if storage is None: LOGGER.warning("SD '%s' not exists." % storageName) return

doFormat = False if storage.get_type() == 'iso' else True

if isStorageAttached(storageName): s = dc.storagedomains.get(storageName) if s.status.state != states.storage.inactive and \ s.status.state != states.storage.maintenance: LOGGER.info("Deactivating storage") s.deactivate() waitForState(s, [states.storage.inactive, states.storage.maintenance]) if not destroy: LOGGER.info("Detaching storage from data center") s.delete() s = API.storagedomains.get(storageName) waitForState(s, states.storage.unattached)

LOGGER.info("Deleting storage '%s'" % (storageName)) param = params.StorageDomain(name=storageName, host=params.Host(name=host), format=doFormat, destroy=destroy) storage.delete(param) storage = API.storagedomains.get(storageName) assert storage is None, "Failed to remove SD '%s'" % (storageName)

deactivateMasterStorage

def deactivateMasterStorage(storageName=config.MAIN_STORAGE_NAME, datacenter=config.MAIN_DC_NAME, host=config.MAIN_HOST_NAME): """ Deactivates the master storage domain and its datacenter.

Fails if the storage doesn't exist (and therefore will not remove the datacenter). """ dc = API.datacenters.get(name=datacenter) assert dc is not None sd = dc.storagedomains

storage = sd.get(storageName) assert storage is not None

if storage.status.state == states.storage.inactive: LOGGER.warning("Master storage in maintenance before removal") else: LOGGER.info("Deactivating storage") storage.deactivate() waitForState(storage, states.storage.maintenance)

SDK Examples

265

removeMasterStorage

def removeMasterStorage(storageName=config.MAIN_STORAGE_NAME, datacenter=config.MAIN_DC_NAME, host=config.MAIN_HOST_NAME): """ Deactivates and removes the master storage domain and its datacenter.

Fails if the storage doesn't exist (and therefore will not remove the datacenter). """ dc = API.datacenters.get(name=datacenter) assert dc is not None sd = dc.storagedomains

storage = sd.get(storageName) assert storage is not None

LOGGER.info("Storage state: %s" %storage.status.state) try: waitForState(storage, states.storage.active) except: LOGGER.warning("Storage state: %s" %storage.status.state) try: storage.activate() waitForState(storage, states.storage.active) except: LOGGER.warning("Storage was not activated.") if storage.status.state == states.storage.inactive: LOGGER.warning("Master storage in maintenance before removal") else: LOGGER.info("Deactivating storage") storage.deactivate() waitForState(storage, states.storage.maintenance)

LOGGER.info("Deleting data center") dc.delete() assert updateObject(dc) is None, "Failed to remove DC"

storage = API.storagedomains.get(storageName) assert storage.status.state == states.storage.unattached, \ "Storage '%s' was not detached from DC" % storageName LOGGER.info("Deleting main storage") storage.delete(params.StorageDomain(name=storageName, host=params.Host(name=host), format=True)) assert API.storagedomains.get(storageName) is None, \ "Cannot remove master storage"

isStorageAttached


266

def isStorageAttached(storageName, datacenter=config.MAIN_DC_NAME): """ Return True if storage domain is attached to a datacenter.

:return: (bool) True if it is attached (even if it is locked or unreachable), False if it doesn't exist or if it is unattached. """ dc = API.datacenters.get(name=datacenter) storage = API.storagedomains.get(storageName) if storage is None: # storage doesn't even exist return False

storageInDc = dc.storagedomains.get(storageName) if storage.status is None and storageInDc is not None and \ storageInDc.status is not None: return True else: return False

detachAttachSD

def detachAttachSD(storageName=config.MAIN_STORAGE_NAME, datacenter=config.MAIN_DC_NAME): """ Detach and attach SD from DC """ if isStorageAttached(storageName): LOGGER.info("Deactivating/activating '%s'" % storageName) deactivateMasterStorage(storageName=storageName, datacenter=datacenter, host=config.MAIN_HOST_NAME) attachActivateStorage(storageName) else: LOGGER.info("Activation/deactivating '%s'" % storageName) attachActivateStorage(storageName) deactivateMasterStorage(storageName=storageName, datacenter=datacenter, host=config.MAIN_HOST_NAME)

Report a bug

A.8. Python SDK Example: GroupsremoveRole

def removeRole(roleName): """ Remove role. Parameters: * roleName - name of role to be removed """ role = API.roles.get(name=roleName) if role is None: LOGGER.warning("Role '%s' can't be removed, because don't exists." % (roleName)) role.delete()

addRole

SDK Examples

267

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13700-385466+%5BSpecified%5D&cf_build_id=13700-385466+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Storage%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def addRole(roleName, permits, description="", administrative=False): """ Add new role to system """ msg = "User role '%s' has not been created"

perms = params.Permits(permits) role = params.Role(name=roleName, permits=perms, description=description, administrative=administrative)

API.roles.add(role) LOGGER.info("Added new role '%s'." %roleName) role = API.roles.get(name=roleName) assert role is not None, msg % roleName

updateRole

def updateRole(roleName, permits=None, description=None, administrative=None): """ Update role roleName permits = list of permits (example: ['create_vm', 'delete_vm']) description = description of role administrative = True/False(Admin/User) """ role = API.roles.get(roleName) if role is None: LOGGER.warning("Role '%s' dont exists. Unable to remove" % roleName) return

if permits is not None: role.set_permits(permits) if description is not None: role.set_description(description) if administrative is not None: role.set_administrative(administrative)

role.update()

deleteRole

def deleteRole(roleName): """ Delete role roleName """ role = API.roles.get(roleName) if role is None: LOGGER.warning("Role '%s' doesnt exists. Cant remove it." % roleName) return role.delete()

role = API.roles.get(roleName) assert role is None, "Unable to remove role '%s'" % roleName

addGroup


268

def addGroup(groupName=config.GROUP_NAME): """ Add group to system """ LOGGER.info("Adding group " + groupName) group = params.Group(name=groupName) group = API.groups.add(group) assert API.groups.get(group.get_name()) is not None return group

addRoleToGroup

def addRoleToGroup(roleName, group): """ *RoleName* that should be added to *group* object. """ LOGGER.info("Adding role to group '%s'" % group.get_name()) group.roles.add(API.roles.get(roleName)) assert group.roles.get(roleName) is not None

deleteGroup

def deleteGroup(group): """ Deletes group from system """ if group is None: LOGGER.warning("Group '%s' doesnt exists. Cant remove it." % group.get_name()) return group.delete()

addUser

def addUser(userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Add user to system """ LOGGER.info("Adding user " + userName) domain = params.Domain(name=domainName) user = params.User(user_name=userName, domain=domain) user = API.users.add(user) assert API.users.get(user.get_name()) is not None

removeAllUsers

def removeAllUsers(domainName=config.USER_DOMAIN): """ Remove all users from system """ for user in API.users.list(): domain = API.domains.get(id=user.get_domain().get_id()) if domain.get_name() == domainName: user.delete()

removeUser

SDK Examples

269

def removeUser(userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Removes user. Parameters: * userName - name of user * domainName - domain of user """ LOGGER.info("Removing user '%s' " % userName) user = getUser(userName, domainName) if user is None: return nameOfUser = user.get_name() user.delete() assert API.users.get(nameOfUser) is None

getUser

def getUser(userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Return user object """ try: return API.users.list(user_name=userName + '@' + domainName)[0] except IndexError: try: return API.users.list(user_name=userName)[0] except Exception as err: LOGGER.error(err) LOGGER.error("User %s not found." % userName) return None

Report a bug

A.9. Python SDK Example: PermissionsgetRoles

def getRoles(): """ Return list of all roles """ return [role.get_name() for role in API.roles.list()]

getRolePermissions

def getRolePermissions(roleName): """ Return permissions of role """ role = API.roles.get(roleName) return [perm.get_name() for perm in role.get_permits().list()]

getSuperUserPermissions

def getSuperUserPermissions(): """ Return SuperUser permissions(all possible permissions) """ return getRolePermissions('SuperUser')

addRoleToUser


270

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13702-385468+%5BSpecified%5D&cf_build_id=13702-385468+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Groups%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

def addRoleToUser(roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Add system permissions to user. Parameters: * roleName - role permissions to add * userName - name of user who will be added permissions * domainName - domain of user """ LOGGER.info("Adding role '%s' to user '%s'" % (roleName, userName)) user = getUser(userName, domainName) if user is None: return user.roles.add(API.roles.get(roleName)) assert user.roles.get(roleName) is not None

removeAllRolesFromUser

def removeAllRolesFromUser(userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Removes all permissions from user. Parameters: * userName - name of user * domainName - domain of user """ LOGGER.info("Removing all roles from user %s" % userName) user = getUser(userName, domainName) if user is None: return

for role in user.roles.list(): LOGGER.info("Removing " + role.get_name()) role.delete()

assert len(user.roles.list()) == 0, "Unable to remove roles from user '%s'" % user.get_name()

removeRoleFromUser

def removeRoleFromUser(roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): """ Remove role(System permissions) from user. Parameters: * roleName - name of role * userName - name of user * domainName - domain of user """ LOGGER.info("Removing role %s to user %s" % (roleName, userName)) user = getUser(userName, domainName) if user is None: return role = user.roles.get(roleName) role.delete()

role = user.roles.get(roleName) assert role is None, "Unable to remove role '%s'" % roleName

SDK Examples

271

givePermissionsToGroup

def givePermissionsToGroup(templateName, roleName='UserTemplateBasedVm', group="Everyone"): """ Give permission to group. Parameters: * templateName - name of template to add group perms * roleName - name of role which perms to be added * group - On which group should be perms added """ template = getObjectByName(API.templates, templateName) r = API.roles.get(roleName)

g = API.groups.get(group) g.permissions.add(params.Permission(role=r, template=template)) LOGGER.info("Adding permissions on template '%s' role '%s' for group '%s'.", template.get_name(), roleName, group)

givePermissionToObject


272

def givePermissionToObject(rhevm_object, roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN, user_object=None, role_object=None): """ Add role permission to user on object. Parameters: * rhevm_object - object to add role permissions on * roleName - Role permissions to be added * userName - user who should be added permissions * domainName - domain of user * user_object - temporaly, because uf bug 869334 * role_object - temporaly, because uf bug 869334 """ # FIXME: rhevm_object can be one of: # [API.clusters, API.datacenters, API.disks, API.groups, API.hosts, # API.storagedomains, API.templates, API.vms, API.vmpools]

try: user = getUser(userName, domainName) if user is None: return except errors.RequestError as e: # User cant access /users url. Bug 869334. Workaround user = user_object

try: role = API.roles.get(roleName) except errors.RequestError as e: # User cant access /roles url. Bug 869334. Workaround role = role_object

if rhevm_object is None or user is None or role is None: LOGGER.warning("Unable to add permissions on 'None' object") returnremoving the first digit from a line

permissionParam = params.Permission(user=user, role=role) try: rhevm_object.permissions.add(permissionParam) except AttributeError as e: # Bz 869334 - after BZ ok, could be removed pass

msg = "Added permission on '%s' with role '%s' for user '%s'" LOGGER.info(msg % (type(rhevm_object).__name__, roleName, user.get_name()))

givePermissionToVm

def givePermissionToVm(vmName, roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): vm = getObjectByName(API.vms, vmName) givePermissionToObject(vm, roleName, userName, domainName)

givePermissionToDc

def givePermissionToDc(dcName, roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): dc = getObjectByName(API.datacenters, dcName) givePermissionToObject(dc, roleName, userName, domainName)

SDK Examples

273

givePermissionToCluster

def givePermissionToCluster(clusterName, roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): cl = getObjectByName(API.clusters, clusterName) givePermissionToObject(cl, roleName, userName, domainName)

givePermissionToTemplate

def givePermissionToTemplate(templateName, roleName, userName=config.USER_NAME, domainName=config.USER_DOMAIN): tmp = getObjectByName(API.templates, templateName) givePermissionToObject(tmp, roleName, userName, domainName)

removeAllPermissionFromObject

def removeAllPermissionFromObject(rhevm_object): """ Removes all permissions from object Parameters: * rhevm_object - object from which permissions should be removed """ LOGGER.info("Removing all permissions from object '%s'" % type(rhevm_object).__name__) if rhevm_object is None: LOGGER.info("Tying to remove perms from object that dont exists") return

permissions = rhevm_object.permissions.list() for perm in permissions: perm.delete() assert len(rhevm_object.permissions.list()) == 0

removeAllPermissionFromVm

def removeAllPermissionFromVm(vmName): vm = getObjectByName(API.vms, vmName) removeAllPermissionFromObject(vm)

removeAllPermissionFromDc

def removeAllPermissionFromDc(dcName): dc = getObjectByName(API.datacenters, dcName) removeAllPermissionFromObject(dc)

removeAllPermissionFromCluster

def removeAllPermissionFromCluster(clusterName): cluster = getObjectByName(API.clusters, clusterName) removeAllPermissionFromObject(cluster)

Report a bug


274

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13703-385560+%5BSpecified%5D&cf_build_id=13703-385560+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Permissions%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

A.10. Python SDK Example: UsersgetFilterHeader

def getFilterHeader(): """ Has user admin role or user role? """ return contextmanager.get('filter')

loginAsUser

def loginAsUser(userName=config.USER_NAME, domain=config.USER_DOMAIN, password=config.USER_PASSWORD, filter_=True): LOGGER.info("Login as %s" % userName) global API API.disconnect() API = ovirtsdk.api.API(url=config.OVIRT_URL, insecure=True, username=userName+'@'+domain, password=password, filter=filter_)

loginAsAdmin

def loginAsAdmin(): loginAsUser(config.OVIRT_USERNAME, config.OVIRT_DOMAIN, config.OVIRT_PASSWORD, filter_=False)

editObject

SDK Examples

275

def editObject(rhevm_object, name, newName=None, description=None, append=False): """ Edit object property. Parameters: * rhevm_object - object to be edited * name - name of object * newName - new name of object * description - description to be updated * append - True if append to old description else create new """ obj = rhevm_object.get(name)

old_name = obj.get_name() old_desc = obj.get_description() if newName is not None:removing the first digit from a line LOGGER.info("Updating name from '%s' to '%s'" %(name, newName)) obj.set_name(newName) obj.update() obj = rhevm_object.get(name) assert old_name != obj.get_name(), "Failed to update object name"

if description is not None: LOGGER.info("Updating desc from '%s' to '%s'" %(name, description)) if old_desc is None: old_desc = "" obj.set_description(old_desc + description if append else description) obj.update() obj = rhevm_object.get(name) assert old_desc != obj.get_description(), "Failed to update object description"

copyTemplate

def copyTemplate(templateName, storageName): """ Copy template disk from SD to another SD Parameters: * templateName - name of template to be copyied * storageName - name of storage where tmp should be copyied """ template = getObjectByName(API.templates, templateName)

try: disk = template.disks.list()[0] except IndexError: LOGGER.warning("Template '%s' has no disks?! => FAIL" % templateName) return except Exception as err: LOGGER.warning("Unexpected error: '%s'" %str(err)) return

sd = getObjectByName(API.storagedomains, storageName) LOGGER.info("Copying '%s' disk to '%s' domain" %(templateName, storageName))

disk.copy(action=params.Action(storage_domain=sd)) waitForState(disk, states.disk.ok)

changeVmCustomProperty


276

def changeVmCustomProperty(vmName, regexp, name, value): """ Changes vm custom property Parameters: * vmName - name of vm to change * regexp - regexp to change * name - name to be changed * value - value to be changed """ cp = params.CustomProperties([params.CustomProperty(regexp=regexp, name=name, value=value)]) vm = getObjectByName(API.vms, vmName) vm.set_custom_properties(cp) vm.update()

hasUserPermissions

def hasUserPermissions(obj, role, user=config.USER_NAME, domain=config.USER_DOMAIN): """ Tests if user have role permssions on rhevm_object Parameters: * obj - object which we wanna tests * role - role we wanna test * user - user we wanna test * domain - domain where user belongs """ perms = obj.permissions.list() for perm in perms: role_name = API.roles.get(id=perm.get_role().get_id()).get_name() user_name = API.users.get(id=perm.get_user().get_id()).get_user_name() if user_name + '@' + domain == user and role_name == role: return True return False

hasPermissions

def hasPermissions(role): """ Get a list of permissions the user role has.

:param role: (string) oVirt user role :return: (list of strings) permissions the role should have """ return getRolePermissions(role)

# If bz plugin is not enabled, use this def bz(*ids): def decorator(func): return func return decorator

# If tcms plugin is not enabled, use this def tcms(*ids): def decorator(func): return func return decorator

Report a bug

SDK Examples

277

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13704-385477+%5BSpecified%5D&cf_build_id=13704-385477+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Python+SDK+Example%3A+Users%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer


278

API Usage with cURL

B.1. API Usage with cURLThis appendix provides instructions on adapting REST requests for use with cURL. cURL is acommand line tool for transfering data across various protocols, including HTTP, and supports multipleplatforms such as Linux, Windows, Mac OS and Solaris. Most Linux distributions include cURL as apackage.

Report a bug

B.2. Installing cURLA 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/).

Report a bug

B.3. Using cURLcURL uses a command line interface to send requests to a HTTP server. Integrating a request requiresthe 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 HatEnterprise Virtualization Manager host within the API entry point path (/api).

cURL options

-X COMMAND, - -request COMMANDThe request command to use. In the context of the REST API, use GET , POST , PUT or DELETE.

Example: -X GET

-H LINE, - -header LINEHTTP header to include with the request. Use multiple header options if more than one headeris required.

Example: -H "Accept: application/xml" -H "Content-Type: application/xml"

-u USERNAME:PASSWORD, - -user USERNAME:PASSWORDThe username and password of the Red Hat Enterprise Virtualization user. This attribute actsas a convenient replacement for the Authorization: header.

Example: -u admin@internal:p@55w0rd!

API Usage with cURL

279

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8639-366624+%5BSpecified%5D&cf_build_id=8639-366624+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+API+Usage+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

http://curl.haxx.se/

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7794-366625+%5BSpecified%5D&cf_build_id=7794-366625+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Installing+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

--cacert CERTIFICATEThe location of the certificate file for SSL communication to the REST API. The certificate file issaved locally on the client machine. Use the -k attribute to bypass SSL.

Example: --cacert ~/Certificates/rhevm.cer

-d BODY, - -data BODYThe body to send for requests. Use with POST , PUT and DELETE requests. Ensure to specifythe 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>"

Report a bug

B.4. Examples

B.4.1. GET Request with cURLExample B.1. GET request

The following GET request lists the virtual machines in the vms collection. Note that a GET requestdoes not contain a body.

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

Adapt the method (GET ), header (Accept: application/xml) and URI (https://[RHEVM-Host]:443/api/vms) into the following cURL command:

$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443/api/vms

An XML representation of the vms collection displays.

Report a bug


280

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7795-366626+%5BSpecified%5D&cf_build_id=7795-366626+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Using+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7996-367083+%5BSpecified%5D&cf_build_id=7996-367083+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+GET+Request+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example B.2. POST request

The following POST request creates a virtual machine in the vms collection. Note that a POST requestrequires a body.


<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]:443/api/vms) and request body into thefollowing 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]:443/api/vms

The REST API creates a new virtual machine and displays an XML representation of the resource.

Report a bug

B.4.3. PUT Request with cURL

API Usage with cURL

281

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7997-367086+%5BSpecified%5D&cf_build_id=7997-367086+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+POST+Request+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example B.3. PUT request

The following PUT request updates the memory of a virtual machine resource. Note that a PUTrequest requires a body.

PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xmlContent-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]:443/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]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039

The REST API updates the virtual machine with a new memory configuration.

Report a bug

B.4.4. DELETE Request with cURLExample B.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]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) into the following cURL command:

$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039

The REST API removes the virtual machine. Note the Accept: application/xml request headeris optional due to the empty result of DELETE requests.

Report a bug

B.4.5. DELETE Request Including Body with cURL


282

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7998-367088+%5BSpecified%5D&cf_build_id=7998-367088+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+PUT+Request+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7999-367089+%5BSpecified%5D&cf_build_id=7999-367089+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+DELETE+Request+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Example B.5. DELETE request with body

The following DELETE request force removes a virtual machine resource as indicated with theoptional body.

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


Adapt the method (DELETE), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:443/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]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039

The REST API force removes the virtual machine.

Report a bug

API Usage with cURL

283

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+8000-367092+%5BSpecified%5D&cf_build_id=8000-367092+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+DELETE+Request+Including+Body+with+cURL%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Certificates

C.1. Creating SSL/TLS CertificatesSummary

SSL/TLS certificates provide a layer of security for accessing your installation over HTTPS. Thisprocedure provides instructions for creating certificates and configuring your host with them.

The following procedure requires the openssl. To install this tool, run the following command on yourhost:

# yum install openssl

Procedure C.1. Creating a Certificate Authority

A Certificate Authority (CA) signs certificates to provide verification of validity. Web browsers contain anumber of CA certificates used to verify HTTPS communication of secure websites. Some of these CAsrequire a fee to provide a CA pair for your host, while some are open and provide free CA pairs. Thisprocedure describes how to generate your own Certificate Authority (CA) certificate and key for your owninternal network usage.

1. Run the following command:

# openssl req -new -x509 -keyout ca.key -out ca.crt -days 3650

This command requests a new CA pair valid for 3650 days.

2. Enter a password to protect your CA:

Generating a 2048 bit RSA private key......................................................................................................................................+++..................................................................................................+++writing new private key to 'ca.key'Enter PEM pass phrase: Verifying - Enter PEM pass phrase:

3. Enter the following details about your organization:

Country Name (2 letter code) [XX]:AUState or Province Name (full name) []:QueenslandLocality Name (eg, city) [Default City]:BrisbaneOrganization Name (eg, company) [Default Company Ltd]:Red HatOrganizational Unit Name (eg, section) []:Engineering Content ServicesCommon Name (eg, your name or your server's hostname) []:www.example.comEmail Address []:[email protected]

This information forms the Distinguished Name (DN) in your certificate.

Conclusion

You have created a Certificate Authority. openssl creates two files: ca.key, which is a keyadministrators use to sign certificates, and ca.crt, which is the public CA certificate that users obtain


284

to verify the validity of signed certificates they receive. Make sure users accessing your host have acopy of the ca.crt so they can import it into their client's trusted CA store.

Report a bug

C.2. Creating an SSL CertificateSummary

The following procedure creates an SSL certificate and signs it with the CA key. SSL/TLS certificatesprovide a layer of security for accessing your installation over HTTPS. This procedure providesinstructions for creating certificates and configuring your host with them.

The following procedure requires the openssl. To install this tool, run the following command on yourhost:

# yum install openssl

Procedure C.2. Creating an SSL Certificate

1. Create a key for your host:

# openssl genrsa -out ssl.key

This creates an ssl.key key file.

2. Use the key to create a signing request for your certificate:

# openssl req -new -key ssl.key -out ssl.csr

The signing request asks for some organization details to form the Distinguished Name (DN) inyour certificate.

Country Name (2 letter code) [XX]:AUState or Province Name (full name) []:QueenslandLocality Name (eg, city) [Default City]:BrisbaneOrganization Name (eg, company) [Default Company Ltd]:Red HatOrganizational Unit Name (eg, section) []:Engineering Content ServicesCommon Name (eg, your name or your server's hostname) []:www.example.comEmail Address []:[email protected]

This creates an ssl.csr signing request file.

3. Create the signed SSL certificate:

# openssl ca -cert ca.crt -keyfile ca.key -out ssl.crt -infiles ssl.csr

openssl asks for your CA key's password.

This creates a certificate file named ssl.crt.

Certificates

285

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13781-434801+%5BSpecified%5D&cf_build_id=13781-434801+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+SSL%2FTLS+Certificates%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=dmacpher%40redhat.com&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Important

The above command may result in the following error:

Using configuration from /etc/pki/tls/openssl.cnfEnter pass phrase for ca.key:/etc/pki/CA/index.txt: No such file or directoryunable to open '/etc/pki/CA/index.txt'139883256969032:error:02001002:system library:fopen:No such file or directory:bss_file.c:355:fopen('/etc/pki/CA/index.txt','r')139883256969032:error:20074002:BIO routines:FILE_CTRL:system lib:bss_file.c:357:

Procedure C.3. Resolving this errora. Create the index.txt file.

# touch /etc/pki/CA/index.txt

b. Create a serial file to label the CA and all subsequent certificates.

# echo '1000' > /etc/pki/CA/serial

You will only need to do this the first time you set up the SSL certificate. Re-run thecommand:

# openssl ca -cert ca.crt -keyfile ca.key -out ssl.crt -infiles ssl.csr

The ssl.crt and ssl.key form the certificate pair that your host uses to encrypt data via HTTPS.

Conclusion

You have created an SSL certificate and signed it with the CA key. openssl creates two files: ca.key,which is a key administrators use to sign certificates, and ca.crt, which is the public CA certificate thatusers obtain to verify the validity of signed certificates they receive. Make sure users accessing yourhost have a copy of the ca.crt so they can import it into their client's trusted CA store.

Report a bug

C.3. Configuring HTTPS CommunicationSummary

Configure HTTPS to use the SSL certificate key on your system.

Procedure C.4 . Configuring HTTPS Communication

1. Edit the /etc/httpd/conf.d/ssl.conf file and modify the following settings:

SSLCertificateFile [location of your ssl.crt]SSLCertificateKeyFile [location of your ssl.key]

2. After editing these settings, restart your webserver:


286

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13837-431313+%5BSpecified%5D&cf_build_id=13837-431313+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Creating+an+SSL+Certificate%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

# service httpd restart

Conclusion

You have configured HTTPS to use the SSL certificate key on your system.

Report a bug

C.4. Network Security Services (NSS) DatabaseNetwork Security Services (NSS) is a 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 auser import the rhevm.cer certificate 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

Report a bug

C.5. Java KeystoresThis appendix demonstrates how to import the X.509 certificate exported from the Red Hat EnterpriseVirtualization server into a new Java keystore file.

Procedure C.5. Import a certificate into a new Java keystore

This process helps a user import the rhevm.cer certificate into a Java keystore. This procedurerequires the keytool management utility from the Java Development Kit (JDK) available for Linux andWindows 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 - listcommand to view the certificate's entry in the keystore:

keytool -list -keystore restapi.jks -storepass [password]

Certificates

287

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+13836-378442+%5BSpecified%5D&cf_build_id=13836-378442+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Configuring+HTTPS+Communication%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12977-435334+%5BSpecified%5D&cf_build_id=12977-435334+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Network+Security+Services+%28NSS%29+Database%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Important

Some versions of keytool parse the certificate incorrectly. If keytool does not recognise thecertificate, 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.

Report a bug


288

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7796-365117+%5BSpecified%5D&cf_build_id=7796-365117+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Java+Keystores%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Enumerated Value Translation

D.1. Enumerated Value TranslationThe API uses Red Hat Enterprise Virtualization Query Language to perform search queries. For moreinformation on the Query Language, read the full specification in Appendix G.1. Search of the Red HatEnterprise Virtualization Administration Guide 3.2.

Please note that certain enumerated values in the API require a different search query when using theQuery Language. The following table provides a translation for these key enumerated values.


289

Table D.1. Enumerated value translations

Resource Type API EnumerableType

API EnumerableValue

QueryLanguageProperty

QueryLanguage 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


290

rhel_4x64 rhel4x64

rhel_3x64 rhel3x64

windows_2008x64

windows2008x64

windows_2008r2

windows2008r2x64

rhel_6 rhel6

rhel_6x64 rhel6x64

Report a bug


291

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+12976-384926+%5BSpecified%5D&cf_build_id=12976-384926+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Enumerated+Value+Translation%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Event Codes

E.1. Event CodesThis table lists all event codes.


292

Table E.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

Event Codes

293

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


294

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

Event Codes

295

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


296

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

Event Codes

297

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


298

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

Event Codes

299

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


300

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

Event Codes

301

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


302

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

Report a bug

Event Codes

303

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+9076-365086+%5BSpecified%5D&cf_build_id=9076-365086+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Event+Codes%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Timezones

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


304

Table F.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

Timezones

305

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


306

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

Report a bug

Timezones

307

https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.10%0ABuild+Name%3A+20664%2C+Developer+Guide-3.2-1%0ABuild+Date%3A+13-08-2013+17%3A03%3A22%0ATopic+ID%3A+7995-365084+%5BSpecified%5D&cf_build_id=7995-365084+13+Aug+2013+17%3A03+en-US+%5BSpecified%5D&comment=Title%3A+Timezones%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&product=Red+Hat+Enterprise+Virtualization+Manager&component=Guides-Developer

Revision HistoryRevision 3.2-20.4 00 2013-10-31 Rüdiger Landmann

Rebuild with publican 4.0.0

Revision 3.2-20 Fri 27 Sep 2013 Zac DoverBZ#1007864 - s/Red Had/ Red Hat/g

Revision 3.2-19 Wed 25 Sep 2013 Zac DoverBZ#1007864 - tagging into the development server this time

Revision 3.2-18 Wed 25 Sep 2013 Zac DoverBZ#1007864

Revision 3.2-17 Thu 09 Aug 2013 Andrew BurdenBZ#977746 - Added 'agents' parent tag and fixed agent formatting

Revision 3.2-16 Tue 11 Jun 2013 Andrew BurdenBZ#966590 - Included port parameter in Host iSCSI Discover Action exampleBZ#969826 - Removed extraneous information from Host iSCSI Discover Action example

Revision 3.2-15 Tue 07 May 2013 Andrew BurdenCorrected a duplicate entry in the Revision History

Revision 3.2-14 Wed 17 Apr 2013 Andrew BurdenFixed a few minor localisation syncing issues

Revision 3.2-13 Mon 25 Mar 2013 Andrew BurdenBrewing for Beta

Revision 3.2-12 Thu 21 Mar 2013 Andrew BurdenUpdated the Python SDK Examples appendix

Revision 3.2-11 Mon 11 Mar 2013 Andrew BurdenBZ#889406 - Removing a VM but retaining the diskBZ#874596 - SSL certificates

Revision 3.2-10 Mon 11 Mar 2013 Andrew BurdenQE Brew

Revision 3.2-9 Tue 5 Mar 2013 Andrew BurdenRestricted some of the unfinished SDK examples

Revision 3.2-8 Mon 4 Mar 2013 Andrew BurdenTesting inclusion of pydoc generated content

Revision 3.2-7 Fri 1 Mar 2013 Andrew BurdenBrew for Beta-1


308

Revision 3.2-6 Fri 22 Feb 2013 Andrew BurdenUpdated Revision History and SDK Examples

Revision 3.2-5 Fri 22 Feb 2013 Andrew BurdenBZ#909041 - SDK Examples

Revision 3.2-4 Fri 22 Feb 2013 Andrew BurdenBZ#889045 - Added libvirt_version to table and exampleBZ#858550 - Updated table, as per requestBZ#910475 - Added Admonition to deal with a running VM - for reviewBZ#913402 - Removed Boolean clone tags

Revision 3.2-3 Fri 15 Feb 2013 Andrew BurdenBZ#888855 - Added para about communicating with mulitple managersBZ#858550 - Added default for 'persistent_auth' entryBZ#888852 - Updated table and example to include smartcard optionsBZ#902257 - Updated Virtual Machine NIC table

Revision 3.2-2 Fri 1 Feb 2013 Andrew BurdenBZ#895962 - Rephrased error entry

Revision 3.2-1 Fri 25 Jan 2013 Andrew BurdenBZ#866446 - Added 'id' argument to 'collection.get' methodBZ#862785 - Included note regarding 'max' parameter in collection searchesBZ#903275 - Removed deprecated VM move actionBZ#895962 - Updated SDK error informationBZ#894111 - Changed ports to 443BZ#891330, 888443, 718682 - Typographical errorsBZ#888498, 888499, 888500 - Updated RHN Channel informationBranched from 3.1 docs

Revision History

309

Red Hat Enterprise Virtualization 3.2 Developer Guide

Documents

Transcript of Red Hat Enterprise Virtualization 3.2 Developer Guide