red hat virtualization 4.1 rest api guide...application programming interface. this guide is...

Red Hat Virtualization Documentation Team

Red Hat Virtualization4.1REST API Guide

Using the Red Hat Virtualization REST Application Programming Interface

Red Hat Virtualization 4.1 REST API Guide

Using the Red Hat Virtualization REST Application Programming Interface

Red Hat Virtualization Documentation [email protected]

Legal Notice

Copyright © 2017 Red Hat, Inc.

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

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

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinitylogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and othercountries.

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

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

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marksor trademarks/service marks of the OpenStack Foundation, in the United States and other countriesand are 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.

AbstractThis guide describes the Red Hat Virtualization Manager Representational State TransferApplication Programming Interface. This guide is generated from documentation comments in theovirt-engine-api-model code, and is currently partially complete. Updated versions of thisdocumentation will be published as new content becomes available.

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

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

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

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

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

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

Table of Contents

CHAPTER 1. INTRODUCTION1.1. REPRESENTATIONAL STATE TRANSFER1.2. API PREREQUISITES

CHAPTER 2. AUTHENTICATION AND SECURITY2.1. TLS/SSL CERTIFICATION

2.1.1. Obtaining the CA Certificate2.1.2. Importing a Certificate to a Client

2.2. AUTHENTICATION2.2.1. OAuth Authentication2.2.2. Basic Authentication2.2.3. Authentication Sessions

2.2.3.1. Requesting an Authenticated Session

CHAPTER 3. COMMON CONCEPTS3.1. TYPES3.2. IDENTIFIED TYPES3.3. OBJECTS3.4. COLLECTIONS3.5. REPRESENTATIONS

3.5.1. XML representation3.5.2. JSON representation

3.6. SERVICES3.7. SEARCHING

3.7.1. Maximum results parameter3.7.2. Case sensitivity3.7.3. Search syntax3.7.4. Wildcards3.7.5. Pagination

3.8. PERMISSIONS3.9. HANDLING ERRORS

CHAPTER 4. QUICK START EXAMPLE4.1. EXAMPLE: ACCESS API ENTRY POINT4.2. EXAMPLE: LIST DATA CENTERS4.3. EXAMPLE: LIST HOST CLUSTERS4.4. EXAMPLE: LIST LOGICAL NETWORKS4.5. EXAMPLE: LIST HOSTS4.6. EXAMPLE: CREATE NFS DATA STORAGE4.7. EXAMPLE: CREATE NFS ISO STORAGE4.8. EXAMPLE: ATTACH STORAGE DOMAINS TO DATA CENTER4.9. EXAMPLE: CREATE VIRTUAL MACHINE4.10. EXAMPLE: CREATE A VIRTUAL MACHINE NIC4.11. EXAMPLE: CREATE VIRTUAL MACHINE DISK4.12. EXAMPLE: ATTACH ISO IMAGE TO VIRTUAL MACHINE4.13. EXAMPLE: START THE VIRTUAL MACHINE

CHAPTER 5. REQUESTS

CHAPTER 6. SERVICES6.1. AFFINITYGROUP

6.1.1. get GET6.1.2. remove DELETE

353535

373737393939414242

4444444545454546465050505051515252

5454565758596062636466676869

71

97979797

Table of Contents

1

6.1.3. update PUT6.2. AFFINITYGROUPVM

6.2.1. remove DELETE6.3. AFFINITYGROUPVMS

6.3.1. add POST6.3.2. list GET

6.3.2.1. max6.4. AFFINITYGROUPS


6.4.2.1. max6.5. AFFINITYLABEL

6.5.1. get GET6.5.2. remove DELETE6.5.3. update PUT

6.6. AFFINITYLABELHOST6.6.1. get GET6.6.2. remove DELETE

6.7. AFFINITYLABELHOSTS6.7.1. add POST6.7.2. list GET

6.8. AFFINITYLABELVM6.8.1. get GET6.8.2. remove DELETE

6.9. AFFINITYLABELVMS6.9.1. add POST6.9.2. list GET

6.10. AFFINITYLABELS6.10.1. add POST6.10.2. list GET

6.10.2.1. max6.11. ASSIGNEDAFFINITYLABEL


6.12. ASSIGNEDAFFINITYLABELS6.12.1. add POST6.12.2. list GET

6.13. ASSIGNEDCPUPROFILE6.13.1. get GET6.13.2. remove DELETE

6.14. ASSIGNEDCPUPROFILES6.14.1. add POST6.14.2. list GET

6.14.2.1. max6.15. ASSIGNEDDISKPROFILE


6.16. ASSIGNEDDISKPROFILES6.16.1. add POST6.16.2. list GET

6.16.2.1. max6.17. ASSIGNEDPERMISSIONS

6.17.1. add POST

989898999999

100100100101101101102102102102102103103103103104104104104105105105106106106106107107107107108108108108109109109109110110110110111111111111112


2

6.17.2. list GET6.18. ASSIGNEDROLES

6.18.1. list GET6.18.1.1. max

6.19. ASSIGNEDTAG6.19.1. get GET6.19.2. remove DELETE

6.20. ASSIGNEDTAGS6.20.1. add POST6.20.2. list GET

6.20.2.1. max6.21. ASSIGNEDVNICPROFILE


6.22. ASSIGNEDVNICPROFILES6.22.1. add POST6.22.2. list GET

6.22.2.1. max6.23. ATTACHEDSTORAGEDOMAIN

6.23.1. activate POST6.23.2. deactivate POST6.23.3. get GET6.23.4. remove DELETE

6.24. ATTACHEDSTORAGEDOMAINS6.24.1. add POST6.24.2. list GET

6.24.2.1. max6.25. BALANCE


6.26. BALANCES6.26.1. add POST6.26.2. list GET

6.26.2.1. max6.27. BOOKMARK


6.28. BOOKMARKS6.28.1. add POST6.28.2. list GET

6.28.2.1. max6.29. CLUSTER

6.29.1. get GET6.29.2. remove DELETE6.29.3. resetemulatedmachine POST6.29.4. update PUT

6.30. CLUSTERLEVEL6.30.1. get GET

6.31. CLUSTERLEVELS6.31.1. list GET

6.32. CLUSTERNETWORK6.32.1. get GET

113113114114114114115115116116117117117117117118118118118119119120120120120121121121121122122122122123123123124124125125125126126127128129129130130131131132132

Table of Contents

3


6.33. CLUSTERNETWORKS6.33.1. add POST6.33.2. list GET

6.33.2.1. max6.34. CLUSTERS


6.34.2.1. case_sensitive6.34.2.2. max

6.35. COPYABLE6.35.1. copy POST

6.36. CPUPROFILE6.36.1. get GET6.36.2. remove DELETE6.36.3. update PUT

6.37. CPUPROFILES6.37.1. add POST6.37.2. list GET

6.37.2.1. max6.38. DATACENTER


6.38.2.1. force6.38.3. update PUT

6.39. DATACENTERNETWORK6.39.1. get GET6.39.2. remove DELETE6.39.3. update PUT

6.40. DATACENTERNETWORKS6.40.1. add POST6.40.2. list GET

6.40.2.1. max6.41. DATACENTERS



6.42. DISK6.42.1. copy POST6.42.2. export POST6.42.3. get GET6.42.4. move POST6.42.5. remove DELETE6.42.6. sparsify POST

6.43. DISKATTACHMENT6.43.1. get GET6.43.2. remove DELETE

6.43.2.1. detach_only6.43.3. update PUT

6.44. DISKATTACHMENTS6.44.1. add POST

132132132133133133134134134135135135135136136136136137137137138138138138139140140141141141141142142143143143143144145145146146147147148148148149149150150150151151


4


6.45. DISKPROFILE6.45.1. get GET6.45.2. remove DELETE6.45.3. update PUT

6.46. DISKPROFILES6.46.1. add POST6.46.2. list GET

6.46.2.1. max6.47. DISKSNAPSHOT


6.48. DISKSNAPSHOTS6.48.1. list GET

6.48.1.1. max6.49. DISKS


6.49.2.1. case_sensitive6.49.2.2. max6.49.2.3. unregistered

6.50. DOMAIN6.50.1. get GET

6.51. DOMAINGROUP6.51.1. get GET

6.52. DOMAINGROUPS6.52.1. list GET


6.53. DOMAINUSER6.53.1. get GET

6.54. DOMAINUSERS6.54.1. list GET


6.55. DOMAINS6.55.1. list GET

6.55.1.1. max6.56. ENGINEKATELLOERRATA

6.56.1. list GET6.56.1.1. max

6.57. EVENT6.57.1. get GET6.57.2. remove DELETE

6.58. EVENTS6.58.1. add POST6.58.2. list GET

6.58.2.1. case_sensitive6.58.2.2. from6.58.2.3. max6.58.2.4. search

6.58.3. undelete POST6.59. EXTERNALCOMPUTERESOURCE

151152152152153153153154154154154154155155155155156156158159159159159159160160160161161161161162162162163163163164164164165166166166167167167168170170170170171171

Table of Contents

5

6.59. EXTERNALCOMPUTERESOURCE6.59.1. get GET

6.60. EXTERNALCOMPUTERESOURCES6.60.1. list GET

6.60.1.1. max6.61. EXTERNALDISCOVEREDHOST

6.61.1. get GET6.62. EXTERNALDISCOVEREDHOSTS

6.62.1. list GET6.62.1.1. max

6.63. EXTERNALHOST6.63.1. get GET

6.64. EXTERNALHOSTGROUP6.64.1. get GET

6.65. EXTERNALHOSTGROUPS6.65.1. list GET

6.65.1.1. max6.66. EXTERNALHOSTPROVIDER

6.66.1. get GET6.66.2. importcertificates POST6.66.3. remove DELETE6.66.4. testconnectivity POST6.66.5. update PUT

6.67. EXTERNALHOSTPROVIDERS6.67.1. add POST6.67.2. list GET

6.67.2.1. max6.68. EXTERNALHOSTS

6.68.1. list GET6.68.1.1. max

6.69. EXTERNALPROVIDER6.69.1. importcertificates POST6.69.2. testconnectivity POST

6.70. EXTERNALPROVIDERCERTIFICATE6.70.1. get GET

6.71. EXTERNALPROVIDERCERTIFICATES6.71.1. list GET

6.71.1.1. max6.72. EXTERNALVMIMPORTS

6.72.1. add POST6.73. FENCEAGENT


