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]
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.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
8
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 →
Red Hat Enterprise Virtualization 3.2 Developer Guide
10
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
16
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]
Chapter 2. Authentication and Security
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]
Red Hat Enterprise Virtualization 3.2 Developer Guide
18
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
Chapter 2. Authentication and Security
19
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
20
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.
Chapter 3. REST API Quick Start Example
21
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
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>
Chapter 3. REST API Quick Start Example
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
24
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:
HTTP/1.1 200 OKContent-Type: application/xml
<data_centers> <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988" href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"> <name>Default</name> <description>The default Data Center</description> <link rel="storagedomains" href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/ storagedomains"/> <link rel="permissions" href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/> <storage_type>nfs</storage_type> <storage_format>v1</storage_format> <version minor="0" major="3"/> <supported_versions> <version minor="0" major="3"/> </supported_versions> <status> <state>up</state> </status> </data_center></data_centers>
Note the id code of your Default data center. This code identifies this data center in relation to 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.
Chapter 3. REST API Quick Start Example
25
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:
HTTP/1.1 200 OKContent-Type: application/xml
<clusters> <cluster id="99408929-82cf-4dc7-a532-9d998063fa95" href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"> <name>Default</name> <description>The default server cluster</description> <link rel="networks" href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/> <link rel="permissions" href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/> <cpu id="Intel Penryn Family"/> <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988" href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/> <memory_policy> <overcommit percent="100"/> <transparent_hugepages> <enabled>false</enabled> </transparent_hugepages> </memory_policy> <scheduling_policy/> <version minor="0" major="3"/> <error_handling> <on_error>migrate</on_error> </error_handling> </cluster></clusters>
Note the id code of your Default host cluster. This code identifies this host cluster in relation to 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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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:
HTTP/1.1 200 OKContent-Type: application/xml
<networks> <network id="00000000-0000-0000-0000-000000000009" href="/api/networks/00000000-0000-0000-0000-000000000009"> <name>rhevm</name> <description>Management Network</description> <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988" href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/> <stp>false</stp> <status> <state>operational</state> </status> <display>false</display> </network></networks>
The rhevm network is attached to the Default data center through a relationship using the 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
Chapter 3. REST API Quick Start Example
27
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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:
Chapter 3. REST API Quick Start Example
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 3. REST API Quick Start Example
31
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
32
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:
Chapter 3. REST API Quick Start Example
33
HTTP/1.1 200 OKAccept: application/xml
<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac" href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac"> <name>data1</name> <link rel="permissions" href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/ permissions"/> <link rel="files" href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/> <type>data</type> <master>false</master> <storage> <type>nfs</type> <address>192.168.0.10</address> <path>/data1</path> </storage> <available>175019917312</available> <used>27917287424</used> <committed>10737418240</committed> <storage_format>v1</storage_format> <host id="0656f432-923a-11e0-ad20-5254004ac988" href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"></storage_domain>
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
34
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:
Chapter 3. REST API Quick Start Example
35
HTTP/1.1 200 OKAccept: application/xml
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"> <name>iso1</name> <link rel="permissions" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/ permissions"/> <link rel="files" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/> <type>iso</type> <host id="" href=""> <master>false</master> <storage> <type>nfs</type> <address>192.168.0.10</address> <path>/iso1</path> </storage> <available>82678120448</available> <used>18253611008</used> <committed>0</committed> <storage_format>v1</storage_format> <host id="0656f432-923a-11e0-ad20-5254004ac988" href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"> </storage_domain>
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
36
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.
Chapter 3. REST API Quick Start Example
37
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
38
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:
Chapter 3. REST API Quick Start Example
39
HTTP/1.1 200 OKAccept: application/xml
<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"> <name>vm1</name> <actions> <link rel="shutdown" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/> <link rel="start" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/> <link rel="stop" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/> <link rel="suspend" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/> <link rel="detach" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/> <link rel="export" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/> <link rel="move" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/> <link rel="ticket" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/> <link rel="migrate" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/> </actions> <link rel="disks" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/> <link rel="nics" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/> <link rel="cdroms" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/> <link rel="snapshots" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/> <link rel="tags" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/> <link rel="permissions" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/> <link rel="statistics" href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/> <type>desktop</type> <status> <state>down</state> </status> <memory>536870912</memory> <cpu> <topology cores="1" sockets="1"/> </cpu> <os type="Unassigned"> <boot dev="cdrom"/> </os> <high_availability> <enabled>false</enabled> <priority>0</priority> </high_availability> <display> <type>spice</type> <monitors>1</monitors> </display> <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 3. REST API Quick Start Example
41
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
42
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
Chapter 3. REST API Quick Start Example
43
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
44
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
Chapter 3. REST API Quick Start Example
45
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.
Chapter 4. Python Quick Start Example
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
48
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
dc_list = api.datacenters.list()
for dc in dc_list: print "%s (%s)" % (dc.get_name(), dc.get_id())
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the Default data center exists, and it is not activated, the 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.
Chapter 4. Python Quick Start Example
49
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") c_list = api.clusters.list() for c in c_list: print "%s (%s)" % (c.get_name(), c.get_id())
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the Default cluster exists, the example outputs:
Default (99408929-82cf-4dc7-a532-9d998063fa95)
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
50
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
n_list = api.logicalnetworks.list()
for n in n_list: print "%s (%s)" % (n.get_name(), n.get_id()) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the default management network exists, the example outputs:
rhevm (00000000-0000-0000-0000-000000000009)
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.
Chapter 4. Python Quick Start Example
51
Example 4 .5. Listing the host collection using Python
This Python example lists the hosts in the hosts collection.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="HOST", username="USER", password="PASS", ca_file="ca.crt")
h_list = api.hosts.list()
for h in h_list: print "%s (%s)" % (h.get_name(), h.get_id())
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only one host, named Atlantic, has been attached the example outputs:
Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
52
Example 4 .6. Approving a host using Python
This Python example calls the approve method for a host named Atlantic.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="HOST", username="USER", password="PASS", ca_file="ca.crt")
h = api.hosts.get(name="Atlantic")
if(h.approve()): print "Host '%s' approved (Status: %s)." % (h.get_name(), h.get_status().get_state()) else: print "Approval of '%s' failed." % h.get_name()
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the approve request is successful then the script will output:
Host 'Atlantic' approved (Status: Up).
Note that the status reflects that the host has been approved and is now considered to be up.
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.
Chapter 4. Python Quick Start Example
53
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.
h = api.hosts.get(name="Atlantic")
3. Define the Storage parameters for the NFS storage domain. In this example the NFS location 192.0.43.10/storage/data is being used.
s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
4. Request creation of the storage domain, using the add method of the 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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
54
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt")
dc = api.datacenters.get(name="Default") h = api.hosts.get(name="Atlantic")
s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs") sd_params = params.StorageDomain(name="data1", data_center=dc, host=h, type_="data", storage_format="v3", storage=s)
try: sd = api.storagedomains.add(sd_params) print "Storage Domain '%s' added (%s)." % (sd.get_name()) except Exception as ex: print "Adding storage domain failed: %s" % ex
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the add method call is successful then the script will output:
Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).
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.
Chapter 4. Python Quick Start Example
55
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.
h = api.hosts.get(name="Atlantic")
3. Define the Storage parameters for the NFS storage domain. In this example the NFS location 192.0.43.10/storage/iso is being used.
s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
4. Request creation of the storage domain, using the add method of the 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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
56
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt")
dc = api.datacenters.get(name="Default") h = api.hosts.get(name="Atlantic")
s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs") sd_params = params.StorageDomain(name="iso1", data_center=dc, host=h, type_="iso", storage_format="v3", storage=s)
try: sd = api.storagedomains.add(sd_params) print "Storage Domain '%s' added (%s)." % (sd.get_name()) except Exception as ex: print "Adding storage domain failed: %s" % ex
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the add method call is successful then the script will output:
Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).
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.
Chapter 4. Python Quick Start Example
57
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
sd_data = api.storagedomains.get(name="data1") sd_iso = api.storagedomains.get(name="iso1")
try: dc_sd = dc.storagedomains.add(sd_data) print "Attached data storage domain '%s' to data center '%s' (Status: %s)." % (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state()) except Exception as ex: print "Attaching data storage domain to data center failed: %s." % ex
try: dc_sd = dc.storagedomains.add(sd_iso) print "Attached ISO storage domain '%s' to data center '%s' (Status: %s)." % (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state()) except Exception as ex: print "Attaching ISO storage domain to data center failed: %s." % ex
api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the calls to the add methods are successful then the script will output:
Attached data storage domain 'data1' to data center 'Default' (Status: maintenance).Attached ISO storage domain 'iso1' to data center 'Default' (Status: maintenance).
Note that the status reflects that the storage domains still need to be activated.
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
58
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
sd_data = dc.storagedomains.get(name="data1") sd_iso = dc.storagedomains.get(name="iso1")
try: sd_data.activate() print "Activated data storage domain '%s' in data center '%s' (Status: %s)." % (sd_data.get_name(), dc.get_name, sd_data.get_status().get_state()) except Exception as ex: print "Activating data storage domain in data center failed: %s." % ex
try: sd_iso.activate() print "Activated ISO storage domain '%s' in data center '%s' (Status: %s)." % (sd_iso.get_name(), dc.get_name, sd_iso.get_status().get_state()) except Exception as ex: print "Activating ISO storage domain in data center failed: %s." % ex
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the activate requests are successful then the script will output:
Activated data storage domain 'data1' in data center 'Default' (Status: active).Activated ISO storage domain 'iso1' in data center 'Default' (Status: active).
Note that the status reflects that the storage domains have been activated.
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.
Chapter 4. Python Quick Start Example
59
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
vm_name = "vm1" vm_memory = 512 * 1024 * 1024 vm_cluster = api.clusters.get(name="Default") vm_template = api.templates.get(name="Blank") vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])
vm_params = params.VM(name=vm_name, memory=vm_memory, cluster=vm_cluster, template=vm_template) os=vm_os)
try: api.vms.add(vm=vm_params) print "Virtual machine '%s' added." % vm_name except Exception as ex: print "Adding virtual machine '%s' failed: %s" % (vm_name, ex)
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 4. Python Quick Start Example
61
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt")
vm = api.vms.get(name="vm1")
nic_name = "nic1" nic_interface = "virtio" nic_network = api.networks.get(name="rhevm")
nic_params = params.NIC(name=nic_name, interface=nic_interface, network=nic_network)
try: nic = vm.nics.add(nic_params) print "Network interface '%s' added to '%s'." % (nic.get_name(), vm.get_name()) except Exception as ex: print "Adding network interface to '%s' failed: %s" % (vm.get_name(), ex)
api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Network interface 'nic1' added to 'vm1'.
Report a bug
Red Hat Enterprise Virtualization 3.2 Developer Guide
62
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.
Chapter 4. Python Quick Start Example
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
64
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
vm = api.vms.get(name="vm1")
sd = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")]) disk_size = 8*1024*1024 disk_type = "system" disk_interface = "virtio" disk_format = "cow" disk_bootable = True
disk_params = params.Disk(storage_domains=sd, size=disk_size, type_=disk_type, interface=disk_interface, format=disk_format, bootable=disk_bootable)
try: d = vm.disks.add(disk_params) print "Disk '%s' added to '%s'." % (d.get_name(), vm.get_name()) except Exception as ex: print "Adding disk to '%s' failed: %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
Disk 'vm1_Disk1' added to 'vm1'.
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.
Chapter 4. Python Quick Start Example
65
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
try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
sd = api.storagedomains.get(name="iso1") iso = sd.files.list()
for i in iso: print "%s" % i.get_name() except Exception as ex: print "Unexpected error: %s"
If successful the script will output an entry like this for each file found in the files collection:
RHEL6.3-Server-x86_64-DVD1.iso
Note that because files on the ISO domain must be uniquely named the id and name attributes of thefile are shared.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
from ovirtsdk.api import API from ovirtsdk.xml import params
try: api = API(url="HOST", username="USER", password="PASS")
sd = api.storagedomains.get(name="iso1")
cd_iso = sd.files.get(name="RHEL6.3-Server-x86_64-DVD1.iso") cd_vm = api.vms.get(name="vm1") cd_params = params.CdRom(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()
except Exception as ex: print "Unexpected error: %s" % ex
If the add request is successful then the script will output:
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
Chapter 4. Python Quick Start Example
67
Starting a virtual machine
Example 4 .16. Starting a virtual machine using Python
This example starts the virtual machine using the start method.
from ovirtsdk.api import API from ovirtsdk.xml import params
try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
vm = api.vms.get(name="vm1")
try: vm.start() print "Started '%s'." % vm.get_name() except Exception ex: print "Unable to start '%s': %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex: print "Unexpected error: %s" % ex
If the start request is successful then the script will output:
Started 'vm1'.
Note that the status reflects that the virtual machine has been started and is now up.
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
68
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.
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt")
event_list = [] event_page_index = 1 event_page_current = api.events.list(query="page %s" % event_page_index)
while(len(event_page_current) != 0): event_list = event_list + event_page_current event_page_index = event_page_index + 1 try: event_page_current = api.events.list(query="page %s" % event_page_index) except Exception as ex: print "Error retrieving page %s of list: %s" % (event_page_index, ex)
event_list.reverse()
for event in event_list: print "%s %s CODE %s - %s" % (event.get_time(), event.get_severity().upper(), event.get_code(), event.get_description())
except Exception as ex: print "Unexpected error: %s" % ex
Output from this script will look like this - albeit with different events depending on the state of 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
Chapter 4. Python Quick Start Example
69
Part II. REST Application Programming Interface
Red Hat Enterprise Virtualization 3.2 Developer Guide
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]
HTTP/1.1 200 OKContent-Type: application/xml
<api> <link rel="hosts" href="/api/hosts"/> <link rel="vms" href="/api/vms"/> ... <product_info> <name>Red Hat Enterprise Virtualization</name> <vendor>Red Hat</vendor> <version revision="0" build="0" minor="1" major="3"/> </product_info> <special_objects> <link rel="templates/blank" href="..."/> <link rel="tags/root" href="..."/> </special_objects> <summary> <vms> <total>10</total> <active>3</active> </vms> <hosts> <total>2</total> <active>2</active> </hosts> <users> <total>8</total> <active>2</active> </users> <storage_domains> <total>2</total> <active>2</active> </storage_domains> </summary></api>
Chapter 5. Entry Point
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
72
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]
Chapter 5. Entry Point
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
Relationship Description
datacenters/search Query data centers.
clusters/search Query host clusters.
storagedomains/search Query storage domains.
hosts/search Query hosts.
vms/search Query virtual machines.
disks/search Query disks.
templates/search Query templates.
vmpools/search Query virtual machine pools.
events/search Query events.
users/search Query users.
Report a bug
5.4. Special Object ElementsSpecial object elements define relationships to special fixed resources within the virtualizationenvironment.
Table 5.3. Special Objects
Relationship Description
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]
Red Hat Enterprise Virtualization 3.2 Developer Guide
74
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:
Chapter 5. Entry Point
75
<?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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 5. Entry Point
77
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
78
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
80
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
Chapter 7. Capabilities
81
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
82
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.
Chapter 7. Capabilities
83
<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
Red Hat Enterprise Virtualization 3.2 Developer Guide
84
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
Chapter 7. Capabilities
85
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
86
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>
Chapter 7. Capabilities
87
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
88
<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.
Chapter 7. Capabilities
89
<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,
Red Hat Enterprise Virtualization 3.2 Developer Guide
90
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
Chapter 7. Capabilities
91
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
92
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
Chapter 8. Common Features
93
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
HTTP/1.1 200 OKContent-Type: application/xml
<collection> <resource id="resource_id" href="/api/collection/resource_id"> ... </resource> ...</collection>
Report a bug
Red Hat Enterprise Virtualization 3.2 Developer Guide
94
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
HTTP/1.1 200 OKContent-Type: application/xml
<collection> <resource id="resource_id" href="/api/collection/resource_id"> <name>Resource-Name</name> <description>A description of the resource</description> ... </resource></collection>
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.
Chapter 8. Common Features
95
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
96
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.
Include an Accept HTTP header to define the MIME type for the response format.
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.
Chapter 8. Common Features
97
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
HTTP/1.1 200 OKContent-Type: application/xml
<creation id="creation_status_id" href="/api/collection/resource_id/creation_status/creation_status_id"> <status> <state>complete</state> </status></creation>
Overriding the asynchronous resource creation requires an Expect: 201-created header:
Red Hat Enterprise Virtualization 3.2 Developer Guide
98
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.
Include an Accept HTTP header to define the MIME type for the response format.
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.
Include an Accept HTTP header to define the MIME type for the response format.
PUT /api/collection/resource_id HTTP/1.1Accept: [MIME type]Content-Type: [MIME type]
[body]
Chapter 8. Common Features
99
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.
Include an Accept HTTP header to define the MIME type for the response format.
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
HTTP/1.1 200 OKContent-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id"> ... <link rel="subcollection" href="/api/collection/resource_id/subcollection"/> ...</resource>
Red Hat Enterprise Virtualization 3.2 Developer Guide
100
The API user now queries the sub-collection.
GET /api/collection/resource_id/subcollection HTTP/1.1Accept: application/xml
HTTP/1.1 200 OKContent-Type: 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
HTTP/1.1 200 OKContent-Type: application/xml
<subcollection> <subresource id="subresource_id" href="/api/collection/resource_id/subcollection/subresource_id"> <resource id="resource_id" href="/api/collection/resource_id"/> ... </subresource></subcollection>
Report a bug
8.4.7. ActionsMost resources include a list of action links to provide functions not achieved through the standardHTTP methods.
Chapter 8. Common Features
101
<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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
HTTP/1.1 200 OKContent-Type: application/xml
<action id="action_id" href="/api/collection/resource_id/action/action_id"> <status> <state>pending</state> </status> <link rel="parent" /api/collection/resource_id"/> <link rel="replay" href="/api/collection/resource_id/action"/><action>
An action representation also includes some links that are identified by the rel attribute:
Table 8.8. Action relationships
Type Description
parent A link back to the resource of this action.
replay A link back to the original action URI. POSTing to this URI causes 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:
Chapter 8. Common Features
103
GET /api/collection/resource_id/permissions HTTP/1.1Accept: application/xml
HTTP/1.1 200 OKContent-Type: application/xml
<permissions> <permission id="permission-id" href="/api/collection/resource_id/permissions/permission_id"> <role id="role_id" href="/api/roles/role_id"/> <user id="user_id" href="/api/users/user_id"/> <resource id="resource_id" href="/api/collection/resource_id"/> </permission> ...</permissions>
A resource acquires a new permission when an API user sends a POST request with a 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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
104
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
Chapter 8. Common Features
105
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
Element Type Description Properties
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
106
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.
Chapter 9. Data Centers
107
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
108
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>
Chapter 9. Data Centers
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
110
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
HTTP/1.1 204 No Content
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:
Chapter 9. Data Centers
111
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
112
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
Element Type Description Properties
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.
link rel="permissions"
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.
Chapter 10. Host Clusters
113
Report a bug
10.2. Memory Policy ElementsThe memory_policy element contains the following elements:
Table 10.2. Memory policy elements
Element Type Description Properties
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
114
Table 10.3. Scheduling policy elements
Element Type Description Properties
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
Chapter 10. Host Clusters
115
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
116
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
HTTP/1.1 204 No Content
Report a bug
10.6. Sub-Collections
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:
Chapter 10. Host Clusters
117
Table 10.4 . Addit ional network elements
Element Type Description Properties
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
HTTP/1.1 204 No Content
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
Chapter 10. Host Clusters
119
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
Element Type Description Properties
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
HTTP/1.1 204 No Content
Chapter 10. Host Clusters
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
Element Type Description Properties
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
122
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.
Chapter 10. Host Clusters
123
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
124
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
Element Type Description Properties
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
The API as documented in this section is experimental and subject to change. It is not covered bythe backwards compatibility statement.
Report a bug
11.2. XML Representation of a Network Resource
Chapter 11. Networks
125
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
126
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
HTTP/1.1 204 No Content
Report a bug
Chapter 11. Networks
127
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
128
Table 12.1. Storage domain elements
Element Type Description Properties
link rel="permissions"
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
Chapter 12. Storage Domains
129
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
130
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
HTTP/1.1 204 No Content
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.
Chapter 12. Storage Domains
131
Table 12.2. NFS specific elements
Element Type Description Properties
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
Element Type Description Properties
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
Element Type Description Properties
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
132
Table 12.5. Logical unit elements
Element Type Description Properties
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
Element Type Description Properties
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.
Chapter 12. Storage Domains
133
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
HTTP/1.1 200 OKContent-Type: application/xml
<vms> <vm id="082c794b-771f-452f-83c9-b2b5a19c0399" href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/ vms/082c794b-771f-452f-83c9-b2b5a19c0399"> <name>vm1</name> ... <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed" href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/> <actions> <link rel="import" href="/api/storagedomains/ fabe0451-701f-4235-8f7e-e20e458819ed/vms/ 082c794b-771f-452f-83c9-b2b5a19c0399/import"/> </actions> </vm></vms>
VMs and templates in these collections have a similar representation to their counterparts in the top-level VMs and templates collection, except they also contain a storage_domain reference and an import action.
The import action imports a virtual machine or a template from an export storage domain. 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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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> <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.
Chapter 12. Storage Domains
135
Example 12.9. Selecting disks for an import action
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1Accept: application/xmlContent-type: application/xml
<action> <cluster> <name>Default</name> </cluster> <vm> <name>MyVM</name> </vm> ... <disks> <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/> </disks></action>
Delete a virtual machine or template from an export storage domain with a DELETE request.
Example 12.10. Delete virtual machine from an export storage domain
DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xml
HTTP/1.1 204 No Content
Report a bug
12.6. Sub-Collections
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
136
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
HTTP/1.1 200 OKContent-Type: application/xml
<files> <file id="en_winxp_pro_with_sp2.iso" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/ en_winxp_pro_with_sp2.iso"> <name>en_winxp_pro_with_sp2.iso</name> <type>iso</type> <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/> </file> <file id="boot.vfd" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/ boot.vfd"> <name>boot.vfd</name> <type>vfd</type> <storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da" href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/> </file></files>
Like other resources, files have opaque id and href attributes. The name element contains 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.
Chapter 12. Storage Domains
137
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>
HTTP/1.1 201 CreatedContent-Type: application/xml
<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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
138
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
Chapter 12. Storage Domains
139
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
140
Table 13.1. Host elements
Element Type Description Properties
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.
link rel="permissions"
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
142
<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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Element Type Description Properties
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
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
146
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
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
HTTP/1.1 204 No Content
Report a bug
13.6. Sub-Collections
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
148
Table 13.3. Elements for a host's network interfaces
Element Type Description Properties
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
HTTP/1.1 204 No Content
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
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
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
152
Table 13.5. Elements for a host's network interface statistics
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
host_nic id= relationship A relationship to the containing host_nic resource.
The following table lists the statistic types for network interfaces on hosts.
Table 13.6. Host NIC statistic types
Name Description
data.current.rx The rate in bytes per second of data received.
data.current.tx The rate in bytes per second of data transmitted.
errors.total.rx Total errors from receiving data.
errors.total.tx Total errors from transmitting data.
Example 13.10. An XML representation of a host's network interface statistics sub-collection
<statistics> <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7" href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/ c34728e8-4338-4540-ac9b-86b8582e602e/statistics/ ecd0559f-e88f-3330-94b4-1f091b0ffdf7"> <name>data.current.rx</name> <description>Receive data rate</description> <values type="DECIMAL"> <value> <datum>0</datum> </value> </values> <type>GAUGE</type> <unit>BYTES_PER_SECOND</unit> <host_nic id="c34728e8-4338-4540-ac9b-86b8582e602e" href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/ c34728e8-4338-4540-ac9b-86b8582e602e"/> </statistic> ...</statistics>
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
154
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
Element Type Description Properties
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
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
The API as documented in this section is experimental and subject to change. It is not covered bythe backwards compatibility statement.
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
156
Table 13.8. Elements for host statistics
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
host id= relationship A relationship to the containing host resource.
The following table lists the statistic types for hosts.
Table 13.9. Host statistic types
Name Description
memory.total Total memory in bytes on the host.
memory.used Memory in bytes used on the host.
memory.free Memory in bytes free on the host.
memory.buffers I/O buffers in bytes.
memory.cached OS caches in bytes.
swap.total Total swap memory in bytes on the host.
swap.free Swap memory in bytes free on the host.
swap.used Swap memory in bytes used on the host.
swap.cached Swap memory in bytes also cached in host's memory.
ksm.cpu.current Percentage of CPU usage for Kernel SamePage Merging.
cpu.current.user Percentage of CPU usage for users.
cpu.current.system Percentage of CPU usage for system.
cpu.current.idle Percentage of idle CPU usage.
cpu.load.avg.5m CPU load average per five minutes.
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
158
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
160
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
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
162
Table 14 .1. Virtual machine elements
Element Type Description Properties
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.
link rel="permissions"
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").
Chapter 14. Virtual Machines
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Chapter 14. Virtual Machines
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
166
<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/>
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 14. Virtual Machines
169
Example 14 .2. Creating a virtual machine with 512 MB and boots from the virtual hard disk
POST /api/vms HTTP/1.1Accept: application/xmlContent-type: application/xml
<vm> <name>vm2</name> <description>Virtual Machine 2</description> <type>desktop</type> <memory>536870912</memory> <cluster> <name>default</name> </cluster> <template> <name>Blank</name> </template> <os> <boot dev="hd"/> </os></vm>
Note
Memory in the previous example is converted to bytes using the following formula:
512MB * 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
Red Hat Enterprise Virtualization 3.2 Developer Guide
170
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
HTTP/1.1 204 No Content
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. Sub-Collections
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:
Chapter 14. Virtual Machines
171
Table 14 .2. Elements for virtual machine disks
Element Type Description Properties
link rel="statistics"
relationship A link to the statistics sub-collection for a virtual machine's 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]
Red Hat Enterprise Virtualization 3.2 Developer Guide
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.
Chapter 14. Virtual Machines
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
HTTP/1.1 204 No Content
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
174
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
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
disk id= relationship A relationship to the containing disk resource.
The following table lists the statistic types for virtual machine disks.
Chapter 14. Virtual Machines
175
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
This statistics sub-collection is read-only.
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
176
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.
Chapter 14. Virtual Machines
177
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
Element Type Description Properties
link rel="statistics"
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
178
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>
Chapter 14. Virtual Machines
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
HTTP/1.1 204 No Content
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
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
nic id= relationship A relationship to the containing nic resource.
The following table lists the statistic types for network interfaces on virtual machines.
Red Hat Enterprise Virtualization 3.2 Developer Guide
180
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
This statistics sub-collection is read-only.
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
Element Type Description Properties
file id= string/filename A reference to an ISO image.
Chapter 14. Virtual Machines
181
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Element Type Description Properties
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 .
Chapter 14. Virtual Machines
183
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
184
Example 14 .26. Clone Virtual Machine from Snapshot
POST /api/vms HTTP/1.1Accept: application/xmlContent-type: application/xml
<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
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
vm id= relationship A relationship to the containing vm resource.
The following table lists the statistic types for virtual machines.
Table 14 .11. Virtual machine statistic types
Name Description
memory.installed Total memory in bytes allocated for the virtual machine's use.
memory.used Current memory in bytes used by the virtual machine.
cpu.current.guest Percentage of CPU used by the guest.
cpu.current.hypervisor Percentage of CPU overhead on the hypervisor.
cpu.current.total Total percentage of the current CPU in use.
Chapter 14. Virtual Machines
185
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
186
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.
Chapter 14. Virtual Machines
187
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
188
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.
Chapter 14. Virtual Machines
189
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
190
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
<action> <force>true</force></action>
Report a bug
Chapter 14. Virtual Machines
191
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
192
Table 15.1. Elements for floating disks
Element Type Description Properties
link rel="statistics"
relationship A link to the statistics sub-collection for a virtual machine's 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
Chapter 15. Floating Disks
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
194
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. Sub-Collections
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
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER
The type of statistic measures.
values type= One of INTEGER or DECIMAL
The data type for the statistical values that follow.
value complex A data set that contains datum .
datum see values type An individual piece of data from a value.
disk id= relationship A relationship to the containing disk resource.
The following table lists the statistic types for floating disks.
Table 15.3. Disk statistic types
Name Description
data.current.read The data transfer rate in bytes per second when reading from thedisk.
data.current.write The data transfer rate in bytes per second when writing to the disk.
Chapter 15. Floating Disks
195
Example 15.3. An XML representation of a virtual machine's statistics sub-collection
<statistics> <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272" href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/ 33b9212b-f9cb-3fd0-b364-248fb61e1272"> <name>data.current.read</name> <description>Read data rate</description> <values type="DECIMAL"> <value> <datum>0</datum> </value> </values> <type>GAUGE</type> <unit>BYTES_PER_SECOND</unit> <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/> </statistic> ...</statistics>
Note
This statistics sub-collection is read-only.
Report a bug
Red Hat Enterprise Virtualization 3.2 Developer Guide
196
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.
Chapter 16. Templates
197
Table 16.1. Virtual machine template elements
Element Type Description Properties
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.
link rel="permissions"
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Chapter 16. Templates
199
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
200
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
HTTP/1.1 204 No Content
Report a bug
16.4. Actions
16.4.1. Export Template Action
Chapter 16. Templates
201
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
202
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
Element Type Description Properties
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
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
HTTP/1.1 204 No Content
Report a bug
Red Hat Enterprise Virtualization 3.2 Developer Guide
204
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
Element Type Description
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. Sub-Collections
18.3.1. Domain Users Sub-Collection
Chapter 18. Domains
205
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
Element Type Description
name string The name of the user.
last_name string The surname of the user.
user_name string The username from directory service.
domain id GUID The containing directory service domain.
groups complex A list of directory service groups for this user.
Example 18.2. An XML representation of a user in the users sub-collection
<user id="225f15cd-e891-434d-8262-a66808fcb9b1" href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/ d3b4e7be-5f57-4dac-b937-21e1771a501f"> <name>RHEV-M Admin</name> <user_name>[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
Element Type Description
name string The name of the group.
domain id GUID The containing directory service domain.
Red Hat Enterprise Virtualization 3.2 Developer Guide
206
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
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
Element Type Description
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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
208
Report a bug
Chapter 19. Groups
209
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
Element Type Description Properties
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
210
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
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
HTTP/1.1 204 No Content
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
212
Example 20.5. Listing a role's permits
GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1Accept: application/xml
HTTP/1.1 200 OKContent-Type: application/xml
<permits> <permit id="1" href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1"> <name>create_vm</name> <administrative>false</administrative> <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9" href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/> </permit> ...</permits>
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"/>
HTTP/1.1 201 CreatedContent-Type: application/xml
<permits> <permit id="1" href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1"> <name>create_vm</name> <administrative>false</administrative> <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9" href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/> </permit></permits>
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
Example 20.7. Remove a permit from a role
DELETE /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1
HTTP/1.1 204 No Content
Report a bug
Red Hat Enterprise Virtualization 3.2 Developer Guide
214
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
Element Type Description Properties
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
216
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
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
Element Type Description Properties
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
218
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>
HTTP/1.1 201 CreatedContent-Type: application/xml
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e" href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/ f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"> <name>Finance</name> <description>Resources for the Finance department</description> <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720" href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/></tag>
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
HTTP/1.1 204 No Content
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
Example 22.4 . Querying a collection for tagged resources
GET /api/vms?search=tag%3DFinance HTTP/1.1Accept: application/xml
HTTP/1.1 200 OKContent-Type: 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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
220
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
Example 22.6. Sett ing an association with a parent tag with the id attribute
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1Accept: application/xmlContent-Type: application/xml
HTTP/1.1 200 OKContent-Type: application/xml
<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
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1Accept: application/xmlContent-Type: application/xml
HTTP/1.1 200 OKContent-Type: application/xml
<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>
Red Hat Enterprise Virtualization 3.2 Developer Guide
222
Report a bug
Chapter 22. Tags
223
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
Element Type Description
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
224
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
226
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:
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4
Example 23.4 . Paginating events
This example paginates event resources. The URL-encoded request is:
GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.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
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
230
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.
Chapter 25. Using the Software Development Kit
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
232
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.
Chapter 25. Using the Software Development Kit
233
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:
dc = api.datacenters.get(name="Default")
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.
Red Hat Enterprise Virtualization 3.2 Developer Guide
234
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.
Chapter 25. Using the Software Development Kit
235
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
236
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
from ovirtsdk.api import APIfrom ovirtsdk.xml import params
try: api = API(url="https://HOST", user="USER, pass="PASS, ca_file="/etc/pki/ovirt-engine/ca.pem")except ConnectionError, err: print "Connection failed: %s" % err
Report a bug
Chapter 25. Using the Software Development Kit
237
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
238
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)
Red Hat Enterprise Virtualization 3.2 Developer Guide
240
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
242
Important
Storage domains have unexpected behaviour (by-design in oVirt). When you use a storagedomain that is unattached (by using `api.storagedomains`) and then attach it, it will have nostatus when you look at it from this angle (and `updateObject` will return None). The state can bethen found in `api.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())
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
246
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)
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
250
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()))
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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")
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
270
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
274
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
--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
Red Hat Enterprise Virtualization 3.2 Developer Guide
280
Example B.2. POST request
The following POST request creates a virtual machine in the vms collection. Note that a POST requestrequires a body.
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>
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
282
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
<action> <force>true</force></action>
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
286
# 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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
288
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.
Enumerated Value Translation
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
290
rhel_4x64 rhel4x64
rhel_3x64 rhel3x64
windows_2008x64
windows2008x64
windows_2008r2
windows2008r2x64
rhel_6 rhel6
rhel_6x64 rhel6x64
Report a bug
Enumerated Value Translation
291
Event Codes
E.1. Event CodesThis table lists all event codes.
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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:
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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
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
Red Hat Enterprise Virtualization 3.2 Developer Guide
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