6.74. FENCEAGENTS6.74.1. add POST6.74.2. list GET

6.74.2.1. max6.75. FILE

6.75.1. get GET6.76. FILES

6.76.1. list GET6.76.1.1. case_sensitive6.76.1.2. max

171171172172172172173173173173173174174174174175175175176176176176176177177177178178178178178179179179179180180180180181181182182182183183183183183184184184185185


6

6.76.1.2. max6.77. FILTER


6.78. FILTERS6.78.1. add POST6.78.2. list GET

6.78.2.1. max6.79. GLUSTERBRICK

6.79.1. get GET6.79.2. remove DELETE6.79.3. replace POST

6.80. GLUSTERBRICKS6.80.1. activate POST6.80.2. add POST6.80.3. list GET

6.80.3.1. max6.80.4. migrate POST6.80.5. remove DELETE6.80.6. stopmigrate POST

6.80.6.1. bricks6.81. GLUSTERHOOK

6.81.1. disable POST6.81.2. enable POST6.81.3. get GET6.81.4. remove DELETE6.81.5. resolve POST

6.82. GLUSTERHOOKS6.82.1. list GET

6.82.1.1. max6.83. GLUSTERVOLUME

6.83.1. get GET6.83.2. getprofilestatistics POST6.83.3. rebalance POST

6.83.3.1. fix_layout6.83.3.2. force

6.83.4. remove DELETE6.83.5. resetalloptions POST6.83.6. resetoption POST6.83.7. setoption POST6.83.8. start POST

6.83.8.1. force6.83.9. startprofile POST6.83.10. stop POST6.83.11. stopprofile POST6.83.12. stoprebalance POST

6.84. GLUSTERVOLUMES6.84.1. add POST6.84.2. list GET


6.85. GROUP6.85.1. get GET6.85.2. remove DELETE

185185185186186186186187187187188189189190191191192192193194194195195195196196196197197197197198199200200201201201201202203203203203204204205205206206207207207207

Table of Contents

7

6.85.2. remove DELETE6.86. GROUPS



6.87. HOST6.87.1. activate POST6.87.2. approve POST6.87.3. commitnetconfig POST6.87.4. deactivate POST

6.87.4.1. stop_gluster_service6.87.5. enrollcertificate POST6.87.6. fence POST6.87.7. forceselectspm POST6.87.8. get GET6.87.9. install POST

6.87.9.1. deploy_hosted_engine6.87.9.2. undeploy_hosted_engine

6.87.10. iscsidiscover POST6.87.11. iscsilogin POST6.87.12. refresh POST6.87.13. remove DELETE6.87.14. setupnetworks POST6.87.15. unregisteredstoragedomainsdiscover POST6.87.16. update PUT6.87.17. upgrade POST6.87.18. upgradecheck POST

6.88. HOSTDEVICE6.88.1. get GET

6.89. HOSTDEVICES6.89.1. list GET

6.89.1.1. max6.90. HOSTHOOK

6.90.1. get GET6.91. HOSTHOOKS

6.91.1. list GET6.91.1.1. max

6.92. HOSTNIC6.92.1. get GET6.92.2. updatevirtualfunctionsconfiguration POST

6.93. HOSTNICS6.93.1. list GET

6.93.1.1. max6.94. HOSTNUMANODE

6.94.1. get GET6.95. HOSTNUMANODES

6.95.1. list GET6.95.1.1. max

6.96. HOSTSTORAGE6.96.1. list GET

6.96.1.1. report_status6.97. HOSTS

6.97.1. add POST

207207208208209209209210211211212212212213214214214216216216217217217218222222223223223224224224225225225225225226226226226227227228228228228228229229229230230231


8

6.97.1. add POST6.97.1.1. deploy_hosted_engine6.97.1.2. undeploy_hosted_engine


6.98. ICON6.98.1. get GET

6.99. ICONS6.99.1. list GET

6.99.1.1. max6.100. IMAGE

6.100.1. get GET6.100.2. import POST

6.101. IMAGETRANSFER6.101.1. extend POST6.101.2. finalize POST6.101.3. get GET6.101.4. pause POST6.101.5. resume POST

6.102. IMAGETRANSFERS6.102.1. add POST6.102.2. list GET

6.103. IMAGES6.103.1. list GET

6.103.1.1. max6.104. INSTANCETYPE


6.105. INSTANCETYPEGRAPHICSCONSOLE6.105.1. get GET6.105.2. remove DELETE

6.106. INSTANCETYPEGRAPHICSCONSOLES6.106.1. add POST6.106.2. list GET

6.106.2.1. max6.107. INSTANCETYPENIC


6.108. INSTANCETYPENICS6.108.1. add POST6.108.2. list GET

6.108.2.1. max6.109. INSTANCETYPEWATCHDOG


6.110. INSTANCETYPEWATCHDOGS6.110.1. add POST6.110.2. list GET

6.110.2.1. max6.111. INSTANCETYPES

231232232232233233233233234234235235235235236239240240240240240241241241241242242242243243244244244245245245245245246246246247247247248248248248249249249250250250

Table of Contents

9

6.111. INSTANCETYPES6.111.1. add POST6.111.2. list GET


6.112. ISCSIBOND6.112.1. get GET6.112.2. remove DELETE6.112.3. update PUT

6.113. ISCSIBONDS6.113.1. add POST6.113.2. list GET

6.113.2.1. max6.114. JOB

6.114.1. clear POST6.114.2. end POST

6.114.2.1. succeeded6.114.3. get GET

6.115. JOBS6.115.1. add POST6.115.2. list GET

6.115.2.1. max6.116. KATELLOERRATA

6.116.1. list GET6.116.1.1. max

6.117. KATELLOERRATUM6.117.1. get GET

6.118. MACPOOL6.118.1. get GET6.118.2. remove DELETE6.118.3. update PUT

6.119. MACPOOLS6.119.1. add POST6.119.2. list GET

6.119.2.1. max6.120. MEASURABLE6.121. MOVEABLE

6.121.1. move POST6.122. NETWORK


6.123. NETWORKATTACHMENT6.123.1. get GET6.123.2. remove DELETE6.123.3. update PUT

6.124. NETWORKATTACHMENTS6.124.1. add POST6.124.2. list GET

6.124.2.1. max6.125. NETWORKFILTER

6.125.1. get GET6.126. NETWORKFILTERS

6.126.1. list GET

250250252253253253253253254254255255256256256257257257258258259260260260261261261262262262263264264264265265265265265266266267268268268269269269270270270270271272


10

6.126.1. list GET6.127. NETWORKLABEL


6.128. NETWORKLABELS6.128.1. add POST6.128.2. list GET

6.128.2.1. max6.129. NETWORKS



6.130. OPENSTACKIMAGE6.130.1. get GET6.130.2. import POST

6.131. OPENSTACKIMAGEPROVIDER6.131.1. get GET6.131.2. importcertificates POST6.131.3. remove DELETE6.131.4. testconnectivity POST6.131.5. update PUT

6.132. OPENSTACKIMAGEPROVIDERS6.132.1. add POST6.132.2. list GET

6.132.2.1. max6.133. OPENSTACKIMAGES

6.133.1. list GET6.133.1.1. max

6.134. OPENSTACKNETWORK6.134.1. get GET6.134.2. import POST

6.134.2.1. data_center6.135. OPENSTACKNETWORKPROVIDER


6.136. OPENSTACKNETWORKPROVIDERS6.136.1. add POST6.136.2. list GET

6.136.2.1. max6.137. OPENSTACKNETWORKS

6.137.1. list GET6.137.1.1. max

6.138. OPENSTACKSUBNET6.138.1. get GET6.138.2. remove DELETE

6.139. OPENSTACKSUBNETS6.139.1. add POST6.139.2. list GET

6.139.2.1. max6.140. OPENSTACKVOLUMEAUTHENTICATIONKEY

272272272273273273274274274275275276276276277277278279279279279280280280281281281281282282282282283283283284284284285285286286286286287287287287288288288288289289

Table of Contents

11

6.140. OPENSTACKVOLUMEAUTHENTICATIONKEY6.140.1. get GET6.140.2. remove DELETE6.140.3. update PUT

6.141. OPENSTACKVOLUMEAUTHENTICATIONKEYS6.141.1. add POST6.141.2. list GET

6.141.2.1. max6.142. OPENSTACKVOLUMEPROVIDER


6.143. OPENSTACKVOLUMEPROVIDERS6.143.1. add POST6.143.2. list GET

6.143.2.1. max6.144. OPENSTACKVOLUMETYPE

6.144.1. get GET6.145. OPENSTACKVOLUMETYPES

6.145.1. list GET6.145.1.1. max

6.146. OPERATINGSYSTEM6.146.1. get GET

6.147. OPERATINGSYSTEMS6.147.1. list GET

6.147.1.1. max6.148. PERMISSION


6.149. PERMIT6.149.1. get GET6.149.2. remove DELETE

6.150. PERMITS6.150.1. add POST6.150.2. list GET

6.150.2.1. max6.151. QOS


6.152. QOSS6.152.1. add POST6.152.2. list GET

6.152.2.1. max6.153. QUOTA


6.154. QUOTACLUSTERLIMIT6.154.1. get GET6.154.2. remove DELETE

6.155. QUOTACLUSTERLIMITS

289289289290290290290291291291292292292292293293294294294294295295295295296296296296296297297297298298298299299300300300301301301301302302302302303303304304304305


12

6.155. QUOTACLUSTERLIMITS6.155.1. add POST6.155.2. list GET

6.155.2.1. max6.156. QUOTASTORAGELIMIT


6.157. QUOTASTORAGELIMITS6.157.1. add POST6.157.2. list GET

6.157.2.1. max6.158. QUOTAS


6.158.2.1. max6.159. ROLE


6.160. ROLES6.160.1. add POST6.160.2. list GET

6.160.2.1. max6.161. SCHEDULINGPOLICIES


6.161.2.1. max6.162. SCHEDULINGPOLICY


6.163. SCHEDULINGPOLICYUNIT6.163.1. get GET6.163.2. remove DELETE

6.164. SCHEDULINGPOLICYUNITS6.164.1. list GET

6.164.1.1. max6.165. SNAPSHOT

6.165.1. get GET6.165.2. remove DELETE6.165.3. restore POST

6.166. SNAPSHOTCDROM6.166.1. get GET

6.167. SNAPSHOTCDROMS6.167.1. list GET

6.167.1.1. max6.168. SNAPSHOTDISK

6.168.1. get GET6.169. SNAPSHOTDISKS

6.169.1. list GET6.169.1.1. max

6.170. SNAPSHOTNIC6.170.1. get GET

305305305305306306306306307307307307308308308309309309310310311311312312312313313313313314314314315315315315316316316316317317318318318318318319319319319319320

Table of Contents

13

6.171. SNAPSHOTNICS6.171.1. list GET

6.171.1.1. max6.172. SNAPSHOTS


6.172.2.1. max6.173. SSHPUBLICKEY


6.174. SSHPUBLICKEYS6.174.1. add POST6.174.2. list GET

6.174.2.1. max6.175. STATISTIC

6.175.1. get GET6.176. STATISTICS

6.176.1. list GET6.176.1.1. max

6.177. STEP6.177.1. end POST

6.177.1.1. succeeded6.177.2. get GET

6.178. STEPS6.178.1. add POST6.178.2. list GET

6.178.2.1. max6.179. STORAGE

6.179.1. get GET6.179.1.1. report_status

6.180. STORAGEDOMAIN6.180.1. get GET6.180.2. isattached POST6.180.3. reduceluns POST6.180.4. refreshluns POST6.180.5. remove DELETE

6.180.5.1. destroy6.180.5.2. host

6.180.6. update PUT6.180.7. updateovfstore POST

6.181. STORAGEDOMAINCONTENTDISK6.181.1. get GET

6.182. STORAGEDOMAINCONTENTDISKS6.182.1. list GET


6.183. STORAGEDOMAINSERVERCONNECTION6.183.1. get GET6.183.2. remove DELETE

6.184. STORAGEDOMAINSERVERCONNECTIONS6.184.1. add POST6.184.2. list GET

320320320321321322322322322323323323323324324324324325325326326326327327328328329330330330330331332332332333334334335335336336336337337337338338338338338339339


14

6.184.2.1. max6.185. STORAGEDOMAINTEMPLATE

6.185.1. get GET6.185.2. import POST

6.185.2.1. clone6.185.3. register POST

6.185.3.1. allow_partial_import6.185.4. remove DELETE

6.186. STORAGEDOMAINTEMPLATES6.186.1. list GET

6.186.1.1. max6.186.1.2. unregistered

6.187. STORAGEDOMAINVM6.187.1. get GET6.187.2. import POST

6.187.2.1. clone6.187.2.2. collapse_snapshots

6.187.3. register POST6.187.3.1. allow_partial_import6.187.3.2. reassign_bad_macs

6.187.4. remove DELETE6.188. STORAGEDOMAINVMDISKATTACHMENT

6.188.1. get GET6.189. STORAGEDOMAINVMDISKATTACHMENTS

6.189.1. list GET6.190. STORAGEDOMAINVMS

6.190.1. list GET6.190.1.1. max6.190.1.2. unregistered

6.191. STORAGEDOMAINS6.191.1. add POST6.191.2. list GET


6.192. STORAGESERVERCONNECTION6.192.1. get GET6.192.2. remove DELETE

6.192.2.1. host6.192.3. update PUT

6.192.3.1. force6.193. STORAGESERVERCONNECTIONEXTENSION


6.194. STORAGESERVERCONNECTIONEXTENSIONS6.194.1. add POST6.194.2. list GET

6.194.2.1. max6.195. STORAGESERVERCONNECTIONS


6.195.2.1. max6.196. SYSTEM

339339340340341341342342342343343343343344344346346346347347347347348348348349349350350350350352352352353353353354354355355355355356356357357358358358358359359

Table of Contents

15

6.196.1. get GET6.196.2. reloadconfigurations POST

6.197. SYSTEMPERMISSIONS6.197.1. add POST6.197.2. list GET

6.198. TAG6.198.1. get GET6.198.2. remove DELETE6.198.3. update PUT

6.199. TAGS6.199.1. add POST6.199.2. list GET

6.199.2.1. max6.200. TEMPLATE

6.200.1. export POST6.200.1.1. exclusive


6.201. TEMPLATECDROM6.201.1. get GET

6.201.1.1. cdrom6.202. TEMPLATECDROMS

6.202.1. list GET6.202.1.1. max

6.203. TEMPLATEDISK6.203.1. copy POST6.203.2. export POST6.203.3. get GET6.203.4. remove DELETE

6.204. TEMPLATEDISKATTACHMENT6.204.1. get GET6.204.2. remove DELETE

6.205. TEMPLATEDISKATTACHMENTS6.205.1. list GET

6.206. TEMPLATEDISKS6.206.1. list GET

6.206.1.1. max6.207. TEMPLATEGRAPHICSCONSOLE


6.208. TEMPLATEGRAPHICSCONSOLES6.208.1. add POST6.208.2. list GET

6.208.2.1. max6.209. TEMPLATENIC


6.210. TEMPLATENICS6.210.1. add POST6.210.2. list GET

6.210.2.1. max

359361361361362363363364364365365366367367367368368368369369370370370371371371371372372372373373373374374374374375375375375376376376377377377377378378378378379


16

6.211. TEMPLATEWATCHDOG6.211.1. get GET6.211.2. remove DELETE6.211.3. update PUT

6.212. TEMPLATEWATCHDOGS6.212.1. add POST6.212.2. list GET

6.212.2.1. max6.213. TEMPLATES

6.213.1. add POST6.213.1.1. clone_permissions6.213.1.2. seal


6.214. UNMANAGEDNETWORK6.214.1. get GET6.214.2. remove DELETE

6.215. UNMANAGEDNETWORKS6.215.1. list GET

6.215.1.1. max6.216. USER


6.217. USERS6.217.1. add POST6.217.2. list GET


6.218. VIRTUALFUNCTIONALLOWEDNETWORK6.218.1. get GET6.218.2. remove DELETE

6.219. VIRTUALFUNCTIONALLOWEDNETWORKS6.219.1. add POST6.219.2. list GET

6.219.2.1. max6.220. VM

6.220.1. cancelmigration POST6.220.2. clone POST6.220.3. commitsnapshot POST6.220.4. detach POST6.220.5. export POST6.220.6. freezefilesystems POST6.220.7. get GET

6.220.7.1. all_content6.220.7.2. next_run

6.220.8. logon POST6.220.9. maintenance POST6.220.10. migrate POST

6.220.10.1. cluster6.220.10.2. force6.220.10.3. host

6.220.11. previewsnapshot POST

379379379380380380380381381381382382383383384384384384384385385385385386386387388389389389389389390390390390391392393393393394394395395396396397397398398398398

Table of Contents

17

6.220.12. reboot POST6.220.13. remove DELETE

6.220.13.1. force6.220.14. reordermacaddresses POST6.220.15. shutdown POST6.220.16. start POST

6.220.16.1. pause6.220.16.2. use_cloud_init6.220.16.3. use_sysprep6.220.16.4. vm

6.220.17. stop POST6.220.18. suspend POST6.220.19. thawfilesystems POST6.220.20. ticket POST6.220.21. undosnapshot POST6.220.22. update PUT

6.220.22.1. next_run6.221. VMAPPLICATION

6.221.1. get GET6.221.1.1. application

6.222. VMAPPLICATIONS6.222.1. list GET

6.222.1.1. applications6.222.1.2. max

6.223. VMCDROM6.223.1. get GET

6.223.1.1. current6.223.2. update PUT

6.223.2.1. current6.224. VMCDROMS

6.224.1. list GET6.224.1.1. max

6.225. VMDISK6.225.1. activate POST6.225.2. deactivate POST6.225.3. export POST6.225.4. get GET6.225.5. move POST6.225.6. remove DELETE6.225.7. update PUT

6.226. VMDISKS6.226.1. add POST6.226.2. list GET

6.226.2.1. max6.227. VMGRAPHICSCONSOLE

6.227.1. get GET6.227.1.1. current

6.227.2. proxyticket POST6.227.3. remoteviewerconnectionfile POST

6.227.3.1. remote_viewer_connection_file6.227.4. remove DELETE6.227.5. ticket POST

6.228. VMGRAPHICSCONSOLES

399400400400400401402402402402403403403404405405405406406406407407407408408408409409410410410411411411412412412412413413413414414414414415415415416417417418418


18

6.228. VMGRAPHICSCONSOLES6.228.1. add POST6.228.2. list GET

6.228.2.1. current6.228.2.2. max

6.229. VMHOSTDEVICE6.229.1. get GET6.229.2. remove DELETE

6.230. VMHOSTDEVICES6.230.1. add POST6.230.2. list GET

6.230.2.1. max6.231. VMNIC

6.231.1. activate POST6.231.2. deactivate POST6.231.3. get GET6.231.4. remove DELETE6.231.5. update PUT

6.232. VMNICS6.232.1. add POST6.232.2. list GET

6.232.2.1. max6.233. VMNUMANODE


6.234. VMNUMANODES6.234.1. add POST6.234.2. list GET

6.234.2.1. max6.235. VMPOOL

6.235.1. allocatevm POST6.235.2. get GET6.235.3. remove DELETE6.235.4. update PUT

6.236. VMPOOLS6.236.1. add POST6.236.2. list GET


6.237. VMREPORTEDDEVICE6.237.1. get GET

6.238. VMREPORTEDDEVICES6.238.1. list GET

6.238.1.1. max6.239. VMSESSION

6.239.1. get GET6.240. VMSESSIONS

6.240.1. list GET6.240.1.1. max

6.241. VMWATCHDOG6.241.1. get GET

6.241.1.1. watchdog6.241.2. remove DELETE

418419419419419420420421421421422423423423423424424425425426427427427428428428429429430430430431431432432433433434434435435435435435436436436436437437437438438438

Table of Contents

19

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

6.241.2. remove DELETE6.241.3. update PUT

6.241.3.1. watchdog6.242. VMWATCHDOGS

6.242.1. add POST6.242.1.1. watchdog

6.242.2. list GET6.242.2.1. max6.242.2.2. watchdogs

6.243. VMS6.243.1. add POST

6.243.1.1. clone6.243.1.2. clone_permissions

6.243.2. list GET6.243.2.1. all_content6.243.2.2. case_sensitive

6.244. VNICPROFILE6.244.1. get GET6.244.2. remove DELETE6.244.3. update PUT

6.245. VNICPROFILES6.245.1. add POST6.245.2. list GET

6.245.2.1. max6.246. WEIGHT


6.247. WEIGHTS6.247.1. add POST6.247.2. list GET

6.247.2.1. max

CHAPTER 7. TYPES7.1. ACCESSPROTOCOL ENUM7.2. ACTION STRUCT7.3. AFFINITYGROUP STRUCT

7.3.1. enforcing7.3.2. positive

7.4. AFFINITYLABEL STRUCT7.4.1. read_only

7.5. AFFINITYRULE STRUCT7.5.1. enabled7.5.2. enforcing7.5.3. positive

7.6. AGENT STRUCT7.6.1. host

7.7. AGENTCONFIGURATION STRUCT7.8. API STRUCT7.9. APISUMMARY STRUCT7.10. APISUMMARYITEM STRUCT7.11. APPLICATION STRUCT7.12. ARCHITECTURE ENUM7.13. AUTHORIZEDKEY STRUCT7.14. AUTONUMASTATUS ENUM

438439439439440440440441441441441444445445446446447447447448448448449450450450450451451451452

453453453458459459460461461461462462462463463464465466466467467468


20

7.15. BALANCE STRUCT7.16. BIOS STRUCT7.17. BLOCKSTATISTIC STRUCT7.18. BONDING STRUCT

7.18.1. ad_partner_mac7.18.2. options7.18.3. slaves7.18.4. active_slave

7.19. BOOKMARK STRUCT7.20. BOOT STRUCT7.21. BOOTDEVICE ENUM7.22. BOOTMENU STRUCT7.23. BOOTPROTOCOL ENUM

7.23.1. autoconf7.23.2. dhcp

7.24. BRICKPROFILEDETAIL STRUCT7.25. CDROM STRUCT

7.25.1. vms7.26. CERTIFICATE STRUCT7.27. CLOUDINIT STRUCT7.28. CLUSTER STRUCT

7.28.1. custom_scheduling_policy_properties7.28.2. fencing_policy7.28.3. gluster_tuned_profile7.28.4. required_rng_sources7.28.5. version7.28.6. scheduling_policy

7.29. CLUSTERLEVEL STRUCT7.30. CONFIGURATION STRUCT

7.30.1. data7.31. CONFIGURATIONTYPE ENUM7.32. CONSOLE STRUCT7.33. CORE STRUCT7.34. CPU STRUCT7.35. CPUMODE ENUM7.36. CPUPROFILE STRUCT7.37. CPUTOPOLOGY STRUCT7.38. CPUTUNE STRUCT7.39. CPUTYPE STRUCT7.40. CREATIONSTATUS ENUM7.41. CUSTOMPROPERTY STRUCT7.42. DATACENTER STRUCT

7.42.1. version7.43. DATACENTERSTATUS ENUM7.44. DEVICE STRUCT

7.44.1. vms7.45. DISK STRUCT

7.45.1. active7.45.2. actual_size7.45.3. bootable7.45.4. initial_size7.45.5. interface7.45.6. provisioned_size

468469469469470470470470471471471472472472473473473474474475476480481481481482483484484484486486486487487488489489489489490490491492493494494496496496497497497

Table of Contents

21

7.45.7. qcow_version7.45.8. shareable7.45.9. wipe_after_delete7.45.10. statistics7.45.11. storage_domains7.45.12. vms

7.46. DISKATTACHMENT STRUCT7.46.1. active7.46.2. logical_name7.46.3. read_only7.46.4. uses_scsi_reservation

7.47. DISKFORMAT ENUM7.48. DISKINTERFACE ENUM7.49. DISKPROFILE STRUCT7.50. DISKSNAPSHOT STRUCT

7.50.1. active7.50.2. actual_size7.50.3. bootable7.50.4. initial_size7.50.5. interface7.50.6. provisioned_size7.50.7. qcow_version7.50.8. shareable7.50.9. wipe_after_delete7.50.10. statistics7.50.11. storage_domains7.50.12. vms

7.51. DISKSTATUS ENUM7.52. DISKSTORAGETYPE ENUM7.53. DISKTYPE ENUM7.54. DISPLAY STRUCT7.55. DISPLAYTYPE ENUM7.56. DNS STRUCT7.57. DNSRESOLVERCONFIGURATION STRUCT

7.57.1. name_servers7.58. DOMAIN STRUCT

7.58.1. users7.59. ENTITYEXTERNALSTATUS ENUM

7.59.1. error7.59.2. failure

7.60. ENTITYPROFILEDETAIL STRUCT7.61. ERRORHANDLING STRUCT7.62. EVENT STRUCT

7.62.1. correlation_id7.62.2. flood_rate7.62.3. cluster7.62.4. data_center7.62.5. host7.62.6. storage_domain7.62.7. template7.62.8. user7.62.9. vm

7.63. EXTERNALCOMPUTERESOURCE STRUCT

497497498499499499499500501501501502502502503505505506506506506506506507508508509509509509510511511512512512513513513513514514514515515516516516516516516516516


22

7.64. EXTERNALDISCOVEREDHOST STRUCT7.65. EXTERNALHOST STRUCT7.66. EXTERNALHOSTGROUP STRUCT7.67. EXTERNALHOSTPROVIDER STRUCT

7.67.1. requires_authentication7.68. EXTERNALPROVIDER STRUCT

7.68.1. requires_authentication7.69. EXTERNALSTATUS ENUM7.70. EXTERNALSYSTEMTYPE ENUM7.71. EXTERNALVMIMPORT STRUCT

7.71.1. url7.71.2. cpu_profile7.71.3. drivers_iso7.71.4. host7.71.5. quota7.71.6. vm

7.72. EXTERNALVMPROVIDERTYPE ENUM7.73. FAULT STRUCT7.74. FENCETYPE ENUM7.75. FENCINGPOLICY STRUCT

7.75.1. skip_if_connectivity_broken7.75.2. skip_if_gluster_bricks_up7.75.3. skip_if_gluster_quorum_not_met7.75.4. skip_if_sd_active

7.76. FILE STRUCT7.77. FILTER STRUCT7.78. FLOPPY STRUCT

7.78.1. vms7.79. FOPSTATISTIC STRUCT7.80. GLUSTERBRICK STRUCT

7.80.1. vms7.81. GLUSTERBRICKADVANCEDDETAILS STRUCT

7.81.1. vms7.82. GLUSTERBRICKMEMORYINFO STRUCT7.83. GLUSTERBRICKSTATUS ENUM7.84. GLUSTERCLIENT STRUCT7.85. GLUSTERHOOK STRUCT7.86. GLUSTERHOOKSTATUS ENUM7.87. GLUSTERMEMORYPOOL STRUCT7.88. GLUSTERSERVERHOOK STRUCT7.89. GLUSTERSTATE ENUM7.90. GLUSTERVOLUME STRUCT7.91. GLUSTERVOLUMEPROFILEDETAILS STRUCT7.92. GLUSTERVOLUMESTATUS ENUM7.93. GLUSTERVOLUMETYPE ENUM

7.93.1. disperse7.93.2. distribute7.93.3. distributed_disperse7.93.4. distributed_replicate7.93.5. distributed_stripe7.93.6. distributed_striped_replicate7.93.7. replicate7.93.8. stripe

517518519520521521522522523523524525525525525525525526526527527527527528528528529530530530532532533534534534535536536537538539540541541542542542542543543543543

Table of Contents

23

7.93.8. stripe7.93.9. striped_replicate

7.94. GRACEPERIOD STRUCT7.95. GRAPHICSCONSOLE STRUCT7.96. GRAPHICSTYPE ENUM7.97. GROUP STRUCT

7.97.1. roles7.98. GUESTOPERATINGSYSTEM STRUCT7.99. HARDWAREINFORMATION STRUCT7.100. HIGHAVAILABILITY STRUCT

7.100.1. priority7.101. HOOK STRUCT7.102. HOOKCONTENTTYPE ENUM7.103. HOOKSTAGE ENUM7.104. HOOKSTATUS ENUM7.105. HOST STRUCT

7.105.1. external_status7.105.2. kdump_status7.105.3. ksm7.105.4. libvirt_version7.105.5. override_iptables7.105.6. protocol7.105.7. se_linux7.105.8. spm7.105.9. status_detail7.105.10. transparent_huge_pages7.105.11. version7.105.12. katello_errata7.105.13. statistics

7.106. HOSTDEVICE STRUCT7.106.1. driver

7.107. HOSTDEVICEPASSTHROUGH STRUCT7.108. HOSTNIC STRUCT

7.108.1. ad_aggregator_id7.108.2. bridged7.108.3. statistics7.108.4. network

7.109. HOSTNICVIRTUALFUNCTIONSCONFIGURATION STRUCT7.109.1. max_number_of_virtual_functions7.109.2. number_of_virtual_functions

7.110. HOSTPROTOCOL ENUM7.111. HOSTSTATUS ENUM

7.111.1. error7.111.2. initializing7.111.3. install_failed7.111.4. installing_os7.111.5. maintenance7.111.6. non_operational7.111.7. non_responsive7.111.8. pending_approval7.111.9. preparing_for_maintenance

7.112. HOSTSTORAGE STRUCT7.112.1. nfs_retrans7.112.2. nfs_timeo

543543543544545545546546547547548548549550550550553553554554554554554554554555555557557559560560561564564564565565565566566566567568568568568568568568568568570570


24

7.112.2. nfs_timeo7.113. HOSTTYPE ENUM

7.113.1. ovirt_node7.114. HOSTEDENGINE STRUCT7.115. ICON STRUCT

7.115.1. media_type7.116. IDENTIFIED STRUCT7.117. IMAGE STRUCT7.118. IMAGETRANSFER STRUCT

7.118.1. direction7.118.2. phase7.118.3. proxy_url

7.119. IMAGETRANSFERDIRECTION ENUM7.120. IMAGETRANSFERPHASE ENUM

7.120.1. cancelled7.120.2. finalizing_success7.120.3. finished_failure7.120.4. finished_success7.120.5. initializing7.120.6. paused_system7.120.7. resuming7.120.8. unknown

7.121. INHERITABLEBOOLEAN ENUM7.122. INITIALIZATION STRUCT7.123. INSTANCETYPE STRUCT

7.123.1. cpu7.123.2. custom_compatibility_version7.123.3. high_availability7.123.4. large_icon7.123.5. lease7.123.6. memory7.123.7. migration_downtime7.123.8. origin7.123.9. small_icon7.123.10. sso

7.124. IO STRUCT7.125. IP STRUCT

7.125.1. address7.125.2. netmask7.125.3. version

7.126. IPADDRESSASSIGNMENT STRUCT7.127. IPVERSION ENUM7.128. ISCSIBOND STRUCT7.129. ISCSIDETAILS STRUCT7.130. JOB STRUCT

7.130.1. external7.131. JOBSTATUS ENUM

7.131.1. aborted7.131.2. finished7.131.3. started7.131.4. unknown

7.132. KATELLOERRATUM STRUCT7.132.1. severity7.132.2. type

570570571571572572572573573574574574575575576576577577577577577577577578579584584584584585585585585586586587587588588588588589589590591592593593593593593593594594

Table of Contents

25

7.132.2. type7.133. KDUMPSTATUS ENUM7.134. KERNEL STRUCT7.135. KSM STRUCT7.136. LOGSEVERITY ENUM

7.136.1. alert7.136.2. error7.136.3. normal7.136.4. warning

7.137. LOGICALUNIT STRUCT7.137.1. discard_max_size7.137.2. discard_zeroes_data

7.138. LUNSTATUS ENUM7.139. MAC STRUCT7.140. MACPOOL STRUCT

7.140.1. allow_duplicates7.140.2. default_pool7.140.3. ranges

7.141. MEMORYOVERCOMMIT STRUCT7.142. MEMORYPOLICY STRUCT

7.142.1. max7.143. MESSAGEBROKERTYPE ENUM7.144. METHOD STRUCT7.145. MIGRATEONERROR ENUM7.146. MIGRATIONBANDWIDTH STRUCT

7.146.1. custom_value7.147. MIGRATIONBANDWIDTHASSIGNMENTMETHOD ENUM

7.147.1. auto7.148. MIGRATIONOPTIONS STRUCT7.149. MIGRATIONPOLICY STRUCT7.150. NETWORK STRUCT

7.150.1. usages7.151. NETWORKATTACHMENT STRUCT

7.151.1. dns_resolver_configuration7.151.2. properties

7.152. NETWORKCONFIGURATION STRUCT7.153. NETWORKFILTER STRUCT

7.153.1. version7.154. NETWORKLABEL STRUCT7.155. NETWORKPLUGINTYPE ENUM7.156. NETWORKSTATUS ENUM7.157. NETWORKUSAGE ENUM

7.157.1. management7.158. NFSPROFILEDETAIL STRUCT7.159. NFSVERSION ENUM

7.159.1. v4_27.160. NIC STRUCT

7.160.1. network7.160.2. vms

7.161. NICCONFIGURATION STRUCT7.162. NICINTERFACE ENUM7.163. NICSTATUS ENUM7.164. NUMANODE STRUCT

7.164.1. statistics

594595595595596596596596596596598598598599599600600600600600601601601602602602603603603604604606607610610612612613613614614614615615615616616618619619619620620621


26

7.164.1. statistics7.165. NUMANODEPIN STRUCT

7.165.1. host_numa_node7.165.2. pinned

7.166. NUMATUNEMODE ENUM7.167. OPENSTACKIMAGE STRUCT7.168. OPENSTACKIMAGEPROVIDER STRUCT

7.168.1. requires_authentication7.169. OPENSTACKNETWORK STRUCT7.170. OPENSTACKNETWORKPROVIDER STRUCT

7.170.1. read_only7.170.2. requires_authentication

7.171. OPENSTACKNETWORKPROVIDERTYPE ENUM7.171.1. external7.171.2. neutron

7.172. OPENSTACKPROVIDER STRUCT7.172.1. requires_authentication

7.173. OPENSTACKSUBNET STRUCT7.173.1. ip_version

7.174. OPENSTACKVOLUMEPROVIDER STRUCT7.174.1. requires_authentication

7.175. OPENSTACKVOLUMETYPE STRUCT7.176. OPENSTACKVOLUMEAUTHENTICATIONKEY STRUCT7.177. OPENSTACKVOLUMEAUTHENTICATIONKEYUSAGETYPE ENUM7.178. OPERATINGSYSTEM STRUCT

7.178.1. custom_kernel_cmdline7.178.2. reported_kernel_cmdline

7.179. OPERATINGSYSTEMINFO STRUCT7.180. OPTION STRUCT7.181. OSTYPE ENUM7.182. PACKAGE STRUCT7.183. PAYLOAD STRUCT7.184. PAYLOADENCODING ENUM7.185. PERMISSION STRUCT7.186. PERMIT STRUCT7.187. PMPROXY STRUCT7.188. PMPROXYTYPE ENUM7.189. POLICYUNITTYPE ENUM7.190. PORTMIRRORING STRUCT7.191. POWERMANAGEMENT STRUCT

7.191.1. agents7.191.2. automatic_pm_enabled7.191.3. kdump_detection7.191.4. type

7.192. POWERMANAGEMENTSTATUS ENUM7.193. PRODUCT STRUCT7.194. PRODUCTINFO STRUCT

7.194.1. vendor7.195. PROFILEDETAIL STRUCT7.196. PROPERTY STRUCT7.197. PROXYTICKET STRUCT7.198. QCOWVERSION ENUM

7.198.1. qcow2_v37.199. QOS STRUCT

621622623623623623624625625626627627628628628629629630630631632632633634634635635636636636638639639639640641641642642642643643643644644644644645645646646646647647

Table of Contents

27

7.199. QOS STRUCT7.199.1. cpu_limit7.199.2. inbound_average7.199.3. inbound_burst7.199.4. inbound_peak7.199.5. max_iops7.199.6. max_read_iops7.199.7. max_read_throughput7.199.8. max_throughput7.199.9. max_write_iops7.199.10. max_write_throughput7.199.11. outbound_average7.199.12. outbound_average_linkshare7.199.13. outbound_average_realtime7.199.14. outbound_average_upperlimit7.199.15. outbound_burst7.199.16. outbound_peak

7.200. QOSTYPE ENUM7.201. QUOTA STRUCT7.202. QUOTACLUSTERLIMIT STRUCT7.203. QUOTAMODETYPE ENUM7.204. QUOTASTORAGELIMIT STRUCT7.205. RANGE STRUCT7.206. RATE STRUCT7.207. REPORTEDCONFIGURATION STRUCT7.208. REPORTEDDEVICE STRUCT7.209. REPORTEDDEVICETYPE ENUM7.210. RESOLUTIONTYPE ENUM7.211. RNGDEVICE STRUCT7.212. RNGSOURCE ENUM

7.212.1. urandom7.213. ROLE STRUCT

7.213.1. mutable7.214. ROLETYPE ENUM7.215. SCHEDULINGPOLICY STRUCT7.216. SCHEDULINGPOLICYUNIT STRUCT7.217. SCSIGENERICIO ENUM7.218. SELINUX STRUCT7.219. SELINUXMODE ENUM7.220. SERIALNUMBER STRUCT7.221. SERIALNUMBERPOLICY ENUM7.222. SESSION STRUCT

7.222.1. console_user7.222.2. ip7.222.3. protocol7.222.4. user

7.223. SKIPIFCONNECTIVITYBROKEN STRUCT7.223.1. enabled7.223.2. threshold

7.224. SKIPIFSDACTIVE STRUCT7.224.1. enabled

7.225. SNAPSHOT STRUCT7.225.1. cpu7.225.2. custom_compatibility_version

647649649649650650650650650650650650651651651651651652652654655655656656657657658658658659659659660660661662662663663663664664665665665665665666666666666666671672


28

7.225.2. custom_compatibility_version7.225.3. high_availability7.225.4. large_icon7.225.5. lease7.225.6. memory7.225.7. migration_downtime7.225.8. next_run_configuration_exists7.225.9. origin7.225.10. persist_memorystate7.225.11. placement_policy7.225.12. small_icon7.225.13. sso7.225.14. stop_reason7.225.15. affinity_labels7.225.16. katello_errata7.225.17. original_template

7.226. SNAPSHOTSTATUS ENUM7.227. SNAPSHOTTYPE ENUM7.228. SPECIALOBJECTS STRUCT7.229. SPM STRUCT7.230. SPMSTATUS ENUM7.231. SSH STRUCT7.232. SSHAUTHENTICATIONMETHOD ENUM7.233. SSHPUBLICKEY STRUCT7.234. SSO STRUCT7.235. SSOMETHOD ENUM7.236. STATISTIC STRUCT7.237. STATISTICKIND ENUM7.238. STATISTICUNIT ENUM7.239. STEP STRUCT

7.239.1. external7.240. STEPENUM ENUM

7.240.1. executing7.240.2. finalizing7.240.3. rebalancing_volume7.240.4. removing_bricks7.240.5. unknown7.240.6. validating

7.241. STEPSTATUS ENUM7.241.1. aborted7.241.2. finished7.241.3. started7.241.4. unknown

7.242. STORAGECONNECTION STRUCT7.243. STORAGECONNECTIONEXTENSION STRUCT7.244. STORAGEDOMAIN STRUCT

7.244.1. discard_after_delete7.244.2. supports_discard7.244.3. supports_discard_zeroes_data7.244.4. wipe_after_delete7.244.5. data_center

7.245. STORAGEDOMAINLEASE STRUCT7.246. STORAGEDOMAINSTATUS ENUM7.247. STORAGEDOMAINTYPE ENUM

672672672672672673673673674674674675675677677678678678678679679679680680681681682684684685686686687687687687687687688688688688688688690691693694694694695695696696

Table of Contents

29

7.247. STORAGEDOMAINTYPE ENUM7.248. STORAGEFORMAT ENUM7.249. STORAGETYPE ENUM

7.249.1. cinder7.249.2. glance7.249.3. glusterfs

7.250. SWITCHTYPE ENUM7.251. TAG STRUCT7.252. TEMPLATE STRUCT


7.253. TEMPLATESTATUS ENUM7.254. TEMPLATEVERSION STRUCT

7.254.1. version_number7.255. TICKET STRUCT7.256. TIMEZONE STRUCT

7.256.1. utc_offset7.257. TRANSPARENTHUGEPAGES STRUCT7.258. TRANSPORTTYPE ENUM7.259. UNMANAGEDNETWORK STRUCT7.260. USB STRUCT7.261. USBTYPE ENUM

7.261.1. legacy7.262. USER STRUCT

7.262.1. namespace7.262.2. principal7.262.3. user_name

7.263. VALUE STRUCT7.264. VALUETYPE ENUM7.265. VCPUPIN STRUCT7.266. VENDOR STRUCT7.267. VERSION STRUCT7.268. VIRTIOSCSI STRUCT7.269. VIRTUALNUMANODE STRUCT

7.269.1. statistics7.270. VLAN STRUCT7.271. VM STRUCT

7.271.1. cpu7.271.2. custom_compatibility_version7.271.3. high_availability7.271.4. large_icon7.271.5. lease7.271.6. memory7.271.7. migration_downtime7.271.8. next_run_configuration_exists7.271.9. origin

696697697698698698698699700703704704704704704705705705705706707707707708708708708709709710710710711711711712712713713713714714716717717722722722723723723723723724


30

7.271.9. origin7.271.10. placement_policy7.271.11. small_icon7.271.12. sso7.271.13. stop_reason7.271.14. affinity_labels7.271.15. katello_errata7.271.16. original_template

7.272. VMAFFINITY ENUM7.273. VMBASE STRUCT


7.274. VMDEVICETYPE ENUM7.275. VMPLACEMENTPOLICY STRUCT7.276. VMPOOL STRUCT

7.276.1. auto_storage_select7.276.2. stateful7.276.3. instance_type

7.277. VMPOOLTYPE ENUM7.278. VMSTATUS ENUM

7.278.1. paused7.278.2. powering_up7.278.3. restoring_state7.278.4. saving_state7.278.5. suspended7.278.6. unknown7.278.7. up7.278.8. wait_for_launch

7.279. VMSUMMARY STRUCT7.280. VMTYPE ENUM

7.280.1. desktop7.280.2. server

7.281. VNICPASSTHROUGH STRUCT7.282. VNICPASSTHROUGHMODE ENUM7.283. VNICPROFILE STRUCT

7.283.1. migratable7.283.2. pass_through7.283.3. port_mirroring7.283.4. network_filter7.283.5. qos

7.284. VNICPROFILEMAPPING STRUCT7.285. VOLUMEGROUP STRUCT7.286. WATCHDOG STRUCT

7.286.1. model7.286.2. vms

7.287. WATCHDOGACTION ENUM

724724725725725727727728728728732732732732732733733733734734734735735736737737737737739739739739739740740740740740741741741741741742742743743744744745745746746746

Table of Contents

31

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

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

7.287. WATCHDOGACTION ENUM7.287.1. none

7.288. WATCHDOGMODEL ENUM7.289. WEIGHT STRUCT

APPENDIX A. PRIMITIVE TYPESA.1. STRING PRIMITIVEA.2. BOOLEAN PRIMITIVEA.3. INTEGER PRIMITIVEA.4. DECIMAL PRIMITIVEA.5. DATE PRIMITIVE

APPENDIX B. CHANGES IN VERSION 4 OF THE APIB.1. REMOVED YAML SUPPORTB.2. RENAMED COMPLEX TYPESB.3. REPLACED THE STATUS TYPE WITH ENUM TYPESB.4. REMOVE THE NIC NETWORK AND PORT_MIRRORING PROPERTIESB.5. REMOVE THE NIC ACTIVE PROPERTYB.6. REMOVE THE DISK TYPE PROPERTYB.7. REMOVE THE DISK SIZE PROPERTYB.8. REMOVED SUPPORT FOR PINNING A VM TO A SINGLE HOSTB.9. REMOVED THE CAPABILITIES.PERMITS ELEMENTB.10. REMOVED THE STORAGE_MANAGER ELEMENTB.11. REMOVED THE DATA CENTER STORAGE_TYPE ELEMENTB.12. REMOVE THE TIMEZONE ELEMENTB.13. REMOVED THE GUEST_INFO ELEMENTB.14. REPLACED CPU ID ATTRIBUTE WITH TYPE ELEMENTB.15. USE ELEMENTS INSTEAD OF ATTRIBUTES IN CPU TOPOLOGYB.16. USE ELEMENTS INSTEAD OF ATTRIBUTES IN VCPU PINB.17. USE ELEMENTS INSTEAD OF ATTRIBUTES IN VCPU PINB.18. USE ELEMENTS INSTEAD OF ATTRIBUTES IN MEMORY OVERCOMMITB.19. USE ELEMENTS INSTEAD OF ATTRIBUTES IN CONSOLEB.20. USE ELEMENTS INSTEAD OF ATTRIBUTES IN VIRTIO SCSIB.21. USE ELEMENT INSTEAD OF ATTRIBUTE FOR POWER MANAGEMENT AGENT TYPEB.22. USE ELEMENTS INSTEAD OF ATTRIBUTES IN POWER MANAGEMENT AGENT OPTIONSB.23. USE ELEMENTS INSTEAD OF ATTRIBUTES IN IP ADDRESS:B.24. USE ELEMENTS INSTEAD OF ATTRIBUTES IN MAC ADDRESS:B.25. USE ELEMENTS INSTEAD OF ATTRIBUTES IN BOOT DEVICE:B.26. USE ELEMENT INSTEAD OF ATTRIBUTE FOR OPERATING SYSTEM TYPEB.27. REMOVED THE FORCE PARAMETER FROM THE REQUEST TO RETRIEVE A HOSTB.28. REMOVED DEPRECATED HOST POWER MANAGEMENT CONFIGURATIONB.29. USE MULTIPLE BOOT.DEVICES.DEVICE INSTEAD OF MULTIPLE BOOTB.30. REMOVED THE DISKS.CLONE AND DISKS.DETACH_ONLY ELEMENTSB.31. RENAME ELEMENT VMPOOL TO VM_POOLB.32. USE LOGICAL_UNITS INSTEAD OF MULTIPLE LOGICAL_UNITB.33. REMOVED THE SNAPSHOTS.COLLAPSE_SNAPSHOTS ELEMENTB.34. RENAMED STORAGE AND HOST_STORAGE ELEMENTSB.35. REMOVED THE PERMISSIONS.CLONE ELEMENTB.36. RENAMED THE RANDOM NUMBER GENERATOR SOURCE ELEMENTSB.37. REMOVED THE INTERMEDIATE TAG.PARENT ELEMENTB.38. REMOVE SCHEDULING BUILT-IN NAMES AND THRESHOLDSB.39. REMOVED THE BRICKS.REPLICA_COUNT AND BRICKS.STRIPE_COUNT ELEMENTSB.40. RENAMED THE STATISTICS TYPE PROPERTY TO KINDB.41. USE MULTIPLE VCPU_PINS.VCPU_PIN INSTEAD OF MULTIPLE VCPU_PIN

746747747747

749749749749750750

752752752754755755755756756756757757757758758759759760760760760761761762762762762763763764764765765766767767768769770771771771


32

B.42. USE FORCE PARAMETER TO FORCE REMOVE A DATA CENTERB.43. USE FORCE PARAMETER TO FORCE REMOVE A HOSTB.44. USE PARAMETERS FOR FORCE REMOVE STORAGE DOMAINB.45. USE HOST PARAMETER TO REMOVE STORAGE SERVER CONNECTIONB.46. USE FORCE AND STORAGE_DOMAIN PARAMETERS TO REMOVE TEMPLATE DISKSB.47. DON’T REMOVE DISKS VIA THE VM DISK APIB.48. USE FORCE QUERY PARAMETER TO FORCE REMOVE A VIRTUAL MACHINEB.49. USE POST INSTEAD OF DELETE TO REMOVE MULTIPLE BRICKSB.50. REMOVED THE SCHEDULING_POLICY.POLICY ELEMENTB.51. ADDED SNAPSHOT.SNAPSHOT_TYPEB.52. REMOVED MOVE ACTION FROM VMB.53. MOVED REPORTED_CONFIGURATIONS.IN_SYNC TO NETWORK_ATTACHMENTB.54. REPLACED CAPABILITIES WITH CLUSTERLEVELSB.55. REPLACED DISKS WITH DISKATTACHMENTSB.56. USE ISCSI_TARGETS ELEMENT TO DISCOVER UNREGISTERED STORAGE

772772773773774774774774775775776776776777779

Table of Contents

33


34

CHAPTER 1. INTRODUCTION

The Red Hat Virtualization Manager provides a Representational State Transfer (REST) API. TheAPI provides software developers and system administrators with control over their Red HatVirtualization environment outside of the standard web interface. The API is useful for developersand administrators to integrate the functionality of a Red Hat Virtualization environment with customscripts or external applications that access the API via the standard Hypertext Transfer Protocol(HTTP).

The benefits of the 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 virtualizationinfrastructure, as many 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 Virtualization environment with scripts.

This documentation acts as a reference for the Red Hat Virtualization API. It aims to providedevelopers and administrators with instructions and examples to help harness the functionality oftheir Red Hat Virtualization environment through the API, either directly or using the provided SDKs.

1.1. REPRESENTATIONAL STATE TRANSFER

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

1.2. API PREREQUISITES

Prerequisites for using the Red Hat Virtualization API:

A networked installation of Red Hat Virtualization Manager, which includes the API.

A client or programming library that initiates and receives HTTP requests from the API server.For example:

The oVirt Python SDK.

The oVirt Ruby SDK.

CHAPTER 1. INTRODUCTION

35

https://github.com/oVirt/ovirt-engine-sdk/tree/master/sdkhttps://github.com/oVirt/ovirt-engine-sdk-ruby/tree/master/sdk

The oVirt Java SDK.

The cURL command line tool.

RESTClient, a debugger for RESTful web services.

Knowledge of Hypertext Transfer Protocol (HTTP), the protocol used for REST API interactions.The Internet Engineering Task Force provides a Request for Comments (RFC) explaining theHypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt.

Knowledge of Extensible Markup Language (XML) or JavaScript Object Notation (JSON), whichthe API uses to construct resource representations. The W3C provides a full specification onXML at http://www.w3.org/TR/xml. ECMA International provide a free publication on JSON athttp://www.ecma-international.org.


36

https://github.com/oVirt/ovirt-engine-sdk-java/tree/master/sdkhttps://curl.haxx.sehttps://addons.mozilla.org/en-US/firefox/addon/restclienthttp://www.ietf.org/rfc/rfc2616.txthttp://www.w3.org/TR/xmlhttp://www.ecma-international.org

CHAPTER 2. AUTHENTICATION AND SECURITY

2.1. TLS/SSL CERTIFICATION

The Red Hat Virtualization API requires Hypertext Transfer Protocol Secure (HTTPS) [1] for secureinteraction with client software, such as the SDK and CLI components. This involves obtaining theCA certificate used by the server, and importing it into the certificate store of your client.

2.1.1. Obtaining the CA Certificate

You can obtain the CA certificate from the Red Hat Virtualization Manager and transfer it to the clientmachine using one of these methods:

Method 1

The preferred method for obtaining the CA certificate is to use the openssl s_clientcommand line tool to perform a real TLS handshake with the server, and then extract thecertificates that it presents. Run a command like this:

$ openssl s_client \-connect myengine.example.com:443 \-showcerts \< /dev/null

This command will connect to the server and display output similar to the following:

CONNECTED(00000003)depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416verify error:num=19:self signed certificate in certificate chain---Certificate chain 0 s:/C=US/O=Example Inc./CN=myengine.example.com i:/C=US/O=Example Inc./CN=myengine.example.com.23416-----BEGIN CERTIFICATE-----MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBsSVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=-----END CERTIFICATE----- 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416 i:/C=US/O=Example Inc./CN=myengine.example.com.23416-----BEGIN CERTIFICATE-----MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBsPkyg1rQHR6ebGQ==-----END CERTIFICATE-----

The text between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marks shows the certificates presented by the server. The first one isthe certificate of the server itself, and the last one is the certificate of the CA. Copy the CAcertificate, including the marks, to the ca.crt file. The result should look like this:

-----BEGIN CERTIFICATE-----MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx


37

https://en.wikipedia.org/wiki/Certificate_authority

FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBsPkyg1rQHR6ebGQ==-----END CERTIFICATE-----

Important

This is the most reliable method to obtain the CA certificate used by the server.The rest of the methods described here will work in most cases, but they will notobtain the correct CA certificate if it has been manually replaced by theadministrator of the server.

Method 2

If you cannot use the openssl s_client method described above, you can instead use acommand line tool to download the CA certificate from the Red Hat Virtualization Manager.

Examples of command line tools include curl and wget, both of which are available onmultiple platforms.

If using curl:

$ curl \--output ca.crt \'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

If using wget:

$ wget \--output-document ca.crt \'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

Method 3

Use a web browser to navigate to the certificate located at:

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

Depending on the chosen browser, the certificate either downloads or imports into thebrowser’s keystore.

1. If the browser downloads the certificate: save the file as ca.crt.

2. If the browser imports the certificate: export it from the browser’s certificationoptions and save it as ca.crt.

Method 4

Log in to the Red Hat Virtualization Manager, export the certificate from the truststore, andcopy it to your client machine.

1. Log in to the Red Hat Virtualization Manager machine as root.


38

2. Export the certificate from the truststore using the Java keytool managementutility:

# keytool \-keystore /etc/pki/ovirt-engine/.truststore \-storepass mypass \-exportcert \-alias cacert \-rfc \-file ca.crt

This creates a certificate file called ca.crt.

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

$ scp ca.crt [email protected]:/home/myuser/.

Each of these methods results in a certificate file named ca.crt on your client machine. You mustthen import this file into the certificate store of the client.

2.1.2. Importing a Certificate to a Client

Importing a certificate to a client relies on how the client stores and interprets certificates. See yourclient documentation for more information on importing a certificate.

2.2. AUTHENTICATION

Any user with a Red Hat Virtualization Manager account has access to the API. All requests must beauthenticated using either OAuth or basic authentication, as described below.

2.2.1. OAuth Authentication

Since version 4.0 of Red Hat Virtualization the preferred authentication mechanism is OAuth 2.0, asdescribed in RFC 6749.

OAuth is a sophisticated protocol, with several mechanisms for obtaining authorization and accesstokens. For use with the Red Hat Virtualization API, the only supported one is the Resource OwnerPassword Credentials Grant, as described in section 4.3 of RFC 6749.

You must first obtain a token, sending the user name and password to the Red Hat VirtualizationManager single sign-on service:

POST /ovirt-engine/sso/oauth/token HTTP/1.1Host: myengine.example.comContent-Type: application/x-www-form-urlencodedAccept: application/json

The request body must contain the grant_type, scope, username, and password parameters:

Table 2.1. OAuth token request parameters


39

https://oauth.net/2https://tools.ietf.org/html/rfc6749https://tools.ietf.org/html/rfc6749#section-4.3

Name Value

grant_type password

scope ovirt-app-api

username admin@internal

password mypassword

These parameters must be URL-encoded. For example, the @ character in the user name needs tobe encoded as %40. The resulting request body will be something like this:

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword

Important

The scope parameter is described as optional in the OAuth RFC, but when using it withthe Red Hat Virtualization API it is mandatory, and its value must be ovirt-app-api.

If the user name and password are valid, the Red Hat Virtualization Manager single sign-on servicewill respond with a JSON document similar to this one:

{ "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=", "token_type": "bearer", "scope": "...", ...}

For API authentication purposes, the only relevant name/value pair is the access_token. Do notmanipulate this in any way; use it exactly as provided by the SSO service.

Once the token has been obtained, it can be used to perform requests to the API by including it inthe HTTP Authorization header, and using the Bearer scheme. For example, to get the list ofvirtual machines, send a request like this:

GET /ovirt-engine/api/vms HTTP/1.1Host: myengine.example.comAccept: application/xmlAuthorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

The token can be used multiple times, for multiple requests, but it will eventually expire. When itexpires, the server will reject the request with the 401 HTTP response code:


40

https://en.wikipedia.org/wiki/Percent-encoding

HTTP/1.1 401 Unauthorized

When this happens, a new token is needed, as the Red Hat Virtualization Manager single sign-onservice does not currently support refreshing tokens. A new token can be requested using the samemethod described above.

2.2.2. Basic Authentication

Important

Basic authentication is supported only for backwards compatibility; it is deprecated sinceversion 4.0 of Red Hat Virtualization, and will be removed in the future.

Each request uses HTTP Basic Authentication [2] to encode the credentials. If a request does notinclude an appropriate Authorization header, the server sends a 401 Authorization Required response:

HEAD /ovirt-engine/api HTTP/1.1Host: myengine.example.com

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. Encode an appropriateRed Hat Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.

The following table shows the process for encoding credentials in Base64.

Table 2.2. Encoding credentials for API access

Item Value

User name admin

Domain internal

Password mypassword

Unencoded credentials admin@internal:mypassword

Base64 encoded credentials YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==


41

https://tools.ietf.org/html/rfc4648

Provide the Base64-encoded credentials as shown:

HEAD /ovirt-engine/api HTTP/1.1Host: myengine.example.comAuthorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK

Important

Basic authentication involves potentially sensitive information, such as passwords, sentas plain text. The API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests.

Important

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

2.2.3. Authentication Sessions

The API also provides authentication session support. Send an initial request with authenticationdetails, then send all subsequent requests using a session cookie to authenticate.

2.2.3.1. Requesting an Authenticated Session

1. Send a request with the Authorization and Prefer: persistent-auth headers:

HEAD /ovirt-engine/api HTTP/1.1Host: myengine.example.comAuthorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==Prefer: persistent-auth

HTTP/1.1 200 OK...

This returns a response with the following header:

Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure

Take note of the JSESSIONID= value. In this example the value is 5dQja5ubr4yvI2MM2z+LZxrK.

2. Send all subsequent requests with the Prefer: persistent-auth and Cookie headerswith the JSESSIONID= value. The Authorization header is no longer needed whenusing an authenticated session.


42

HEAD /ovirt-engine/api HTTP/1.1Host: myengine.example.comPrefer: 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 /ovirt-engine/api HTTP/1.1Host: myengine.example.comAuthorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK...

[1] HTTPS is described in RFC 2818 HTTP Over TLS.

[2] Basic Authentication is described in RFC 2617 HTTP Authentication: Basic and Digest AccessAuthentication.


43

http://tools.ietf.org/html/rfc2818http://tools.ietf.org/html/rfc2617

CHAPTER 3. COMMON CONCEPTS

3.1. TYPES

The API uses the type concept to describe the different kinds of objects accepted and returned.

There are three relevant kinds of types:

Primitive types

Describe simple kinds of objects, like strings or integers.

Enumerated types

Describe lists of valid values like VmStatus or DiskFormat.

Structured types

Describe structured objects, with multiple attributes and links, like Vm or Disk.

3.2. IDENTIFIED TYPES

Many of the types used by the API represent identified objects, objects that have an unique identifierand exist independently of other objects. The types used to describe those objects extend theIdentified type, which contains the following set of common attributes:

Attribute Type Description

id String Each object in the virtualization infrastructure contains an id,which acts as an unique identifier.

href String The canonical location of the object as an absolute path.

name String A user-supplied human readable name for the object. The name name is unique across all objects of the same type.

description String A free-form user-supplied human readable description of theobject.

Important

Currently for most types of objects the id attribute is actually a randomly generated UUID,but this is an implementation detail, and users should not rely on that, as it may change inthe future. Instead users should assume that these identifiers are just strings.


44

https://en.wikipedia.org/wiki/Universally_unique_identifier

3.3. OBJECTS

Objects are the individual instances of the types supported by the API. For example, the virtualmachine with identifier 123 is an object of the Vm type.

3.4. COLLECTIONS

A collection is a set of objects of the same type.

3.5. REPRESENTATIONS

The state of objects needs to be represented when it is transferred beetween the client and theserver. The API supports XML and JSON as the representation of the state of objects, both for inputand output.

3.5.1. XML representation

The XML representation of an object consists of an XML element corresponding to the type of theobject, XML attributes for the id and href attributes, and nested XML elements for the rest of theattributes. For example, the XML representation for a virtual machine appears as follows:

The XML representation of a collection of objects consists of an XML element, named after the typeof the objects, in plural. This contains the representations of the objects of the collection. Forexample, the XML respresentation for a collection of virtual machines appears as follows:

myvm My VM 1073741824 ...

yourvm Your VM 1073741824 ... myname My description 2147483648 ... ...


45

Important

In the XML representation of objects the id and href attributes are the only ones that arerepresented as XML attributes, the rest are represented as nested XML elements.

3.5.2. JSON representation

The JSON representation of an object consists of a JSON document containing a name/value pairfor each attribute (including id and href). For example, the JSON representation of a virtualmachine appears as follows:

{ "id": "123", "href": "/ovirt-engine/api/vms/123", "name": "myvm", "description": "My VM", "memory": 1073741824, ...}

The JSON representation of a collection of objects consists of a JSON document containg aname/value pair (named ater the type of the objects, in singular) which in turn contains an array withthe representations of the objects of the collection. For example, the JSON respresentation for acollection of virtual machines appears as follows:

{ "vm": [ { "id": "123", "href": "/ovirt-engine/api/vms/123", "name": "myvm", "description": "My VM", "memory": 1073741824, ... }, { "id": "456", "href": "/ovirt-engine/api/vms/456", "name": "yourvm", "description": "Your VM", "memory": 2147483648, ... }, ]}

3.6. SERVICES

Services are the parts of the server responsible for retrieving, adding updating, removing andexecuting actions on the objects supported by the API.

There are two relevant kinds of services:


46

Services that manage a collection of objects

These services are reponsible for listing existing objects and adding new objects. Forexample, the Vms service is responsible for managing the collection of virtual machinesavailable in the system.

Services that manage a specific object

These services are responsible for retrieving, updating, deleting and executing actions inspecific objects. For example, the Vm service is responsible for managing a specific virtualmachine.

Each service is accessible via a particular path within the server. For example, the service thatmanages the collection of virtual machines available in the system is available in the via the path /vms, and the service that manages the virtual machine 123 is available via the path /vms/123.

All kinds of services have a set of methods that represent the operations that they can perform. Theservices that manage collections of objects usually have the list and add methods. The servicesthat manage specific objects usually have the get, update and remove methods. In addition,services may also have action methods, that represent less common operations. For example, theVm service has a start method that is used to start a virtual machine.

For the more usual methods there is a direct mapping between the name of the method and thename of the HTTP method:

Method name HTTP method

add POST

get GET

list GET

update PUT

remove DELETE

The path used in the HTTP request is the path of the service, with the /ovirt-engine/api prefix.

For example, the request to list the virtual machines should be like this, using the HTTP GETmethod and the path /vms:

GET /ovirt-engine/api/vms

For action methods the HTTP method is always POST, and the name of the method is added as asuffix to the path. For example, the request to start virtual machine 123 should look like this, usingthe HTTP POST method and the path /vms/123/start:


47

POST /ovirt-engine/api/vms/123/start

Each method has a set of parameters.

Parameters are classified into two categories:

Main parameter

The main parameter corresponds the object or collection that is retrieved, added orupdated. This only applies to the add, get, list and update methods, and there will beexactly one such main parameter per method.

Secondary parameters

The rest of the parameters.

For example, the operation that adds a virtual machine (see here) has three parameters: vm, cloneand clone_permissions. The main parameter is vm, as it describes the object that is added. The clone and clone_permissions parameters are secondary parameters.

The main parameter, when used for input, must be included in the body of the HTTP request. Forexample, when adding a virtual machine, the vm parameter, of type Vm, must be included in therequest body. So the complete request to add a virtual machine, including all the HTTP details, mustlook like this:

POST /ovirt-engine/api/vms HTTP/1.1Host: myengine.example.comAuthorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=Content-Type: application/xmlAccept: application/xml

myvm My VM Default Blank

When used for output, the main parameters are included in the response body. For example, whenadding a virtual machine, the vm parameter will be included in the response body. So the completeresponse body will look like this:

HTTP/1.1 201 CreatedContent-Type: application/xml

myvm My VM ...


48

Secondary parameters are only allowed for input (except for action methods, which are describedlater), and they must be included as query parameters. For example, when adding a virtual machinewith the clone parameter set to true, the complete request must look like this:

POST /ovirt-engine/api/vms?clone=true HTTP/1.1Host: myengine.example.comAuthorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=Content-Type: application/xmlAccept: application/xml

myvm My VM Default Blank

Action methods only have secondary parameters. They can be used for input and output, and theyshould be included in the request body, wrapped with an action element. For action method usedto start a virtual machine (see here) has a vm parameter to describe how the virtual machine shouldbe started, and a use_cloud_init parameter to specify if cloud-init should be used to configurethe guest operating system. So the complete request to start virtual machine 123 using cloud-init willlook like this when using XML:

POST /ovirt-engine/api/vms/123/start HTTP/1.1Host: myengine.example.comAuthorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=Content-Type: application/xmlAccept: application/xml

true eth0 true static 192.168.0.100 255.255.255.0 192.168.0.1 192.168.0.1


49

https://cloudinit.readthedocs.io

3.7. SEARCHING

The list method of some services has a search parameter that can be used to specify a searchcriteria. When used, the server will only returns objects within the collection that satisfy thosecriteria. For example, the following request will return only the virtual machine named myvm:

GET /ovirt-engine/api/vms?search=name%3Dmyvm

3.7.1. Maximum results parameter

Use the max parameter to limit the number of objects returned. For example, the following requestwill only return one virtual machine, regardless of how many are available in the system:

GET /ovirt-engine/api/vms?max=1

A search request without the max parameter will return all the objects. Specifying the max parameteris recommended to reduce the impact of requests in the overall performance of the system.

3.7.2. Case sensitivity

By default queries are not case sensitive. For example, the following request will return the virtualmachines named myvm, MyVM and MYVM:


The optional case_sensitive boolean parameter can be used to change this behaviour. Forexample, to get exactly the virtual machine named myhost, and not MyHost or MYHOST, send arequest like this:

GET /ovirt-engine/api/vms?search=name%3D=myvm&case_sensitive=true

3.7.3. Search syntax

The search parameters uses the same format as the Red Hat Virtualization query language:

(criteria) [sortby (element) asc|desc]

The sortby clause is optional and only needed when ordering results.

Example search queries:

Collection Criteria Result

hosts vms.status=up

Returns a list of all hosts running virtual machines that are up.


50

vms domain=example.com

Returns a list of all virtual machines running on the specifieddomain.

vms users.name=mary

Returns a list of all virtual machines belonging to users withthe user name mary.

events severity > normal sortby time

Returns a list of all events with severity higher than normaland sorted by the the value of their time attribute.

events severity > normal sortby time desc

Returns a list of all events with severity higher than normaland sorted by the the value of their time attribute indescending order.

Collection Criteria Result

The value of the search parameter must be URL-encoded to translate reserved characters, suchas operators and spaces. For example, the equals sign should be encoded as %3D:


3.7.4. Wildcards

The asterisk can be used as part of a value, to indicate that any string matches, including the emtpystring. For example, the following request will return all the virtual machines with names beginningwith myvm such as myvm, myvm2, myvma or myvm-webserver:

GET /ovirt-engine/api/vms?search=name%3Dmyvm*

3.7.5. Pagination

Some Red Hat Virtualization environments contain large collections of objects. Retrieving all of themwith one request isn’t practical, and hurts performace. To allow retrieving them page by page the search parameter supports an optional page clause. This, combined with the max parameter, isthe basis for paging. For example, to get the first page of virtual machines, with a page size of 10virtual machines, send request like this:

GET /ovirt-engine/api/vms?search=page%201&max=10

Note

The search parameter is URL-encoded, the actual value of the search parameter, beforeencoding, is page 1, so this is actually requesting the first page.


51

https://en.wikipedia.org/wiki/Percent-encoding

Increase the page value to retrieve the next page:

GET /ovirt-engine/api/vms?search=page%202&max=10

The page clause can be used in conjunction with other clauses inside the search parameter. Forexample, the following request will return the second page of virtual machines, but sorting by name:

GET /ovirt-engine/api/vms?search=sortby%20name%20page%202&max=10

Important

The API is stateless; it is not possible to retain a state between different requests since allrequests are independent from each other. As a result, if a status change occurs betweenyour requests, then the page results may be inconsistent.

For example, if you request a specific page from a list of virtual machines, and virtualmachines are created or removed before you request the next page, then your resultsmay be missing some of them, or contain duplicates.

3.8. PERMISSIONS

Many of the services that manage a single object provide a reference to a permissions servicethat manages the permissions assigned to that object. Each permission contains links to the user orgroup, the role and the object. For example, the permissions assigned to a specific virtual machinecan be retrieved sending a request like this:

GET /ovirt-engine/api/vms/123/permissions

The response body will look like this:

A permission is added to an object sending a POST request with a permission representation to thisservice. Each new permission requires a role and a user.

3.9. HANDLING ERRORS

Some errors require further explanation beyond a standard HTTP status code. For example, the APIreports an unsuccessful object state update or action with a fault in the response body. The faultcontains the reason and detail attributes. For example, when the server receives a request tocreate a virtual machine without the mandatory name attribute it will respond with the followingHTTP response line:

HTTP/1.1 400 Bad Request

...


52

And the following response body:

Incomplete parameters Vm [name] required for add


53

CHAPTER 4. QUICK START EXAMPLE

This chapter provides an example to demonstrate the REST API’s ability to setup a basic Red HatVirtualization environment and create a virtual machine. In addition to the standard prerequisites,this example requires the following:

A networked and configured Red Hat Virtualization installation;

An ISO file containing a desired virtual machine operating system to install. This chapter usesCentOS 7 for our installation ISO example; and

Red Hat Virtualization’s engine-iso-uploader tool to upload your chosen operating systemISO file.

This example uses curl to demonstrate API 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 headers. However, these fields are mandatory and require data specificto your installation of Red Hat Virtualization.

Important

All the curl examples use admin@internal as the user name, mypassword as thepassword, /etc/pki/ovirt-engine/ca.pem as the certificate location and myengine.example.com as the host name. These are just examples, Make sure toreplace them with valid values for your environment.

Note

Red Hat Virtualization generates an unique identifier for the id attribute for eachresource. Identifier codes in this example might appear different to the identifier codes inyour Red Hat Virtualization environment.

Note

In many examples of this section some of the attributes of results returned by the APIhave been omitted, to make them shorter. You can always use the reference to find thecomplete list of attributes. For example, if you want to see the complete list of attributes ofthe Cluster type, just go here.

4.1. EXAMPLE: ACCESS API ENTRY POINT

The following request retrieves a representation of the main entry point for version 4 of of the API:


54

https://www.centos.orghttps://curl.haxx.se

GET /ovirt-engine/api HTTP/1.1Version: 4Accept: application/xml

Same request, but using the /v4 URL prefix instead of the Version header:

GET /ovirt-engine/api/v4 HTTP/1.1Accept: application/xml

Same request, using the curl command:

curl \--cacert '/etc/pki/ovirt-engine/ca.pem' \--request GET \--header 'Version: 4' \--header 'Accept: application/xml' \--user 'admin@internal:mypassword' \https://myengine.example.com/ovirt-engine/api

The resul

red hat virtualization 4.1 rest api guide...application programming interface. this guide is...

Documents